Run functions using the Functions Emulator

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.

Installation prerequisites

Before proceeding, make sure you have the following installed:

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 \
    --no-gen2 \
    --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 \
    --no-gen2 \
    --runtime=go121

Java 

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

Ruby 

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

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.

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