Multitenancy: Migration

Feature history for multitenancy migration

Table 1. Feature history
Feature name Release information Description

Migrate Multitenant Cisco Catalyst SD-WAN Overlay

Cisco IOS XE Catalyst SD-WAN Release 17.6.1a

Cisco vManage Release 20.6.1

This feature enables you to migrate a multitenant Cisco Catalyst SD-WAN overlay comprising shared Cisco SD-WAN Manager instances and Cisco SD-WAN Validator, and tenant-specific Cisco SD-WAN Controllers to a multitenant overlay comprising shared Cisco SD-WAN Manager instances, Cisco SD-WAN Validator, and Cisco SD-WAN Controllers.

Migration of a tenant from a multitenant overlay to a single-tenant deployment

Cisco IOS XE Catalyst SD-WAN Release 17.13.1a

Cisco Catalyst SD-WAN Manager Release 20.13.1

 This feature supports the migration of a tenant from a multitenant overlay to a single-tenant deployment. To migrate a tenant between two Cisco Catalyst SD-WAN deployments, move the tenant configurations, statistical data, and WAN edge devices from one deployment to another.

Tenant migration in a multitenant deployment

The tenant migration involves

  • export of tenant data from the source Cisco SD-WAN Manager instance, and

  • and import of data to the destination Cisco SD-WAN Manager instance.

After the data migration is complete, the tenant WAN edge devices with active control connections with the source Cisco SD-WAN Manager migrate and form connections with the destination Cisco SD-WAN Manager.

Availability

  • From Cisco IOS XE Catalyst SD-WAN Release 17.6.1a and Cisco vManage Release 20.6.1, migration of a single-tenant overlay to a multitenant deployment is supported only with Cisco Catalyst SD-WAN controllers deployed on-premises.

  • From Cisco IOS XE Catalyst SD-WAN Release 17.13.1a and Cisco Catalyst SD-WAN Manager Release 20.13.1, migration of a tenant from a multitenant overlay to a single-tenant deployment is supported.

Restrictions for migration of a tenant from a multitenant overlay to a single-tenant deployment

Defines the restrictions during tenant migration in Cisco Catalyst SD-WAN deployments.

  • Change in the tenant organization name is not supported when the tenant moves from the Cisco Catalyst SD-WAN source to destination deployment.

  • Tenant migration with multitenant WAN edge devices is not supported.

  • Data traffic loss is expected during migration as devices are migrating from one set of SD-WAN Controllers to another.

  • All user passwords are set to the default Cisco password on the destination overlay. The default password is Cisco#123@Viptela.

  • Statistical data of the tenant that can be relearned by destination SD-WAN Manager is not migrated.

  • The migration procedure does not support multiple imports on the same destination SD-WAN Manager. Reinitialize the destination SD-WAN Manager to allow import again.

Migrate single-tenant Cisco Catalyst SD-WAN overlay to multitenant Cisco Catalyst SD-WAN deployment

Prerequisites to migrate single-tenant SD-WAN overlay to multitenant SD-WAN deployment

Follow these prerequistes to ensure a successful migration.

  • Ensure that the edge devices in the single-tenant deployment can reach the Cisco SD-WAN Validator in the multitenant deployment

  • Ensure that the template, routing, and policy configuration on the edge devices is synchronized with the current configuration on Cisco SD-WAN Manager

  • Configure a maintenance window for the single-tenant overlay before performing this procedure. See Configure or Cancel SD-WAN Manager Server Maintenance Window.

  • We recommend that you use a custom script or a third-party application like Postman to execute the API calls.

  • The software versions of the Cisco Catalyst SD-WAN controllers and WAN edge devices must be identical in both the single-tenant and multitenant deployments.

Minimum software requirements for to migrate a single-tenant overlay

Table 2. Software requirements

Device

 Software version
Cisco SD-WAN Manager Cisco vManage Release 20.6.1
Cisco SD-WAN Validator Cisco SD-WAN Release 20.6.1
Cisco SD-WAN Controller Cisco SD-WAN Release 20.6.1
Cisco IOS XE Catalyst SD-WAN device Cisco IOS XE Catalyst SD-WAN Release 17.6.1a

