Migrating from Google App Engine Java app to Cloud Run with Docker

1. Overview

This series of codelabs (self-paced, hands-on tutorials) aims to help Google App Engine (Standard) Java developers modernize their apps by guiding them through a series of migrations. By following these steps, you can update your app to be more portable and decide to containerize them for Cloud Run, Google Cloud's container-hosting sister service to App Engine, and other container-hosting services.

This tutorial teaches you how to containerize an App Engine app for deploying to the Cloud Run fully-managed service with a Dockerfile. Dockerfiles are the most hands on deployment method for this migration, but they also offer the most options to customize your build process.

In addition to teaching you the required steps to move from App Engine to Cloud Run, you will also learn how to upgrade a Java 8 App Engine app to Java 17.

If the application you're interested in migrating makes heavy use of App Engine legacy bundled services, or other App Engine specific features, the Accessing App Engine bundled services for Java 11/17 guide might be a better starting point than this codelab.

You'll learn how to

  • Use Cloud Shell
  • Enable the Cloud Run, Artifact Registry, and Cloud Build APIs
  • Containerize your app using Docker, Docker, and Cloud Build
  • Deploy your container images to Cloud Run

What you'll need

Survey

How will you use this tutorial?

Read it through only Read it and complete the exercises

How would you rate your experience with Java?

Novice Intermediate Proficient

How would you rate your experience with using Google Cloud services?

Novice Intermediate Proficient

2. Background

PaaS systems like App Engine and Cloud Functions provide many conveniences for your team and application, such as enabling SysAdmins and Devops to focus on building solutions. With severless platforms, your app can autoscale up as needed, scale down to zero with pay-per-use billing to help control costs, and use a variety of common development languages.

However, the flexibility of containers is compelling as well. With the ability to choose any language, any library, and any binary, containers give you the best of both worlds: the convenience of serverless along with the flexibility of containers. This is what Google Cloud Run is all about.

Learning how to use Cloud Run is not within the scope of this codelab; that's covered by the Cloud Run documentation. The goal here is for you to get familiar with how to containerize your App Engine app for Cloud Run (or other container-hosted services). There are a few things you should know before moving forward, primarily that your user experience will be slightly different.

In this codelab, you'll learn how to build and deploy containers. You'll learn how to containerize your app with a Dockerfile, migrate away from App Engine configuration, and (optionally) define build steps for Cloud Build. This will involve moving away from certain App Engine specific features. If you prefer not to follow this path, you can still upgrade to a Java 11/17 runtime while keeping your apps on App Engine instead.

3. Setup/Prework

1. Setup project

For this tutorial, you will use a sample app from the appengine-java-migration-samples repository on a brand new project. Ensure the project has an active billing account.

If you intend to move an existing App Engine app to Cloud Run, you can use that app to follow along instead.

Run the following command to enable the necessary APIs for your project:

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com run.googleapis.com

2. Get baseline sample app

Clone the sample app either on your own machine or the Cloud Shell, then navigate to the baseline folder.

The sample is a Java 8, Servlet-based Datastore app intended for deployment on App Engine. Follow the instructions in the README on how to prepare this app for App Engine deployment.

3. (Optional) Deploy baseline app

The following is only necessary if you would like to confirm that the app works on App Engine before we migrate to Cloud Run.

Refer to the steps in the README.md:

  1. Install/Re-familiarize yourself with the gcloud CLI
  2. Initialize the gcloud CLI for your project with gcloud init
  3. Create the App Engine project with gcloud app create
  4. Deploy the sample app to App Engine
./mvnw package appengine:deploy -Dapp.projectId=$PROJECT_ID
  1. Confirm the app runs on App Engine without issues

4. Create an Artifact Registry repository

After containerizing your app, you'll need somewhere to push and store your images. The recommended way to go about this on Google Cloud is with Artifact Registry.

Create the repository named migration with gcloud like so:

gcloud artifacts repositories create migration --repository-format=docker \
--description="Docker repository for the migrated app" \
--location="northamerica-northeast1"

Note that this repository uses the docker format type, but there are several repository types available.

At this point, you have your baseline App Engine app, and your Google Cloud project is prepared to migrate it to Cloud Run.

4. Modify Application Files

In cases where your app makes heavy use of App Engine's legacy bundled services, configuration, or other App Engine only features, we recommend continuing to access those services while upgrading to the new runtime. This codelab demonstrates a migration path for applications that already use standalone services, or can feasibly be refactored to do so.

1. Upgrading to Java 17

If your app is on Java 8, consider upgrading to a later LTS candidate like 11 or 17 to keep up with security updates and gain access to new language features.

Start by updating the properties in your pom.xml to include the following:

<properties>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

This will set the project version to 17, inform the compiler plugin that you want access to java 17 language features, and would like the compiled classes to be compatible with the Java 17 JVM.

2. Including a web server

There are a number of differences between App Engine and Cloud Run worth considering when moving between them. One difference is that while App Engine's Java 8 runtime provided and managed a Jetty server for the apps it hosted, Cloud Run does not. We'll be using Spring Boot to provide us with a web server and servlet container.

Add the following dependencies:

<dependencies>
<!-- ... -->
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
       <version>2.6.6</version>
       <exclusions>
           <!-- Exclude the Tomcat dependency -->
           <exclusion>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-starter-tomcat</artifactId>
           </exclusion>
       </exclusions>
   </dependency>
   <!-- Use Jetty instead -->
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-jetty</artifactId>
       <version>2.6.6</version>
   </dependency>
<!-- ... -->
</dependencies>

Spring Boot embeds a Tomcat server by default, but this sample will exclude that artifact and stick with Jetty to minimize differences in default behavior after the migration.

3. Spring Boot setup

While Spring Boot will be able to re-use your servlets without modification, it will require some configuration to make sure they're discoverable.

Create the following MigratedServletApplication.java class in the com.example.appengine package:

package com.example.appengine;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.servlet.ServletComponentScan;

@ServletComponentScan
@SpringBootApplication
@EnableAutoConfiguration
public class MigratedServletApplication {
    public static void main(String[] args) {
        SpringApplication.run(MigratedServletApplication.class, args);
    }
}

Note that this includes the @ServletComponentScan annotation, which will look (in the current package by default) for any @WebServlets, and make them available as expected.

4. Packaging the app as a JAR

While it is possible to containerize your app starting from a war, it becomes easier if you package your app as an executable JAR. This won't require much configuration, particularly for projects using Maven as a build tool — as jar packaging is the default behavior.

Remove the packaging tag in thepom.xml file:

<packaging>war</packaging>

Next, add the spring-boot-maven-plugin:

<plugins>
<!-- ... -->
  <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>2.6.6</version>
  </plugin>
<!-- ... -->
</plugins>

5. Migrating away from App Engine configuration, services, and dependencies

As mentioned in the beginning of the codelab, Cloud Run and App Engine are designed to offer different user experiences. Certain features that App Engine offers out of the box—like the Cron and Task Queue services—need to be re-created manually and will be covered in more detail in later modules.

The sample app does not make use of legacy bundled services, but users whose apps do can refer to the following guides:

Since you will be deploying to Cloud Run from now on, the appengine-maven-plugin can be removed:

<plugin>
 <groupId>com.google.cloud.tools</groupId>
 <artifactId>appengine-maven-plugin</artifactId>
 <version>2.4.1</version>
 <configuration>
   <!-- can be set w/ -DprojectId=myProjectId on command line -->
   <projectId>${app.projectId}</projectId>
   <!-- set the GAE version or use "GCLOUD_CONFIG" for an autogenerated GAE version -->
   <version>GCLOUD_CONFIG</version>
 </configuration>
</plugin>

5. Containerize Application

At this point you're ready to inform Cloud Build on how to actually build your application's container. With this containerization method a separate build config file (cloudbuild.yaml) is not required. We can simply define a minimal Dockerfile as a starting point:

FROM eclipse-temurin

ARG JAR_FILE=JAR_FILE_MUST_BE_SPECIFIED_AS_BUILD_ARG

COPY ${JAR_FILE} app.jar

ENTRYPOINT ["java", "-jar","/app.jar"]

This dockerfile bundles the uber-jar version of your spring boot service in a single layer. It's the simplest approach to Dockerfile containerization, but comes with a number of drawbacks, especially when comparing repeated times where dependencies are relatively stable. Concerns like this one are the reason why this containerization method is considered more advanced. On the plus side however, writing your own dockerfile offers complete control over your base image and access to the performance benefits of writing a carefully layered image.

2**. Run the build process**

Now that you've informed Cloud Build on the desired build steps, you're ready for a one-click deploy.

Run the following command:

gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME

Replace the placeholder values in the above command with the following:

  • LOCATION: the regional or multi-regional location for your repository.
  • PROJECT_ID: your Cloud project ID.
  • REPOSITORY: the name of your Artifact Registry repository.
  • IMAGE_NAME: the name of your container image.

Once the process is finished, your container image has been built, stored in Artifact Registry, and deployed to Cloud Run.

At the end of this codelab, your app should look the same as the one in the mod4-migrate-to-cloud-run folder.

And there you have it! You have successfully migrated a Java 8 App Engine app to Java 17 and Cloud Run, and now have a clearer understanding of the work involved when switching and choosing between hosting options.

6. Summary/Cleanup

Congratulations, you've upgraded, containerized, migrated and your app, which concludes this tutorial!

From here, the next step is to learn more about the CI/CD and Software supply chain security features that are within reach now that you can deploy with Cloud Build:

Optional: Clean up and/or disable service

If you deployed the sample app on App Engine during this tutorial, remember to disable the app to avoid incurring charges. When you're ready to move to the next codelab, you can re-enable it. While App Engine apps are disabled, they won't get any traffic to incur charges, however Datastore usage may be billable if it exceeds its free quota, so delete enough to fall under that limit.

On the other hand, if you're not going to continue with migrations and want to delete everything completely, you can either delete your service or shutdown your project entirely.

7. Additional resources

App Engine migration module codelabs issues/feedback

If you find any issues with this codelab, please search for your issue first before filing. Links to search and create new issues:

Migration resources

Online resources

Below are online resources which may be relevant for this tutorial:

App Engine

Other Cloud information

Videos

License

This work is licensed under a Creative Commons Attribution 2.0 Generic License.