Skip to main content
NetApp virtualization solutions

Configure the Shift Toolkit

Contributors netapp-jsnyder kevin-hoke
PDFs

Configure the Shift Toolkit to automate the migration or conversion of VMs) This process includes adding source and destination sites, configuring storage, grouping VMs into resource groups, creating migration blueprints, and scheduling migrations.

Run Shift toolkit

  • Using the browser, access Shift toolkit UI by entering the "http://<IP address specified during installation>:3001"

    Note Use Google chrome or Internet explorer for best experience.

  • Access the UI using default credentials as below:

    Username: admin

    Password: admin

Note The admin credentials can be changed using "Change Password" option.

Figure showing input/output dialog or representing written content

Accept the legal EULA by clicking on "Accept and Continue".

Figure showing input/output dialog or representing written content

Shift Toolkit Configuration

Once the storage and connectivity to both the source and destination hypervisors have been configured properly, begin configuring Shift toolkit to automate the migration or conversion of the virtual machine VMDK to appropriate format, leveraging the FlexClone functionality.

Add Sites

The first step is to discover and add the source vCenter and then the target Hyper-V details (both hypervisors and storage) to Shift toolkit. Open Shift toolkit in a supported browser and use the default username and password (admin/admin) and click on "Add Sites".

Figure showing input/output dialog or representing written content

Note Sites can also be added using Discover option.

Add the following platforms:

Source

  • Source Site Details

    • Site Name - Provide a name for the site

    • Hypervisor – Select VMware as the source (only option available during GA)

    • Site Location – Select the default option

    • Connector – Select the default selection

Once filled, click Continue.

Figure showing input/output dialog or representing written content

  • Source vCenter

    • Endpoint - Enter the IP address or FQDN of the vCenter server

    • Username - username to access the vCenter (in UPN format: username@domain.com)

    • vCenter Password – Password to access vCenter for performing inventory of the resources.

    • vCenter SSL Thumbprint (optional)

Select "Accept Self signed certificate" and click Continue.

Figure showing input/output dialog or representing written content

  • ONTAP Storage system credentials

Figure showing input/output dialog or representing written content

Once added, Shift toolkit will perform an automatic discovery and display the VMs along with the relevant metadata information. Shift toolkit will automatically detect the networks and port groups used by the VMs and will populate them.

Note If any modifications are made to the source site, ensure to run the discovery to fetch the latest information. This can be done by clicking on 3 dots against the site name and click on "Discover Site".
Note The VM inventory is auto-refreshed every 24 hours.

Figure showing input/output dialog or representing written content

To view the data for a specific vCenter, go to the dashboard, click on "View VM List" against the appropriate site name. The page will display the VM inventory along with the VM attributes.

Next step is to add the destination hypervisor. To add, click on "Add New Site" and select "Destination".

Destination

Figure showing input/output dialog or representing written content

  • Destination Site Details

    • Site Name - Provide a name for the site

    • Hypervisor – Select Hyper-V or KVM as the target

    • Site Location – Select the default option

    • Connector – Select the default selection

Once filled, click Continue.

Figure showing input/output dialog or representing written content

Based on the hypervisor selection, fill in the necessary details.

  • Destination Hyper-V details

    • Hyper-V Standalone or failover cluster manager IP address or FQDN

    • Username - username to access (in UPN format: username@domain.com or domain\administrator)

      Password – Password to access Hyper-V host or FCI instance for performing inventory of the resources.

      Select "Accept Self signed certificate" and click Continue.

Figure showing input/output dialog or representing written content

Once done, Click Continue

Note Shift toolkit does not communicate with System Center directly in the current release.
Note The Hyper-V FCI and host discovery relies on DNS resolution. Ensure the hostnames should be resolvable from Shift toolkit VM. In case resolution fails, update the host file (C:\Windows\System32\drivers\etc\hosts) and retry the discovery operation.

ONTAP Storage system

Figure showing input/output dialog or representing written content

