Customize migration plan for JBoss servers

Important: The Migrate to Containers UI in the Google Cloud console, migctl, and CRDs that use processing clusters to migrate workloads to Google Cloud are now deprecated. They are supported for existing users until May 2024, after which they will no longer be available. If you're new to Migrate to Containers, then use the Migrate to Containers CLI to perform migrations on your local machine. For more information, see Migrate to Containers CLI architecture.

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 that 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 and have the migration plan file.

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.

   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 --main-config 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.

1. Open the Migrate to Containers page in the Google Cloud 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.

   Note: You can also select Download Migration Plan to download a local copy.

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.

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

Migration plan structure

The migration plan for a JBoss workload has the following structure, which you can customize as described in the following sections.

# Server name. Edit this to change the artifacts naming.
serverName: jboss-server
# JBoss home directory.
home: /opt/jboss/wildfly
# Parent Wildfly image for the generated container image.
fromImage: docker.io/jboss/wildfly:10.1.0.Final
# JBoss home directory in the target image.
targetImageHome: /opt/wildfly
# Configuration file path from source VM.
configurationFile: /opt/jboss/wildfly/standalone/configuration/standalone.xml
# Ports list to expose on the generated container image.
ports:
- name: management-http
  port: 9990
- name: management-https
  port: 9993
- name: ajp
  port: 8009
- name: http
  port: 8080
- name: https
  port: 8433
- name: txn-recovery-environment
  port: 4712
- name: txn-status-manager
  port: 4713
# List of deployments files to copy.
deployments:
  directory: /opt/jboss/wildfly/standalone/deployments
  applications:
  - test.war
# List of modules to copy in rsync filter format.
# Note: files under '/system/layers/base/' are JBoss/Wildfly binaries and should be copied only if they have been modified.
modules:
- '- system/layers/base'
# External paths required for running the JBoss server or apps.
additionalFiles: []
# Sensitive data which is filtered out of the container image.
# If includeSensitiveData is set to true the sensitive data is mounted on the container.
sensitiveData:
  includeSensitiveData: false
  sensitiveDataPaths:
  - /opt/jboss/wildfly/standalone/configuration/application-roles.properties
  - /opt/jboss/wildfly/standalone/configuration/application-users.properties
  - /opt/jboss/wildfly/standalone/configuration/application.keystore
  - /opt/jboss/wildfly/standalone/configuration/mgmt-groups.properties
  - /opt/jboss/wildfly/standalone/configuration/mgmt-users.properties

To add information as needed, review your migration plan details and guiding comments.

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 JBoss version. The JBoss version is detected and converted to a major version (minor versions are not supported). If we fail to detect a JBoss version, then fromImage will contain an empty string.

On the migration plan, the fromImage field represents the Docker Image tag used as the base of the container image.

The original JBoss 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 fromImage tag in your migration plan using the following format:

# Parent Wildfly image for the generated container image.
 fromImage: docker.io/jboss/wildfly:10.1.0.Final

The targetImageHome field specifies the path of the JBoss home directory in the target image, and is derived from the fromImage field. You don't need to change the value of this field unless you use a JBoss image with a different JBoss home value.

Specify applications

To exclude applications from the container image, remove them from the application list.

Specify modules

The module list contains a list of existing JBoss modules marked with either a plus or a minus sign. Only modules marked with a plus sign will be added to the generated container image. The modules that are marked with a minus sign, for examples, (/system/layers/base) are already present in the community image, and will not be overwritten unless you re-mark them with a plus sign.

Configure sensitive data migration

In order to upload sensitive data to the repository, you need to set the includeSensitiveData field on the migration plan to true. The secrets are uploaded in secrets.yaml.

The sensitiveDataPaths field specifies the lists of files to filter out from the migration plan. These files may contain sensitive information such as certificates, secret store, users, and passwords used by JBoss. If you remove a file path from the sensitiveDataPaths field, the file is uploaded to the image.

What's next

• Learn how to execute the migration.