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.
You should use the appengine-web.xml file for configuring your app only
if you are migrating an existing app from the App Engine Java 8 runtime to the
latest supported Java version and you want to use the legacy bundled services.
If you are using an appengine-web.xml in your project, the app.yaml is
automatically generated for you at deployment.
App Engine Java applications use a configuration file, named appengine-web.xml,
to specify information about your app and to identify which files in the app's
WAR file are static files (like images) and which are resource files used by
the application.
Syntax
An App Engine Java app must have a file named appengine-web.xml in its
WAR, in the directory WEB-INF/. This is an XML file whose root element is
<appengine-web-app>.
You can find the Document Type Definition and schema specifications for the
appengine-web.xml in the SDK's docs/ directory.
| Element | Description |
|---|---|
<application> |
Not required if you deploy your app using Google Cloud SDK-based
tooling, such as the |
|
Optional. If you want to use the
App Engine legacy bundled services for second-generation runtimes,
set this field to |
|
Optional and only for second-generation runtimes. Overrides the default entrypoint which is the process command line that boots the Java application. By default, the generated entrypoint for a F4 instance class (memory settings are calculated from the instance class) is equivalent to the following configuration: <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <entrypoint> java -showversion -Xms32M -Xmx819M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED --add-opens java.logging/java.util.logging=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com/google/apphosting/runtime/JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime </entrypoint> </appengine-web-app>
You can modify the configuration to add extra JVM process flags or define your own process to boot.
Notice that the application is deployed in the |
<async-session-persistence> |
Optional. It's possible to reduce request latency by configuring your application to asynchronously write HTTP session data to the datastore: <async-session-persistence enabled="true" /> With async session persistence turned on, App Engine will submit a Task Queue task to write session data to the datastore before writing the data to memcache. By default the task will be submitted to the `default` queue. If you'd like to use a different queue, add the `queue-name` attribute: <async-session-persistence enabled="true" queue-name="myqueue"/> Session data is always written synchronously to memcache. If a request tries to read the session data when memcache is not available (or the session data has been flushed), it will fail over to Datastore, which might not yet have the most recent session data. This means that asynchronous session persistence can cause your application to see stale session data. However, for most applications the latency benefit far outweighs the risk. |
<auto-id-policy> |
Optional. If you are
setting entity identifiers automatically, you can change the method
employed by setting the auto ID policy. The following are valid options:
|
<automatic-scaling> |
Optional. For a full explanation, see the automatic scaling section. |
<basic-scaling> |
Optional. For a full explanation, see the basic scaling section. |
<env-variables> |
Optional.
The <env-variables> <env-var name="DEFAULT_ENCODING" value="UTF-8" /> </env-variables> To avoid conflicts with your local environment, the development server does not set environment variables based on this file, and requires that the local environment have these variables already set to matching values. export DEFAULT_ENCODING="UTF-8" dev_appserver war When deployed to App Engine, the environment is created with these variables already set. |
<inbound-services> |
Optional.
Before an application can receive email, the
application must be configured to enable the service.
You enable the service for a Java app by including an
The following inbound service is available:
|
<instance-class> |
Optional. The instance class size for this module. The following instance classes are available when specifying different scaling options:
|
<manual-scaling> |
Optional. For a full explanation, see the manual scaling section. |
<precompilation-enabled> |
Optional. App Engine uses a "precompilation" process with the Java bytecode of an app to enhance the performance of the app in the Java runtime environment. Precompiled code functions identically to the original bytecode.
If for some reason you prefer that your app not use precompilation,
you can turn it off by adding the following to your
<precompilation-enabled>false</precompilation-enabled> |
<module> |
Note: Modules are now named
Services
and services are still declared in Required if creating a service. Optional for the default service. Each service and each version must have a name. A name can contain numbers, letters, and hyphens. It cannot be longer than 63 characters, start or end with a hyphen, and contain the string `-dot`. Choose a unique name for each service and each version. Don't reuse names between services and versions. Also see service. |
<public-root> |
Optional.
The
The default
For example, the following would map the URL path
<public-root>/static</public-root> |
<resource-files> |
Optional. The files listed in the
The
App Engine resource files are read using |
<runtime> |
To use the latest supported Java version, you must specify this entry with the value
<runtime>java21</runtime> |
<service> |
Services were formerly known as modules. Currently, defining a service as:
|
<service-account> |
Optional. The <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account> |
<sessions-enabled> |
Optional. App Engine includes an implementation of sessions, using the servlet session interface. The implementation stores session data in Datastore for persistence, and also uses memcache for speed. As with most other servlet containers, the session attributes that are set with `session.setAttribute()` during the request are persisted at the end of the request.
This feature is off by default. To turn it on, add the following to
<sessions-enabled>true</sessions-enabled>
The implementation creates Datastore entities of the kind
Note: Because App Engine stores session data in
Datastore and memcache, all values stored in the session must
implement the
See
|
<ssl-enabled> |
Optional. By default, any user can access any URL using either HTTP or HTTPS. You can configure an app to require HTTPS for certain URLs in the deployment descriptor. See Deployment Descriptor: Secure URLs.
If you want to disallow the use of HTTPS for the application, put the
following in the <ssl-enabled>false</ssl-enabled> There is no way to disallow HTTPS for some URL paths and not others in the Java runtime environment. |
<static-error-handlers> |
Optional.
When certain errors occur, App Engine serves a generic error
page. You can configure your app to serve a custom static file instead
of these generic error pages, so long as the custom error data is less
than 10 kilobytes. You can set up different static files to be served
for each supported error code by specifying the files in your app's
<static-error-handlers> <handler file="default_error.html" /> <handler file="over_quota.html" error-code="over_quota" /> </static-error-handlers> Warning: Make sure that the path to the error response file does not overlap with static file handler paths.
Each
The
You can optionally specify a |
<static-files> |
Optional.
The
The
<static-files> <include path="/my_static-files" > <http-header name="Access-Control-Allow-Origin" value="http://example.org" /> </include> </static-files> |
<system-properties> |
Optional. The <system-properties> <property name="myapp.maximum-message-length" value="140" /> <property name="myapp.notify-every-n-signups" value="1000" /> <property name="myapp.notify-url" value="http://www.example.com/signupnotify" /> </system-properties> <env-variables> <env-var name="DEFAULT_ENCODING" value="UTF-8" /> </env-variables> Optional. You can configure an HTTP connector for improving CPU and memory utilization. <system-properties> <property name="appengine.use.httpconnector" value="true"/> </system-properties> Starting in Java 21, you can configure your Java web server to use virtual threads. For example: <system-properties> <property name="appengine.use.virtualthreads" value="true"/> </system-properties> |
<url-stream-handler> |
Optional. Possible values, The default value is If you set <url-stream-handler>urlfetch</url-stream-handler> |
<version> |
The
Version names should begin with a letter, to distinguish them from
numeric instances which are always specified by a number. This avoids
the ambiguity with URLs like |
<warmup-requests-enabled> |
Optional. Default: true. Warmup requests are enabled by default for Java applications.
With warmup requests enabled, the App Engine infrastructure issues `GET`
requests to
To disable warmup requests, specify <warmup-requests-enabled>false</warmup-requests-enabled> |
<vpc-access-connector> |
Optional.
Configures your application to use a Serverless VPC Access
connector, enabling the application to send requests to internal
resources in your VPC network. Specify the fully-qualified name of a
connector in the <vpc-access-connector>
<name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc-access-connector>For more information, see Connecting to internal resources in a VPC network. |
Scaling elements
The following table lists the options for defining how you can specify that your application should scale.
For a comparison of the performance features of the scaling types, see Scaling dynamic instances.
| Element | Description |
|---|---|
<automatic-scaling> |
Optional. Automatic scaling is assumed by default with a default
instance class of
The This element can contain the following elements:
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <instance-class>F2</instance-class> <automatic-scaling> <target-cpu-utilization>0.65</target-cpu-utilization> <min-instances>5</min-instances> <max-instances>100</max-instances> <max-concurrent-requests>50</max-concurrent-requests> </automatic-scaling> </appengine-web-app> |
<basic-scaling> |
Optional.
The This element can contain the following elements:
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <instance-class>B8</instance-class> <basic-scaling> <max-instances>11</max-instances> <idle-timeout>10m</idle-timeout> </basic-scaling> </appengine-web-app> |
<manual-scaling> |
Optional.
The This element can contain the following elements:
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <instance-class>B8</instance-class> <manual-scaling> <instances>5</instances> </manual-scaling> </appengine-web-app> |
Staging elements
Much of the work done during a deployment occurs locally in a preparation step called staging, where JAR files are assembled, JSPs are compiled, and so forth. You can optionally configure certain parts of the staging behavior using staging elements in the application configuration file. Most applications will deploy successfully without manually configuring staging behavior. If your app doesn't deploy, you may need to configure staging using the options shown below.
| Element | Description |
|---|---|
<staging> |
Optional. Most applications do not need to change default behavior. The staging element allows you to specify a particular staging configuration if needed for deployment. This element can contain the following elements:
For example:
<staging>
<delete-jsps>false</delete-jsps>
</staging>
|
Staging option defaults
The defaults for staging options are different depending on whether you use Google Cloud SDK-based tooling, such as the gcloud CLI, or the Google Cloud SDK-based Maven, Gradle, Eclipse, or IntelliJ plugins.
| Staging element | App Engine SDK-based defaults - | Google Cloud SDK-based defaults |
|---|---|---|
enable-jar-splitting |
false |
true |
jar-splitting-excludes |
NA | NA |
disable-jar-jsps |
false |
false |
enable-jar-classes |
false |
true. This can impact class loading order, so if your app depends on a certain order using the former false default, you can set this to false. |
delete-jsps |
false |
true |
compile-encoding |
utf-8 |
utf-8 |
Include and exclude syntax
Path patterns are specified using zero or more <include> and
<exclude> elements. In a pattern, '*' represents zero or more
of any character in a file or directory name, and ** represents zero or more
directories in a path. Files and directories matching <exclude>
patterns will not be uploaded when you deploy your app to App Engine. However,
these files and directories will still be accessible to your application when
running on the local Development Server.
An <include> element overrides the default behavior of including
all files. An <exclude> element applies after all
<include> patterns (as well as the default if no explicit
<include> is provided).
The following example demonstrates how to designate all .png files as static
files (except those in the data/ directory and all of its subdirectories):
<static-files>
<include path="/**.png" />
<exclude path="/data/**.png" />
</static-files>
You can also set HTTP headers to use when responding to requests to these static resources.
<static-files>
<include path="/my_static-files" >
<http-header name="Access-Control-Allow-Origin"
value="http://example.org" />
</include>
</static-files>
MIME types for static files
By default, static files are served using a MIME type selected based on the
filename extension. You can associate custom MIME types with filename
extensions for static files using mime-mapping elements in web.xml.
URLFetch timeout
You can set a deadline for each
URLFetch request. By default, the deadline for a fetch is 5 seconds.
You can change this default by including the following setting in your
appengine-web.xml configuration file. Specify the timeout in seconds:
<system-properties>
<property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>