Note The source and destination storage system should be the same as the disk format conversion happens at the volume level and within the same volume.

Figure showing input/output dialog or representing written content

Next step is to group the required VMs into their migration groups as resource groups.

Resource Groupings

Once the platforms have been added, group the VMs you want to migrate or convert into resource groups. Shift toolkit resource groups allow you to group set of dependent VMs into logical groups that contain their boot orders and boot delays.

Note Ensure the Qtrees are provisioned (as mentioned in the pre-requisite section) before creating the resource groups.

To start creating resource groups, click on the "Create New Resource Group" menu item.

  1. Access Resource groups, click on "Create New Resource Group".

    Figure showing input/output dialog or representing written content

  2. On the "New resource group", select the Source site from the dropdown and click "Create"

  3. Provide Resource Group Details and select the workflow. The workflow provides two options

    1. Clone based Migration – performs end to end migration of the VM from source hypervisor to destination hypervisor.

    2. Clone based Conversion – Performs conversion of the disk format to the selected hypervisor type.

      Figure showing input/output dialog or representing written content

  4. Click on "Continue"

  5. Select appropriate VMs using the search option. The default filter option is "Datastore".

    Note Move the VMs to convert or migrate to a designated datastore on a newly created ONTAP SVM before conversion. This helps isolating the production NFS datastore and the designated datastore can be used for staging the virtual machines.

    Figure showing input/output dialog or representing written content

    Note The datastore dropdown in this context will only show NFSv3 datastores. NFSv4 datastores will not be displayed.

    Figure showing input/output dialog or representing written content

  6. Update the migration details by selecting "Destination Site", Destination Hyper-V entry" and Datastore to Qtree mapping.

    Figure showing input/output dialog or representing written content

    Note Make sure that the destination path (where the converted VMs are stored) is set to a qtree when converting VMs from ESX to Hyper-V. Set the destination path to the appropriate qtree.
    Note Multiple qtrees can be created and used for storing the converted VM disks accordingly.

  7. Select the Boot Order and Boot delay (secs) for all the selected VMs. Set the order of power on sequence by selecting each virtual machine and setting up the priority for it. 3 is the default value for all virtual machines.

    Options are as follows:

    1 – The first virtual machine to power on
    3 – Default
    5 – The last virtual machine to power on

    Figure showing input/output dialog or representing written content

  8. Click on "Create Resource Group".

    Figure showing input/output dialog or representing written content

    Note In the event of the need to modify the resource group so as to add or remove virtual machines, use the 3 dots against the resource group name and select "Edit Resource Group".

Blueprints

To migrate or convert virtual machines, a plan is necessary. Select the source and destination hypervisor platforms from the drop down and pick the resource groups to be included in this blueprint, along with the grouping of how applications should be powered on (i.e. domain controllers, then tier-1, then tier-2, etc). These are often called as migration plans as well. To define the blueprint, navigate to the "Blueprints" tab and click on "Create New Blueprint".