Minimum software requirements for the multitenant deployment to which the single-tenant overlay must be migrated

Table 3. Software requirements

Device

 Software version
Cisco SD-WAN Manager Cisco vManage Release 20.6.1
Cisco SD-WAN Validator Cisco SD-WAN Release 20.6.1
Cisco SD-WAN Controller Cisco SD-WAN Release 20.6.1
Cisco IOS XE Catalyst SD-WAN device Cisco IOS XE Catalyst SD-WAN Release 17.6.1a

Migrate single-tenant SD-WAN overlay to multitenant SD-WAN deployment

Migration of a single-tenant overlay to a multitenant deployment is only supported with the SD-WAN Controllers deployed on-premises. Migration is yet to be supported with cloud-hosted SD-WAN Controllers.

Procedure

Step 1

Export the single-tenant deployment and configuration data from a SD-WAN Controller instance controlling the overlay.

While exporting the data, SD-WAN Controller attempts to detach any CLI templates from the edge devices in preparation for the migration to the multitenant deployment. If prompted by SD-WAN Manager, detach CLI templates from the edge devices and execute the export API call again.

Method POST
URL https://ST-vManage-IP-address
Endpoint /dataservice/tenantmigration/export
Authorization Admin user credentials.
Body

Required

Format: Raw JSON

{
    "desc": <tenant_description>,
    "name": <tenant_name>,
    "subdomain": <tenant_name>.<domain>,
    "orgName":  <tenant_orgname >       
 }

Field Description:

  • desc: A description of the tenant. The description can be up to 256 characters and can contain only alphanumeric characters.

  • name: Unique name for the tenant in the multitenant deployment.

  • subdomain: Fully qualified sub-domain name of the tenant. The sub-domain name must include the domain name of the service provider. For example, if managed-sp.com is the domain name of service provider, and the tenant name is Customer1, the tenant sub-domain name would be customer1.managed-sp.com.

  • orgName: Name of the tenant organization. The organization name is case-sensitive.

Response

Format: JSON

{
    "processId": <vManage_process_ID>,
}

Step 2

Check the status of the data export task in SD-WAN Manager.

When the task succeeds, download the data using the URL https://ST-vManage-IP-address/dataservice/tenantmigration/download/default.tar.gz

Step 3

Import the data exported from the single-tenant overlay, on a multitenant SD-WAN Manager instance.

When the task succeeds, on the multitenant Cisco SD-WAN Manager, you can view the devices, templates, and policies imported from the single-tenant overlay.

Method POST
URL https://MT-vManage-IP-address
Endpoint /dataservice/tenantmigration/import
Authorization Provider admin user credentials.
Body Required

Format: form-data

Key Type: File

Value: default.tar.gz
Response 
Format:
            JSON
{
    "processId": <vManage_process_ID>,
    "migrationTokenURL": <token_URL>,
}

Step 4

Obtain the migration token using the token URL obtained in response to the API call in step 3.

Method GET
URL https://MT-vManage-IP-address
Endpoint migrationTokenURL obtained in Step 3.
Authorization Provider Admin user credentials.
Response The migration token as a large blob of encoded text.

Step 5

On the single-tenant SD-WAN Manager instance, initiate the migration of the overlay to the multitenant deployment.

Method POST
URL https://ST-vManage-IP-address
Endpoint dataservice/tenantmigration/networkMigration
Authorization Admin user credentials.
Body Required

Format: Raw text

Content: Migration token obtained in Step 4.
Response

Format: JSON

{
    "processId": <vManage_process_ID>,
}
As part of the migration task, the address of the multitenant Cisco SD-WAN Validator, and the service provider and tenant organization names are pushed to the WAN edge devices of the single-tenant overlay.

If the task succeeds, WAN edge devices form control connections to controllers in the multitenant deployment; the WAN edge devices are no longer connected to the controllers of the single-tenant overlay.

What to do next

In SD-WAN Manager, check the status of the migration task.

