OS Migrate Operator Guide

The migrator host is the machine that executes OS Migrate Ansible playbooks and serves as the orchestration point for OpenStack cloud migrations. It can be deployed as:

Location: /roles/conversion_host/

Purpose: Deploys the infrastructure and compute instances needed for conversion hosts.

Key Responsibilities:

Location: /roles/conversion_host_content/

Purpose: Installs and configures software packages on the conversion hosts.

Key Responsibilities:

During workload migration, conversion hosts are used in the following workflow:

Use the provided playbook to deploy conversion hosts:

This playbook will:

Clean up conversion hosts and their infrastructure:

You can also use the roles directly for more control:

The deployment requires OpenStack permissions for:

1. Conversion Host Not Reachable

2. Network Connectivity Issues

3. SSH Key Problems

4. Package Installation Failures

The os-migrate AEE image contains:

The vmware-migration-kit AEE image contains:

Before building AEE images, ensure you have the following tools installed:

Navigate to the os-migrate repository and build the AEE:

Navigate to the vmware-migration-kit repository and build the AEE:

Both repositories include GitHub Actions workflows that automatically build and test AEE images:

These workflows:

The GitHub Actions workflows implement a sophisticated versioning strategy for AEE images:

Execute os-migrate playbooks using the AEE container:

Access the AEE container interactively for debugging:

Common volume mounts for AEE usage:

AEE images are defined using execution-environment.yml files that specify:

Example structure:

To customize AEE images for specific requirements:

Enable verbose output for troubleshooting:

Check container logs:

Regular updates ensure security and compatibility:

The automated GitHub Actions workflows handle version management based on Git references:

Improve the way collections (os-migrate or vmware-migration-kit) are installed within AEE images to ensure proper version alignment:

This improvement will ensure that AEE images always contain the correct version of the collection that matches the build context and tag strategy, providing better reproducibility and version alignment.

Users are encouraged to use os-migrate using specific credentials for each project/tenant, this means not using the admin user to execute the resources migration (unless the resource is owned by the admin project, e.g. public Glance images).

In case the circumstances require migrating by the admin user, this user needs to have access to the respective projects. There are two options:

Let’s create an os-migrate-vars.yml file with Ansible variables:

The file contains the source and destination tenant credentials, a directory on the migrator host (typically localhost) and a directory where the exported data will be saved.

If you are migrating content from multiple source projects, make sure to use a separate data directory for each source project. In other words, when changing os_migrate_src_auth or os_migrate_src_region_name, make sure to also change os_migrate_data_dir.

As depicted in content of the previously defined os-migrate-vars.yml file, the parameters os_migrate_src_auth and os_migrate_dst_auth refer to the usage of Keystone v3. In the case of a user needing to execute a migration between tenants not supporting Keystone v3 the following error will be raised:

To fix this issue, the user must adjust their auth parameters:

Notice that the parameters project_domain_name and user_domain_name are removed and the auth_url parameter points to the Keystone v2 endpoint.

Workloads require the support of several resources in a given cloud to operate properly. Some of these resources include networks, subnets, routers, router interfaces, security groups, and security group rules. The pre-workload migration process includes exporting these resources from the source cloud onto the migrator machine, the option to edit the resources if desired, and importing them into the destination cloud.

Exporting or importing resources is enabled by running the corresponding playbook from OS Migrate. Let’s look at a concrete example. To export the networks, run the "export_networks" playbook.

Workload information is exported in a similar method to networks, security groups, etc. as in the previous sections. Run the "export_workloads" playbook, and edit the resulting workloads.yml as desired:

Note that this playbook only extracts metadata about servers in the specified tenant - it does not download OpenStack volumes directly to the migration data directory. Data transfer is handled by the import_workloads playbook. The data is transfered directly between the clouds, meaning both clouds have to be running and reachable at the same time. The following sections describe the process in more detail.

The following features are availables:

Currently we are supporting the following matrice:

Edit vars.yaml file and add our own setting:

If you already have a conversion host, or if you want to re-used a previously deployed one:

Then specify the Openstack credentials:

OS-Migrate can migrate directly from a local shared directory mounted on the conversion host. If the VMware virtual machines are located on an NFS datastore that is accessible to the conversion host, you can mount the NFS storage on the conversion host and provide the path to the NFS mount point.

OS-Migrate will then directly consume the disks of the virtual machines located on the NFS mount point. Configure the Ansible variable to specify your mount point as follows:

Create an invenvoty file, and replace the conv_host_ip by the ip address of your conversion host:

Then run the migration with:

You can also run migration outside of Ansible because the Ansible module are written in Golang. The binaries are located in the plugins directory.

From your conversion host (or an Openstack instance inside the destination cloud) you need to export Openstack variables:

Then create the argument json file, for example:

Then execute the migrate binary:

You can see the logs into:

Resource filters allow the user to control which resources will be migrated. The filters match against resource names.

The filters work both during export and during import, and it is not required that the same value is used during export and import. This feature can be used e.g. to export a subset of the existing resources, and then during import further limit the subset of resources being imported into batches.

The value of a filter variable is a list, where each item can be a string (exact match) or a dictionary with regex key (regular expression match). A resource is exported if it matches at least one of the list items.

The above example says: Export only networks named my_net or other_net or starting with myprefix_.

The filters default to:

meaning "export all resources". (The set of resources exported will still be limited to those you can see with the authentication variables you used.)

Sometimes two roles use the same variable where this makes sense, especially for attached resources. E.g. roles export_security_groups and export_security_group_rules both use os_migrate_security_groups_filter. Similarly, export_routers and export_router_interfaces both use os_migrate_routers_filter.

