migctl reference

migctl is a command-line tool for setting up and managing a Migrate to Containers migration environment on Google Cloud:

For a step-by-step introduction to key migctl commands and to make a simple migration, see Quickstart.

migctl

Command Description
artifacts-repo Configure an artifacts repository
completion Generate bash completion scripts
debug Troubleshooting commands
debug collect-info Download collect_sysreport.sh, the Sysreport script
docker-registry Configure a Docker registry
doctor Check Migrate to Containers deployment status and related configuration
help Help about any command
logging Configure logging
migration Migration operations
setup Install or uninstall Migrate to Containers
source Manage references to the migration source
version Print version for Migrate to Containers, and for migctl

Synopsis

migctl [-h]

Flags

-h, --help
Help for this command.

Notes

migctl included in Cloud Shell

migctl artifacts-repo

Command Description
migctl artifacts-repo create Create an artifacts repository configuration.
migctl artifacts-repo update Update an artifacts repository configuration.
migctl artifacts-repo delete Delete an artifacts repository configuration.
migctl artifacts-repo list List the artifacts repository configurations.
migctl artifacts-repo set-default Set the default artifacts repository configuration.

See also

Defining data repositories

migctl artifacts-repo create

Create an artifacts repository configuration.

Synopsis

migctl artifacts-repo create gcs|s3|basic-auth repository-name flags

Positional arguments

repository-name

Name of the artifacts repository configuration.

Flags

-h, --help

Help for this command.

The remaining flags are based on the type of registry:

  • Cloud Storage

    migctl artifacts-repo create gcs repository-name --bucket-name bucket-name  --json-key=m4a-install.json

    where:

    • repository-name is the user-defined name of the artifacts repository configuration.

    • bucket-name specifies an existing bucket in the Cloud Storage repository. If you do not have an existing bucket, create one using the instructions at Create buckets.

      Note: When installing Migrate to Containers on clusters on Google Cloud, the Migrate to Containers installer automatically creates a default bucket named:

      PROJECT-migration-artifacts

    • m4a-install.json is the name of the JSON key file for the service account for accessing Container Registry and Cloud Storage as described in Configuring a service account.

  • S3

    migctl artifacts-repo create s3 repository-name --bucket-name bucket-name --region aws-region --access-key-id=key-id

    You're prompted to enter the secret key for key-id.

    Alternatively, specify the path to a credentials file:

    migctl artifacts-repo create s3 repository-name --bucket-name bucket-name --region aws-region --credentials-file-path file-path 

    where:

    • repository-name is the user-defined name of the artifacts repository configuration.

    • bucket-name specifies an existing bucket in the S3 repository. If you do not have an existing bucket, create one using the instructions at Working with Amazon S3 Buckets.

    • aws-region specifies the AWS region for the repository. The processing cluster and the repository can be in separate regions as long as the cluster has permissions to access the repository.

    • key-id specifies the access key. See Managing access keys for IAM users for more.

    • file-path specifies the path to a CSV file, downloaded from the AWS console, containing the credentials.

Examples

  • Cloud Storage

    migctl artifacts-repo create gcs myRepository --json-key=m4a-install.json
  • S3

    migctl artifacts-repo create s3 myRepository --bucket-name bucket-name --region aws-region --access-key-id=key-id

migctl artifacts-repo update

Update an artifacts repository configuration.

Synopsis

migctl artifacts-repo update gcs|s3|basic-auth repository-name same-flags-as-create

Positional arguments

repository-name

Name of the artifacts repository configuration.

Flags

same-flags-as-create

Specify the same flags for updating the registry configuration as you used to create it as shown in migctl artifacts-repo create.

migctl artifacts-repo delete

Delete an artifacts repository configuration.

Synopsis

migctl artifacts-repo delete repository-name

Positional arguments

repository-name

Name of the artifacts repository configuration.

Flags

-h, --help

Help for this command.

migctl artifacts-repo list

List the currently configured repositories, including the current default.