Attach any CLI templates detached from the edge devices (in Step 1) after migration to the multitenant deployment. Before you attach the templates, update the Cisco SD-WAN Validator IP address and the Organization name to match the configuration of the multitenant deployment.

In the single-tenant deployment, if Cisco SD-WAN Manager-signed certificates are installed on cloud-based WAN edge devices, the certificates are cleared when the devices are migrated to the multitenant deployment.

You must re-certify the devices on the multitenant SD-WAN Manager. If enterprise certificates are installed on the cloud-based WAN edge devices, the certificates are not affected by the migration. For more information, see Enterprise Certificates.

Migrate a tenant from a multitenant Cisco Catalyst SD-WAN overlay to single-Tenant Cisco Catalyst SD-WAN deployment

Prerequisites to migrate a tenant from a multitenant SD-WAN overlay to single-tenant SD-WAN deployment

Ensure these prerequisites are met for a successful migration.

  • Manually migrate the serial number of the WAN edge device associated to a virtual account on the source Cisco SD-WAN Manager overlay in Cisco PNP to the destination virtual account.

  • Ensure that you manually create the controller profile on the destination virtual account for on-prem to on-prem or cloud to on-prem deployments.

  • Ensure that the source and destination Cisco SD-WAN Manager instances use the same Certificate Authority (CA) and software release; a mismatch can block tenant data import and cause migration failure.

  • Ensure that you check the CPU, memory, and disk size requirements of the destination overlay Cisco SD-WAN Controller before the migration to meet the WAN edge forecast requirements.

  • Ensure that there is no overlap between the configured system IP addresses of edge devices and the destination overlay controllers.

  • Ensure that all devices in a tenant have connectivity to the Cisco SD-WAN Validator in the destination single-tenant overlay. The migration procedure supports a Cisco SD-WAN Validator on the single-tenant deployment configured either with IP or DNS.

    Push any required static route configuration to the devices before initiating any of the migration steps.

  • Ensure that there are valid control connections from Cisco SD-WAN Manager to the WAN edge devices in the source overlay.

Configuration

  • Ensure that the destination single-tenant Cisco SD-WAN Manager does not have any configurations before migration. You can configure only mandatory admin settings and all other configurations can be done after data import.

  • Configure a maintenance window for the multitenant overlay before performing this procedure. See Configure or Cancel SD-WAN Manager Server Maintenance Window.

  • Ensure that the WAN edge devices that are configured using CLI, device template, or configuration groups, have an IP host mapping to the Cisco SD-WAN Validator in the destination single-tenant overlay.

  • We recommend that you use a custom script or a third-party application like Postman to execute the API calls.

Migrate a tenant from a multitenant SD-WAN overlay to single-tenant SD-WAN deployment

Use these steps to migrate a tenant from a multitenant SD-WAN overlay to single-tenant SD-WAN deployment.

Procedure

Step 1

Export the multitenant deployment configuration and statistical data from a Cisco SD-WAN Manager instance controlling the source overlay.

Method POST
URL https://MT-vManage-IP-address
Endpoint /dataservice/tenantmigration/export
Authorization Administrator user credentials.
Body

Required

Format: Raw JSON

Example:

{
    "name": "tenant1",
    "desc": "This is tenant1",
    "orgName": "vIPtela Inc MT to ST Migration Regression-Tenant1 Inc",
    "subDomain": "tenant1.mtreg.com",
    "wanEdgeForecast": 100,
    "migrationKey="tenant1TenantMigrationKey123",
    "isDestinationOverlayMT": false
}

Field descriptions:

Note

 

Ensure that the name, desc, orgName, subdomain, and wanEdgeForecast match the tenant you wish to migrate.

  • name: Unique name for the tenant in the multitenant deployment. The name should be between 8-32 characters and can contain only alphanumeric characters.

  • desc: Description of the tenant. The description can be up to 256 characters and can contain only alphanumeric characters.

  • orgName: Name of the tenant organization. The organization name is case-sensitive.

  • subdomain: Fully qualified sub-domain name of the tenant. The sub-domain name must include the domain name of the service provider. For example, if managed-sp.com is the domain name of service provider, and the tenant name is Customer1, the tenant sub-domain name would be customer1.managed-sp.com.

  • wanEdgeForecast: Number of WAN edge devices that the tenant can deploy.

  • migrationKey: Migration key which is used to encrypt sensitive data during migration. The migration key should be between 8-32 characters and can contain only alphanumeric characters.

  • isDestinationOverlayMT: Boolean variable which speficies if the migration is happening to a mutitenant overlay or not.

Response

Format: JSON

{
    "processId": <vManage_process_ID>,
}

Step 2

Check the status of the data export task in SD-WAN Manager When the task is successfully complete, download the data from the following URL: https://MT-vManage-IP-address/dataservice/tenantmigration/download/default.tar.gz

Step 3

Import the data to the single-tenant instance, as follows:

  1. Execute the following API:

    Method POST
    URL https://ST-vManage-IP-address
    Endpoint /dataservice/tenantmigration/import/{migrationKey}

    Use the same migration key specified earlier.
    Authorization Provider administrator user credentials.
    Body

    Required

    Format: form-data

    Key Type: File

    Value: default.tar.gz
    Response 
    Format:
            JSON
    {
    "processId": <vManage_process_ID>,
    "migrationTokenURL": <token_URL>,
}

  2. When the task is complete, on the single-tenant SD-WAN Manager you can view the devices, templates, and policies imported from the multitenant overlay.

Step 4

After the import, update information related to the device templates, policies, and other deployment-specific parameters.

  1. Check and update the administrator settings as some of the administrator settings specific to the source overlay are not exported. The import does not override the administrator settings that are already configured in destination SD-WAN Manager.

Step 5

If a centralized policy is present on the source tenant, the migration copies the policy to the destination overlay.

We recommend creating Cisco SD-WAN Controller templates and attaching them to the devices. Apply the centralized policy to devices in the destination overlay before proceeding.

Step 6

Obtain the migration token using the token URL from the previous step.

Method GET
URL https://ST-vManage-IP-address
Endpoint migrationTokenURL obtained in the previous step.
Authorization Provider administrator user credentials.
Response The migration token as a large encoded text.

Step 7

On the multitenant SD-WAN Manager instance, initiate the migration of the overlay to the single-tenant deployment.

Method POST
URL https://MT-vManage-IP-address
Endpoint dataservice/tenantmigration/networkMigration
Authorization Administrator user credentials.
Body

Required

Format: Raw text

Content: Migration token obtained in the previous step.
Response

Format: JSON

{
    "processId": <vManage_process_ID>,
}

When the task succeeds, WAN edge devices form control connections to controllers in the single-tenant deployment; the WAN edge devices are no longer connected to the controllers of the multitenant overlay.

What to do next

In SD-WAN Manager, check the status of the migration task.

After the migration is successfully complete, perform the following tasks:

  • If WAN edge devices have SD-WAN Manager signed certificates in the source setup, the certificates are cleared from the device during migration and control connections are lost. Recertify the devices in the destination.

  • The passwords are updated to the default password in the destination overlay for users created on a tenant in the source overlay. Make any configuration changes specific to the destination overlay.

  • Delete the tenant on the source overlay after migration and verification is complete.

Migrate multitenant Cisco Catalyst SD-WAN overlay

Restrictions for migrating multitenant Cisco Catalyst SD-WAN overlay

Defines restrictions for migrating a multitenant Cisco Catalyst SD-WAN overlay.

  • This migration procedure applies only to SD-WAN Controllers deployed on premises.

  • The multitenant overlay can only be migrated to a setup in which Cisco SD-WAN Manager instances run Cisco vManage Release 20.6.1 software and SD-WAN Controllers run Cisco SD-WAN Release 20.6.1 software.

  • This migration procedure cannot be used to merge two or more multitenant overlays. Only one multitenant overlay can be migrated to the new setup at a time.

Migrate multitenant Cisco Catalyst SD-WAN overlay

