Go Runtime Environment

With App Engine, you can build web applications using the Go Programming Language. Your Go application runs on Google's scalable infrastructure and uses large-scale persistent storage and services.

With App Engine, you can build web applications that use Google's scalable infrastructure and services.

Introduction

App Engine builds and executes Go application code using a secure sandboxed environment. Your app receives web requests, performs work, and sends responses by interacting with this environment.

The App Engine SDK for Go provides an interface similar to the standard Go http package; writing Go App Engine apps is akin to writing stand-alone Go web servers.

The Go runtime environment uses Go version 1.6. The App Engine SDK includes the Go compiler and standard library, so it has no additional dependencies. As with the other runtimes, not all the standard library's functionality is available inside the sandbox. For example, attempts to open a socket or write to a file will return an os.ErrPermission error.

The App Engine SDK includes an automated build service to compile your app, so you'll never need to invoke the compiler yourself. And—as with the Python SDK—your app will be automatically re-built whenever you change the source.

The Go runtime environment for App Engine provides full support for goroutines, but not for parallel execution: goroutines are scheduled onto a single operating system thread. This single-thread restriction may be lifted in future versions. Multiple requests may be handled concurrently by a given instance; that means that if one request is, say, waiting for a Cloud Datastore API call, another request may be processed by the same instance.

Go apps run inside a secure sandbox environment with a reduced set of libraries. For instance, an app cannot write data to the local file system or make arbitrary network connections. Instead, apps use scalable services provided by App Engine to store data and communicate over the Internet.

The App Engine platform provides many services that your code can call.

The Go Getting Started Guide provides an introduction to developing web applications with Go and Google App Engine.

Selecting the Go runtime

You specify the Go runtime environment in the app.yaml configuration file, which is used to deploy your application to App Engine. For example:

runtime: go
api_version: go1

The first element, runtime, selects the Go runtime environment.

The second element, api_version, selects which version of the Go runtime environment to use. As of this writing, the most recent version of the Go environment is go1 which is an alias of the latest release of Go (currently go1.6). The version identifier will be incremented when the App Engine team releases changes to the environment that might not be compatible with existing code. This means you can continue to use the older APIs until you are able to update your app and change the api_version setting. The available api_version values are go1, go1.6, and go1.8.

Organizing Go apps

When developing an App Engine app in Go, your code is partitioned into one or more services; each service is usually contained in its own directory, along with an app.yaml file for the service:

- project-dir
   - service1-dir
      app.yaml
      src1-1.go
      src1-2.go
   - service2-dir
      app.yaml
      src2-1.go
      src2-2.go

Go applications are organized into packages that mirror the directory structure of your source files. When you use an import statement in App Engine source code, the SDK tools interpret the relative paths in the import two ways:

  • Relative to the directory that contains the service's app.yaml file

  • Relative to the src subdirectory of all the directories in GOPATH (this is called a "fully-qualifed" import path)

For example, if GOPATH is defined this way:

export GOPATH=/home/fred/go

And the file src1-1.go in the project directory example above contains this statement:

import "foo/bar"

The App Engine SDK will look for the package "foo/bar" in these locations when you run or deploy service1:

project-dir/service1/foo/bar
/home/fred/go/src/foo/bar

If you include your package sources in GOPATH, you must be careful not to place the source code at or below any directories in your App Engine project that contain app.yaml files. If that happens, a package could be loaded twice, once for the path relative to a service's directory, and once for the fully-qualified path. This can cause subtle problems, so the App Engine SDK scans your project and your GOPATH, detects this case, and reports it as an error.

For best results, we recommend:

  • Create a separate directory in your project for each service.
  • Each service directory should contain the service's app.yaml file and one or more .go files.
  • Do not include any subdirectories in a service's directory.
  • Your .go files should import packages using fully-qualified paths; place all package code beneath src directories that are direct children of the project directory, or not under your project directory at all.

For more information about the structuring of services, see the App Engine Overview.

For an introduction to Go's GOPATH and how it relates to App Engine development, please see The App Engine SDK and workspaces.

The sandbox

To allow App Engine to distribute requests for applications across multiple web servers, and to prevent one application from interfering with another, the application runs in a restricted "sandbox" environment. In this environment, the application can execute code, store and query the data in Cloud Datastore, use the App Engine mail, URL fetch and users services, and examine the user's web request and prepare the response.

An App Engine application cannot:

  • write to the filesystem. Applications must use Cloud Datastore for storing persistent data. Reading from the filesystem is allowed, and all application files uploaded with the application are available.

  • respond slowly. A web request to an application must be handled within a few seconds. Processes that take a very long time to respond are terminated to avoid overloading the web server.

  • make other kinds of system calls.

The Go runtime restricts the use of standard library packages that would violate the sandbox policies. Such functions have been replaced by stubs that return an os.ErrPermission error or removed entirely.

Background requests

Code running on manual or basic scaling instances can start a request that can outlive the request that spawns it. This allows instances to perform arbitrary periodic or scheduled tasks or to continue working in the background after a request has returned to the user.

Use runtime.RunInBackground to execute code in a background goroutine:

err := runtime.RunInBackground(c, func(c appengine.Context) {
  // do something...
})

The provided function will be invoked with a background context that is distinct from (and may outlast) the provided context. Note that there is a limit of 10 simultaneous background requests per instance.

Tools

The SDK for App Engine includes tools for testing your application and uploading application files.

The development server runs your application on your local computer for testing your application. The server simulates the Cloud Datastore services and sandbox restrictions. The development server can also generate configuration for Cloud Datastore indexes based on the queries the app performs during testing.

The gcloud tool handles all command-line interaction with your application running on App Engine. You use gcloud app deploy to upload your application to App Engine, or to update individual configuration files like the Cloud Datastore index configuration, which allows you to build new indexes before deploying your code. You can also view your app's log data, so you can analyze your app's performance using your own tools.

Concurrency and latency

Your application's latency has the biggest impact on the number of instances needed to serve your traffic. If you process requests quickly, a single instance can handle a lot of requests.

There is a direct relationship between the latency and number of requests that can be handled on the instance per second. For example, 10ms latency equals 100 request/second/instance.

A Go runtime instance can handle multiple requests concurrently, though only one running goroutine will get CPU time at a time. Other goroutines can perform I/O (read a file, make a system or API call) while that happens.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

App Engine standard environment for Go