Migrate Tomcat applications to containers with Migrate to Containers

Last reviewed 2022-06-17 UTC

This document is for application owners and cloud architects. This document describes how to migrate Java applications running on Tomcat to containers running in Google Kubernetes Engine (GKE), GKE Autopilot, Cloud Run, or GKE Enterprise. You can use this process to migrate Tomcat applications from on-premises environments, private hosting environments, or other cloud providers. It also highlights the benefits of using Migrate to Containers to automate your migration.

This document assumes that you're familiar with the following products:

  • Java applications deployed on Tomcat application servers and running on Linux virtual machines (VMs).
  • Kubernetes concepts and the basic use of the Kubernetes command-line tool.

This document is part of a series about migrating to Google Cloud. For an overview of the series, see Migration to Google Cloud: Choosing your migration path.

Read this document to migrate compatible Tomcat applications from a supported source environment to a GKE, GKE Enterprise, or Cloud Run environment, by using Migrate to Containers. These source environments can include the following:

Migrate to Containers uses the fit assessment tool to discover, inspect, and migrate all your Tomcat applications in your Linux VMs. The tool splits the Tomcat applications into individual Tomcat application containers. After migration, you can group some or all applications into a shared container image. The following diagram shows how Migrate to Containers splits and migrates the applications:

Migrate to Containers splits and migrates Tomcat applications.

Migrate to Containers offers the following benefits:

  • Workload modernization: provides the following capabilities:
  • Containerized environment: containerizes existing VM-based applications. See Benefits of migrating to containers.
  • Official Tomcat image: uses the Tomcat official image by default, or you can update the migration or the Dockerfile to use your own. Docker official images bring Docker best practices to your base images.
  • Automatic applications splitting: automatically suggests splitting each discovered application into an individual container while keeping Tomcat's original configuration.
  • Secrets management: discovers the keystores, truststores, and certificates used by your Tomcat server, and automatically generates Kubernetes primitives to externalize and mount them as Kubernetes Secrets.
  • Recommended logging changes: automatically discovers common Java logging framework configuration files (such as log4j2, log4j, and logback), and suggests changes to align with logging on Kubernetes.

Migrating Tomcat applications to containers with Migrate to Containers is one possible step in your workload modernization journey. Migrating helps you to transform your Tomcat applications so they run in a cloud environment. It also helps you avoid expensive rewrites.

Ideal migration candidates are applications running on supported Tomcat and Java versions for which modernization through a complete rewrite is too expensive or too difficult.

Design the migration to Google Cloud

To migrate your Tomcat applications from your source environment to containers running on Google Cloud, follow the framework described in the Migration to Google Cloud series.

The following diagram illustrates the path of your migration journey:

Migration path with four phases.

The framework illustrated in the preceding diagram has four phases:

  1. Assess: you assess your source environment, assess the applications that you want to migrate to Google Cloud, and assess which Tomcat applications are suitable for migration.
  2. Plan: you create the basic infrastructure for Migrate to Containers, such as provisioning the resource hierarchy and setting up network access.
  3. Deploy: you migrate the Tomcat applications from the source environment to GKE, GKE Autopilot, Cloud Run, or GKE Enterprise with Migrate to Containers.
  4. Optimize: you begin to take advantage of the cloud technologies and capabilities.

Assessing the source environment and applications

In the assessment phase, you gather information about your source environment and the applications that you want to migrate. Doing so helps you rightsize the resources that you need—both for the migration and your target environment.

In the assessment phase, you do the following:

  1. Build a comprehensive inventory of your applications.
  2. Catalog your applications according to their properties and dependencies.
  3. Train and educate your teams on Google Cloud.
  4. Build an experiment and proof of concept on Google Cloud.
  5. Calculate the total cost of ownership (TCO) of the target environment.
  6. Choose the applications that you want to migrate first.

The following sections are based on Migration to Google Cloud: Assessing and discovering your workloads. However, they provide information that is specific to assessing the Tomcat applications that you want to migrate to containers with Migrate to Containers.