List of the currently implemented filters with default values you can copy into your variables file and customize:

The conversion hosts might be configured using different names, this is in case an operator needs to have them registered with the subscription manager and avoid collisions with the names.

The conversion hosts names can be customized using the following variables:

By default, these variables have the same value for both conversion hosts os_migrate_conv_src and os_migrate_conv_dst respectively.

The conversion host image is the guest configure to execute the instances migrations.

The variables to be configured are:

This image must be accessible to both tenants/projects prior to executing the conversion host deployment playbook. The variables default to os_migrate_conv, so if a conversion host image is uploaded to Glance as public image with this name (in both src and dst clouds), these variables do not need to be configured explicitly.

Make sure this image exists in Glance on both clouds. Currently it should be a CentOS 9 Cloud Image or RHEL 8 KVM Guest Image.

The conversion host flavor defines the compute, memory, and storage capacity that will be allocated for the conversion hosts. It needs to have at least a volume with 20GB.

The variables to be configured are:

Usually, 'm1.medium' will suffice this requirement, but again, it can be different between deployments.

The external network configuration allows the connection of the conversion host router for external access, this external network must be able to allocate floating IPs reachable between both conversion hosts.

Set the name of the external (public) network to which conversion host private subnet will be attached via its router, for source and destination clouds respectively, via these variables:

This is not required if you are attaching your conversion host to pre-existing network (when os_migrate_src/dst_conversion_manage_network is false).

In addition to the name variables described above, it is possible to customize names of other conversion host dependency resources:

Availability zones are defined by attaching specific metadata information to an aggregate:

The conversion host can set logical abstractions for partitioning instances to a specific set of hosts belonging to an aggregate.

The default is false (meaning no specification provided).

It is possible to disable creation and deletion of conversion host private network by setting these variables to false:

This disables creation of the network, the subnet, and the router that typically makes the conversion host reachable from outside the cloud.

When disabling network management like this, you’ll need pre-existing network that the conversion host can attach to and use it to talk to the other conversion host. Set these network name variables accordingly:

OS Migrate can be told to not attempt to create any floating IPs on the conversion hosts. This can be useful when attaching a conversion host to some public network, where its IP address will be automatically reachable from outside. The variables to control whether conversion hosts should have floating IPs are:

When the conversion hosts are removed, the required and assigned floating IPs need to be detached or removed.

The following variables allow to change the behavior of deleting of detaching the floating IP when deleting the conversion hosts (default: true):

When the corresponding …​_manage_fip variable is set to false, floating IP deletion is not attempted even if …​_delete_fip is set to true.

Each conversion host needs to have a floating IP, these floating IPs can be assigned automatically or defined by the operator with the usage of the following variables:

When using this variable to specify an exact IP address, the floating IP must already exist and be available for attaching.

A combination of variables described earlier can be used to attach the conversion hosts directly onto pre-existing public networks. We need to make sure that we don’t try to create any private network, we don’t try to create a floating IP, and we set the conversion host network names accordingly:

The modes for workload migrations can be changed in either cloud. The variable that control the behavior are:

The default is true (meaning the copying of data using os-migrate is skipped).

This is useful if there are pre-created volumes in the destination cloud that we just want to attach when creating the VM in the destination.

The conversion hosts can be created as boot-from-volume servers in either cloud. The variables that control the behavior are:

The default is false (meaning boot from Nova local disk).

When creating boot-from-volume conversion hosts, it is possible to customize the size in GB for the boot volume:

The size should be 20 or more, the default is 20.

When using RHEL as conversion host, set the SSH user name as follows:

It is also necessary to set RHEL registration variables. The variables part of this role are set to omit by default.

The variables os_migrate_conversion_rhsm_auto_attach and os_migrate_conversion_rhsm_activationkey are mutually exclusive, given that, they are both defaulted to omit.

Typically the only registration variables to set are:

In this case, os_migrate_conversion_rhsm_auto_attach should be set to True in order to fetch automatically the content once the node is registered.

or:

For this case, os_migrate_conversion_rhsm_auto_attach must be left undefined with its default value of omit.

The complete list of registration variables corresponds to the redhat_subscription Ansible module. In OS Migrate they are named as follows:

Additionally is possible to enable specific repositories in the conversion hosts using the following variable:

The os_migrate_conversion_rhsm_repositories variable is a list of those repositories that will be enabled on the conversion host.

When required, a user can configure password-based SSH access to the conversion hosts, this feature might be useful for debugging when the private key of the hosts is not available anymore.

The variables required in order to configure the password-based access are named as follows:

The variable os_migrate_conversion_host_ssh_user_enable_password_access is set by default to false, and the variable os_migrate_conversion_host_ssh_user_password is set by default to the following string weak_password_disabled_by_default.

The user enabled to access the conversion hosts with password-based authentication is the one defined in the os_migrate_conversion_host_ssh_user variable.

It is possible to run custom bash scripts in the conversion hosts before and after configuring their content. The content of the conversion hosts is a set of required packages and in the case of using RHEL then the configuration of the subscription manager.

The variables allowing to run the custom scripts are:

The Ansible module used to achieve this is shell, so users can execute a simple one-liner command, or more complex scripts like the following examples:

or:

It is possible to disable the subscription manager native tasks by setting to false the following variable:

This will skip the tasks related to RHSM when using RHEL in the conversion hosts. Disabling RHSM can be useful in those cases where the operator has custom scripts they need to use instead the standard Ansible module.

To upgrade to the latest release if you already have the OS Migrate collection installed, make sure to pass the -f flag to the installation command, which will force installing the (latest) collection even if it is already present:

To upgrade/downgrade to a particular release:

You can find available releases at OS Migrate Galaxy page.