Variables Guide =============== The goal of this document is to guide users to correctly configure the most important variables in OS Migrate. For a complete listing of variables configurable for each Ansible role, refer to the documentation of the individual roles. General variables ----------------- Resource filters ~~~~~~~~~~~~~~~~ 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. .. code:: yaml os_migrate_networks_filter: - my_net - other_net - regex: ^myprefix_.* The above example says: Export only networks named ``my_net`` **or** ``other_net`` **or** starting with ``myprefix_``. The filters default to: .. code:: yaml - regex: .* 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: .. code:: yaml os_migrate_flavors_filter: - regex: .* os_migrate_images_filter: - regex: .* os_migrate_keypairs_filter: - regex: .* os_migrate_networks_filter: - regex: .* os_migrate_projects_filter: - regex: .* os_migrate_routers_filter: - regex: .* os_migrate_security_groups_filter: - regex: .* os_migrate_subnets_filter: - regex: .* os_migrate_users_filter: - regex: .* os_migrate_workloads_filter: - regex: .* Conversion host variables ------------------------- The following variables are those that need to be configured prior to running OS Migrate. Conversion host name ~~~~~~~~~~~~~~~~~~~~ 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:: os_migrate_src_conversion_host_name os_migrate_dst_conversion_host_name By default, these variables have the same value for both conversion hosts `os_migrate_conv_src` and `os_migrate_conv_dst` respectively. Conversion host image name ~~~~~~~~~~~~~~~~~~~~~~~~~~ The conversion host image is the guest configure to execute the instances migrations. The variables to be configured are:: os_migrate_src_conversion_image_name os_migrate_dst_conversion_image_name 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 `_. Conversion host flavor name ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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:: os_migrate_src_conversion_flavor_name os_migrate_dst_conversion_flavor_name Usually, ‘m1.medium’ will suffice this requirement, but again, it can be different between deployments. Conversion host external network name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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:: os_migrate_src_conversion_external_network_name os_migrate_dst_conversion_external_network_name 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`). Other conversion host dependency names ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In addition to the name variables described above, it is possible to customize names of other conversion host dependency resources:: os_migrate_src_conversion_net_name os_migrate_dst_conversion_net_name os_migrate_src_conversion_subnet_name os_migrate_dst_conversion_subnet_name os_migrate_src_conversion_router_name os_migrate_dst_conversion_router_name os_migrate_src_conversion_secgroup_name os_migrate_dst_conversion_secgroup_name os_migrate_src_conversion_keypair_name os_migrate_dst_conversion_keypair_name Conversion host availablility zone management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Availability zones are defined by attaching specific metadata information to an aggregate:: os_migrate_src_conversion_availability_zone os_migrate_dst_conversion_availability_zone 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). Conversion host network management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is possible to disable creation and deletion of conversion host private network by setting these variables to `false`:: os_migrate_src_conversion_manage_network os_migrate_dst_conversion_manage_network 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_src_conversion_net_name os_migrate_dst_conversion_net_name Conversion host floating IP management ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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:: os_migrate_src_conversion_manage_fip os_migrate_dst_conversion_manage_fip 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):: os_migrate_src_conversion_host_delete_fip os_migrate_dst_conversion_host_delete_fip When the corresponding `..._manage_fip` variable is set to `false`, floating IP deletion is not attempted even if `..._delete_fip` is set to `true`. Conversion host specific floating IP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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:: os_migrate_src_conversion_floating_ip_address os_migrate_dst_conversion_floating_ip_address When using this variable to specify an exact IP address, the floating IP must already exist and be available for attaching. Attaching conversion hosts onto public networks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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:: os_migrate_src_conversion_manage_network: false os_migrate_dst_conversion_manage_network: false os_migrate_src_conversion_manage_fip: false os_migrate_dst_conversion_manage_fip: false os_migrate_src_conversion_net_name: some_public_net_src os_migrate_dst_conversion_net_name: some_public_net_dst Storage migration modes ~~~~~~~~~~~~~~~~~~~~~~~~~ The modes for workload migrations can be changed in either cloud. The variable that control the behavior are:: os_migrate_workloads_data_copy 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. Conversion host boot from volume ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The conversion hosts can be created as boot-from-volume servers in either cloud. The variables that control the behavior are:: os_migrate_src_conversion_host_boot_from_volume os_migrate_dst_conversion_host_boot_from_volume 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:: os_migrate_src_conversion_host_volume_size os_migrate_dst_conversion_host_volume_size The size should be 20 or more, the default is 20. Conversion host RHEL variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When using RHEL as conversion host, set the SSH user name as follows:: os_migrate_conversion_host_ssh_user: cloud-user 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:: os_migrate_conversion_rhsm_username os_migrate_conversion_rhsm_password 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:: os_migrate_conversion_rhsm_activationkey os_migrate_conversion_rhsm_org_id 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:: os_migrate_conversion_rhsm_activationkey os_migrate_conversion_rhsm_auto_attach os_migrate_conversion_rhsm_consumer_id os_migrate_conversion_rhsm_consumer_name os_migrate_conversion_rhsm_consumer_type os_migrate_conversion_rhsm_environment os_migrate_conversion_rhsm_force_register os_migrate_conversion_rhsm_org_id os_migrate_conversion_rhsm_password os_migrate_conversion_rhsm_pool os_migrate_conversion_rhsm_pool_ids os_migrate_conversion_rhsm_release os_migrate_conversion_rhsm_rhsm_baseurl os_migrate_conversion_rhsm_rhsm_repo_ca_cert os_migrate_conversion_rhsm_server_hostname os_migrate_conversion_rhsm_server_insecure os_migrate_conversion_rhsm_server_proxy_hostname os_migrate_conversion_rhsm_server_proxy_password os_migrate_conversion_rhsm_server_proxy_port os_migrate_conversion_rhsm_server_proxy_user os_migrate_conversion_rhsm_syspurpose os_migrate_conversion_rhsm_username Additionally is possible to enable specific repositories in the conversion hosts using the following variable:: os_migrate_conversion_rhsm_repositories The `os_migrate_conversion_rhsm_repositories` variable is a list of those repositories that will be enabled on the conversion host. Enabling password-based SSH access to the conversion hosts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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:: os_migrate_conversion_host_ssh_user_enable_password_access os_migrate_conversion_host_ssh_user_password 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. Running custom bash scripts in the conversion hosts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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:: os_migrate_src_conversion_host_pre_content_hook os_migrate_src_conversion_host_post_content_hook os_migrate_dst_conversion_host_pre_content_hook os_migrate_dst_conversion_host_post_content_hook 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:: os_migrate_src_conversion_host_pre_content_hook: | ls -ltah echo "hello world" df -h or:: os_migrate_src_conversion_host_pre_content_hook: "echo 'this is a simple command'" Disabling the subscription manager tasks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is possible to disable the subscription manager native tasks by setting to false the following variable:: os_migrate_conversion_rhsm_manage 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. OpenStack REST API TLS variables -------------------------------- If either of your clouds uses TLS endpoints that are not trusted by the Migrator host by default (e.g. using self-signed certificates), or if the Migrator host should authenticate itself via key+cert, you will need to set TLS-related variables. - ``os_migrate_src_validate_certs`` / ``os_migrate_dst_validate_certs`` - Setting these to ``false`` disables certificate validity checks of the source/destination API endpoints. - ``os_migrate_src_ca_cert`` / ``os_migrate_dst_ca_cert`` - These variables allow you to specify a custom CA certificate that should be used to validate the source/destination API certificates. - ``os_migrate_src_client_cert``, ``os_migrate_src_client_key`` / ``os_migrate_dst_client_cert``, ``os_migrate_dst_client_key`` - If the Migrator host should authenticate itself using a TLS key + certificate when talking to source/destination APIs, set these variables. Workload import/export variables -------------------------------- - ``os_migrate_workload_stop_before_migration`` - Set to true if you wish for os_migrate to stop your workloads/vms prior to migration. Note that only workloads/vms in `SHUTOFF` state will be migrated. Workload migration variables ---------------------------- Workloads to be migrated with OS Migrate can have varying storage configurations in the source cloud, and the desired way to migrate their storage also varies, per cloud operators preference. The following table summarizes the matrix of options (whats in the source, how it should be migrated, how should OS Migrate workloads YAML file be configured, is the conversion host required for this mode of migration, is this migration mode implemented). .. list-table:: Workload Migration options :widths: 25 25 25 25 :header-rows: 1 * - Source workload - Desired migration properties - Migration parameter settings - Conversion hosts required? * - | Booted from image (local boot disk), optionally | additional volumes attached - | Boot disk not copied, VM booted from image (local boot disk), | any additional volumes copied and attached - | ```_migration_params: data_copy: true boot_disk_copy: false boot_volume: null additional_volumes: null params: { image_ref: { domain_name: '%auth%' name: some_image project_name: '%auth%' }} (this is the default)``` - Yes * - | Booted from image (local boot disk), | optionally additional volumes attached - | Boot disk copied as volume, VM booted from volume, | any additional volumes copied and attached - | ```_migration_params: data_copy: true boot_disk_copy: true boot_volume: null additional_volumes: null params: image_ref: domain_name: '%auth%' name: some_image project_name: '%auth%' (image_ref doesn’t matter, can be null)``` - Yes * - Booted from volume, optionally additional volumes attached - | Boot disk copied as volume, VM booted from volume, | any additional volumes copied and attached - | ```_migration_params: data_copy: true boot_disk_copy: true boot_volume: null additional_volumes: null params: image_ref: null``` - Yes * - | Booted from image (local boot disk), | optionally additional volumes attached - | Nothing copied, VM booted from image (local boot disk), | no additional volumes - | ```_migration_params: data_copy: false boot_disk_copy: false boot_volume: null additional_volumes: null params: image_ref: domain_name: '%auth%' name: some_image project_name: '%auth%' (boot_disk_copy doesn't matter)``` - No * - | Booted from image (local boot disk), | optionally additional volumes attached - | Nothing copied, VM booted from image (local boot disk), | additional pre-existing volumes attached - | ```_migration_params: data_copy: false boot_disk_copy: false boot_volume: null additional_volumes: uuid: some_uuid2 uuid: some_uuid3 params: image_ref: domain_name: '%auth%' name: some_image project_name: '%auth%' (boot_disk_copy doesn't matter)``` - No * - | Booted from image or volume, optionally additional | volumes attached - | Nothing copied, VM booted from pre-existing volume, | no additional volumes - | ```_migration_params: data_copy: false boot_disk_copy: false boot_volume: uuid: some_uuid additional_volumes: null params: image_ref: domain_name: '%auth%' name: some_image project_name: '%auth%' (image_ref doesn’t matter, can be null, boot_disk_copy doesn't matter)``` - No * - | Booted from image or volume, optionally additional | volumes attached - | Nothing copied, VM booted from pre-existing volume, | additional pre-existing volumes attached - | ```_migration_params: data_copy: false boot_disk_copy: false boot_volume: uuid: some_uuid additional_volumes: uuid: some_uuid2 uuid: some_uuid3 params: image_ref: domain_name: '%auth%' name: some_image project_name: '%auth%' (image_ref doesn’t matter, can be null, boot_disk_copy doesn't matter)``` - No