Create and deploy an HTTP Cloud Run function with Go

Note: This content applies only to Cloud Run functions—formerly Cloud Functions (2nd gen).

For the 1st gen version of this document, see Create and deploy an HTTP Cloud Run function with Go (1st gen).

Introduction

This guide takes you through the process of writing a Cloud Run function using the Go runtime. There are two types of Cloud Run functions:

• An HTTP function, which you invoke from standard HTTP requests.
• An event-driven function, which is triggered by events in your Cloud infrastructure, such as messages on a Pub/Sub topic or changes in a Cloud Storage bucket.

For more detail, read writing HTTP functions and writing event-driven functions.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Functions, Cloud Build, Artifact Registry, Cloud Run, and Cloud Logging APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Cloud Functions, Cloud Build, Artifact Registry, Cloud Run, and Cloud Logging APIs.

   Enable the APIs

8. Install and initialize the gcloud CLI.
Note: Need a command prompt? You can use the Google Cloud Shell. The Google Cloud Shell is a command line environment that already includes the Google Cloud CLI, so you don't need to install it. The Google Cloud CLI also comes preinstalled on Google Compute Engine Virtual Machines.
9. Update and install gcloud components with the following command.

   gcloud components update

10. Prepare your development environment.

    Go to the Go setup guide

Create your function

1. Create a directory on your local system for the function code:

   Linux or Mac OS X

   mkdir ~/helloworld
   cd ~/helloworld
   

   Windows

   mkdir %HOMEPATH%\helloworld
   cd %HOMEPATH%\helloworld
   

2. Create a file called hello_http.go in the helloworld directory with the following contents.

   
   // Package helloworld provides a set of Cloud Functions samples.
   package helloworld
   
   import (
   	"encoding/json"
   	"fmt"
   	"html"
   	"net/http"
   
   	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
   )
   
   func init() {
   	functions.HTTP("HelloHTTP", HelloHTTP)
   }
   
   // HelloHTTP is an HTTP Cloud Function with a request parameter.
   func HelloHTTP(w http.ResponseWriter, r *http.Request) {
   	var d struct {
   		Name string `json:"name"`
   	}
   	if err := json.NewDecoder(r.Body).Decode(&d); err != nil {
   		fmt.Fprint(w, "Hello, World!")
   		return
   	}
   	if d.Name == "" {
   		fmt.Fprint(w, "Hello, World!")
   		return
   	}
   	fmt.Fprintf(w, "Hello, %s!", html.EscapeString(d.Name))
   }
   

   This example function takes a name supplied in the HTTP request and returns a greeting, or "Hello, World!" when no name is supplied.

Specify dependencies

Create a go.mod file to track your dependencies:

cd ~/helloworld
go mod init example.com/hello
go mod tidy

If your function has dependencies beyond the Functions Framework library, edit the go.mod file to add them. You can also specify dependencies with a Go vendor directory. For more details, read Specifying dependencies in Go.

Build and test your function locally

You can choose to build and test your function locally without deploying it. To do this, you must create a local main.go module to invoke your function.

1. Create a cmd subdirectory:

   mkdir ~/helloworld/cmd
   cd ~/helloworld/cmd
   

2. Create a main go module to invoke your function by copying the following code snippet into a file called main.go in the ~/helloworld/cmd directory:

   package main
   
   import (
     "log"
     "os"
   
     // Blank-import the function package so the init() runs
     _ "example.com/hello"
     "github.com/GoogleCloudPlatform/functions-framework-go/funcframework"
   )
   
   func main() {
     // Use PORT environment variable, or default to 8080.
     port := "8080"
     if envPort := os.Getenv("PORT"); envPort != "" {
       port = envPort
     }
     if err := funcframework.Start(port); err != nil {
       log.Fatalf("funcframework.Start: %v\n", err)
     }
   }
   

3. Resolve your remaining dependencies with the go mod tidy command:

   go mod tidy
   

4. Run your function locally with the following command:

   export FUNCTION_TARGET=HelloHTTP
   go run ~/helloworld/cmd/main.go
   

5. Test your function by visiting http://localhost:8080 in a browser or by running curl localhost:8080 from another window.

   See Sending requests to local functions for more detail.

Deploy your function

To deploy your function, run the following command in the helloworld directory:

  gcloud functions deploy go-http-function \
    --gen2 \
    --runtime=go121 \
    --region=REGION \
    --source=. \
    --entry-point=HelloHTTP \
    --trigger-http \
    --allow-unauthenticated

Replace REGION with the name of the Google Cloud region where you want to deploy your function (for example, us-west1).

The optional --allow-unauthenticated flag lets you reach your function without authentication.

Learn more: For more details, read about deploying Cloud Run functions.

Test your deployed function

1. After the function deploys, note the uri property from the output of the gcloud functions deploy command, or retrieve it with the following command:

     gcloud functions describe go-http-function \
       --region=REGION
   

   Replace REGION with the name of the Google Cloud region where you deployed your function (for example, us-west1).

2. Visit this URL in your browser. The function returns a "Hello World!" message.

   You can also find this URL in Google Cloud console. Go to the Cloud Run functions Overview page, and click the name of your function to open its Function details page. Open the TRIGGER tab to see your function's URL.

View your function's logs

View the logs with the command-line tool

You can review your function's logs with the Cloud Logging UI or via the Google Cloud CLI.

To view logs for your function with the gcloud CLI, use the logs read command:

    gcloud functions logs read \
      --gen2 \
      --limit=10 \
      --region=REGION \
      go-http-function

Replace REGION with the name of the Google Cloud region where you deployed your function (for example, us-west1).

The output resembles the following:

LEVEL: I
NAME: hellohttp
TIME_UTC: 2023-05-31 21:52:20.473
LOG:

LEVEL: I
NAME: hellohttp
TIME_UTC: 2023-05-31 21:52:20.370
LOG:

LEVEL: I
NAME: hellohttp
TIME_UTC: 2023-05-31 21:52:20.280
LOG: Default STARTUP TCP probe succeeded after 1 attempt for container "h-hello_h_t_t_p-1" on port 8080.

LEVEL: I
NAME: hellohttp
TIME_UTC: 2023-05-31 21:52:20.108
LOG:

Note: There might be a slight delay before log entries show up in Cloud Logging.

View logs with the logging dashboard

To view the logs for your function with the logging dashboard, open the Cloud Run functions Overview page and click the name of your function from the list, then click the Logs tab.

Learn more: For more details, read about writing, viewing, and responding to logs.