Build your inventories

To scope your migration, you must understand your Tomcat environment. To understand your environment, gather information about your applications and their dependencies.

Building an inventory of your apps describes how to build an inventory of your workloads and their dependencies in your Tomcat environment. Follow that guidance and build your inventories. When you're done with that work, continue reading this document.

After you've built an inventory of your workloads and their dependencies, you refine the inventory. Assess the aspects and features that interest your organization when it migrates its Tomcat applications with Migrate to Containers.

Before assessing your Tomcat environment for migration, complete the assessment work in Migrating VMs to containers with Migrate to Containers and Migration to Google Cloud: Assessing and discovering your workloads. When you're done with that work, complete the inventory of your workloads.

To complete the inventory of your workloads, consider the following:

  • Operating systems running in your Tomcat instances: Gather information about the operating systems and their licenses running in your Tomcat instances, and ensure that the operating systems are listed in Compatible operating systems and Kubernetes versions.
  • Tomcat versions running your applications: Gather information about the Tomcat versions running your applications, and ensure their compatibility with Migrate to Containers.
  • Applications deployed in your Tomcat instances: Assess which applications are deployed in each Tomcat instance. Then, map the dependencies between your applications, and between your applications and external services. Next, gather information about the configuration sources of your applications, which can include the following configurations:
    • Environment variables
    • Non-standard Tomcat installation paths
    • LDAP user registries
    • Java Database Connectivity (JDBC) connections
    • Tomcat proxy
    • Java proxy
  • Migrate to Containers fit score: Assess if your Tomcat applications are fit to migrate with Migrate to Containers. Migrate to Containers provides a fit assessment tool that you must run on the VMs hosting your Tomcat instances to compute a fit score and recommend a migration journey. Migrate to Containers uses a set of assessment rules to successfully migrate Tomcat applications.
  • Tomcat clustering: Tomcat clustering enables session replication across all Tomcat nodes in the cluster. Some clustering implementations, including the built-in McastService membership provider, don't work properly in Kubernetes due to lack of support for network-level multicast. That means that configuring Tomcat clustering requires some manual configuration during the migration. For more information, see ClusteringCloud on the Apache Tomcat wiki.
  • Tomcat proxy: In many real world scenarios, Tomcat might be configured to run behind a reverse proxy. The main uses of a reverse proxy include the following:
  • Java proxy: If you use a proxy server to control egress from Tomcat and Java applications, you can disable the Java proxy settings. Remove the proxy settings from the Java virtual machine (JVM) command-line options. Then, configure an Anthos Service Mesh (ASM) egress gateway to control egress networking from your Tomcat container.

Complete the assessment

After building the inventories related to your environment and your Tomcat workloads, complete the rest of the assessment phase activities documented in Migration to Google Cloud: Assessing and discovering your workloads. When you're done with that work, continue reading this document.

Plan and build your foundation

After following the guidance in Planning and building your foundation, complete your Tomcat foundation:

  1. Confirm that your Tomcat workloads and source environment meet the prerequisites for migrating a Tomcat workload.
  2. To complete the data collection phase, run mfit on the VMs running your Tomcat instances. For more information, see Using the fit assessment tool.

To provision and configure Migrate to Containers and its dependencies, see Set up Migrate to Containers.

When you're done with that work, continue reading this document.

Migrate your Tomcat applications to containers

In the deployment phase, use the following milestones to guide you.

Generate and review the migration plan

Create a Migrate to Containers migration plan for your Tomcat applications:

  1. Configure the source environments as Migrate to Containers migration sources: To migrate your Tomcat applications, Migrate to Containers needs information about the source environments where your VMs run. You gathered that information by performing the tasks described in the Build your inventories section within this document. For more information about configuring source environments, see Adding a migration source.

  2. Create a migration plan: To specify which Tomcat applications you want to migrate from a source environment to a supported target environment, create a migration plan. For example, you can configure where you want to store your persistent data.

    For more information about creating and monitoring migration plans, see Creating a migration. To create a migration plan for Tomcat applications, you use the migctl command-line tool as described in Executing a migration.

  3. Review and customize migration plans: After generating migration plans for each of the VMs you want to migrate, review and customize each plan to ensure that it fits your requirements. For more information about customizing migration plans, see Customizing a migration plan.

