Customizing a migration plan

You should review the migration plan file that results from creating a migration, and customize it before proceeding to execution. The details of your migration plan are used to extract the workload's container artifacts from the source VM, and also to generate Kubernetes deployment files that you can use to deploy the container image to other clusters, such as a production cluster.

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

Prerequisites

• This topic assumes that you've already created a migration and have the resulting migration plan file.

Editing the migration plan

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

Note: For migrations with an intent set to Data or ImageAndData, you must edit the migration plan to set the dataVolumes field with a list of folders to include in the volume. See Setting handling for the data volume below for more.

migctl

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

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

   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 the GenerateArtifactsFlow CRD:

1. Open the Migrate for Anthos and GKE page in the 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 represented by the GenerateArtifactsFlow CRD:

1. Get the name of the GenerateArtifactsFlow:

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

   The naming pattern is returned in the form of generate-artifacts-flow-id.

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

   kubectl get generateartifactsflows.anthos-migrate.cloud.google.com -n v2k-system generate-artifacts-flow-id -o yaml > my-plan.yaml

3. Edit the migration plan as necessary.

4. Apply the file:

   kubectl apply -f my-plan.yaml

Impact of Intent on migration plan

The contents of the migration plan you generated will differ depending on the kind of migration you created with the Intent flag.

This topic describes the purpose of each migration plan section. Each section indicates which Intent value is relevant for YAML in the section. For more information on using the Intent flag, see Creating a migration.

Specifying content to exclude from the migration

Intent: Any

By default, Migrate for Anthos and GKE excludes typical VM content that isn't relevant in the context of GKE. You can customize that filter.

The filters field value lists paths that should be excluded from migration and will not be part of either the container image or the data volume. The field's value lists rsync filter rules that specify which files to transfer and which to skip. Preceding each path and file with a minus sign specifies that the item in the list should be excluded from migration. The list is processed according to the order of lines in the YAML, and exclusions/inclusions are evaluated accordingly.

For more, see the INCLUDE/EXCLUDE PATTERN RULES section of the rsync manpage

Files that are too large to be included in the docker image will be listed in the YAML file. This will flag files that are larger than 1GB for your consideration. Docker images that are too large, or greater than 15GB, are at risk of failure during migration.

You can edit the YAML list to add or remove paths. See an example YAML below, which includes example exclusions, as well as notifications for large and sparse files. Follow the inline guidance to either:

• Exclude the detected folders by uncommenting them and placing them under the global filters section.
• Move the detected folders to to a persistent volume by uncommenting them and placing them under the data folder section.

You may also consider excluding or moving the detected sparse files in the same manner.

  global:
    # Files and directories to exclude from the migration, in rsync format.
    filters:
      - "- *.swp"
      - "- /etc/fstab"
      - "- /boot/"
      - "- /tmp/*"
      - "- /var/log/*.log*"
      - "- /var/log/*/*.log*"
      - "- /var/cache/*"
      
    ## The data folders below are too large to be included in the docker image.
    ## Consider uncommenting and placing them under either the global filters
    ## or the data folder section.
      # - '- /a' # (1.8GB, last access 2022-02-02 10:50:30, last modified 2020-02-02 10:50:30)
      # - '- /a/c' # (1.8GB, last access 2022-02-02 10:50:30, last modified 2020-02-02 10:50:30)
      
    ## Sparse files will fail the run of a docker image. Consider excluding the below
    ## detected files and any other sparse files by uncommenting and placing them in 
    ## the global filters section, or export them to a persistent volume by specifying 
    ## them in the data folder section.
      # - '- /a/b' # (1.8GB, last access 2022-02-02 10:50:30, last modified 2020-02-02 10:50:30)
      # - '- /a/d' # (1.8GB, last access 2022-02-02 10:50:30, last modified 2020-02-02 10:50:30)

Setting handling for the data volume

Intent: Data or ImageAndData

