Migration Parameters Guide
==========================

What are migration parameters
-----------------------------

Resource YAML files generated by OS Migrate when exporting are
editable by the user. The parameters in ``params`` section of a
resource generally specify direct resource properties, i.e. *what* the
resource is like. Sometimes, a resource can be copied from source to
destination in multiple different ways, each suitable for different
use cases. To control *how* an individual resource should be migrated,
there is another editable section in resource serializations, called
``_migration_params``. The descriptions of the most important ones are
in this guide.

Workload migration parameters
-----------------------------

-  ``boot_disk_copy`` controls how if the boot disk of the destination
   server is copied or re-imaged:

   -  ``false``: The destination server will be booted from a
      Glance image of the same name as the source server. (This is the
      default for servers which were booted from an image in the
      source cloud.)

   -  ``true``: The source server's boot disk will be copied
      into the destination as a volume, and the destination server
      will be created as boot-from-volume. (For servers which are
      already boot-from-volume in the source cloud, this is the
      default and the only possible path.)

-  ``data_copy`` controls storage migration modes for workloads:

   - ``false``: The copying of data using os-migrate is skipped.

   - ``true``: (Default) We result to using os-migrate for data copying.

-  ``boot_volume_params`` controls new boot disk creation parameters in
   the destination, in case the source VM has no boot disk, but
   ``boot_disk_copy`` is ``true``.

   There are a few pre-filled parameters, defaulted to ``None``.  Then
   ``None`` value means those parameters will not be specified when
   creating the boot volume, or in case of the ``name`` parameter, the
   default for workload migration will be used (prefix + VM name).

   When the source VM *does* have a boot volume already, do not use
   ``boot_volume_params`` to edit the destination creation
   parameters. Instead, edit the serialized volume in the ``volumes``
   section of the workload's ``params``.

-  ``boot_volume`` controls new boot disk creation parameters for 
   workload migrations with storage mode (data_copy) set to false.

   There are a few pre-filled parameters, defaulted to ``None``.  Then
   ``None`` value means those parameters will not be specified when
   creating the boot volume, or in case of the ``name`` parameter, the
   default for workload migration will be used (prefix + VM name).

   When the source VM *does* have a boot volume already, do not use
   ``boot_volume_params`` to edit the destination creation
   parameters. Instead, edit the serialized volume in the ``volumes``
   section of the workload's ``params``.

-  ``additional_volumes`` any additonal volumes to be configured for 
   workload migrations with storage mode (data_copy) set to false.

-  ``floating_ip_mode`` controls whether and how floating IPs should be
   created for workloads:

   -  ``skip``: Do not create any floating IPs on the destination
      server.

   -  ``new``: Create a new floating IP (auto-assigned address).

   -  ``existing``: Assume the floating IP address as specified in
      the workload serialization is already assigned to the
      destination project, but not attached. Attach this floating
      IP. If this is not possible for some reason, fail.

   -  ``auto`` (default): Attempt the ``existing`` method of floating
      IP assignment first, but should it fail, fall back to the
      ``new`` method instead.

   General remarks regarding floating IPs:

   In the ``workloads.yml`` export, each serialized floating IP
   contains a ``fixed_ip_address`` property, so a floating IP will
   be created on the port with this address. (When editing
   ports/fixed addresses of a workload, make sure to also edit the
   ``fixed_ip_address`` properties of its floating IPs accordingly.)

   It is important to note that the address of a newly created
   floating IP will be automatically selected by the cloud, it will
   not match the floating IP address of the source server. (In most
   cases, the floating IP ranges of src/dst clouds don't overlap
   anyway.)