Customizing a migration plan

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

Edit the migration plan

You can edit the migration plan by using the migctl tool or the Google Cloud console.

migctl

You must download the migration plan before you can edit it:

  1. Download the migration plan. The plan is represented by Tomcat migration plan:

    migctl migration get my-migration
    
  2. Edit the downloaded migration plan, my-migration.yaml, in a text editor.

  3. When your edits are complete, save and upload the revised migration plan:

    migctl migration update my-migration --file my-migration.yaml
    
  4. Repeat these steps if more edits are necessary.

Console

Edit the migration plan in the Google Cloud console by using the YAML editor. The migration plan is represented by Tomcat migration plan:

  1. Open the Migrate to Containers page in the console.

    Go to the Migrate to Containers page.

  2. Click the Migrations tab to display a table containing the available migrations.

  3. In the row for your desired migration, select the migration Name to open the Details tab.

  4. Select the YAML tab.

  5. Edit the migration plan as necessary.

  6. When you are done editing, you can either:

    1. Save the migration plan. You will then have to manually execute the migration to generate the migration artifacts. Use the procedure shown in Executing a migration.

    2. Save and generate the artifacts. Execute the migration by using your edits to generate the migration artifacts. The process is the same as described in Executing a migration. You can then monitor the migration as described in Monitoring a migration.

CRD

You must download the migration plan, edit it, then apply it. The migration plan is stored inside the appXGenerateArtifactsConfig field of the AppXGenerateArtifactsFlowSpec CRD and represented by Tomcat migration plan:

  1. Get the name of the AppXGenerateArtifactsFlow:

    kubectl get migrations.anthos-migrate.cloud.google.com -n v2k-system -o jsonpath={.status.migrationPlanRef.name} my-migration

    The naming pattern is returned in the form of appx-generateartifactsflow-id.

  2. Get the migration plan by name and write to a file named my-plan.yaml:

    kubectl -n v2k-system get appxgenerateartifactsflows.anthos-migrate.cloud.google.com -o jsonpath={.spec.appXGenerateArtifactsConfig} appx-generateartifactsflow-id > my-plan.yaml
  3. Edit the migration plan as necessary.

  4. Apply the file:

    kubectl patch appxgenerateartifactsflows.anthos-migrate.cloud.google.com --type merge -n v2k-system --patch '{"spec": {"appXGenerateArtifactsConfig": '"$(jq -n --rawfile plan my-plan.yaml '$plan')"'}}' appx-generateartifactsflow-id

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

On 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 fromImage will contain an empty string.
  • Java version – The Java version is set using the information from the fit assessment collection. If CATALINA_BASE or CATALINA_HOME are entered manually, or if fit assessment failed to collect the Java version, the Java version is set to 11 by default.
  • Java vendor – The Java vendor is set to a constant: openjdk.

On the migration plan, the fromImage 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 which 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 fromImageTag in your migration plan using the following format:

tomcatServers:
    - name: latest
      . . .
      images:
        - name: tomcat-latest
          . . .
          fromImage: tomcat:9.0-jdk11-openjdk

Configure SSL

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

In order to upload the certificates to the repository you need to set the includeSensitiveData field on the migration plan to true. The secrets are uploaded in secrets.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: false
tomcatServers:
- name: latest-62afb0c1
  catalinaBase: /opt/tomcat/latest
  catalinaHome: /opt/tomcat/latest
  images:
  - name: tomcat-latest-docs-62afb0c1
    ...
    # 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

The migration will filter out the sensitive data paths defined in the sensitiveDataPaths field on the migration plan, Notice, if you remove a certificate path, the certificate will be uploaded to the image.

Webapps logging

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

Migrate to Containers will create 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).

Memory allocation

During the migration process, Migrate to Containers attempts to locate memory limits for the max heap of the Tomcat Java Heap on the source VMs. If memory limits are detected on a source VM, Migrate to Containers sets requests to initial andlimits to maximum for your migrated container.

These values are based on the Java maximum heap size (-Xmx/-XX:MaxHeapSize) value which is collected from the source instance using the fit-assessment (mfit). The values will be: limit=200%Xmx, request=125%Xmx.

If you want to specify the memory limits of applications migrated to individual containers, or if no memory limits were found in your source VMs, you can edit memory limits directly in your migration plan using the following format:

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

If memory limits have been defined in your migration plan, the Dockerfile that was generated alongside other artifacts after a successful migration will reflect 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 will allow the Tomcat Java heap allocation size to change according to any change with the pod memory limit.

Set Tomcat environment variables

If you would like to set CATLINA_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 catalineOpts field:

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

Migrate to Containers will parse 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 may 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.

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

Set Tomcat health probes

You can monitor the downtime and ready status of your managed containers by specifying probes in your Tomcat web server's 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 may send traffic to a container instance that is not ready. This can cause traffic loss. Kubelet may also not detect containers that are in a frozen state and will not 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 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 and share the same function as the corresponding fields of container-v1-core

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

  • 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 may act similarly to a liveness probe, but a readiness probe in the specifications indicates that a Pod will start without receiving any traffic and only start receiving traffic after the probe succeeds.

After discovery, the probe configuration is added to the migration plan. The probes can be used in their default configuration as shown below. To disable probes, remove the probes section from the 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.

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 pre-defined 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.

Next steps