The Go Runtime

Cloud Functions supports the following Go runtimes:

  • Go 1.16 (preview)
  • Go 1.13 (recommended)
  • Go 1.11

For instructions on how to prepare your local machine for Go development, see Setting Up a Go Development Environment.

To get started with Go on Cloud Functions, see the Quickstart.

Selecting the runtime

You can select the Go runtime for your function during deployment.

gcloud

If you are using the gcloud command-line tool, you can specify the runtime by using the --runtime parameter with the Go runtime of your choice (supported values are go111, go113, and go116). For example:

gcloud functions deploy FUNCTION_NAME --runtime go113 FLAGS...

FLAGS... refers to arguments passed during the first deployment of your function. For more information regarding required and optional arguments, see Deploy using the gcloud tool.

Console

If you are using the Cloud Console, you can select the runtime when you create and deploy a function. See the Cloud Console quickstart for detailed instructions.

Execution environment

The execution environment includes the runtime, the operating system, packages, and a library that invokes your function.

The Go 1.11.6, Go 1.13.15, and Go 1.16.7 runtimes use an execution environment based on Ubuntu 18.04. See Cloud Functions Execution Environment for more information.

Source code structure

In order for Cloud Functions to find your function's definition, each runtime has certain structuring requirements for your source code. See Writing Cloud Functions for more information.

Specifying dependencies

Cloud Functions in Go must provide all of their dependencies via either Go modules with a go.mod file, or a vendor directory. For more information, see Specifying dependencies in Go.

One-time initialization

Your functions might need to do one-time initialization, like creating API clients and configuring database access. There are multiple ways to do this:

  • Use a func init() function to initialize values when a new instance of your function starts up. Note that code in the func init() function runs before your function receives its first request.

  • Use the sync.Once.Do() function to run code once per Cloud Functions instance. This is useful in cases where you only want to initialize on-demand rather than when your function instance first starts up. You might, for example, only need to initialize a database client under certain circumstances.

context.Context

Go's context package defines the Context type, which carries deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes.

API clients that outlive a given function invocation should be initialized with a global context.Context value, such as one created by the context.Background() function. To optimize performance, you might initialize a client in global scope. This client, and its context, might persist throughout the lifetime of a given function instance.

You should only use the function invocation context for objects or operations that fall within the lifetime of a specific function invocation. The invocation context might be canceled at any point after your function finishes executing, meaning any clients initialized using this context might be closed. The function invocation context is accessible through the function's arguments: usually r.Context() for HTTP functions, and ctx for background functions.

See the following code for an example using a Pub/Sub client:

functions/tips/contexttip/context_tip.go 

// Package contexttip is an example of how to use Pub/Sub and context.Context in
// a Cloud Function.
package contexttip

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"

	"cloud.google.com/go/pubsub"
)

// GOOGLE_CLOUD_PROJECT is a user-set environment variable.
var projectID = os.Getenv("GOOGLE_CLOUD_PROJECT")

// client is a global Pub/Sub client, initialized once per instance.
var client *pubsub.Client

func init() {
	// err is pre-declared to avoid shadowing client.
	var err error

	// client is initialized with context.Background() because it should
	// persist between function invocations.
	client, err = pubsub.NewClient(context.Background(), projectID)
	if err != nil {
		log.Fatalf("pubsub.NewClient: %v", err)
	}
}

type publishRequest struct {
	Topic   string `json:"topic"`
	Message string `json:"message"`
}

// PublishMessage publishes a message to Pub/Sub. PublishMessage only works
// with topics that already exist.
func PublishMessage(w http.ResponseWriter, r *http.Request) {
	// Parse the request body to get the topic name and message.
	p := publishRequest{}

	if err := json.NewDecoder(r.Body).Decode(&p); err != nil {
		log.Printf("json.NewDecoder: %v", err)
		http.Error(w, "Error parsing request", http.StatusBadRequest)
		return
	}

	if p.Topic == "" || p.Message == "" {
		s := "missing 'topic' or 'message' parameter"
		log.Println(s)
		http.Error(w, s, http.StatusBadRequest)
		return
	}

	m := &pubsub.Message{
		Data: []byte(p.Message),
	}
	// Publish and Get use r.Context() because they are only needed for this
	// function invocation. If this were a background function, they would use
	// the ctx passed as an argument.
	id, err := client.Topic(p.Topic).Publish(r.Context(), m).Get(r.Context())
	if err != nil {
		log.Printf("topic(%s).Publish.Get: %v", p.Topic, err)
		http.Error(w, "Error publishing message", http.StatusInternalServerError)
		return
	}
	fmt.Fprintf(w, "Message published: %v", id)
}

Go 1.16 (Public preview)

Go 1.16 introduces changes to dependency management. Most notably, it now operates in "module-aware" mode by default, which means that the source code is expected to include a go.mod file. The full release notes are available at golang.org.

To support existing deployments in versions older than 1.16 and ease the migration path:

  • Functions without go.mod will continue to be supported.
  • Functions with vendor and without go.mod will work as before for versions older than 1.16. Cloud Functions will add the Functions Framework if it is not in vendor.
  • Functions with vendor and go.mod are supported for Go 1.14+, but they must have the Functions Framework in go.mod/vendor. If they don't, the build will fail with the following error:
vendored dependencies must include "github.com/GoogleCloudPlatform/functions-framework-go";
if your function does not depend on the module, please add a blank import:
`_ "github.com/GoogleCloudPlatform/functions-framework-go"`

Learn more about how to use the vendor directory for your particular Go version.