Runbook reference

Runbooks define the VMs to be migrated, their order, and additional configuration parameters. This page describes the columns that can be part of a runbook. For more information on runbooks, see the Migration waves overview.

Be sure to see the example runbook.

The fields in a runbook are defined in the following table.

Field Required Format Notes
BlockOnFailure Yes TRUE or FALSE If set to TRUE and an action fails, the wave stops and subsequent RunGroups are not run. The default value is FALSE.
BootFirmware Info only* UEFI or BIOS. Generated by Migrate for Compute Engine when the runbook is generated. Where this value is UEFI, you can enable Secure Boot for the migrated VM on Compute Engine by specifying TRUE in the GcpSecureBoot column.

Values include UEFI for UEFI-based source VMs and BIOS for vSphere BIOS VMs, AWS, and Azure VMs.
feature-flags:migrate-storage-ha No TRUE (default) or FALSE

When booting your migrating Windows VMs in Compute Engine, Migrate for Compute Engine runs code to adapt the VMs to the Compute Engine environment. If high availability support could not be installed, you might see the following error:

"Operation system adaptation process failed to install packages required for storage high availability. This can be overridden by setting migrate-storage-ha to FALSE, or by running Offline Migration."

You can override the error by setting feature-flags:migrate-storage-ha to FALSE, or by using offline migration.
GcpDiskType for FullMigration, OfflineMigration standard, SSD, or balanced Used to create a disk in the PrepareToDetach operation only.
GcpEphemeralPublicIp No TRUE or FALSE Assign an ephemeral public-facing IP address.
GcpInstanceServiceAccount No Service Account to apply to the new instance. If the default Cloud Extension checkbox is selected when the runbook is created, then that Cloud Extension's default network is populated.
GcpNetworkTags No

Workload network tags to apply to the new instance. If empty, no tag will be added to the instance. If the default Cloud Extension checkbox is selected when the runbook is created, then that Cloud Extension's default network is populated.

Enclose multiple tags in quotation marks (""), separated by commas.

For more about the role of network tags in your migration environment, see Network access requirements.
GcpProject Yes String The Google Cloud project to launch the migrated VM in.
GcpSecureBoot No TRUE or FALSE. Default is FALSE. Use TRUE to specify that a UEFI-based source VM should have Secure Boot enabled after it is migrated. Default is FALSE. The BootFirmware field value must be UEFI in order for a GcpSecureBoot TRUE value to be accepted.
label:KEY No String Label key/value pairs applied to migrated VMs. You must add a new column to the runbook for each label. The column name is in the form "label:KEY", where KEY specifies the label name, and the row value specifies the label value for the VM.
license:msql Yes String

To append a MSQL PAYG licence to a VM, add the license:msql column to the runbook file, and specify the relevant MSSQL PAYG license string URI in the column. The specified license string is appended to the migrated instance created in Google Cloud.

For the list of URIs for different versions of MSQL, see VM OS license support.
license:os Only if changing software license source String

Specifies the license type for the migrated VM. By default, this field is left empty when generating a runbook. An empty value corresponds to the following license types:

  • Linux VM: BYOL (Bring Your Own License) license
  • Windows VM: PAYG (Pay-as-you-go) license

To override this default, set this field to apply a specific license based on your operating system type:

  • Linux VM

    • Set this field to indicate which Linux VMs have a premium license to convert the default BYOL license to a PAYG license billed via Google Cloud. A premium license is available for Red Hat Enterprise Linux (RHEL) or Suse Linux Enterprise Server (SLES).

      For more information, see Using premium OS licenses.

  • Windows VM
    • Set this field to specify which Windows VMs have a BYOL license. See VM OS license support for the list of values for different versions of Windows.
    • When upgrading Windows Server 2008 R2 VMs to Windows Server 2012, set this field to https://www.googleapis.com/compute/v1/projects/windows-cloud/global/licenses/windows-server-2012-r2-byol.
    • For Windows BYOL licenses, sole-tenant nodes are recommended to host your migrated VMs.
MemoryGB Info only* Integer, GB Current memory size of the source VM.
NumCPU Info only* Integer Current number of CPUs of the source VM.
NumDisks Info only* Integer Current number of disks of the source VM.
OSType Info only* String VM operating system. Populated from vSphere.
ProbeTCPPort Yes Unsigned Integer TCP port to probe the VM on. We recommend you use 3389 (RDP) for Windows VMs, or 22 (SSH) for Linux VMs.