Synopsis

migctl artifacts-repo list

Flags

-h, --help

Help for this command.

migctl artifacts-repo set-default

Sets the default artifacts repository, meaning the active registry used by the processing cluster.

Synopsis

migctl artifacts-repo set-default repository-name

Positional arguments

repository-name

Name of the artifacts repository configuration.

Flags

-h, --help

Help for this command.

migctl completion

Generate bash completion scripts.

To load completion run . <(migctl completion bash)

To configure your bash shell to load completions for each session, add the following to your ~/.bashrc or ~/.profile: . <(migctl completion bash)

Synopsis

migctl completion {bash | zsh}

Positional arguments

{bash | zsh}
The shell to use.

Flags

-h, --help
Help for this command.

migctl debug

Command Description
migctl debug release-m4ce-vm Release a Migrate to Virtual Machines V4 VM.
migctl debug collect-info Download collect_sysreport.sh, the Sysreport script.

migctl debug release-m4ce-vm

Release a Migrate to Virtual Machines V4 VM that may be unresponsive post-migration.

Synopsis

migctl debug release-m4ce-vm -i VM_NAME -s SOURCE_PROVIDER_NAME

Flags

-h, --help
Help for this command.
-i, --instance
Source VM instance ID.
-s, --source
Name of the source created with migctl source create.

migctl debug collect-info

Download collect_sysreport.sh, the Sysreport script. You can then run the script to collect information used by the Support team to help resolve your issue.

This command downloads the script to /tmp/sysreportINDEX/collect_sysreport.sh, where INDEX is a random suffix assigned when the temporary directory is created.

Synopsis

migctl debug collect-info

Flags

-h, --help
Help for this command.

See also

Personalize support

Examples

Download the Sysreport collect_sysreport.sh:

migctl debug collect-info
Saved /tmp/sysreportINDEX/collect_sysreport.sh, please run it manually to collect sysreport

To run the script:

  1. Change to the /tmp/sysreportINDEX directory:

    cd /tmp/sysreportINDEX
  2. Run the collect_sysreport.sh script:

    ./collect_sysreport.sh [-n NAMESPACE] [-o OUTPUT_DIRECTORY] [-m MIGRATION]

See Personalize support for more information on running the script.

migctl docker-registry

Command Description
migctl docker-registry create Create a Docker registry configuration.
migctl docker-registry update Update a Docker registry configuration.
migctl docker-registry delete Delete an artDocker registry configuration.
mmigctl docker-registry list List the Docker registry configurations.
migctl docker-registry set-default Set the default Docker registry configuration.

See also

Defining data repositories

migctl docker-registry create

Create a Docker registry configuration.

Synopsis

migctl docker-registry create gcr|basic-auth registry-name flags

Positional arguments

registry-name

Name of the Docker registry configuration.

Flags

-h, --help

Help for this command.

The remaining flags are based on the type of registry:

  • GCR

    migctl docker-registry create gcr registry-name --project project-id --json-key=m4a-install.json

    where:

    • registry-name is the user-defined name of the Docker registry configuration.

    • project-id is your Google project ID.

    • m4a-install.json is the name of the JSON key file for the service account. It is used for accessing Container Registry and Cloud Storage as described in Configuring a service account.

  • Docker registry

    migctl docker-registry create basic-auth registry-name --registry-path url --username username --ca-pem-file ca-pem-filename

    where:

    • registry-name is the user-defined name of the Docker registry configuration.

    • url specifies the URL of the registry without the http:// or https:// prefix. For example, localhost:8080/myregistry.

    • username for the basic authentication credentials of the registry. You're prompted to enter the password.

    • If the registry uses a self-signed cert, ca-pem-filename specifies a PEM file containing either the public key or the complete CA chain. This entails a concatenation from the intermediate CA certificates up to the root certificate. For example:

      cat int1.pem int2.pem ... root.pem

