Skip to content

Latest commit

 

History

History
160 lines (124 loc) · 6.19 KB

overview.md

File metadata and controls

160 lines (124 loc) · 6.19 KB

Google App Engine Overview

An Overview of App Engine

App Engine is one of the fully managed, serverless platforms for developing and hosting web applications at scale. You can choose from several popular languages to develop your apps, and then let App Engine take care of provisioning servers and scaling your app instances based on demand.

Access Bundled Services for Java 17+

This page describes how to install and use the bundled services with the latest supported Java version for the App Engine standard environment. Your app can access the bundled services through the App Engine API JAR.

Before You Begin

  • Refer to the list of bundled services APIs you can call in the latest supported Java version
  • This page requires that your app is running a supported Java version
  • To migrate your app from the first-generation to the second-generation runtime, see Migrate from Java 8 to the latest Java runtime
  • If you use bundled services and want to upgrade to Java 21, see Upgrade an existing application

To use bundled services in your latest supported Java app, you must use an appengine-web.xml file to configure your app (instead of an app.yaml file).

Configuration Settings

appengine-web.xml

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java21</runtime> <!-- or another supported version -->
<app-engine-apis>true</app-engine-apis> </appengine-web-app>

To specify the bundled services as a dependency, add the following lines in your pom.xml file:

<dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>3.0.0</version>
</dependency>

You must add the <app-engine-apis> element and set it to true in appengine-web.xml:

<app-engine-apis>true</app-engine-apis>

To deploy your Java 21 app, run the mvn appengine:deploy command, or the gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml command on a compiled and staged web application.

Default Entrypoint Used by Java 21

Java 21 apps can benefit from extra user configuration when starting the JVM for web apps. The default entrypoint used to boot the JVM is generated by App Engine buildpacks. Essentially, it is equivalent to define this entrypoint in the appengine-web.xml file:

--add-opens java.base/java.nio.charset=ALL-UNNAMED -showversion -Xms32M -Xmx204M
-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags
-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

Entry Point Features

The entry point for the second-generation Java versions can be customized with user-defined environment variables added in the appengine-web.xml configuration file.

Env Var Description Type Default
CPROF_ENABLE Stackdriver Profiler boolean false
GAE_MEMORY_MB Available memory size Set by App Engine or /proc/meminfo-400M
HEAP_SIZE_RATIO Memory for the heap percent 80
HEAP_SIZE_MB Available heap size ${HEAP_SIZE_RATIO}% of ${GAE_MEMORY_MB}
JAVA_HEAP_OPTS JVM heap args JVM args -Xms${HEAP_SIZE_MB}M
JAVA_GC_OPTS JVM GC args JVM args -XX:+UseG1GC plus configuration
JAVA_USER_OPTS JVM other args JVM args
JAVA_OPTS JVM args JVM args See below

If not explicitly set, JAVA_OPTS is defaulted to:

JAVA_OPTS:=-showversion ${JAVA_HEAP_OPTS} ${JAVA_GC_OPTS} ${JAVA_USER_OPTS}

When CPROF_ENABLE is true, the default entrypoint adds the PROFILER_AGENT as:

-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr

Example: If your application code needs more -add-opens flags, you can use the JAVA_USER_OPTS environment variable defined in the appengine-web.xml file:

<env-variables>
  <env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
</env-variables>

Migration Considerations

You should be aware of the following considerations if you are migrating to a second-generation Java runtime and your app uses bundled services:

  • To test the bundled services capabilities in your second-generation Java app, you can use the local development server
  • Unlike the Java 8 runtime, the second-generation Java runtimes include JVM as part of the instance memory. If you see memory-related errors in the logs, consider increasing the instance class size in your appengine-web.xml file
  • If your application is trying to call an API which is not enabled for the second-generation Java runtimes, it will receive a com.google.apphosting.api.ApiProxy$FeatureNotEnabledException error
  • All apps are assumed to be thread safe in the second-generation Java runtimes. You must remove the threadsafe element in your app.yaml or appengine-web.xml file