To start creating blueprint, click on the "Create New Blueprint".

  1. Access Blueprints, click on "Create New Blueprint".

    Figure showing input/output dialog or representing written content

  2. On the "New Blueprint", provide a name for plan and add necessary host mappings by selecting Source Site > associated vCenter, Destination Site and the associated Hyper-V hypervisor.

  3. Once mappings are done, select the cluster and host mapping.

    Figure showing input/output dialog or representing written content

  4. Select Resource Group Details and click on "Continue"

    Figure showing input/output dialog or representing written content

  5. Set Execution Order for Resource Group. This option enables to select the sequence of operations when multiple resource groups exist.

  6. Once done, select Network Mapping to the appropriate virtual switch. The virtual switches should already be provisioned within Hyper-V.

    Figure showing input/output dialog or representing written content

    Note On Hyper-V side, the virtual switch type "External" is the only supported option for network selection.
    Note For test migration, "Do no configure Network" is the default selection and Shift toolkit does not perform IP address assignment. Once the disk is converted and virtual machine is bought on Hyper-V side, manually assign the bubble network switches to avoid any colliding with production network.

    Figure showing input/output dialog or representing written content

  7. Based on the selection of VMs, storage mappings will be automatically selected.

    Note Make sure the qtree is provisioned beforehand and the necessary permissions are assigned so the virtual machine can be created and powered ON from SMB share.

  8. Under VM details, provide service account and valid user credentials for each OS type. This is used to connect to the virtual machine to create and run certain scripts that are necessary for removing VMware tools and backing up IP configuration details.

    1. For Windows based OS, it is recommended to use a user with local administrator privileges. Domain credential can also be used, however ensure there is a user profile existing on the VM before conversion, otherwise domain credentials won't work as it would look for domain authentication when there is no network connected.

    2. In case of Linux distro-based guest VMs, provide a user that can execute sudo commands without password meaning the user should be part of the sudoers list or added as a new configuration file to the /etc/sudoers.d/ folder.

      Figure showing input/output dialog or representing written content

  9. Again under VM details, select the relevant IP config option. By default, "Do not configure" is selected.

    1. To migrate VMs with the same IPs from the source system, select "Retain IP".

    2. To migrate VMs using static IPs in the source system and to assign DHCP on the target VMs, then select "DHCP".

      Make sure the following requirements are met for this functionality to work:

      • Ensure the VMs are powered on during the prepareVM phase and up to the scheduled migration time.

      • For VMware VMs, ensure that VMware Tools are installed.

      • Ensure the preparation script is run on the source VM by an account with administrator privileges on windows OS and with sudo privileges with no password option on Linux based distro OS to create cron jobs.

  10. The next step is VM configuration.

    1. Optionally resize the VMs CPU/RAM parameters which can be very helpful for resizing purposes.

    2. Boot Order override: Also modify the Boot Order and Boot delay (secs) for all the selected VMs across the resource groups. This is an additional option to modify the boot order if any changes required from what was selected during Resource group boot order selection. By default, the boot order selected during resource group selection is used, however any modifications can be done at this stage.

    3. Power ON: Uncheck this option if workflow should not power ON the virtual machine. Default option is ON meaning the VM will be powered ON.

    4. Remove VMware tools: Shift toolkit removes VMware tools after the conversion. This option is selected by default. This can be unselected if the plan is to execute customer's own customized scripts.

    5. Generation: Shift toolkit uses the following rule of thumb and defaults to the appropriate one- Gen1 > BIOS and Gen2 > EFI. No selection is possible for this option.

    6. Retain MAC: The MAC address of the respective VMs can be retained to overcome licensing challenges for those applications relying on MAC.

    7. Service Account override: This option allows to specify a separate service account if the global one cannot be used.

      Figure showing input/output dialog or representing written content

  11. Click "Continue".

  12. In the next step, schedule the migration by selecting the checkbox to set the date and time. Make sure all the virtual machines (VMs) are prepared and powered off before the scheduled date. Once done, click on "Create Blueprint".

    Figure showing input/output dialog or representing written content

    Note While scheduling, choose a date that is at least 30 minutes ahead of the current Shift VM time. This is to ensure the workflow gets enough time to prepare the VMs within the resource group.

  13. Once the blueprint is created, a prepareVM job is initiated and it automatically runs scripts on the source VMs to prepare them for migration

    Figure showing input/output dialog or representing written content

    This job runs a script using invoke-VMScript method to copy the necessary scripts for removing VMware tools and backing up network configuration details, including IP address, routes, and DNS information, which will be used to maintain the same settings on the target VM.

    • For Windows-based operating systems, the default location where the preparation scripts are stored is the "C:\NetApp" folder.

      Figure showing input/output dialog or representing written content

    • For Linux-based VMs, the default location where the preparation scripts are stored is /NetApp and the /opt directory.

      Figure showing input/output dialog or representing written content

      Note For a Linux source VM running CentOS or Red Hat, Shift toolkit is intelligent to automatically install the necessary Hyper-V drivers. These drivers must be present in the source VM before the disk conversion to ensure the VM can boot successfully after the conversion.
      Note For detailed information, refer to System stuck in dracut after the migration of a RHEL VM to hyper-v.

      Once the prepareVM job completes successfully (as shown in the screenshot below), the VMs are ready for migration, and the blueprint status will update to "Active."

      Figure showing input/output dialog or representing written content

      Figure showing input/output dialog or representing written content

      Migration will now happen at the set time or can be started manually by clicking on Migrate option.