The dataVolumes field specifies a list of folders to include in the data volume as part of the migration. You must edit this list for a migration with an intent of Data or ImageAndData.

Note: The filters field described above specifies the folder paths to exclude from the migration. These filters are applied to the migration before the dataVolumes section. Therefore if a folder is excluded by one of the rules in the filters list, it is excluded from the exported data volume as well.

By default, folders contains a placeholder value that you must change. If you do not change the placeholder value, you get an error when you generate the migration artifacts, in the form Replace the folder placeholder with the relevant path:

        dataVolumes:
        
        # Folders to include in the data volume, e.g. "/var/lib/mysql"
        # Included folders contain data and state, and therefore are automatically excluded from a generated container image
        # Replace the placeholder with the relevant path and add more items if needed
        - folders:
          - <folders>

Shown below is an example that specifies a list of folders to include in the data volume:

        - folders:
          - /var/lib/mysql
          - /my-data-folder

Setting the migration's name and namespace

Intent: Any

Using the metadata field, you can specify the name and namespace for the migration. By default, Migrate for Anthos and GKE uses the values you specified when you created the migration. (You should not change the kind and apiVersion values.) The fields are the same for all intent values.

• name -- Name of the migration.
• namespace -- Namespace for the migration defined in this YAML file. It should be v2k-system.

  apiVersion: anthos-migrate.cloud.google.com/v1beta2
  kind: GenerateArtifactsFlow
  metadata:
    name: generate-artifacts-flow-id
    namespace: v2k-system

Setting the name of the container image

Intent: Image or ImageAndData

The image field value defines the names and locations of two images created from a migrated VM. You can change these values if you prefer to use other names.

During migration, Migrate for Anthos and GKE copies files and directories representing your migrating workload to (by default) Container Registry for use during migration. The migration process adapts the extracted workload to an image runnable on GKE.

Migrate for Anthos and GKE preserves files and directories from the original VM (at the base path) in the registry. This image functions as a non-runnable base layer that includes the extracted workload files, which are then combined with the Migrate for Anthos and GKE runtime software layer to build an executable container image.

The use of separate layers simplifies later updates to the container image by allowing separate updates to the base layer or to the Migrate for Anthos and GKE software layer, as needed.

This image isn't runnable, but makes it possible for Migrate for Anthos and GKE to update the container from that original when you upgrade Migrate for Anthos and GKE.

The base and name field values specify images created in the registry.

• base -- Name of the image that is created from the VM files and directories copied from the source platform. This image is not runnable on GKE because it hasn't been adapted for deployment there.
• name -- Name of the runnable image that is used for the container. This image contains both the content from the source VM, and the Migrate for Anthos and GKE runtime, which allows it to be runnable.

        image:
          # Review and set the name for extracted non-runnable base image,
          # if an image tag is not specified, a random tag is auto-generated when the image is built.
          base: "gcr.io/my-project/centos-mini-non-runnable-base"

          # Review and set the name for runnable container image,
          # if an image tag is not specified, a random tag is auto-generated when the image is built.
          name: "gcr.io/my-project/centos-mini"

By default, a tag corresponding to the timestamp of the migration is automatically applied to these values. This tag is in the form:

MM-DD-YYYY--hh:mm:ss

To apply your own tag, overriding the default tag, edit the CRD and add it as shown below:

        image:
          # Review and set the name for extracted non-runnable base image,
          # if an image tag is not specified, a random tag is auto-generated when the image is built.
          base: "gcr.io/my-project/centos-mini-non-runnable-base:tag"

          # Review and set the name for runnable container image,
          # if an image tag is not specified, a random tag is auto-generated when the image is built.
          name: "gcr.io/my-project/centos-mini:tag"

Note: Because the tag is used to cache the values, ensure that the tag is unique for all GenerateArtifactsFlow CRDs.

Setting the Cloud Storage location for deployment artifacts

Intent: Any

During migration, Migrate for Anthos and GKE uses Cloud Storage to store files that you'll later use to deploy your VM on a production cluster. You can change the bucket and folder names to use your own.

