Cisco Catalyst SD-WAN Multitenancy Guide, Releases 26.x and Later

PDF

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

Updated: June 21, 2026

Want to summarize with AI?

Log in

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 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 SD-WAN Manager.

  • Configure a maintenance window for the single-tenant overlay before performing this procedure. Refer to the information about configuring an SD-WAN Manager server maintenance window in the Cisco Catalyst SD-WAN Control Components and Device Management Guide.

  • 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 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 1. 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 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

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

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>,
}
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
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>,
}
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.
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.