Region ID
The REGION_ID
is an abbreviated code that Google assigns
based on the region you select when you create your app. The code does not
correspond to a country or province, even though some region IDs may appear
similar to commonly used country and province codes. For apps created after
February 2020, REGION_ID.r
is included in
App Engine URLs. For existing apps created before this date, the
region ID is optional in the URL.
Learn more about region IDs.
Learn how to run your application locally, deploy it, and test on App Engine.
Running locally
To test your application's functionality before deploying, run your application in your local environment with the development tools that you usually use.
Before deploying your application
Before you can deploy your application:
- The Owner of the Cloud project must enable App Engine.
- You must ensure that your user account includes the required privileges.
Deploying your application
You can use any of the following techniques to deploy your app:Use the Google Cloud CLI to deploy your app's source code and a Maven POM or Gradle build file. Cloud Build will build your app and deploy it to App Engine.
Use the App Engine plugin for Maven or Gradle, which builds your app locally and deploys the built app to App Engine.
Use any build framework to build a fat JAR (executable JAR) locally, then use the Google Cloud CLI to deploy the JAR to App Engine.
To programmatically deploy your apps, use the Admin API.
Deploying your app's source code
If you use Maven or Gradle to manage your app's local builds, and if all of
your app's dependencies are publicly available for download, you can enter the
gcloud app deploy
command from the
directory that contains your app's pom.xml
or build.gradle
file:
gcloud app deploy
The command instructs Cloud Build to use App Engine Buildpacks to build your app and deploy it to App Engine.
If you use Maven:
The buildpack uses the following build command:
mvn clean package --batch-mode -DskipTests
If your app's root directory contains a
mvnw
file, the build command substitutes./mvnw
in place ofmvn
. Cloud Build then looks in thetarget
directory for the.jar
file with a Main-Class manifest entry and creates anentrypoint
with the valuejava -jar <jarfile>
.
If you use Gradle:
The buildpack uses the following build command:
gradle clean assemble -x test --build-cache
If your app's root directory contains a
gradlew
file the build command substitutes./gradlew
in place ofgradle
. Cloud Build then looks in thebuild/libs
directory for the.jar
file with a Main-Class manifest entry and creates anentrypoint
with the valuejava -jar <jarfile>
.Make sure there is no
pom.xml
in the root of your project. Maven projects take precedence over Gradle projects.
Viewing build logs
Cloud Build streams build and deploy logs, and you can view them in the Cloud Build history section of the Google Cloud 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.
Note the following about this deployment technique:
If your app has dependencies that are only available locally, Cloud Build is not able to build your app and your deployment will fail. In this case, we recommend using the App Engine Maven or Gradle plugin instead.
Building your app uses Cloud Build quota and storing your app's source code uses Cloud Storage quota. Cloud Build and Cloud Storage provide free quotas, so you won't incur costs from deploying App Engine apps until you surpass the free quotas. For information, see Pricing.
Currently, it isn't possible to specify additional arguments for the Gradle build command. For more information, see the Google Issue Tracker.
Using the App Engine Maven or Gradle plugin
App Engine provides Maven and Gradle plugins that you can use to build
and deploy your app. For example, after you set up the App Engine
Maven plugin, you can enter the following command from the directory that
contains your project's pom.xml
file:
mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID
Replace PROJECT_ID with the ID of your Cloud project. If
your pom.xml
file already
specifies your
project ID, you don't need to include the -Dapp.deploy.projectId
property in the
command you run.
For more information, see Using Apache Maven and the App Engine Plugin or Using Gradle and the App Engine Plugin.
Deploying an executable JAR
Use any build framework to build an executable JAR locally, then do one of
the following depending on whether you
created an app.yaml
file
for your app:
If you created an
app.yaml
file:Copy the file into the same directory as the executable JAR file you created.
From the directory that contains the
app.yaml
and your JAR, enter the following command:gcloud app deploy
If you haven't created an
app.yaml
file, enter the following command:gcloud app deploy your-executable.jar
gcloud app deploy
will create anapp.yaml
file that contains the minimum settings, using all default values.
Ignoring files
You can use a .gcloudignore
file to specify files and directories that will
not be uploaded to App Engine when you deploy your services. This is
useful for ignoring build artifacts and other files that do not need to be
uploaded with your deployment.
Managing build images
Each time you deploy a new version, a container image is created using the Cloud Build service. That container image is built in the app's region, and then runs in the App Engine standard environment.
Built container images are stored in the app-engine-tmp/app
folder
in Container Registry. You can
download these images to keep or run elsewhere. Once deployment is complete,
App Engine no longer needs the
container images. Note that they are not automatically deleted, so to avoid
reaching your storage quota, you can safely delete any images you don't need.
For more information about managing images in Container Registry, see the
Container Registry documentation.
Viewing your application
After you deploy your application to App Engine, you can run the
following command to launch your browser and view it at
https://PROJECT_ID.REGION_ID.r.appspot.com
:
gcloud app browse
Testing on App Engine before shifting traffic
Before configuring a new version to receive traffic, you can test it on
App Engine. For example, to test a new version of your default
service:
Deploy your new version, but prevent traffic from being automatically routed to the new version:
mvn appengine:deploy -Dapp.deploy.projectId=PROJECT_ID -Dapp.deploy.promote=False
Access your new version by navigating to the following URL:
https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com
Now you can test your new version in the App Engine runtime environment. You can debug your application by viewing its logs. For more information, see Writing Application Logs.
App Engine routes requests sent to
https://PROJECT_ID.REGION_ID.r.appspot.com
to the version previously configured to receive traffic.When you want to send traffic to the new version, use the Google Cloud console to migrate traffic:
Select the version you just deployed and click Migrate traffic.
You can use the same process to test new versions of other services by replacing
default
in the URL with your service's name:
https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com
For more information about targeting specific services and versions, see How Requests are Routed.
Using build environment variables
You can also set build environment variables for runtimes that support buildpacks.
Build environment variables are key/value pairs deployed alongside an app that
let you pass
configuration information
to buildpacks. For example, you might want to customize compiler options. You
can add or remove these build environment variables by configuring the
build_env_variables
field in your app.yaml
file.
Using Cloud Debugger
You can use Debugger to inspect the state of your deployed app at any code location, without stopping or slowing down the running app.
To use Debugger with a Java 11 app, the following flag needs to
be included in the entrypoint
field of your app.yaml
file:
-agentpath:/opt/cdbg/cdbg_java_agent.so=--log_dir=/var/log
If you have already specified the entrypoint
in app.yaml
,
file add the agentpath flag to the java
command in the entrypoint
field.
If you haven't specified the entrypoint
field, or if you generate the app.yaml
file when you deploy your app, App Engine adds the flag to the command
it uses to start your app.
Using Cloud Profiler
Cloud Profiler is a statistical, low-overhead profiler that continuously gathers CPU usage and memory-allocation information from your production applications. It attributes that information to your app's source code, helping you identify the parts of the app consuming the most resources, and otherwise illuminating the performance characteristics of the code.
To use Cloud Profiler, set up your app's configuration files as described in Starting your program and redeploy the app.