Examples

  • GCR

    migctl docker-registry create gcr my-registry --project myproject --json-key=m4a-install.json
  • Docker registry

    migctl docker-registry create basic-auth my-registry --registry-path myexample.com/registry --username user1 --password pass1

    If the registry uses a self-signed cert:

    migctl docker-registry create basic-auth my-registry --registry-path myexample.com/registry --username user1 --password pass1 --ca-pem-file cert.pem

migctl docker-registry update

Update a Docker registry configuration.

Synopsis

migctl docker-registry update gcr|basic-auth registry-name same-flags-as-create

Positional arguments

registry-name

Name of the Docker registry configuration.

Flags

same-flags-as-create

Specify the same flags for updating the registry configuration as you used to create it as shown in migctl docker-registry create.

migctl docker-registry delete

Delete a Docker registry configuration.

Synopsis

migctl docker-registry delete registry-name

Positional arguments

registry-name

Name of the Docker registry configuration.

Flags

-h, --help

Help for this command.

migctl docker-registry list

List the currently configured Docker registries, including the current default.

Synopsis

migctl docker-registry list

Flags

-h, --help

Help for this command.

migctl docker-registry set-default

Sets the default Docker registry, meaning the active registry used by the processing cluster.

Synopsis

migctl docker-registry set-default registry-name

Positional arguments

registry-name

Name of the Docker registry configuration.

Flags

-h, --help

Help for this command.

migctl doctor

Check Migrate to Containers deployment status and related configuration.

Synopsis

migctl doctor

Flags

-h, --help
Help for this command.

See also

Installing Migrate to Containers

Examples

Response for a functioning Migrate to Containers deployment.

migctl doctor
[✓] Deployment

migctl help

Provide help on the migctl tool.

Use "migctl [command] --help" for more information about a command.

Synopsis

migctl --help

Flags

-h, --help
Help for this command.

migctl logging

Command Description
migctl logging set-verbosity Set the logging verbosity of the backend.

migctl logging set-verbosity

Set the logging verbosity of the backend using any non-negative integer.

  • Set the level to 0 to see only information logs.
  • Set the level to 1 or above to see also debug logs.

Synopsis

migctl logging set-verbosity LEVEL [flags]

Examples

Set the verbosity level to show only info logs.

migctl logging set-verbosity 0

Set the verbosity level to show most debug logs.

migctl logging set-verbosity 1

Flags

-h, --help
Help for this command.

migctl migration

Command Description
migration create Create a migration plan.
migration delete Delete a migration plan.
migration generate-artifacts Create artifacts for a given migration.
migration get Get a migration plan specification.
migration get-artifacts Get artifacts for the migration, such as Deployment/StatefulSet spec YAML and Dockerfile.
migration list List migrations.
migration list-types List available migration types.
migration status Get migration plan status.
migration update Update a migration plan.

migctl migration create

Create a migration plan.

A migration plan defines the specifics of the migration, including the source platform, VM ID, project name, and more.

The generated migration plan file is copied to the machine where the command is run -- it is not applied to the processing cluster. If you like, you can edit the file before using it in migration.

Synopsis

migctl migration create migration-name --source source-name --vm-id source-vm-id --type type [flags]

Positional arguments

migration-name
Name to give this migration.

Flags

-r, --artifacts-repository string
Artifacts repository to store the artifacts.
-h, --help
Help for create
--image-repository string
Image repository to upload images to, for migrations that upload images.
-l, --labels strings --labels=[KEY=VALUE,…]
List of label KEY=VALUE pairs to add. Keys must start with a lowercase character and contain only hyphens (-), underscores (_), lowercase characters, and numbers. Values must contain only hyphens (-), underscores (_), lowercase characters, and numbers.
-p, --parameters strings --parameters=[KEY=VALUE,…]
List of label KEY=VALUE pairs to add
-s, --source string
Source name
-t, --type string
The type of migration
-v, --vm-id string
Source vm-id

Examples

Create a migration plan for containerization of a linux VM.

