Run functions using the Functions Emulator

Note: This content applies only to Cloud Run functions—formerly Cloud Functions (2nd gen). See Run functions with Functions Framework for the Cloud Run functions—formerly Cloud Functions (1st gen) version of this document.

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

The Google Cloud CLI Functions Emulator enables you to you manage local instances of your Cloud Run functions through the gcloud alpha functions local command. This lets you deploy and test your functions on your local system before deploying them to the Google Cloud environment.

The Functions Emulator uses Google Cloud's buildpacks to package your function code into locally-runnable container images. You then run these images locally with Docker.

Note: The gcloud alpha functions local command is available as an alpha pre-release, and might be unstable or change without notice. If you prefer to run your functions locally without containerization, use the Functions Framework.

Installation prerequisites

Before proceeding, make sure you have the following installed:

• Google Cloud CLI
• Buildpacks pack tool
• Docker

Deploy your function locally

To deploy your function locally with the Functions Emulator, use the gcloud functions command:

Node.js

  gcloud alpha functions local deploy LOCAL_DEPLOYMENT_NAME \
    --entry-point=ENTRY_POINT \
    --runtime=nodejs20

Python

  gcloud alpha functions local deploy LOCAL_DEPLOYMENT_NAME \
    --entry-point=ENTRY_POINT \
    --runtime=python312

Go

  gcloud alpha functions local deploy LOCAL_DEPLOYMENT_NAME \
    --entry-point=ENTRY_POINT \
    --runtime=go121

Java

  gcloud alpha functions local deploy LOCAL_DEPLOYMENT_NAME \
    --entry-point=ENTRY_POINT \
    --runtime=java17

Note: Java functions use [PACKAGE_NAME].[CLASS_NAME] as an entry-point value.

C#

  gcloud alpha functions local deploy LOCAL_DEPLOYMENT_NAME \
    --entry-point=ENTRY_POINT \
    --runtime=dotnet6

Note: .NET functions use their class name as an entry-point value.

Ruby

  gcloud alpha functions local deploy LOCAL_DEPLOYMENT_NAME \
    --entry-point=ENTRY_POINT \
    --runtime=ruby32

PHP

  gcloud alpha functions local deploy LOCAL_DEPLOYMENT_NAME \
    --entry-point=ENTRY_POINT \
    --runtime=php82

Replace:

• LOCAL_DEPLOYMENT_NAME: The name under which you are locally deploying your function.
• ENTRY_POINT: The entry point of your function.

You can further configure your deployment command with the following optional flags:

Flag	Description
--port	The port on which to listen for requests (default: 8080).
--builder	The name of the buildpack builder to use.

The --builder value defaults to the App Engine builder for your function's language. For example, it defaults to gcr.io/serverless-runtimes/google-22-full/builder/python for Python.

When you first use the gcloud alpha command, the gcloud command will prompt you to install the gcloud alpha command set.

Call your local function

To call your local function without data, use the following command:

gcloud alpha functions local call LOCAL_DEPLOYMENT_NAME

Replace LOCAL_DEPLOYMENT_NAME with the name you want to locally deploy your function under.

Note: gcloud alpha functions local call calls your function with an HTTP POST request. To use a different HTTP method, use a dedicated HTTP request tool such as curl. See calling local functions for instructions on how to interact with your locally-running function using curl.

To include data in the call to your local function, choose the tab that matches your function type:

HTTP function

Call your local HTTP function as follows:

gcloud alpha functions local call LOCAL_DEPLOYMENT_NAME \
    --data='{"message": "MESSAGE"}'

Replace:

• LOCAL_DEPLOYMENT_NAME: The name to locally deploy your function under.
• ENTRY_POINT: The entry point of your function.
• MESSAGE: A text string to pass in as the body of the HTTP request.

CloudEvent function

To call your local CloudEvent function, you must supply a CloudEvent JSON object describing the trigger event:

gcloud alpha functions local call LOCAL_DEPLOYMENT_NAME \
    --cloud-event="CLOUD_EVENT_JSON"

Replace:

• LOCAL_DEPLOYMENT_NAME: The name to locally deploy your function under.
• ENTRY_POINT: The entry point of your function.
• CLOUD_EVENT_JSON: A JSON-encoded string in structured content mode describing the triggering event. For more details and examples, see CloudEvents - JSON event format.

Here is an example command line:

gcloud alpha functions local call my-function --cloud-event='{
 "specversion" : "1.0",
  "type" : "com.github.pull.create",
  "source" : "https://github.com/cloudevents/spec/pull",
  "subject" : "123",
  "id" : "ce",
  "time" : "2021-01-27T18:30:00Z", "data" : "{\n \"subscription\": \"projects\/test-project\/subscriptions\/my-subscription\",\n \"message\": {\n \"attributes\": {\n \"attr1\":\"attr1-value\"\n },\n \"data\": \"d29ybGQ=\",\n \"messageId\": \"message-id\",\n \"publishTime\":\"2021-02-05T04:06:14.109Z\",\n \"orderingKey\": \"ordering-key\"\n }\n}"
  }'

See CloudEvent specs for more information about how the JSON format is defined for CloudEvents.

Delete your local function deployment

Delete your local function deployment with the following command:

gcloud alpha functions local delete LOCAL_DEPLOYMENT_NAME

Replace LOCAL_DEPLOYMENT_NAME with the name to locally deploy your function under.

This command undeploys your function but doesn't delete the function code.

Next steps

• Learn how to Deploy a Cloud Run function on Google Cloud.