Deploy your app to upload and run it on App Engine. When you deploy your apps, you create versions of those apps and their corresponding services in App Engine. You can deploy entire apps, including all the source code and configuration files, or you can deploy and update individual versions or configuration files.
To programmatically deploy your apps, use the Admin API.
Before you begin
Before you can deploy your app:
Ensure that your user account includes the required privileges.
Give Cloud Build permission to deploy apps in your project. When you deploy your app, App Engine uses Cloud Build to build the app into a container and deploy the container to the runtime in the app's region. Cloud Build does not have permission to deploy Python 2 apps by default, so you need to give permission before you can deploy apps.
Installing the gcloud CLI
To deploy your app with the gcloud CLI, you must download, install, and initialize the gcloud CLI.
If you already have the gcloud CLI installed and want to configure it to use a Cloud project ID other than the one that you initialized it to, see Managing gcloud CLI Configurations.
Using a proxy
If you are running the deployment command from a system which uses an HTTP or HTTPS proxy, you must configure the tool so that it can communicate via the proxy.
Run the following commands to configure the gcloud CLI:
gcloud config set proxy/type [PROXY_TYPE] gcloud config set proxy/address [PROXY_ADDRESS] gcloud config set proxy/port [PROXY_PORT]
You can also set a
password for the proxy. For more
information, see gcloud config.
Deploying an app
To deploy your app to App Engine, use
gcloud app deploy command
from where your configuration
files are located, for
Choosing unique version IDsFor manually-scaled instances, the ID of your version should begin with a letter to distinguish them from numeric instance IDs. This ensures that requests are routed to the correct destination and avoids the ambiguity with URL patterns like
123-dot-my-service.[REGION_ID].r.appspot.com, which can be interpreted two ways:
- If version
123exists, the request is routed to version
- If version
123does not exist, the request is instead routed to instance ID
123where the versions of the
my-serviceservice are running.
You can name your versions however you like for instances that are configured for auto scaling or basic scaling because targeting those instances is not supported.
gcloud app deploy [CONFIGURATION_FILES]
By default, the command deploys the
app.yaml configuration file from the current
directory. If you're running the command from a directory that does not contain
app.yaml, or if you want to deploy multiple apps,
[CONFIGURATION_FILES] with the path to one or more configuration files.
Use a single white space to separate pathnames.
--version: Specifies a custom version ID. By default, App Engine generates a version ID.
--no-promote: Deploys your app without automatically routing all traffic to that version. By default, each version that you deploy is automatically configured to receive 100% of traffic.
--project: Specifies an alternate Cloud project ID to what you initialized as the default in the gcloud CLI.
For more information, see the
gcloud app deploy reference
gcloud help from the command line.
gcloud app deploy gcloud app deploy app.yaml dos.yaml index.yaml gcloud app deploy --version [YOUR_VERSION_ID] --no-promote --project [YOUR_PROJECT_ID]
If you deploy a version that specifies the same version ID as a version that already exists on App Engine, the files that you deploy will overwrite the existing version. This can be problematic if the version is serving traffic because traffic to your application might be disrupted. You can avoid disrupting traffic if you deploy your new version with a different version ID and then move traffic to that version.
Deploying multiple service applications
When your application is factored into multiple services, you can deploy and update individually targeted services or all the services simultaneously. Deploying updates to services can include updating individual configuration files or updating the source code in the corresponding versions.
For example, you can deploy and create two versions in App Engine, where each version runs in their own service. The first version serves as the frontend service and the other as the backend of your app. You can then deploy individual configuration files to update only the settings of a service. You can also choose to deploy a new version to a service in order to update the source code of the frontend, backend, or both simultaneously.
Requirements for multiple services
You use the same deployment commands for deploying and updating the multiple services of your application with the following requirements:
You must initially deploy a version of your app to the
defaultservice before you can create and deploy subsequent services.
You must specify the ID of your service in the
app.yamlconfiguration file of the corresponding version. To specify the service ID, you include the
service: [YOUR_SERVICE_ID]element definition in each configuration file. By default, excluding this element definition from your configuration file deploys the version to the
You must specify all the corresponding
app.yamlconfiguration files in your deployment command to simultaneously deploy multiple services.
To deploy multiple services
From the root directory of the application where the configuration files are
located, you run the deployment command and specify the relative paths and file
names for each service's
gcloud app deploy [CONFIGURATION_FILES]
[CONFIGURATION_FILES] is one or more configuration file's path and name
separated by a single whitespace.
gcloud app deploy main/app.yaml service1/app.yaml service2/app.yaml
You will receive verification via the command line as each service is successfully deployed.
Viewing build logs
Cloud Build streams build and deploy logs that are viewable in the Cloud Build history section of the console. To view builds in the app's region, use the Region drop-down menu at the top of the page to choose the region you would like to filter by.
To create or update the indexes that your apps use, upload the
configuration file to Datastore. Indexes that don't exist yet are
created after that configuration file is uploaded.
It can take a while for Datastore to create all the indexes and therefore, those indexes won't be immediately available to App Engine. If your app is already configured to receive traffic, then exceptions can occur for queries that require an index which is still in the process of being built.
To avoid exceptions, you must allow time for all the indexes to build, for example:
index.yamlconfiguration file to Datastore before you deploy your version:
index.yamlfile to Datastore:
<pre class="prettyprint lang-sh">gcloud datastore indexes create index.yaml</pre> For information, see the <a href="/sdk/gcloud/reference/datastore/"><code>gcloud datastore</code> reference</a>.
Use the console to monitor the status of all your indexes:
After all your indexes are built, deploy the new version to App Engine.
Build your indexes before migrating or splitting traffic to your version:
Deploy the new version without routing traffic to that
You must specify both the
index.yamlfiles and also include the
--no-promoteflag so that no traffic is routed to the version:
gcloud app deploy app.yaml index.yaml --no-promote
- Use the console to monitor the status of all your indexes:
- After all your indexes are built, use the console to migrate or split traffic to your version:
- Deploy the new version without routing traffic to that version: You must specify both the
For more information about indexes, see Configuring Datastore Indexes.
The following are common error messages that you might encounter:
PERMISSION_DENIED: Operation not allowed
The "appengine.applications.create" permission is required.
- If the Cloud project does not include the required
gcloud app deploycommand can fail when it tries to run the
gcloud app createcommand. Only accounts with Owner role have the necessary permissions to create App Engine applications.
Command not found
- If you did not create symlinks for the
dev_appserver.shtools when you installed the (deprecated) App Engine SDK, you might need to specify the full directory path to run the tool, for example:
- If you installed both the gcloud CLI as well as the original App
Engine SDK, the entries to your PATH might conflict with one another and
cause import errors. If you received errors when running gcloud CLI
commands, try explicitly using the original App Engine SDK. You can move the
entry for the original App Engine SDK to earlier in your PATH so that those
commands have priority. Alternatively, you can run the command by specifying
the full directory path:
 The first service (module) you upload to a new application must be the 'default' service (module)