migctl migration create my-migration-1 --source my-source --vm-id my-id --type linux-system-container

Create a migration plan for a VM running a Tomcat application component.

migctl migration create my-migration-1 --source my-source --vm-id my-id --type tomcat-container

See also

Creating a migration

migctl migration delete

Delete a migration plan.

This command deletes a migration that you created with migctl migration create.

Synopsis

migctl migration delete migration-name

Positional arguments

migration-name
Name of the migration to delete.

Flags

-h, --help
Help for this command.

migctl migration generate-artifacts

Create artifacts for a given migration.

For example, this command creates an image, data-volume, Dockerfile, deployment YAML, and more.

Synopsis

migctl migration generate-artifacts migration-name

Positional arguments

migration-name
Name of the migration for which to create artifacts.

Flags

-h, --help
Help for this command.

See also

Executing a migration

migctl migration get

Get a migration plan specification.

Synopsis

migctl migration get migration-name  [--output-file migration-yaml-file]

Positional arguments

migration-name
Name of the migration whose plan to get.

Flags

--output-file migration-yaml-file
Output YAML file of migration plan specification.
-r, --overwrite
Overwrite existing output YAML file(s) of migration plan specification.
-h, --help
Help for this command.

migctl migration get-artifacts

Get artifacts for the migration, such as Deployment/StatefulSet spec YAML and Dockerfile.

Synopsis

migctl migration get-artifacts migration-name [--output-directory directory-path] [--overwrite]

Positional arguments

migration-name
The migration for which to get artifacts.

Flags

--output-directory directory-path
Output directory path. Default is "."
--overwrite
Overwrite existing local files.
-h, --help
Help for this command.

See also

Reviewing generated deployment files

migctl migration list

List migrations.

Synopsis

migctl migration list [--all-namespaces]

Flags

-A, --all-namespaces
List migrations across all namespaces.
-h, --help
Help for this command.

See also

Monitoring a migration

migctl migration list-types

List available migration types

Synopsis

migctl migration list-types [flags]

Flags

-h, --help
Help for list-types.

See also

Monitoring a migration

migctl migration status

Get migration plan status.

Synopsis

migctl migration status migration-name  [--verbose]

Positional arguments

migration-name
Name of the migration to get status for.

Flags

-v, --verbose
Verbose status.
-h, --help
Help for this command.

See also

Monitoring a migration

migctl migration update

Update a migration specification.

Synopsis

migctl migration update migration-name --main-config migration-spec.yaml --data-config data-spec.yaml

Positional arguments

migration-name
Name of the migration to update.

Flags

--main-config migration-spec.yaml
YAML file containing the updated migration plan specification.
--data-config data-spec.yaml
YAML file containing the updated data configuration specification.
-h, --help
Help for this command.

See also

migctl setup

Command Description
setup install Install Migrate to Containers on the current cluster.
setup uninstall Uninstall Migrate to Containers from a cluster.
setup upgrade Upgrade Migrate to Containers on a cluster.
setup proxy Configure an HTTPs proxy used by Migrate to Containers.

migctl setup install

Install Migrate to Containers on the current cluster.

Synopsis

migctl setup install [--runtime] [--json-key service-account-json] [--node-selectors string] [--tolerations string] [--version version-number]

Flags

--runtime
Install runtime support on workload clusters with Container-Optimized OS nodes.
--json-key service-account-json
JSON key file for the service account with the necessary permissions to install Migrate to Containers. See Create a service account for a migration for more.
--node-selectors string
Node selector for the components deployed by Migrate to Containers in the form: LABEL1=VALUE1,LABEL2=VALUE2,..... See Installation options for more.
--tolerations string
Tolerations for the components deployed by Migrate to Containers in the form: KEY1=VALUE1:EFFECT1,KEY2=VALUE2:EFFECT2,..... See Installation options for more.
--version version-number
Migrate to Containers version to install (default is "1.15.0").
-h, --help
Help for this command.

Examples

