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

PDF

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

Updated: June 21, 2026

Want to summarize with AI?

Log in

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. Refer to the information about configuring a maintenance window in the basic settings section of the Cisco Catalyst SD-WAN Control Components and Device Management Guide.

  • 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

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