• bucket -- Name of the Cloud Storage bucket in which to store artifacts.
• folder -- Name of the folder inside bucket in which to store artifacts.
• appName -- Name to give the Kubernetes controller to use in the deployment file. The type of controller will differ based on the value you specified for the intent flag when you created the migration:
  • For an image-and-data value, the result is a StatefulSet object with this name.
  • For an image value, the result is a Deployment object with this name.

        deployment:
 
         # Review and set the app-name for your StatefulSet or Deployment YAML spec
         appName: app-centos-mini

         # Artifacts are uploaded to the project-default artifacts repository.
         # In order to specify a custom repository, uncomment the lines below and replace the placeholders with the relevant values
         # artifactsRepository:
         #   spec:
         #     bucket: bucket_name
         #     credentials:
         #       type: gcs
         #       secret: secret

         folder: storage-folder-name/

Configuring persistent storage

Intent: Data or ImageAndData

For Data or ImageAndData migration intents, the migration plan includes a pvc definition with default values. You can change these values to match the needs of your system.

   pvc:
     spec:
       accessModes:
       - ReadWriteOnce
       resources:
         requests:
         # Modify the required disk size on the storage field below based on the capacity needed
           storage: 10G

Note: When using Anthos clusters on AWS to migrate Linux VMs, the source VM might reference an encrypted EBS volume. If you want to export data to an encrypted volume, ensure you edit the migration plan accordingly. See Prerequisites for migrating Linux VMs using AWS processing clusters for more.

Customizing the services list

Intent: Image or ImageAndData

By default, Migrate for Anthos and GKE disables unneeded services on a VM when you migrate it to a container. These services can sometimes cause issues with the migrated container, or are not needed in a container context.

Along with the services automatically disabled by Migrate for Anthos and GKE, you can optionally disable other services:

• Migrate for Anthos and GKE automatically discovers services that you can optionally disable and lists them in the migration plan. These services, such as ssh or a web server, might not be required in your migrated workload but it is up to you to make that decision. If necessary, edit the migration plan to disable these services.

• Migrate for Anthos and GKE does not list all services running on the source VM. For example, it omits operating-system related services. You can optionally edit the migration plan to add your own list of services to disable in the migrated container.

The systemServices field specifies the list of services discovered by Migrate for Anthos and GKE. For example:

    systemServices:
    - enabled: true|false
      name: service-name
    - enabled: true|false
      name: service-name
      ...

To disable a service, set enabled to false.

Migrate for Anthos and GKE does not list all services running on the source VM, such as operating-system related services. You can also add additional services to the list. For example, to disable service2 and the cron service:

    systemServices:
    - enabled: true
      name: service1
    - enabled: false
      name: service2
    - enabled: false
      name: cron

When you execute a migration to generate the migration artifacts, Migrate for Anthos and GKE creates the blocklist.yaml file. This file lists the container services to disable based on your settings in the migration plan. For example:

service_list:
- name: disabled-services
  services:
  # Because you used systemServices above to disabled service2 and cron:
  - service2
  - cron

To later modify the list of disabled services:

• Edit the list of services in the migration plan.
• Execute the migration to regenerate the migration artifacts, including an updated blocklist.yaml file, deployment_spec.yaml file, and Dockerfile.

Alternatively, after you execute a migration to generate the migration artifacts, you can edit the blocklist.yaml file directly, and then rebuild and push the container image yourself. For example:

1. Update the blocklist.yaml file.

2. Rebuild and push the container image.

   The way you rebuild and push the container image depends on your build environment. You can use:

   1. gcloud to rebuild the image and push it to the Container Registry as described at Quickstart: Build.
   2. docker build as described at Build and run your image.

3. After you rebuild and push the new image, open the deployment_spec.yaml file in an editor to update the image location:

   spec:
    containers:
      - image: new-image-location
   

   For example, new-image-location could be gcr.io/my-project/my-new-image:v1.0 if you used gcloud to rebuild the image and push it to the Container Registry.