Install Migrate to Containers on a processing cluster.

migctl setup install

Install runtime support on workload clusters with COS nodes.

migctl setup install --runtime

See also

Installing Migrate to Containers

migctl setup uninstall

Uninstall Migrate to Containers from a cluster.

Synopsis

migctl setup uninstall [-f]

Flags

-f
Force uninstalling while migrations are in progress.
-h, --help
Help for this command.

Examples

Uninstall Migrate to Containers.

migctl setup uninstall

Force uninstalling Migrate to Containers while migrations are in progress.

migctl setup uninstall --force

See also

Uninstalling Migrate to Containers

migctl setup upgrade

Upgrade Migrate to Containers on a cluster.

Synopsis

migctl setup upgrade

Flags

--runtime
Install runtime support on workload clusters with COS nodes.
-f, --force
If any migrations are in an error state, recreate them as part of the upgrade to see if they can be completed.
--gcp-project string
Google Cloud project for uploading to Container Registry and Cloud Storage.
--gcp-region string
Google Cloud region for uploading to Cloud Storage.
--json-key string
JSON key for the service account used for uploading to Container Registry and Cloud Storage.
--node-selectors string
node-selector for the components deployed by Migrate to Containers in the format of LABEL1=VALUE1,LABEL2=VALUE2,...
--skip-validation
Override the cluster deployment validation.
--tolerations string
Tolerations for the components deployed by Migrate to Containers in the form KEY1=VALUE1:EFFECT1,KEY2=VALUE2:EFFECT2,...
--version string
Migrate to Containers version to install (default is "1.15.0").
-h, --help
Help for this command.

Examples

Upgrade Migrate to Containers to current version.

migctl setup upgrade

Upgrade Migrate to Containers to a specific version.

migctl setup upgrade --version 1.15.0

See also

Upgrading Migrate to Containers

migctl setup proxy

Configure a proxy server to access Migrate to Containers repositories. Migrate to Containers supports proxy requests over HTTPS only. HTTP is not supported.

When using an HTTPS proxy, Migrate to Containers does not support self-signed certificates. You must use a signed certificate with an HTTPS proxy.

Synopsis

migctl setup proxy --https-proxy proxy-address
    [--proxy-basic-authentication] [--no-proxy address] [--remove]

Flags

--https-proxy proxy-address
Specify the IP or proxy server address used to route requests, omitting the https:// prefix. If your proxy uses basic authentication, then you can include the username and password in proxy-address. For example:
user:password@proxy-address
Alternatively, you can use the --proxy-basic-authentication option to specify these values interactively in the console.
--no-proxy address
Specify an optional list of comma-separated IPs or domains where the proxy is not used.
--remove
Remove the proxy configuration.
--proxy-basic-authentication
If the proxy requires authentication, use this option to specify the username and password interactively. You're then prompted to enter the username and password required to access the proxy when you enter the command. Alternatively, you can use the --https-proxy option to specify these values as part of the proxy-address.
--h, --help
Help for this command.

Examples

To configure an HTTPS proxy with no authentication:

migctl setup proxy --https-proxy myproxy.com

To configure an HTTPS proxy and also specify domains where the proxy is not used:

migctl setup proxy --https-proxy myproxy.com --no-proxy localhost,mydomain.com

If the proxy uses basic authentication:

migctl setup proxy --https-proxy myproxy.com --proxy-basic-authentication

You're prompted to enter the username and password.

Or you can enter the credentials as part of the proxy-address:

migctl setup proxy --https-proxy user:pword@myproxy.com

To remove the proxy configuration:

migctl setup proxy --remove 

See also

Configuring an HTTPS proxy

migctl source

Perform operations related to a migration source.

Command Description
source create Add a migration source to the processing cluster.
source delete Delete a migration source from the processing cluster.
source list List migration source configurations in the processing cluster.
source status Get the migration source status on the processing cluster.

migctl source create

Add a migration source to the processing cluster.