Probing is performed during the RunInCloud and Detach phases.
ProvisionedSpaceGB Info only* Integer Total allocated storage space for the VM.
ProbeWaitMinutes Yes Unsigned Integer Number of minutes to wait for the port probe to respond, after which the probe check is considered to have failed. The default is 0 minutes (no wait). Used by RunInCloud, Detach phases.
RunGroup Yes Signed Integer Grouping of VMs to be migrated. VMs in the same group are migrated in parallel. VMs in different groups are migrated sequentially in ascending order.
SoleTenancy-NodeAffinity:[KEY] No String For use with sole-tenant nodes. The list of node affinity labels defining where to place the VM.
SoleTenancy-NodeAffinityNot:[KEY] No String For use with sole-tenant nodes. The list of node affinity labels defining where not to place the VM.
SoleTenancy-RestartOnFailure No Yes (default) or No For use with sole-tenant nodes. Attempt to restart the VM on the same physical host. For more information on how to set this field for your licenses, see the sole-tenant documentation.
SoleTenancy-VmHostMaintenancePolicy No migrate (default) or terminate For use with sole-tenant nodes. Useful for when changing hosts incurs an additional software license cost. If set to migrate, the VM is migrated to a new host during maintenance. If set to terminate, Compute Engine won't attempt to migrate the VM until the host has been down for more than 60 minutes. For more information on how to set this field for your licenses, see the sole-tenant documentation.

The migrate policy is currently not supported for Windows BYOL. Your wave migration can't proceed if the terminate option is not explicitly set when using BYOL.
SourceCloudDetails For RunInCloud, FullMigration, OfflineMigration String The name of the Cloud Details that contains Cloud authentication information.
tag:* columns No String Label key/value pairs applied to migrated VMs.
TargetCloudExtension For RunInCloud, FullMigration, OfflineMigration String The name of the Cloud Extension that migrates the VMs.
TargetEdgeNode For RunInCloud, FullMigration, OfflineMigration NodeA or NodeB Primary edge node of the Cloud Extension that handles this VM's migration.
TargetInstanceName For RunInCloud, FullMigration, OfflineMigration String If the source instance has a Name tag, its value is reformatted according to Google Cloud naming limitations and used. Otherwise, the AWS, vSphere, or Azure instance ID is used.
TargetInstanceType For RunInCloud, FullMigration, OfflineMigration String Instance type of the VM to be created on Google Cloud (for example, n1-standard-1). For a complete list of instance types, see the Compute Engine documentation.
TargetPublicIP For RunInCloud, FullMigration, OfflineMigration The name of a reserved static public IP address. The name of a public static IPv4 IP address to assign to the instance in the cloud. You can create IPs from the Google Cloud console.
TargetStaticIP For RunInCloud, FullMigration, OfflineMigration The name of a reserved static internal IP address. The name of an internal static IPv4 IP address to assign to the instance in the cloud. You can create IPs from the Google Cloud console.
TargetSubnet For RunInCloud, FullMigration, OfflineMigration String Subnet ID to be used by the target instance. When empty, the default subnet (as specified during the Cloud Extension creation) is selected. For example, https://www.googleapis.com/compute/v1/projects/<project ID>/regions/europe-west1/subnetworks/<subnet> name>
UpgradeOS No TRUE or FALSE. Default is FALSE. When the VM OS is supported for upgrade during migration, setting this field to TRUE makes this VM available to upgrade when you run the Upgrade OS task after the Detach phase. A TRUE value on an unsupported-for-upgrade VM OS will cause an error at runbook validation and at migration runtime.

Migrate for Compute Engine supports Windows Server 2008R2 for upgrade to Windows Server 2012. For more, see Upgrading Windows Server VMs from 2008R2 to 2012.
VmID Yes String If migrating from on-premises vSphere, this is the VM ID of the source VM.

If migrating from AWS or Azure, this is the instance ID.
VmName No String If migrating from on-premises vSphere, this is the name of the source VM.

If migrating from AWS or Azure, this is the instance ID.
WriteIsolation For On-Premises to Cloud Migrations TRUE or FALSE For on-premises to cloud migrations, you can select either TRUE (write isolation enabled) or FALSE (write-back mode).

For cloud-to-cloud migrations, TRUE is the only valid option; write-back synchronization is currently not supported in cloud-to-cloud migrations.
*Fields marked as Info only display information about the VM and cannot be changed.