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:
-
The Owner of the GCP project must create the App Engine application.
-
Ensure that your user account includes the required privileges.
To deploy your app with the
gcloud
tool, you must
download,
install, and initialize the Google Cloud SDK:
If you already have the gcloud
tool installed and want
to configure it to use a GCP project ID other than the one
that you initialized it to, see
Managing Cloud SDK 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.
gcloud
Run the following commands to configure the gcloud
tool:
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 username
and password
for the proxy. For more
information, see gcloud config.
appcfg
Set the environment variable that corresponds to your proxy:
- Mac / Linux
-
export HTTP_PROXY="http://cache.example.com:3128" export HTTPS_PROXY="http://cache.example.com:3128"
- Windows
-
set HTTP_PROXY=http://cache.example.com:3128 set HTTPS_PROXY=http://cache.example.com:3128
Deploying an app
To deploy your app to App Engine, you run the gcloud app
deploy
command from within the root directory of your
application where your configuration
files are located, for
example app.yaml
.
gcloud
gcloud app deploy [YOUR_DEPLOYMENTS]
Where [YOUR_DEPLOYMENTS]
is one or more configuration file's path and
name. You separate each configuration file that you specify with a single
white space. By default, the app.yaml
is deployed when no configuration
file is specified.
Optional flags:
- Include the
--version
flag to specify a custom version ID, otherwise one is generated for you. - To deploy your app without automatically routing all traffic to that
version, include the
--no-promote
flag. - Include the
--project
flag to specify an alternate GCP project ID to what you initialized as the default in thegcloud
tool.
Examples:
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]
By default, each version that you deploy is automatically configured to
receive 100% of traffic. For configuration options, see the --promote
flag
in the gcloud app deploy
reference.
Tip: Run gcloud help
from the command line for a complete list of
arguments and flags.
appcfg
After you install the original App Engine SDK for Python, you can run the following command:
appcfg.py -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update [YOUR_APP_DIR]
By default, the initial version that you deploy to a service is automatically configured to receive 100% of traffic. However, all subsequent versions that you deploy to the same service must be manually configured, otherwise they receive no traffic.
Choosing unique version IDs
For 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 like123.my-service.appspot.com
, which can be interpreted
two ways:
- If version
123
exists, the request is routed to version123
of themy-service
service. - If version
123
does not exist, the request is instead routed to instance ID123
where the versions of themy-service
service 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.
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
default
service before you can create and deploy subsequent services. -
You must specify the ID of your service in the
app.yaml
configuration file of the corresponding version. To specify the service ID, you include theservice: [YOUR_SERVICE_ID]
element definition in each configuration file. By default, excluding this element definition from your configuration file deploys the version to thedefault
service. -
You must specify all the corresponding
app.yaml
configuration 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 app.yaml
file:
gcloud
gcloud app deploy [DEPLOYMENTS]
appcfg
appcfg.py update [DEPLOYMENTS]
Where [DEPLOYMENTS]
is one or more configuration file's path and name. You
separate each configuration file that you specify with a single white space.
Example
gcloud
gcloud app deploy main/app.yaml service1/app.yaml service2/app.yaml
appcfg
appcfg.py update main/app.yaml service1/app.yaml service2/app.yaml
You will receive verification via the command line as each service is successfully deployed.
Updating indexes
To create or update the indexes that your app's use, you upload the
index.yaml
configuration file to Cloud Datastore. Indexes that don't exist yet are
created after that configuration file is uploaded.
It can take a while for Cloud 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:
-
Upload the
index.yaml
configuration file to Cloud Datastore before you deploy your version:-
Upload the
index.yaml
file to Cloud Datastore:gcloud gcloud datastore create-indexes index.yaml
For information, see thegcloud datastore
reference.appcfg appcfg.py -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update_indexes [YOUR_APP_DIR]
-
Use the GCP 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
version:
gcloud You must specify both theapp.yaml
andindex.yaml
files and also include the--no-promote
flag so that no traffic is routed to the version:gcloud app deploy app.yaml index.yaml --no-promote
appcfg appcfg.py -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update [YOUR_APP_DIR]
- Use the GCP Console to monitor the status of all your indexes:
- After all your indexes are built, use the GCP Console to migrate or split traffic to your version:
- Deploy the new version without routing traffic to that
version:
For more information about indexes, see Configuring Datastore Indexes.
Troubleshooting
The following are common error messages that you might encounter:
PERMISSION_DENIED: Operation not allowed
The "appengine.applications.create" permission is required.
- If the GCP project does not include the required
App Engine
application, the
gcloud app deploy
command can fail when it tries to run thegcloud app create
command. 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
appcfg.py
ordev_appserver.py
tools when you installed the SDK, you might need to specify the full directory path to run the tool, for example:[PATH_TO_APP_ENGINE_SDK]/appcfg.py
or[PATH_TO_CLOUD_SDK]/bin/dev_appserver.py
.Note: To use
appcfg.py
you must download and install the original App Engine SDK for Python. Import Error
-
If you installed both the Google Cloud SDK 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 Cloud SDK 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:
[PATH_TO_APP_ENGINE_SDK]/dev_appserver.py
.
Tip: On Linux or Mac, you can runwhich dev_appserver.py
to determine which SDK is first in your PATH. [400] 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
default
service. For details about how to deploy a version to thedefault
service, 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 GCP Console to delete an older version and then upload your latest code.
What's next
- Learn how to download source code you've uploaded.
- Use services to build a large application.
- Split traffic or migrate traffic to route traffic to the versions you deploy.
- Review the
gcloud app deploy
command line arguments and flags. - Optional:
Review the
appcfg
command line arguments.