A custom runtime allows you to easily deploy and run web applications written in any language. The App Engine flexible environment provides the scaling, monitoring, and load balancing infrastructure, so you can focus on building your application.
To create a custom runtime you need:
- An app.yaml file that describes your application's runtime configuration.
- A Dockerfile that configures the runtime environment. In many cases, this can be just one line specifying a base image.
- To ensure your application is listening on port 8080 and has request handlers that respond to lifecycle events, such as start, stop, and health check requests.
Create an app.yaml file
You must use an
app.yaml configuration file with the following settings:
runtime: custom env: flex
You might also want to use other app.yaml settings that apply to all App Engine runtimes.
Create a Dockerfile
The Dockerfile is always named
Dockerfile and should be placed in the same directory with the corresponding
Comprehensive documentation is available on the Docker website.
You need to do this whether you use your own base image or one of Google's base images.
For simplicity, this page shows an example using a Google-supplied base image.
Configuring the Dockerfile
The first command in a Dockerfile is usually a
FROM command specifying a base image.
FROM command for each of the Google-supplied base images is shown in the
following table, along with the github project used to build the image:
|Java (Open JDK 8 only)
|Java (Open JDK 8 + Jetty9.3)
|Python 2.7 & 3.4
(*) To access the App Engine service APIs from a Go app running the
golang base image you must
import the App Engine Go libraries into your source code.
For more information on configuring a custom runtime for Java 8, see Java 8 Custom Runtime
Developing code for custom runtimes
This section describes behavior that your code must implement whether you use a Google-supplied base image or your own base image.
Listen to port 8080
The App Engine front end will route incoming requests to the appropriate module on port 8080. You must be sure that your application code is listening on 8080.
All applications running in the flexible environment receive start, stop, and health check requests. If you run an app in a custom runtime, you might have the option of ignoring these requests or writing your own handlers for them.
Start and Stop requests
start lifecycle event is sent to your application as soon as your
container is built or provisioned. It is signaled as a HTTP request to the
/_ah/start. No response is required to this handler, however your
application might use it as a signal that App Engine expects your container to
be ready to respond to incoming traffic.
stop lifecycle event is sent to your application when App Engine is preparing to
turn down the container. It is signaled as a HTTP request to the handler
The application does not need to respond to this event - but can use it to perform any
necessary clean up actions prior to the container being shut down.
Health check requests
By default, an application running in the flexible environment is periodically sent health check requests.
If you create a custom runtime your app must handle health check requests or disable them, otherwise, the app won't come up properly.
A health check is an HTTP request to the URL
/_ah/health. A healthy
application should respond with status code 200.
At its simplest, an application can check that its serving stack is up and running; it might also perform more sophisticated checks, such as ensuring any background processes are running.
To disable health checking, add this line to your app's configuration file:
Using Google Cloud Platform services
Applications running in the flexible environment can access the Google API Client Libraries or any third party services via standard APIs.
With custom runtimes, client libraries can use the Application Default Credentials to authenticate with and call Google APIs.
Alternatively, you can authenticate your application directly with access tokens using the Compute Engine Metadata API. You can then use these access tokens in API requests, such as requests against Google Cloud Storage and Google Cloud Datastore services and resources.
When a request is sent to your application running in App Engine, request and response details are logged automatically, and can be viewed in the Google Cloud Platform Console Logs Viewer.
When your application handles a request, it can also
write its own logging messages to
stderr. These files are
automatically collected and can be viewed in the Logs Viewer. Only the most
recent entries to
stderr are retained, in order
to limit their size.
The request and application logs for your app are collected by a Cloud Logging agent and are kept for a maximum of 90 days, up to a maximum size of 1GB. If you want to store your logs for a longer period or store a larger size than 1GB, you can export your logs to Cloud Storage. You can also export your logs to BigQuery and Pub/Sub for further processing.
Other logs are also available for your use. The following are some of the logs that are configured by default:
|Log name||Payload type||Purpose|
||text||Information logged when setup fails. If your application fails to run, check this log.|
||text||Information from the Google Docker container publishing data to Cloud Monitoring.|
||text||Information logged on shutdown.|
||text||Standard output from your app.|
||text||Standard error from your container.|
||text||The VM syslog, outside of the Docker container.|