- Before you can deploy and create the multiple services of your application,
you must first deploy and create the
defaultservice. For details about how to deploy a version to the
defaultservice, see Deploying multiple service applications.
Too Many Versions (403)
- App Engine has a limit on the number of deployed versions of your application. These differ for free applications and deployed applications. You can use the console to delete an older version and then upload your latest code.
 An internal error occurred while creating a Cloud Storage bucket.
App Engine creates a default Cloud Storage multi-regional bucket on your behalf, on the same region where your application is created. This bucket is required to store the contents of your application. This error is returned when this bucket cannot be created, in the following scenarios:
Your project is under an organization enforcing the
constraints/gcp.resourceLocationspolicy, and the organization is not allowing the creation of resources on the same region where your App Engine was created. You will need to override the enforced
constraints/gcp.resourceLocationspolicy for your project, and allow the multi-region locations on the same region where your App Engine app is created.
 An internal error occurred
This error can occur if the App Engine's
app.yamlconfiguration file contains an invalid resource
vpc_access_connectorkey. Make sure that the
namefield contains the correct project and region where your Serverless VPC Access connector is created.
If the issue persists after ensuring your
app.yamlconfiguration is valid, use the Google Cloud SDK to re-deploy your service, adding the
--verbosity=debugflag, and contact GCP Support by providing the command's output.
- Other deployment error
If your deployment fails, make sure the Cloud Build API is enabled in your project. App Engine enables this API automatically the first time you deploy an app, but if someone has since disabled the API, deployments will fail.
- Use services to build a large application.
- Split traffic or migrate traffic to route traffic to the versions you deploy.
- Review the
gcloud app deploycommand line arguments and flags.