The Go Runtime

The Go runtime is the software stack responsible for installing your application code and dependencies, and then running that application in the flexible environment.

  • Version 1.18 and later are built using buildpacks, which requires you to choose an operating system in your app.yaml file. For example, to use Go 1.22 (preview), you must specify Ubuntu 22 as the operating system.

  • Version 1.15 and earlier are built using Docker.

For the full list of supported Go versions, and their corresponding Ubuntu version, see the Runtime support schedule.

Choose a Go version

New runtime versions

For Go runtime version 1.18 and later, you must include the runtime_config and operating_system settings in your app.yaml to specify an operating system.

To use the new runtimes, you must install gcloud CLI version 420.0.0 or later. You can update your CLI tooling by running the gcloud components update command. To view your installed version, you can run the gcloud version command.

Go recommends that you use a go.mod file for managing dependencies. To install dependencies during deployment, include a go.mod file in the same folder as the app.yaml file.

For example, the folder structure of your app with go.mod must represent:

  <application-root>/
  --> app.yaml
  --> go.mod
  --> Other source files used in your application.

Optionally, you can specify a runtime version by including the runtime_version setting in your app.yaml. By default, the latest Go version is used if the runtime_version setting is not specified.

Examples

  • To specify Go 1.22 (preview) on Ubuntu 22:

    runtime: go
    env: flex
    
    runtime_config:
        operating_system: "ubuntu22"
        runtime_version: "1.22"
    
  • To specify the latest supported Go version on Ubuntu 22:

      runtime: go
      env: flex
    
      runtime_config:
          operating_system: "ubuntu22"
    

Your app uses the latest stable release of the version that is specified in your app.yaml file. App Engine automatically updates to new patch revisions, but will not automatically update the major version.

For example, your application might be deployed at Go 1.18.10 and later automatically updated to Go 1.18.11, but it will not be automatically updated to the major version Go 1.19.

Choosing Go 1.22 (preview) as shown below in your app.yaml file results in the latest patch version of Go 1.22 (preview) available.

  runtime: go
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      runtime_version: "1.22"

See the app.yaml reference for more information.

Previous runtime versions

For Go version 1.15 and earlier, you specify a version using the go1.x format in app.yaml config file as runtime: go1.x:

Example

  runtime: go1.14
  env: flex

If no version is specified, the default version of go1.11 will be automatically selected.

Your app uses the latest stable release of the version that is specified in your app.yaml file. App Engine automatically updates to new patch revisions, but will not automatically update the major version.

For example, your application might be deployed at Go 1.14.10 and later automatically updated to Go 1.14.11, but it will not be automatically updated to the major version Go 1.15.

Choosing the go runtime version go1.15 as shown below in app.yaml results in the latest version of 1.15 available, for example, 1.15.15.

  runtime: go1.15
  env: flex

Importing packages

Your code is compiled when you deploy your app to App Engine. When you run the deployment command, your app's dependencies are first collected from your local GOPATH and then they are all sent to the build server. Any missing dependencies, for example third-party libraries, results in build failures.

To avoid build failures and ensure that all your app's dependencies get deployed with your code, you should test your app locally before deploying it.

Extending the runtime

For instructions on how to extend and customize the Go runtime, read the Go runtime builder on GitHub.

Metadata server

Each instance of your application can use the Compute Engine metadata server to query information about the instance, including its host name, external IP address, instance ID, custom metadata, and service account information. App Engine does not allow you to set custom metadata for each instance, but you can set project-wide custom metadata and read it from your App Engine and Compute Engine instances.

Use the cloud.google.com/go/compute/metadata package to access the metadata server.