Monitoring and Dashboard

Monitor the status of the jobs using Job Monitoring.

Figure showing input/output dialog or representing written content

With the intuitive UI, confidently evaluate the status of migration, conversion and blueprints. This enables administrators to swiftly identify successful, failed, or partially failed plans along with the number of VMs migrated or converted.

Figure showing input/output dialog or representing written content

Advanced Settings

Shift toolkit provides advanced settings that provides which can be accessed by Clicking the Settings icon in the top toolbar.

Figure showing input/output dialog or representing written content

CredSSP

Shift leverages Credential Security Service Provider (CredSSP) to manage the credentials transfer. During the conversion process, the Shift server runs a number of scripts on the guest OS of the VM being converted. The credentials to run these scripts are passed via a "double-hop" from the Shift server to the guest OS through the Hyper-V server.

Figure showing input/output dialog or representing written content

Configuring the Shift server as a CredSSP client:

The "Advanced Settings" wizard automatically configures the Shift server as a CredSSP client. Doing so enables the Shift server to delegate credentials to the Hyper-V servers.

What happens behind the scenes:

The Shift toolkit executes a series of commands to configure itself as a client, enabling it to manage Hyper-V hosts. This process involves setting up necessary configurations.

  • Runs these commands:

    • Set-Item WSMan:\localhost\Client\TrustedHosts -Value "fqdn-of-hyper-v-host"

    • Enable-WSManCredSSP -Role client -DelegateComputer "fqdn-of-hyper-v-host"

  • Configures the following group policy:

    • Computer Configuration > Administrative Templates > System > Credentials Delegation > Allow delegating fresh credentials with NTLM-only server authentication

Select Enable and add wsman/fqdn-of-hyper-v-host.

Configuring the Hyper-V server as a CredSSP server

Use the Enable-WSManCredSSP cmdlet on Hyper-V server to configure the Hyper-V server as a CredSSP server, which enables the Hyper-V server to receive credentials from the Shift server.

On the Hyper-V host where the virtual machines will be provisioned by Shift toolkit server, open a Windows PowerShell session as Administrator and run the following commands:

  1. Enable-PSRemoting

  2. Enable-WSManCredSSP -Role server

Swagger

The swagger page in the Advanced setting allows interaction with available APIs. The resources available through the Shift toolkit REST API are organized in categories, as displayed on the swagger API documentation page. A brief description of each of the resources with the base resource paths is presented below, along with additional usage considerations where appropriate.

Figure showing input/output dialog or representing written content

Session

You can use this API to log into the Shift toolkit Server. This API returns a user authorization token that is used to authenticate subsequent requests.

  • Start a session

  • Validate a session

  • Get all session ID

  • End a session

Connector

  • Add a connector

  • Get details of all connectors

  • Update the connector details by ID

  • Get connector details by ID

Tenant

Use APIs to perform Add and Get operations

  • Add tenant

  • Get all tenant

User

Use APIs to perform Add, get, change and accept operations

  • Add User

  • Get all user

  • Change password of the user

  • Accept EULA

CredSSP

Use APIs to perform enable and get operations

  • Enable credssp

  • Get status of credssp

Site