Command Description
source create compute-engine Add Compute Engine as a migration source.
source create local-vmware Add VMware as a migration source to a processing cluster.
source create m2vm Add Migrate to Virtual Machines as a migration source to the processing cluster.

See also

Adding a migration source

migctl source create compute-engine

Add Compute Engine as a migration to the processing cluster.

Synopsis

migctl source create compute-engine name --project project [--json-key service-account-json ]

Positional arguments

name
A name to give the source.

Flags

--project project
Default project for the Compute Engine source type.
--json-key service-account-json
JSON key file for the service account used to create the Compute Engine source. See Creating a service account for using Compute Engine as a migration source for more.
-h, --help
Help for this command.

Examples

Add Compute Engine as a migration source.

migctl source create compute-engine my-ce-src --project myproject --zone us-west1-a

See also

Adding a migration source

migctl source create local-vmware

Add VMware as a migration source to a processing cluster.

Synopsis

migctl source create local-vmware name --vc vcenter --user user [flags]

Positional arguments

name
A name to give the source.

Flags

--dc datacenter
--vc host
Specifies the vCenter DNS name or vCenter IP address.
--username user
The username for a user that has permission to access the vCenter. You're prompted to enter the user password.
-h, --help
Help for this command.

Examples

Add VMware as a migration source.

migctl source create local-vmware local-vmware-src --vc '1.2.3.4' --username 'admin'

See also

Adding a migration source

migctl source create m2vm

Add Migrate to Virtual Machines as a migration source to the processing cluster.

Synopsis

migctl source create m2vm name --project m2vm-service-project
--json-key path --location m2vm-service-location --m2vm-source m2vm-service-source
[ --target-project target-project ][ --target-json-key path ] [ --target-zone target-zone ]
[ --target-network target-network ] [ --target-subnet target-subnet ] [flags]

Positional arguments

name
A name to give the source.

Flags

-h, --help
Help for m2vm.
--json-key string
Path for a service account json key used for the Migrate to Virtual Machines project. See Use Migrate to Virtual Machinesas a migration source.
--location string
The Migrate to Virtual Machines service location, for example, us-central1.
--m2vm-source string
Migrate to Virtual Machines source name.
--project string
Migrate to Virtual Machines project.
--target-json-key string
Path for a service account json key used for the target project. If left empty, will be the same as the json key to the Migrate to Virtual Machines.
--target-network string
The target network for clone VM deployments.
--target-project string
The target project for clone VM deployments. If left empty, will be the same as the Migrate to Virtual Machines project.
--target-subnet string
The target subnet for clone VM deployments.
--target-zone string
The target zone for clone VM deployments.

Examples

Add Migrate to Virtual Machines as a migration source.

migctl source create m2vm name --project m2vm-service-project --json-key m2vm-service-sa.json --location m2vm-service-location --m2vm-source m2vm-service-source

See also

Adding a migration source

migctl source delete

Delete a migration source from the processing cluster.

Synopsis

migctl source delete source-name [-f]

Positional arguments

source-name
The name of the source to delete, meaning the name that you specified when you created the source with migctl source create.

Flags

-f
Ignore errors and force the deletion.
-h, --help
Help for this command.

Examples

Delete the migration source.

migctl source delete my-source

Attempt to force deletion of a source.

migctl source delete my-source -f

migctl source list

List migration source configurations in the processing cluster.

Synopsis

migctl source list

Flags

-h, --help
Help for this command.

migctl source list-vms

List VM candidates for migration.

Synopsis

migctl source list-vms [flags]

Flags

--help
Help for this command.
--refresh
Refresh the inventory instead of using cached results.
--wide
Show more information about the VMs.

migctl source status

Get the migration source status on the processing cluster.

Synopsis

migctl source status 

Flags

-h, --help
Help for this command.
-v, --verbose
Verbose output for this command.

migctl version

Print the version for Migrate to Containers and for migctl.

Synopsis

migctl version

Flags

-h, --help
Help for this command.