The Go Runtime
Cloud Functions supports the following Go runtimes:
- Go 1.19 (recommended)
- Go 1.18
- Go 1.16
- Go 1.13
- 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 Google Cloud CLI, you can specify the runtime
by using the --runtime
parameter with the Go runtime of your choice.
For example:
gcloud functions deploy FUNCTION_NAME --runtime go119 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 Google Cloud console, you can select the runtime when you create and deploy a function. See the Google 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, Go 1.13, and Go 1.16 runtimes use an execution environment based on Ubuntu 18.04. The The Go 1.18 and Go 1.19 runtimes use an execution environment based on Ubuntu 22.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.
Environment variables
The Go 1.13+ runtimes automatically set fewer environment variables than previous runtimes supported by Cloud Functions. For details, see Using Environment Variables.
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 thefunc 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:
Go 1.16
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 withoutgo.mod
will work as before for versions older than 1.16. Cloud Functions will add the Functions Framework if it is not invendor
. - Functions with
vendor
andgo.mod
are supported for Go 1.14+, but they must have the Functions Framework ingo.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.