Use APIs to perform get, add, delete and update operations

  • Get count of site

  • Get all site details

  • Add a site

  • Get site detail by ID

  • Delete a site by ID

  • Add virtual environment to a site

  • Add storage environment to a site

  • Get virtual environment detail for a site

  • Update virtual environment detail for a site

  • Delete virtual environment detail for a site

  • Get storage environment detail for a site

  • Update storage environment detail for a site

  • Delete storage environment detail for a site

Discovery

Use APIs to perform discover and get operations

  • Discover source site

  • Get all discovery requests for source site

  • Discover target site

  • Get all discovery requests for target site

  • Get discovery steps for source site by Id

  • Get discovery steps for target site by Id

VM

Use APIs to perform get operations

  • Get VMs for a site and virtual environment in source

  • Get unprotected VMs for a site and virtual environment

  • Get VM count

  • Get protected VM count

Resource

Use APIs to perform get operations

  • Get resource details for a site and virtual environment

  • Get source site resources count

Resource Group

Use APIs to perform add, update and get operations

  • Get protection group count

  • Get all protection group details

  • Add a protection group

  • Get a protection group details by Id

  • Delete a protection group by Id

  • Update protection group details by Id

  • Get VMs of a protection group by Id

  • Get Blueprints containing the protection group

Blueprint

Use APIs to perform add, update and get operations

  • Get Blueprint Count

  • Get all Blueprint details

  • Add a Blueprint

  • Get blueprint details by Id

  • Delete blueprint by Id

  • Update blueprint details for Id

  • Get VMs of a blueprint

  • Get power status of VMs present in the blueprint

  • Get blueprint Count

  • Get all blueprint details

Compliance

Use APIs to perform add and get operations

  • Get compliance check result for a blueprint

  • Get compliance check final status for a blueprint

  • Add on demand new compliance check for a blueprint

Execution

Use APIs to perform get operations

  • Get all execution details

  • Get details of execution in progress

  • Get execution count

  • Get count of executions in progress

  • Get steps for execution Id

Recovery

Use APIs to perform add and get operations

  • Add new execution request for a Blueprint

  • Add retry request of execution for a Blueprint

  • Get execution statuses of all Blueprints

  • Get execution status for Blueprint ID

Script Block

Use APIs to perform get and update operations

  • Get all scripts metadata

  • Get script metadata by Id

  • Get all refresh metadata

  • Execute script

Script block

The script block within in Shift toolkit provides sample code that help automate, integrate and develop features via internal and external APIs available. On the Code Samples section in the script block, browse and download samples written by Shift toolkit Automation team and by the community members. Use the samples to get started with automation, management or integration tasks.

Figure showing input/output dialog or representing written content

Here is an example of a sample powershell script which can be used to delete a specific job within Shift UI. The capability is not exposed via workflow, however the same can be accomplished via the script block. The same script is also available as a bat script that can executed easily by downloading and calling the same.

Figure showing input/output dialog or representing written content

The objective here is to provide sample scripts to perform day 0 and day N operations for specific hypervisors using the Shift toolkit APIs and the respective hypervisor published APIs.

SAN Environments

As a key requirements of Shift toolkit, the VMs to be converted must reside in a NAS environment (NFS for ESX). If the VMs reside in a SAN environment (iSCSI, FC, FCoE, NVMeFC), then they must be migrated to a NAS environment before conversion.

Figure showing input/output dialog or representing written content

The approach above depicts a typical SAN environment in which VMs are stored in a SAN datastore. The VMs to be converted from ESX to Hyper-V along with their disks are first migrated to an NFS data-store with VMware vSphere Storage vMotion. Shift toolkit uses FlexClone to convert the VMs from ESX to Hyper-V. The converted VMs (along with their disks) reside on a CIFS share. The converted VMs (along with their disks) are migrated back to the SAN enabled CSV with Hyper-V Storage Live Migration.

Note The live VM migration might fail if nodes have different process capability sets. This can be handled by setting "Migrate to a physical computer with a different processor". This script is available under script block.