Customizing Service endpoints

Intent: Image or ImageAndData

The migration plan includes the endpoints array that defines the ports and protocols used to create the Kubernetes Services provided by the migrated workload. You can add, edit, or delete endpoint definitions to customize the migration plan.

Note: To auto-generate the entries in the endpoints array, you must first run the fit assessment tool.

For each Service endpoint detected, Migrate for Anthos and GKE adds the following definition to the migration plan:

    endpoints:
    - port: PORT_NUMBER
      protocol: PORT_PROTOCOL
      name: PORT_NAME

Where:

• PORT_NUMBER specifies the container port number to which requests to the service are routed.
• PORT_PROTOCOL specifies the port protocol, such as HTTP, HTTPS, or TCP. See Supported protocols for the complete list of protocols.
• PORT_NAME specifies the name used to acccess the Service endpoint. Migrate for Anthos and GKE generates a unique PORT_NAME for each generated endpoint definitions.

For example, Migrate for Anthos and GKE detects the following endpoints:

  endpoints:
    - port: 80
      protocol: HTTP
      name: backend-server-nginx
    - port: 6379
      protocol: TCP
      name: backend-server-redis

To set the value of the name property, Migrate for Anthos and GKE combines the source VM name, backend-server in this example, with the program name of the Service. The generated names are compatible with Kubernetes naming conventions, and are unique within the migration plan. For example, the migration plan above creates a Service that targets Nginx on port 80 over HTTP.

For any duplicates names, Migrate for Anthos and GKE appends a counter suffix. For example, if Nginx is associated with two ports, it adds the -2 suffix to the name in the second definition:

  endpoints:
    - port: 80
      protocol: HTTP
      name: backend-server-nginx
    - port: 8080
      protocol: HTTPS
      name: backend-server-nginx-2
    - port: 6379
      protocol: TCP
      name: backend-server-redis

When you execute a migration to generate the migration artifacts, Migrate for Anthos and GKE creates a Service definition in the deployment_spec.yaml file for each endpoint.

For example, shown below is a Service definition in the deployment_spec.yaml file:

apiVersion: v1
kind: Service
metadata:
  creationTimestamp: null
  name: backend-server-nginx
spec:
  ports:
  - port: 80
    protocol: HTTP
    targetPort: 80
  selector:
    app: backend-server
status:
  loadBalancer: {}

Customizing NFS mounts

Intent: Image or ImageAndData

Migrate for Anthos and GKE includes NFS mounts in the generated migration plan. This information is collected from the fstab file and written to the nfsMounts array in the migration plan. You can add or edit NFS mount point definitions to customize the migration plan.

Note: The entries in nfsMounts array are disabled by default. You must enable them if you want Migrate for Anthos and GKE to generate entries in the deployment_spec.yaml file for each NFS mount.

When generating the migration plan, Migrate for Anthos and GKE:

• Ignores NFS mounts for /sys and /dev.
• Ignores NFS mounts with a type other than nfs or nfs4.

Each NFS mount in the migration plan includes the server's IP address or DNS name and local mount path in the form:

    nfsMounts:
    - mountPoint: MOUNT_POINT
      exportedDirectory: DIR_NAME
      nfsServer: IP_OR_DNS
      mountOptions:
         - OPTION_1
         - OPTION_2
      enabled: false|true

Where:

• MOUNT_POINT specifies the mount point obtained from fstab.
• DIR_NAME specifies the name of the shared directory.
• IP_OR_DNS specifies the IP address or DNS name of the server hosting the mount point.
• OPTION_N specifies any options extracted from the fstab for the mount point.

For example, for the following entry in fstab:

<file system>       <mount point>   <type>  <options>   <dump>  <pass>
10.49.232.26:/vol1  /mnt/test       nfs     rw,hard     0       0

