Cloud Run functions supports several methods of running your
functions outside of the target deployment environment. This is particularly
useful for iterative development, and for situations where you want to test
your function before deploying.
The ability to run your functions without deploying them can simplify local
testing, compliance with data locality restrictions, and multicloud
deployments:
- **Data locality restrictions**: Test your function locally without accessing
production data, to avoid violating your organization's data locality rules.
- **Multicloud deployments**: Multicloud function deployments are an established
pattern to mitigate downtime risk in reliability-critical environments.
Deploying functions to environments other than
Cloud Run functions itself reduces the risk of your application
experiencing unplanned downtime.
## Develop functions locally using Functions Framework
You can develop and test functions locally using
[Functions Framework](https://github.com/GoogleCloudPlatform/functions-framework).
Developing a function locally can help you test your code without having to
rebuild your function container. This can save time and make it easier to test
your function.
Cloud Run uses the open-source
[Functions Framework](https://github.com/GoogleCloudPlatform/functions-framework)
libraries to wrap your deployed functions in a persistent HTTP application.
The Functions Framework can also run on any other platform that supports the
language itself, including your local machine, on-premises servers, and
[Compute Engine](https://cloud.google.com/products/compute).
### Install dependencies
In your function's directory, install the Functions Framework library for your
language:
### Node.js
> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.
```bash
npm install --save-dev @google-cloud/functions-framework
```
### Python
> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.
```bash
pip3 install functions-framework
```
### Go
> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.
```bash
go install github.com/GoogleCloudPlatform/functions-framework-go/funcframework
```
### Java
> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.
#### Maven
If you're using [Maven](http://maven.apache.org/install.html), add the
following to your `pom.xml` file:
com.google.cloud.functions
functions-framework-api
1.1.0
provided
#### Gradle
If you're using [Gradle](https://gradle.org/), add the following to your
`build.gradle` file:
dependencies {
// Every function needs this dependency to get the Functions Framework API.
compileOnly 'com.google.cloud.functions:functions-framework-api:1.1.0'
// To run function locally using Functions Framework's local invoker
invoker 'com.google.cloud.functions.invoker:java-function-invoker:1.3.1'
}
See the [Java Functions Framework library](https://github.com/GoogleCloudPlatform/functions-framework-java)
for more information.
### C#
The following commands use .NET Templates to create a new .NET function
codebase with the
[.NET Functions Framework library](https://github.com/GoogleCloudPlatform/functions-framework-dotnet)
as a dependency:
```bash
# HTTP functions
dotnet new gcf-http
# CloudEvent functions
dotnet new gcf-event
```
### Ruby
In Ruby the Functions Framework **must** be added to your function's
dependencies in order to deploy it to Cloud Run:
```bash
bundle add functions_framework
```
### PHP
> [!NOTE]
> **Note:** This library is automatically included when deploying your function if you do not specify it in your function's dependencies.
```bash
composer require google/cloud-functions-framework
```
### Configure the Functions Framework
Before running a function using the Functions Framework, you'll first need to
specify both the type and the name of the function you want to run. These
attributes can be specified as either command-line interface (CLI) flag
or as environment variables.
#### Supported function types
The Functions Framework supports both types of functions
supported by Cloud Run functions. All language runtimes
support both the `http` and `cloudevent` signature types.
| Function type | Signature type | Description | Supporting Runtimes |
|---|---|---|---|
| [HTTP-triggered functions](https://docs.cloud.google.com/run/docs/write-functions#write-http-functions) | `http` | Functions that receive and respond to HTTP requests. | All runtimes |
| [Event-driven functions](https://docs.cloud.google.com/run/docs/write-functions#write-event-driven-functions) | `cloudevent` | Industry-standard event format. | All runtimes |
#### Specify which function to run
Before running a function with the Functions Framework, you must first specify
which function within your code to run. For most languages, you can do
this by specifying the target function's method name as shown in the
following tables. Note that there are exceptions to this rule for the
[Java](https://docs.cloud.google.com/run/docs/runtimes/java) and [.NET](https://docs.cloud.google.com/run/docs/runtimes/dotnet) runtimes.
#### Per-language instructions
See the following table for a list of configuration options supported by each
language.
### Node.js
| CLI Argument | Environment Variable | Description |
|---|---|---|
| `--port` | `PORT` | The port to listen for requests on. (Default: `8080`) |
| `--target` | `FUNCTION_TARGET` | The name of the `export`ed function to be invoked. (Default: `function`) |
| `--signature-type` | `FUNCTION_SIGNATURE_TYPE` | The signature type used by your function. Can be `http` (the default) or `cloudevent`. |
### Python
| CLI Argument | Environment Variable | Description |
|---|---|---|
| `--port` | `PORT` | The port to listen for requests on. (Default: `8080`) |
| `--target` | `FUNCTION_TARGET` | The name of the `export`ed function to be invoked. (Default: `function`) |
| `--signature-type` | `FUNCTION_SIGNATURE_TYPE` | The signature type used by your function. Can be `http` (the default) or `cloudevent`. |
### Go
| Environment Variable | Description |
|---|---|
| `PORT` | The port to listen for requests on. (Default: `8080`) |
> [!NOTE]
> **Note:** The Go Functions Framework automatically detects your function's signature type.
### Java
| Argument Name | Environment Variable | Description |
|---|---|---|
| `run.port` | `PORT` | The port to listen for requests on. (Default: `8080`) |
| `run.functionTarget` | `FUNCTION_TARGET` | The name of the `export`ed function to be invoked. (Default: `function`) |
> [!NOTE]
> **Note:** The Java Functions Framework automatically detects your function's signature type.
### C#
| CLI Argument | Environment Variable | Description |
|---|---|---|
| `--port` | `PORT` | The port to listen for requests on. (Default: `8080`) |
| `--target` (or only argument) | `FUNCTION_TARGET` | The *classname* of the function to be invoked. (Default: `function`) |
> [!NOTE]
> **Note:** The .NET Functions Framework automatically detects your function's signature type.
### Ruby
| CLI Argument | Environment Variable | Description |
|---|---|---|
| `--port` | `PORT` | The port to listen for requests on. (Default: `8080`) |
| `--target` | `FUNCTION_TARGET` | The name of the `export`ed function to be invoked. (Default: `function`) |
### PHP
| Environment Variable | Description |
|---|---|
| `FUNCTION_TARGET` | The name of the function to be invoked. (Default: `function`) |
| `FUNCTION_SIGNATURE_TYPE` | The signature type used by your function. Can be `http` (the default) or `cloudevent`. |
Follow these instructions to configure and run the Functions Framework:
### Node.js
The Node.js Functions Framework lets you specify your function's name and
signature type as command line arguments
or [environment variables](https://github.com/GoogleCloudPlatform/functions-framework-nodejs/#configure-the-functions-framework).
> [!NOTE]
> **Note:** Command-line arguments take precedence over environment variables when running the Node.js Functions Framework.
You can also specify these values in the `package.json` buildfile by adding a
`start` script with the required CLI arguments as shown in the example below.
```bash
"scripts": {
"start": "npx functions-framework --target=YOUR_FUNCTION_NAME [--signature-type=YOUR_SIGNATURE_TYPE]"
}
```
The same can be done using environment variables:
```bash
"scripts": {
"start": "FUNCTION_TARGET=YOUR_FUNCTION_NAME FUNCTION_SIGNATURE_TYPE=YOUR_SIGNATURE_TYPE npx functions-framework"
}
```
Replace YOUR_FUNCTION_NAME with the method name of your function, and
YOUR_SIGNATURE_TYPE (if applicable) with the signature type of your
function as shown in [supported function types](https://docs.cloud.google.com/run/docs/local-dev-functions#supported_function_types).
### Python
The Python Functions Framework lets you specify your function's name and
signature type as command line arguments
or [environment variables](https://github.com/GoogleCloudPlatform/functions-framework-python/#configure-the-functions-framework). Command-line arguments must be specified when you
[run the framework](https://docs.cloud.google.com/run/docs/local-dev-functions#run_your_function).
> [!NOTE]
> **Note:** Command-line arguments take precedence over environment variables when running the Python Functions Framework.
### Go
The Go Functions Framework uses `funcframework.RegisterHTTPFunctionContext` to
specify the function target and signature type.
### Java
The Java Functions Framework accepts configuration data from three different
sources, in the following priority order (most specific to least specific):
- Command-line arguments
- Buildfiles
- Environment variables
### Command-line arguments
#### Maven
You can specify the function you want to run by adding the following
command-line interface (CLI) flag to your `mvn` commands:
```bash
-Drun.functionTarget=YOUR_FUNCTION_NAME
```
You can also specify the target port by adding the following CLI flag in a
similar manner:
```bash
-Drun.port=12345
```
#### Gradle
Gradle's CLI flags are nearly identical to Maven's. The only change Gradle makes
is to swap the leading `-D` in each flag for a `-P` as shown in the following
example:
```bash
# Maven version
-Drun.functionTarget=...
# Gradle version
-Prun.functionTarget=...
```
### Buildfiles
You can also specify the function you want to run in your project's buildfile.
While Maven and Gradle have similar CLI flags, their buildfile clauses differ
significantly.
#### Maven
Maven buildfiles are named `pom.xml`. Add the following clause to this file to
specify a target function:
com.google.cloud.functions
function-maven-plugin
0.11.0
functions.HelloWorld
Replace `` with the class name of your
function. For example, a function in package `functions` with class name
`HelloCloudFunctions` would have a class name of
`functions.HelloCloudFunctions`. This is relative to the parent build file
- either `pom.xml` or `build.gradle`.
#### Gradle
Gradle buildfiles are named `build.gradle`. Add the following clause to
this file to specify a target function:
// Register a "runFunction" task to run the function locally
tasks.register("runFunction", JavaExec) {
main = 'com.google.cloud.functions.invoker.runner.Invoker'
classpath(configurations.invoker)
inputs.files(configurations.runtimeClasspath, sourceSets.main.output)
args(
'--target', project.findProperty('run.functionTarget') ?: '',
'--port', project.findProperty('run.port') ?: 8080
)
doFirst {
args('--classpath', files(configurations.runtimeClasspath, sourceSets.main.output).asPath)
}
}
### C#
If you create your project using `dotnet new` and one of the templates specified
earlier, the .NET Functions Framework will automatically detect your function.
If your project contains multiple functions, see the
[Running the Framework](https://docs.cloud.google.com/run/docs/local-dev-functions#run_your_function) section for information on how
to run a specific function.
### Ruby
The Ruby Functions Framework lets you specify your function's name and
signature type as command line arguments
or [environment variables](https://googlecloudplatform.github.io/functions-framework-ruby/v0.9.0/file.running-a-functions-server.html#configuring-the-server). Command-line arguments must be specified when you
[run the framework](https://docs.cloud.google.com/run/docs/local-dev-functions#run_your_function).
> [!NOTE]
> **Note:** Command-line arguments take precedence over environment variables when running the Ruby Functions Framework.
### PHP
The PHP Functions Framework lets you specify
[environment variables](https://github.com/GoogleCloudPlatform/functions-framework-php#configure-the-functions-framework) as command line arguments.
You can also specify these values in the `composer.json` buildfile by adding a
`start` script, as shown in the following example.
```bash
"scripts": {
"start": [
"Composer\\Config::disableProcessTimeout",
"FUNCTION_TARGET=YOUR_FUNCTION_NAME php -S localhost:${PORT:-8080} vendor/bin/router.php"
].
}
```
Replace YOUR_FUNCTION_NAME with the name of your function, and
YOUR_SIGNATURE_TYPE (if applicable; it is not included in the example
shown here).
### Run your function
Use the following command to run your function with the Functions Framework.
By default, your function will be accessible at `localhost:8080` unless you
explicitly specify a `PORT` value.
### Node.js
```bash
npm start
```
### Python
Using command line arguments:
```bash
functions-framework --target=YOUR_FUNCTION_NAME
```
Using environment variables:
```bash
FUNCTION_TARGET=YOUR_FUNCTION_NAME functions-framework
```
Replace YOUR_FUNCTION_NAME with your function's method name.
### Go
Create a `cmd/main.go` file that defines a `main` package and `main()`
function to start the local HTTP server, as described in the
[Functions Framework for Go documentation](https://github.com/GoogleCloudPlatform/functions-framework-go#quickstart-hello-world-on-your-local-machine).
```bash
cd cmd
go build
FUNCTION_TARGET=YOUR_FUNCTION_NAME PORT=8080 ./cmd
```
Replace YOUR_FUNCTION_NAME with the name of your Go function.
### Java
#### Maven
Use the following command to run a function specified in `pom.xml`:
```bash
mvn function:run
```
Use the following command to run a function specified in a command-line
argument:
```bash
mvn function:run -Drun.functionTarget=YOUR_FUNCTION_NAME
```
Use the following command to run a function specified as an environment variable:
```bash
FUNCTION_TARGET=YOUR_FUNCTION_NAME mvn function:run
```
Replace YOUR_FUNCTION_NAME with your function's classname.
#### Gradle
Use the following command to run a function specified in `build.gradle`:
```bash
./gradlew runFunction
```
Use the following command to run a function specified in a command-line
argument:
```bash
./gradlew runFunction -Prun.functionTarget=YOUR_FUNCTION_NAME
```
Use the following command to run a function specified as an environment variable:
```bash
FUNCTION_TARGET=YOUR_FUNCTION_NAME ./gradlew runFunction
```
Replace YOUR_FUNCTION_NAME with your function's classname.
### C#
Use the following command to run your function when exactly one function is
present in the current .NET project. Note that this is the default structure for
template-created projects.
```bash
dotnet run
```
> [!NOTE]
> **Note:** The .NET runtime detects functions by searching for classes that implement one of the Functions Framework interfaces (`IHttpFunction` or `ICloudEventFunction`).
If your .NET project contains multiple functions, use the following command to
run a specific function. Replace YOUR_FUNCTION_CLASSNAME with your
function's classname, including the namespace.
```bash
dotnet run YOUR_FUNCTION_CLASSNAME
```
If you want to run multiple functions simultaneously, you'll need to run
multiple Functions Framework instances. To avoid conflicts between running
framework instances, each instance should use a different `PORT` value. The
following command shows how to run a function with a `PORT` value of `8080`.
Using command line arguments:
```bash
dotnet run --target YOUR_FUNCTION_CLASSNAME --port 8080
```
Using environment variables:
```bash
FUNCTION_TARGET=YOUR_FUNCTION_CLASSNAME PORT=8080 dotnet run
```
### Ruby
Using command line arguments:
```bash
bundle exec functions-framework-ruby --target YOUR_FUNCTION_NAME
```
Using environment variables:
```bash
FUNCTION_TARGET=YOUR_FUNCTION_NAME bundle exec functions-framework-ruby
```
Replace YOUR_FUNCTION_NAME with your function's method name.
### PHP
```bash
export FUNCTION_TARGET=YOUR_FUNCTION_NAME
php -S localhost:8080 vendor/bin/router.php
```
Replace YOUR_FUNCTION_NAME with your function's name.
## Call your locally running function
The exercises in this section assume that you've
set up a locally running function on
`localhost` using [Functions Framework](https://docs.cloud.google.com/run/docs/write-functions).
> [!NOTE]
> **Note:** While some operating systems include `curl` by default, others (such as Windows) don't. See [instructions](https://curl.haxx.se/download.html) on how to install `curl` on your machine. Alternatively, you can also use other HTTP testing tools such as [Postman](https://postman.com/downloads) to test your functions.
You can trigger locally-running functions by sending them HTTP requests routed
using a local serving process.
### HTTP functions
When you test your HTTP function from your development environment, it normally
listens for requests on `localhost:8080`. This interface is only accessible from
the machine or VM your function is running on; requests sent from any other
system can't reach it. For this reason, you must issue the HTTP request from the
same system that your function is running on. In the following examples, if your
function is listening on a port other than *8080* , replace the *8080* in the
example with the port number for your function.
#### Testing HTTP functions with Cloud Shell
If you're using Cloud Shell to build and test your function, start your
function locally in the Cloud Shell terminal window, then issue the HTTP
trigger request from a browser or `curl` instance as follows:
### Browser
Click the  icon
on your Cloud Shell toolbar and choose *port 8080* or *Change port* to
pick a different port. This opens a browser window on the correct system and
issues a GET request to the indicated port.
### Curl
To control the format of your HTTP request or to see the unformatted reply,
use `curl`:
1. Click the **+** icon on the Cloud Shell menu bar to open a new terminal window on the same system your function is running on.
2. From within that window, run the `curl` command to trigger your function.
For example:
curl localhost:8080
#### Testing HTTP functions on your desktop server
If you're building and running your function on your local desktop system, first
start your function locally, then issue your HTTP trigger request from a browser
or `curl` instance as follows:
### Browser
Open a new browser window or tab and type `http://localhost:8080` into the
browser address bar. This opens a browser window to `localhost:8080` on your
desktop server to trigger your function.
### Curl
Open a new terminal window on your local desktop, then run the `curl` command
in that window to trigger your function. For example:
curl localhost:8080
This runs the specified `curl` command to trigger your function and displays
the unformatted response.
### Event-driven functions
You can send sample events to
[event-driven functions](https://docs.cloud.google.com/run/docs/write-functions#write-event-driven-functions)
using `curl`. The following `curl` requests show how to send sample
[Pub/Sub](https://docs.cloud.google.com/run/docs/triggering/pubsub-triggers) and
[Cloud Storage](https://docs.cloud.google.com/run/docs/triggering/storage-triggers) events to an
event-driven function running at `localhost:8080`.
### Pub/Sub
```bash
curl localhost:8080 \
-X POST \
-H "Content-Type: application/json" \
-H "ce-id: 123451234512345" \
-H "ce-specversion: 1.0" \
-H "ce-time: 2020-01-02T12:34:56.789Z" \
-H "ce-type: google.cloud.pubsub.topic.v1.messagePublished" \
-H "ce-source: //pubsub.googleapis.com/projects/MY-PROJECT/topics/MY-TOPIC" \
-d '{
"message": {
"data": "d29ybGQ=",
"attributes": {
"attr1":"attr1-value"
}
},
"subscription": "projects/MY-PROJECT/subscriptions/MY-SUB"
}'
```
**Note:** `data` values from [Pub/Sub events](https://docs.cloud.google.com/run/docs/triggering/pubsub-triggers) have `base64`-encoded `data` values. Functions that need access to the original Pub/Sub message's `data` value are expected to perform this decoding. In this example, `base64`-encoding the word `world` gives us `d29ybGQ=`.
### Cloud Storage
```bash
curl localhost:8080 \
-X POST \
-H "Content-Type: application/json" \
-H "ce-id: 123451234512345" \
-H "ce-specversion: 1.0" \
-H "ce-time: 2020-01-02T12:34:56.789Z" \
-H "ce-type: google.cloud.storage.object.v1.finalized" \
-H "ce-source: //storage.googleapis.com/projects/_/buckets/MY-BUCKET-NAME" \
-H "ce-subject: objects/MY_FILE.txt" \
-d '{
"bucket": "MY_BUCKET",
"contentType": "text/plain",
"kind": "storage#object",
"md5Hash": "...",
"metageneration": "1",
"name": "MY_FILE.txt",
"size": "352",
"storageClass": "MULTI_REGIONAL",
"timeCreated": "2020-04-23T07:38:57.230Z",
"timeStorageClassUpdated": "2020-04-23T07:38:57.230Z",
"updated": "2020-04-23T07:38:57.230Z"
}'
```
**Note:** The bottom section of the previous example contains the most commonly used attributes of a Cloud Storage Object event. See the [Cloud Storage Object reference](https://docs.cloud.google.com/storage/docs/json_api/v1/objects#resource) for a complete list of Cloud Storage object properties.
## What's next
- Learn how to [deploy Cloud Run functions](https://docs.cloud.google.com/run/docs/deploy-functions).