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

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 by using Buildpacks. Buildpacks are a CNCF project that allow you to take your app directly from source code to highly portable images that can run on any cloud.

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 fit 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 Buildpacks on Cloud Build
Deploy your container images to Cloud Run

What you'll need

A Google Cloud Platform project with an active GCP billing account and App Engine enabled
Working knowledge of common Linux commands
Basic knowledge of developing and deploying App Engine apps
A Java 8 servlet app that you'd like to migrate to Java 17 and deploy to Cloud Run (this can be an app on App Engine or just the source)

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 Buildpacks, migrate away from App Engine configuration, and 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:

Install/Re-familiarize yourself with the gcloud CLI
Initialize the gcloud CLI for your project with gcloud init
Create the App Engine project with gcloud app create
Deploy the sample app to App Engine

./mvnw package appengine:deploy -Dapp.projectId=$PROJECT_ID

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. Build configuration

Next, remove the configuration to package our application as a WAR. 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:

Migrating from bundled services to find suitable standalone services.
Migrating XML configuration files to YAML, for users migrating to the Java 11/17 runtimes while remaining on App Engine.

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 & Deploy Application

At this point you are ready to deploy your app to Cloud Run directly from your source code. This is an excellent option that uses Cloud Build behind the scenes to provide a hands off deploy experience. Note that in order to make use of this feature you will either need an account with at least one of the following permissions, and to have followed these environment setup steps - or use the Cloud Shell:

Owner role
Editor role
The following set of roles:
Cloud Build Editor role
Artifact Registry Admin role
Storage Admin role
Cloud Run Admin role
Service Account User role

With those prerequisites in place, simply run the following from your source directory:

gcloud run deploy SERVICE --source .

You'll be prompted for a few things during the run deploy command such as:

Providing the source code location
Providing the service name
Enabling the Cloud Run API
Selecting your region

After responding to those prompts the build and deploy process begins, during which Cloud Build does the following:

zips and saves your source in a cloud storage bucket
uses the Cloud Native Computing Foundation buildpacks in the background to build your image
creates a registry to store the resulting container image (if not already present)
And creates a cloud run service to host your app (if not already present)

Once the build and deploy is complete, you should get a message explaining that a new revision is live and serving 100% of traffic.

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: