# Customize migration plan for Tomcat servers

You should review the migration plan file that resulted from creating a migration.
Customize the file before executing the migration. The details of
your migration plan are used to extract the workload container artifacts from the source.

This section describes the contents of the migration and the kinds of
customizations you might consider before you execute the migration and generate
deployment artifacts.

## Before you begin

This topic assumes that you've already
[created a migration](https://docs.cloud.google.com/migrate/containers/docs/m2c-cli/create-a-migration-plan.md.txt)
and have the migration plan file.

## Edit the migration plan

After you have copied the file system and analyzed it, you can find the
migration plan in the new directory that is created in the specified output
path: <var translate="no">ANALYSIS_OUTPUT_PATH</var>/`config.yaml`.

Edit the migration plan as necessary and save the changes.

Review your migration plan's details and guiding comments to add information as needed.
Specifically, consider edits around the following sections.

## Specify the Docker image

In the migration plan, we generate a Docker community image tag based on the
Tomcat version, Java version, and Java vendor.

- **Tomcat version:** the Tomcat version is detected and converted to a major version (minor versions are not supported). If we fail to detect a Tomcat version, then `baseImage.name` contains an empty string.
- **Java version:** the Java version depends on the `java-version` parameter. It is set to `11` by default.
- **Java vendor:** the Java vendor is set to a constant: `temurin`.

For example, the Docker community image tag generated for Tomcat version 9.0,
Java version 11, and Java vendor `temurin` is `tomcat:9.0-jre11-temurin`.

In the migration plan, the `baseImage.name` field represents the Docker image
tag used as the base of the container image.

The original Tomcat and Java versions detected on the source VM are contained in
`discovery-report.yaml` that is generated by the initial discovery.

If you want to change the Docker community image, or provide your own Docker
image, you can modify the `baseImage.name` in your migration plan using the
following format:

```yaml
tomcatServers:
    - name: latest
      . . .
      images:
        - name: tomcat-latest
          . . .
          baseImage:
            name: BASE_IMAGE_NAME
```

Replace <var translate="no">BASE_IMAGE_NAME</var> with the Docker image that you want to use
as the base of the container image.

## Update Tomcat installation path

During the migration process, if your target image has a non default
`CATALINA_HOME` path, then you can specify a custom `CATALINA_HOME` path. Edit
the target `catalinaHome` field directly in your migration plan:

```yaml
tomcatServers:
  - name: latest
    . . .
    images:
      - name: tomcat-latest
        . . .
        baseImage:
          name: BASE_IMAGE_NAME
          catalinaHome: PATH
```

Replace <var translate="no">PATH</var> with the Tomcat installation path.

## Customize user and group

During the migration process, if your target image runs with a different user
and group than `root:root`, then you can specify a custom user and group
under which you want the application to run. Edit the user and group directly
in your migration plan:

```yaml
tomcatServers:
  - name: latest
    . . .
    images:
      - name: tomcat-latest
        . . .
        userName: USERNAME
        groupName: GROUP_NAME
```

Replace the following:

- <var translate="no">USERNAME</var>: the username that you want to use
- <var translate="no">GROUP_NAME</var>: the group name that you want to use

## Configure SSL

When you create a new Tomcat migration, a discovery process scans the server
against the different applications that are discovered.

After discovery, the following fields are automatically populated in the
migration plan:

- `excludeFiles`: lists the files and directories to exclude from the migration.

  By default, all the sensitive paths and certificates located during discovery
  are automatically added to this field and are excluded from the migration.
  If you remove a path from this list, then the file or directory is uploaded
  to the container image. To exclude a file or directory from the container
  image, add the path to this list.
- `sensitiveDataPaths`: lists all the sensitive paths and certificates located
  by the discovery process.

  To upload the certificates to the repository, set the `includeSensitiveData`
  field to `true`:

  ```yaml
  # Sensitive data which will be filtered out of the container image.
  # If includeSensitiveData is set to true the sensitive data will be mounted on the container.

  includeSensitiveData: true
  tomcatServers:
  - name: latest
    catalinaBase: /opt/tomcat/latest
    catalinaHome: /opt/tomcat/latest
    # Exclude files from migration.
    excludeFiles:
    - /usr/local/ssl/server.pem
    - /usr/home/tomcat/keystore
    - /usr/home/tomcat/truststore
    images:
    - name: tomcat-latest
      ...
      # If set to true, sensitive data specified in sensitiveDataPaths will be uploaded to the artifacts repository.
      sensitiveDataPaths:
      - /usr/local/ssl/server.pem
      - /usr/home/tomcat/keystore
      - /usr/home/tomcat/truststore
  ```

  After the migration is complete, the secrets are added to the secrets file
  `secrets.yaml` in the artifacts repository.

> [!NOTE]
> **Note:** In addition to the files and directories listed in the `excludeFiles` field, the directories `/bin`, `/lib`, `/temp`, `/logs`, and `/work` are also excluded from the container image.

## Webapps logging

Migrate to Containers supports logging with `log4j v2`, `logback` and
`log4j v1.x` that reside in `CATALINA_HOME`.

> [!IMPORTANT]
> **Important:** Paths outside of `CATALINA_HOME` are not supported.

Migrate to Containers creates an additional archive file with
modified log configurations and convert all file type appenders to console
appenders. You can use the content of this archive as a reference to enable
log collection and stream to a log collection solution (such as Google
Cloud Logging).

> [!NOTE]
> **Note:** When migrating to a container image, Migrate to Containers filters out the `logs` directory from the Tomcat server to omit old logs.

## Memory allocation

During the migration process, you can specify the memory limits of applications
migrated to individual containers.
Edit the memory limits directly in your migration plan using the following
format:

```yaml
tomcatServers:
    - name: latest
      . . .
      images:
        - name: tomcat-latest
          . . .
          resources:
            memory:
              limit: 2048M
              requests: 1280M
```

The recommended value for `limit` is 200% of `Xmx`, which is the maximum Java
heap size. The recommended value for `requests` is 150% of `Xmx`.

To see the value of `Xmx`, run the following command:

    ps aux | grep catalina

If memory limits have been defined in your migration plan, the Dockerfile that
was generated alongside other artifacts after a successful migration reflects
your declaration:

    FROM tomcat:8.5-jdk11-openjdk

    # Add JVM environment variables for tomcat
    ENV CATALINA_OPTS="${CATALINA_OPTS} -XX:MaxRAMPercentage=50.0 -XX:InitialRAMPercentage=50.0 -XX:+UseContainerSupport <additional variables>"

This defines the initial and maximum size to be 50% of limit value. This enables
the Tomcat Java heap allocation size to change according to any change with the
pod memory limit.

> [!NOTE]
> **Note:** If the `catalinaOpts` field contains a `-Xms/InitialRAMPrecentage/InitialRAMFraction/InitialHeapSize` variable, the `InitialRAMPercentage=50` environment variable isn't set.

## Set Tomcat environment variables

If you would like to set `CATALINA_OPTS` in the Dockerfile that was
generated alongside other artifacts after a successful migration,
you can first add to the `catalinaOpts` field in your migration plan. The
following example shows an updated `catalinaOpts` field:

```yaml
tomcatServers:
    - name: latest
      . . .
      images:
        - name: tomcat-latest
          . . .
          resources:
            . . .
          catalinaOpts: "-Xss10M"
```

Migrate to Containers parses your `catalinaOpts` data to your
Dockerfile. The following example shows the output of the parsing:

    FROM 8.5-jdk11-openjdk-slim

    ## setenv.sh script detected.
    ## Modify env variables on the script and add definitions to the migrated
    ## tomcat server, if needed (less recommended than adding env variables directly
    ## to CATALINA_OPTS) by uncomment the line below
    #ADD --chown=root:root setenv.sh /usr/local/tomcat/bin/setenv.sh

    # Add JVM environment variables for the tomcat server
    ENV CATALINA_OPTS="${CATALINA_OPTS} -XX:MaxRAMPercentage=50.0 -XX:InitialRAMPercentage=50.0 -Xss10M"

You might also set Tomcat environment variables using the `setenv.sh` script,
which is located in the `/bin` folder on your Tomcat server. For more
information about Tomcat environment variables, see the
[Tomcat documentation](https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt).

If you choose to use `setenv.sh` for setting your Tomcat environment
variables, then you need to edit the Dockerfile.

> [!NOTE]
> **Note:** If you set `-Xmx`, it overwrites `-XX:MaxRAMPercentage`. If you set `-Xms`, it overwrites `-XX:InitialRAMPercentage`.

> [!NOTE]
> **Note:** Migrate to Containers and GKE don't evaluate `setenv.sh` content. As a result, it is recommended that you add your Tomcat environment variables to `CATALINA_OPTS` directly.

## Set Tomcat health probes

You can monitor the downtime and ready status of your managed containers by
specifying probes in your Tomcat web server migration plan. Health probe
monitoring can help reduce the downtime of migrated containers and provide
better monitoring.

Unknown health states can create availability degradation, false-positive
availability monitoring, and potential data loss. Without a health probe,
kubelet can only assume the health of a container and might send traffic to a
container instance that is not ready. This can cause traffic loss. Kubelet might
also not detect containers that are in a frozen state and doesn't restart them.

A health probe functions by running a small scripted statement when the
container starts. The script checks for successful conditions, which are
defined by the type of probe used, every period. The period is defined in the
migration plan by a `periodSeconds` field. You can run or define these scripts
manually.

To learn more about kubelet probes, see [Configure Liveness, Readiness and Startup Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) in the
Kubernetes documentation.

There are two types of probes available to configure, both probes are
probe-v1-core defined in [probe-v1-core reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#probe-v1-core)
and share the same function as the corresponding fields of
[container-v1-core](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#container-v1-core)

- **Liveness probe:** Liveness probes are used to know when to restart a container.

  <br />

  > [!NOTE]
  > **Note:** If a process in your container can crash on its own when it encounters an issue, or becomes unhealthy, you don't necessarily need a liveness probe. The kubelet automatically performs the correct action in accordance with the Pod's `restartPolicy`.

- **Readiness probe:** Readiness probes are used to know when a container is ready to start accepting traffic. To start sending traffic to a Pod only when a probe succeeds, specify a readiness probe. A readiness probe might act similarly to a liveness probe, but a readiness probe in the specifications indicates that a Pod starts without receiving any traffic and only start receiving traffic after the probe succeeds.

<br />

After discovery, the probe configuration is added to the migration plan. The
probes can be used in their default configuration as shown in the following
example. To turn off the probes, remove the `probes` section from the YAML file.

```yaml
tomcatServers:
- name: latest
  images:
  - name: tomcat-latest
    ports:
    - 8080
    probes:
      livenessProbe:
        tcpSocket:
          port: 8080
      readinessProbe:
        tcpSocket:
          port: 8080
```

You can change this migration plan to use an existing Tomcat HTTP endpoint.

```yaml
tomcatServers:
- name: latest
  images:
  - name: tomcat-latest
    ports:
    - 8080
    probes:
      livenessProbe:
       httpGet:
          path: /healthz
          port: 8080
          httpHeaders:
          - name: Custom-Header
            value: Awesome
        initialDelaySeconds: 3
        periodSeconds: 3
      readinessProbe:
        httpGet:
        tcpSocket:
          port: 8080
```

There are four predefined ways to check a container using a probe. Each probe
must define exactly one of these four mechanisms:

- `exec`: Executes a specified command inside the container. Execution is considered successful if the exit status code is 0.
- `grpc`: Performs a remote procedure call using \`gRPC\`. \`gRPC\` probes are an alpha feature.
- `httpGet`: Performs an HTTP GET request against the Pod's IP address on a specified port and path. The request is considered successful if the status code is greater than or equal to 200 and less than 400.
- `tcpSocket`: Performs a TCP check against the Pod's IP address on a specified port. The diagnostic is considered successful if the port is open.

By default, a migration plan enables the `tcpSocket` probing method. Use the
manual configuration of your migration plan to use a different probing methods.
You can also define custom commands and scripts through the migration plan.

To add external dependencies for the readiness probe, while using the default
liveness probe, define an exec readiness probe and a script that implements the
logic.

## Verify Tomcat clustering configuration

Tomcat clustering is used to replicate session information across all Tomcat
nodes, which lets you to call any of the backend application servers and not lose
client session information. To learn more about clustering configuration,
see [Clustering/Session Replication How-To](https://tomcat.apache.org/tomcat-8.5-doc/cluster-howto.html)
in the Tomcat documentation.

Tomcat clustering class is called `SimpleTcpListener`, which uses multicast
heartbeat messages for peer discovery. Cloud environments don't support multicast,
so you must change the clustering configuration or remove it, when possible.

When a load balancer is configured to run and maintain a sticky session to the
backend Tomcat server, it can use the `jvmRoute` property configured in the
server.xml `Engine` configuration.

If your source environment is using an unsupported clustering configuration,
modify the `server.xml` file to either disable the configuration, or use a
supported configuration.

- **Tomcat v8.5 or above:** Clustering must be disabled on Tomcat version 8.5. To disable clustering, you need to comment out the `<Cluster ... />` section in `server.xml`.
- **Tomcat v9 or above:** In Tomcat version 9 or later, you can enable the
  `Cluster` class using `KubernetesMembershipService`.
  `KubernetesMembershipService` is a Kubernetes specific class,
  which uses the Kubernetes APIs for peer discovery.

  - **Kubernetes provider:** The following is a sample configuration for a
    Kubernetes provider:

        <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster">
        <Channel className="org.apache.catalina.tribes.group.GroupChannel">
        <Membership className="org.apache.catalina.tribes.membership.cloud.CloudMembershipService" membershipProviderClassName="org.apache.catalina.tribes.membership.cloud.KubernetesMembershipProvider"/>
        </Channel>
        </Cluster>

  - **DNS provider:** Use the `DNSMembershipProvider` to use the DNS APIs
    for peer discovery. The following is a sample configuration for a DNS
    provider:

        <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster">
        <Channel className="org.apache.catalina.tribes.group.GroupChannel">
        <Membership className="org.apache.catalina.tribes.membership.cloud.CloudMembershipService" membershipProviderClassName="org.apache.catalina.tribes.membership.cloud.DNSMembershipProvider"/>
        </Channel>
        </Cluster>

  - **jvmRoute:** When your load balancer relies on a jvmRoute value, the
    value should be changed from static to using the POD name. This configures
    Tomcat to add a suffix to the session cookie with the POD name. This can
    be used by the frontend load balancer to direct traffic to the correct
    Tomcat POD. Change the value in the `server.xml` file to use the
    following:

        <Engine name="Catalina" defaultHost="localhost" jvmRoute="${HOSTNAME}">

## Verify Tomcat proxy configuration

If Tomcat is configured to run behind a reverse proxy, or using several proxy
configuration settings in the `Connector` section of `server.xml`, you must
verify that the same proxy configurations are still applicable once migrated to
run in Kubernetes.

To run a functional containerized Tomcat application, choose one of the
following configuration changes to the reverse proxy configuration:

- **Disable proxy configuration:** If the migrated application no longer runs behind a reverse proxy, you can disable proxy configuration by removing `proxyName` and `proxyPort` from the connector configuration.
- **Migrate the proxy:** Migrate the proxy VM and retain all the existing Tomcat configurations.
- **Configure Ingress to replace the reverse proxy:** If no custom or
  sophisticated logic has been implemented for your reverse proxy, you can
  configure an Ingress resource to expose your migrated Tomcat application. This
  process uses the same FQDN that was used prior to the migration. To configure
  an Ingress, you must verify that your Tomcat Kubernetes Service is of
  `type: Nodeport`. The following is a sample configuration of an Ingress:

  ```yaml
  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: my-tomcat-ingress
  spec:
    rules:
    - host: APP_DOMAIN
      http:
        paths:
        - pathType: ImplementationSpecific
          backend:
            service:
              name: my-tomcat-service
              port:
                name: my-tomcat-port
  ```

  > [!NOTE]
  > **Note:** If the reverse proxy was used to offload SSL traffic, you might want to configure your Ingress using SSL certificates. To learn more about using SSL certificates, see [Using multiple SSL certificates in HTTPS load balancing with Ingress](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/ingress-multi-ssl).

- **Configure a Cloud Service Mesh with Cloud Load Balancing:** If you are using
  GKE Enterprise, you can choose to expose your application using
  Cloud Service Mesh. To learn more about exposing service mesh applications,
  see [From edge to mesh: Exposing service mesh applications through GKE Ingress](https://docs.cloud.google.com/architecture/exposing-service-mesh-apps-through-gke-ingress.md.txt).

## Verify Java proxy configuration

When migrating to containers, you must verify the availability of your proxy
servers in your new environment. When the proxy server is not available, choose
one of the following configuration changes to the proxy:

- **Disable proxying:** If the original proxy is no longer in use, then disable the proxy configuration. Remove all the proxy settings from either the `setenv.sh` script, or from the configuration file where they are maintained on your Tomcat server.
- **Change proxy settings:** If your Kubernetes environment is using a different egress proxy, you can change your proxy settings in `setenv.sh`, or other file, to point at the new proxy.

## What's next

- Learn how to [execute the migration](https://docs.cloud.google.com/migrate/containers/docs/m2c-cli/execute-the-migration-plan.md.txt).