Before you begin

Minimum software requirements for SD-WAN Controllers and WAN edge devices in the multitenant overlay to be migrated:

Device Software version
Cisco SD-WAN Manager Cisco vManage Release 20.3.3
Cisco SD-WAN Validator Cisco SD-WAN Release 20.3.3
Cisco SD-WAN Controller Cisco SD-WAN Release 20.3.3
Cisco IOS XE Catalyst SD-WAN device Cisco IOS XE Release 17.3.3

Procedure

Step 1

Upgrade the software on the three SD-WAN Manager instances in the cluster to Cisco vManage Release 20.6.1. For more information, see Upgrade Cisco SD-WAN Manager Cluster.

Run the command request nms configuration-db upgrade on only one of the SD-WAN Manager instances.

Step 2

After the SD-WAN Manager software is upgraded to Cisco vManage Release 20.6.1, log in to the SD-WAN Manager.

You're prompted to set a new password. Enter a new password that adheres to the password guidelines.

Step 3

Upload the Cisco SD-WAN Release 20.6.1 software to SD-WAN Manager. For more information, see Add an Image to the Software Repository.

Step 4

Upgrade the Cisco SD-WAN Validator software to Cisco SD-WAN Release 20.6.1. For more information, see Upgrade the Software Image on a Device.

Step 5

Create two SD-WAN Controllers instances running Cisco SD-WAN Release 20.6.1 software. See Deploy the Cisco SD-WAN Controller.

With two SD-WAN Controllerinstances, you can support up to 24 tenants. To support up to 50 tenants, create six Cisco SD-WAN Controller instances.

Step 6

Add Cisco SD-WAN Controllers to the overlay network.

The Provider Dashboard shows the new SD-WAN Controller running Cisco SD-WAN Release 20.6.1 software.

The Tenant Dashboard shows the older SD-WAN Controller running Cisco SD-WAN Release 20.3.3 software.

Step 7

Enable the maintenance window on SD-WAN Manager. For more information, see Configure or Cancel SD-WAN Manager Server Maintenance Window.

A maintenance window of 3 to 4 hours is recommended.

Step 8

Migrate the tenant configuration from the older tenant-specific SD-WAN Controller running Cisco SD-WAN Release 20.3.3 software to the new shared SD-WAN Controller running Cisco SD-WAN Release 20.6.1 software.

Method POST
URL https://<vmanageip>:<port>
Endpoint dataservice/tenant/vsmart-mt/migrate
Authorization Provider admin user credentials.
Body

Required

Format: Raw JSON

{}
Response

Format: JSON

{
    "processId": <vManage_process_ID>,
}

Step 9

Upgrade the Cisco IOS XE Catalyst SD-WAN device software to Cisco IOS XE Catalyst SD-WAN Release 17.6.1a. For more information, see Upgrade the Software Image on a Device and Activate a New Software Image.

It is not necessary to upgrade the tenant WAN edge device software in the same maintenance window in which you migrate the multitenant overlay. However, we recommend that you upgrade the tenant WAN edge device software within a few weeks of the migration.

During the migration task, the following changes are affected:

  1. The older SD-WAN Controllers are invalidated and deleted from the overlay network.

  2. In the tenant view, the older SD-WAN Controllers are removed from the Tenant Dashboard, and the Devices and the Certificates page.

  3. The tenant WAN edge devices are connected to the new SD-WAN Controller.

What to do next

In SD-WAN Manager check the status of the migration task using the processId from the API response.

Verify the migration

Use these steps to verify multitenant migration.

Procedure

Step 1

In the provider view, perform these checks:

  1. From the Main Dashboard page, verify whether the tenant WAN edge devices are connected to the new multitenant s.

  2. View Tenants Associated with a Cisco SD-WAN Controller.

  3. On the SD-WAN Controller CLI, run the command show control connections . In the command output, verify that control connections are established between the SD-WAN Controller and the tenant WAN edge devices.

Step 2

In the provider-as-tenant view, verify whether the multitenant SD-WAN Controllers appear on the Tenant Dashboard.