Migrate for Anthos and GKE generates the following entry in the migration plan:

    nfsMounts:
    - mountPoint: /mnt/test
      exportedDirectory: /vol1
      nfsServer: 10.49.232.26
      mountOptions:
         - rw
         - hard
      enabled: false

To configure Migrate for Anthos and GKE to process entries in the nfsMounts array, set enabled to true for the mountPoint entry. You can enable one, some, or all mountPoints entries, edit the entries, or add your own entries.

When you execute a migration to generate the migration artifacts, Migrate for Anthos and GKE creates a volumes and volumeMounts definition and a PersistentVolume and PersistentVolumeClaim definition in the deployment_spec.yaml file for each enabled NFS mount.

Note: Migrate for Anthos and GKE requires that NFS servers be accessible from the deployment cluster hosting the migrated container workload. However, Migrate for Anthos and GKE does not validate that connectivity. A migrated container with a connectivity issue cannot be started and you might have to edit the deployment_spec.yaml file to fix the issue. See Accessing file shares from Google Kubernetes Engine clusters for more information.

For example, shown below is a volumeMounts definition in the deployment_spec.yaml file:

    spec:
      containers:
          - image: gcr.io/myimage-1/image-name
            name: some-app
            volumeMounts:
                   - mountPath: /sys/fs/cgroup
                     name: cgroups
                   - mountPath: /mnt/test
                     name: nfs-pv

Where the value of name is a unique identifier generated by Migrate for Anthos and GKE.

Shown below is an example PersistentVolumeClaim and PersistentVolume definitions in the deployment_spec.yaml file:

apiVersion: v1
kind: PersistentVolumeClaim
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Mi
  storageClassName: ""
  volumeName: nfs-pv

apiVersion: v1
kind: PersistentVolume
metadata:
  name: nfs-pv
spec:
  mountOptions:
    - rw
    - hard
  nfs:
    path: /vol1
    server: 10.49.232.26

Customizing log data written to Cloud Logging

Intent: Any

Typically a source VM writes information to one or more log files. As part of migrating the VM, you can configure the migrated workload to write that log information to Cloud Logging.

Note: Previous releases of Migrate for Anthos and GKE supported customizing logging by using a ConfigMap on your target workload cluster, as described in Configuring logging to Cloud Logging. This section describes how to use the logs.yaml file to configure logging. If the logs.yaml file exists, logging settings defined by a ConfigMap are ignored.

When you generate the migration plan, Migrate for Anthos and GKE automatically searches for log destination files on the source VM. Migrate for Anthos and GKE then writes information about those detected files to the logPaths area of the migration plan:

spec:
    ...
    logPaths:
    - appName: APP_NAME
      globs:
      - LOG_PATH

For example:

spec:
    ...
    logPaths:
    - appName: tomcat
      globs:
      - /var/log/tomcat*/catalina.out

When you generate the migration artifacts, Migrate for Anthos and GKE generates the logs.yaml file from the migration plan. This file contains the list of log files detected on the source VM. For example, from the logsPath definition above, logs.yaml contains:

logs:
  tomcat:
  - /var/log/tomcat*/catalina.out

In this example, when you deploy the migrated workload, log information written to catalina.out is automatically written to Cloud Logging.

Entries each appear on a line in the log in the following form:

DATE TIME APP_NAME LOG_OUTPUT

The following example illustrates the form with an entry from Tomcat:

2019-09-22 12:43:08.681193976 +0000 UTC tomcat log-output

To configure logging, you can either:

• Edit the migration plan before you generate the migration artifacts to add, remove, or edit logPaths entries. When you generate the migration artifacts, these edits are reflected in the logs.yaml file.

• Edit logs.yaml after you generate the migration artifacts to add, remove, or edit logs entries.

The advantage to editing the migration plan is that your edits are reflected in logs.yaml every time you generate the artifacts. If you edit logs.yaml directly, then regenerate the artifacts for some reason, you have to reapply your edits to logs.yaml.

Next Steps

• Execute a migration