Generate migration artifacts and deployment descriptors

To generate the target Tomcat artifacts for your applications, Migrate to Containers extracts the applications running in the VMs you configured in the migration plans. It then creates several artifacts and places them in a Cloud Storage bucket. Migrate to Containers also generates the deployment descriptors that you can customize and use to deploy instances of the container images in the target environment.

For each migrated application, Migrate to Containers creates a folder containing the following:

  • Dockerfile
  • Application binaries
  • Tomcat configuration files
  • Build script
  • Skaffold YAML, for building and deploying
  • (Optional) secrets.sh script
  • (Optional) logging archive

You can monitor the progress of the container artifacts you create and migrate. For more information about monitoring a migration, see Monitoring migrated workloads.

Verify and validate the generated resources and descriptors

After you generate container artifacts and deployment descriptors with Migrate to Containers, review and update those artifacts and descriptors to ensure that they meet your requirements. For example, consider the following aspects:

  • Container image descriptors: Review the container image descriptors that you generated with Migrate to Containers and verify that they are sufficient for the container workload. If you need to update the base container image, update the FROM value in the generated Dockerfile. You may also change the CATALINA_OPTS environment variable in the Dockerfile to set or change JVM environment variables.
  • Application-level logging: Migrate to Containers automatically generates a modified logging archive, which you can use to modify your logging setting to write logs to the console instead of local files.

For more information about reviewing container artifacts and deployment descriptors, see Review the artifacts.

Deploy and validate the containerized workloads to GKE, GKE Autopilot, Cloud Run, or GKE Enterprise

When the deployment descriptors for your workloads are ready, you can perform the following tasks:

  1. Build an application container image: Build an application container image for your migrated workload. For instructions, see Build the container image.
  2. Deploy your migrated applications in the target environment:
  3. Monitor your migrated workloads: After deploying your Tomcat application container, you can gather data about how they are performing in the target environment. For more information, see Monitoring migrated workloads.
  4. Integrate your migrated workloads: After your workloads are deployed in the target environment, integrate the container artifact generation and deployment processes of the workloads with your deployment processes and pipelines. If you don't have an automated deployment process in place and are manually deploying your workloads, we recommend that you migrate from manual deployments to automated deployments.

Uninstall Migrate to Containers

After you complete the migration of your workloads with Migrate to Containers, we recommend that you take the following actions:

  1. Ensure that you have all the references to the artifacts that Migrate to Containers generated during the migration.
  2. Uninstall Migrate to Containers.

Optimize your environment after migration

To complete your migration, see Optimizing your environment.

You can perform these Tomcat-specific optimizations for your migrated Tomcat applications:

  • Adjust your logging: Unlike VMs where log files are normally written to the local file system, Kubernetes logs are normally streamed to stdout or stderr. The logs are then stored, analyzed, and queried through a dedicated backend, such as Cloud Logging. You can use the Migrate to Containers recommended changes in the logConfigs archive artifact or manually change your logging configuration to write logs to stdout or stderr.
  • Securing your sensitive data: Put passwords and any other sensitive data into Kubernetes Secrets. Use Kubernetes secrets to replace configuration placeholders at container start-up.
  • Tune your resource profile: To help Kubernetes schedule your Pods efficiently, fine-tune your resource constraints for both requests and limits. Fine tuning your resources to align with your JVM heap size is also critical to avoid out of memory (OOM) exceptions.
  • Control Pod placement: If your migrated Tomcat applications frequently communicate with each other, you may want to schedule them to run on the same nodes. If controlling pod placement would be beneficial for your migrated applications, see Assigning Pods to Nodes.

What's next