License Hub Migration Guide : Migration procedure from SSP - License Hub 5.1.2 (Source) to License Hub 2.0 (Target)

search cancel

License Hub Migration Guide : Migration procedure from SSP - License Hub 5.1.2 (Source) to License Hub 2.0 (Target)

book

Article ID: 450105

calendar_today

Updated On:

Products

VMware vDefend Firewall VMware vDefend Firewall with Advanced Threat Prevention VMware Avi Load Balancer

Issue/Introduction

This document provides the procedure for migrating from License Hub 5.1.2 to License Hub 2.0. There is no supported automated upgrade path between these two versions.

This guide details the following steps:

- Data export from the source deployment
- License transfer via the AVI Cloud Console
- Endpoint onboarding on the target deployment
- License assignment
- Post-migration verification

Environment

Security Services Platform (SSP) Source License Hub 5.1.2 And Target License Hub 2.0

Cause

A direct in-place upgrade is not supported from License Hub 5.1.2 to License Hub 2.0.

Resolution

Due to differences in deployment architecture, a direct in-place upgrade between License Hub 5.1.2 and License Hub 2.0 is not supported. Please follow this manual migration procedure strictly in the specified sequence.

Terminology

Source License Hub: The existing License Hub 5.1.2 deployment being migrated from
Target License Hub: The new License Hub 2.0 deployment to which data is being migrated
AVI Cloud Console: The centralized cloud management plane for license lifecycle management and usage reporting

Prerequisites

Target License Hub must be freshly installed with no configuration.
Target License Hub must be registered with the AVI Cloud Console with no licenses assigned. In case of Private/Critical Mode, please Log in to Target License Hub in Private Mode.
Confirmed network connectivity from Target License Hub to all managed endpoints onboarded on Source License Hub.
Current endpoint credentials (username, password, and certificates) must be available.
A maintenance window must be scheduled, approved, and communicated to stakeholders. Please note, the onboarding on Target License Hub after Source License Hub Config cleanup from endpoint may take about 5 to 20 minutes per endpoint. The total downtime will depend on the number of endpoints on the Source License Hub. These downtime estimates do not account for potential delays caused by manual steps & the Rollback operations (if applicable).
The rollback procedure must be reviewed and the team must be prepared to execute it if necessary.

Before you begin

Expected behavior during migration window:
- Steps 3 & 4 under Migration Steps:
  - Managed endpoints will continue to function using their current licenses.
  - Because the Source License Hub will be offline, license-refresh and usage-reporting alarms will be triggered on the endpoints.
- Step 5 (Configuration Import) under Migration Steps:
  - The import script will clean up the Source License Hub configuration from the endpoints and add the Target License Hub configuration.
  - During this cleanup, endpoints will temporarily lose the licenses supplied by the Source License Hub.
  - Endpoints will remain without licenses until the import script completes onboarding to the Target License Hub and restores the license assignment. On a normal setup, this would be a maximum of 15 to 20 minutes duration.
  - Once an endpoint successfully connects to the Target License Hub, the license-refresh and usage-reporting alarms raised during Steps 3 and 4 will clear automatically.
Read all steps entirely and confirm all prerequisites are met.
Ensure endpoint credentials are ready before Migration Step #5.

Prepare for migration

Copy and extract the attached migration scripts (migration.zip).
To extract to the current directory using python utility: (if your machine supports any other utilities, you may extract using them):
```
python3 -m zipfile -e migration.zip .
```
The scripts can be run from any/same system (e.g., export from a system with access to Source and import from a system with access to Target).
Requirements: Python 3.6 or higher and the Python requests module and unzip tool to extract the attached migration.zip file.

Migration Workflow

Export Configuration: Run export_config.py on the Source License Hub to generate source_lh_export.json.
Import Configuration: Run import_config.py on the Target License Hub using the source_lh_export.json file as input.

Migration Steps

1. Report Usage - Source License Hub in Disconnected Mode Only

If the Source License Hub is operating in Connected Mode or in Private/Critical Mode, skip to Step # 2. Otherwise, login to Source License Hub and submit all pending usage data to Avi Cloud Console to ensure usage records are synchronized. For detailed instructions, please refer to the License Hub 5.1.2 User Guide.

2. Export Configuration from Source License Hub

Login to the machine that you have copied and extracted the migration.zip file and navigate to the directory where the files have been exported.

Run the attached export_config.py script(this is present inside the migration.zip) using the following command:

python3 export_config.py

Sample Commands with other options:

python3 export_config.py [options]

Examples:

Fully interactive — prompts for FQDN, username, and password

python3 export_config.py

Provide FQDN and username as flags; password is always prompted securely

python3 export_config.py --fqdn source-lh.corp.internal --username admin

Custom output path and self-signed certificate environment

python3 export_config.py --fqdn source-lh.corp.internal --username admin --output /secured-directory/source_lh_export.json --no-verify-ssl

For more details about options, please refer to the README.md file from the migration bundle file.

This script generates a source_lh_export.json file that resides in the same directory. Please verify that this file is not empty and store it in a secure location, as it contains sensitive data. If the output option is not used, by default this file will be generated in the directory from where the script is run. If these file is empty, it means probably there is nothing for migration.

Please confirm whether all endpoints and their assignments have been properly exported. In case of any discrepancy, the export step can be executed again. Please do not proceed with Step # 3 (i.e. Uninstall Source License Hub) without this confirmation.

This file includes:

Endpoint Configuration: Connectivity data for registered endpoints (excluding credentials)
License Assignment Data: All current license-to-endpoint records.

3. Uninstall Source License Hub

Please copy the Source License Hub ID from "Registration & Reporting" UI page. This will be useful to locate the Source License Hub on Avi Cloud Console.

Please Note: IMPORTANT

If the export configuration step (i.e. Step # 2 above) was executed from the Source License Hub VM, copy the generated configuration file (default: source_lh_export.json) to the system where the import configuration script (from Step #5) is planned for execution.
Expected behaviour after this step and until we start the import in Step # 5:
a. Managed Endpoints will retain their current licenses and function normally.
b. Since Source License Hub will no longer be functional, "License Refresh Failure" and "Usage Reporting Failure" alarms will be raised on endpoints.

Uninstall the Source License Hub by logging into the Security Services Platform Installer (SSP-I 5.1.2) UI.

To uninstall, navigate to "Instance Management→3 vertical dots→Delete Instance", choose force delete(if prompted) and wait until the instance deletion is completed. Once the deletion is complete, delete the SSP-I 5.1.2 virtual machine from the disc after powering it off.

In the vCenter Inventory -> Select SSPI VM -> Right click and Delete from Disk.

4. Migrate Licenses via Avi Cloud Console

Based on the License Hub Registration mode, please follow the applicable steps to migrate the licenses from Source License Hub to Target License Hub.

Private/Critical Mode:

In this mode, the licenses are not tied to the Source License Hub. Hence, the license file from Source License Hub can directly be imported on to the Target License Hub without requiring any action in the Avi Cloud Console.

Steps:

1. Log in to Target License Hub in Private Mode.
2. Navigate to Licenses
3. Click on 'Update License' button, use the license file from the Source License Hub and the key that was used while generating this license file. After successful license import, the Target License Hub should have all the licenses from Source License Hub.

Standard Connected/Disconnected Mode:

In this mode, the licenses are strictly tied to specific License Hub for which they were generated. Hence the licenses must be migrated from Source License Hub to Target License Hub.
To initiate the license and usage data transfer from the Source to the Target License Hub, follow the procedure outlined in the Cloud Console Guide.

After license migration is completed, verify following items. Please do not proceed until all the following checks pass. Proceeding with incomplete licenses will cause assignment failures in the import steps.

Verification Item	Expected Result
All valid (non-expired) licenses are visible on Target License Hub	Pass
Usage Data reflected accurately on Target License Hub	Pass
Source License Hub is no longer registered and does not have any licenses	Pass

5. Import Configuration on Target License Hub

Expected behavior during and after this Step:

- The import script will clean up the Source License Hub configuration from the endpoints and add the Target License Hub configuration.
- During this cleanup, endpoints will temporarily lose the licenses supplied by the Source License Hub.
- Endpoints will remain without licenses until the import script completes onboarding to the Target License Hub and restores the license assignment. On a normal setup, this would be a maximum of 15 to 20 minutes duration.
- Once an endpoint successfully connects to the Target License Hub, the license-refresh and usage-reporting alarms raised during Steps 3 and 4 will clear automatically.

1. Update Endpoint Credentials: Open source_lh_export.json and populate the username, password, and certificate fields for every endpoint. Do not change any other fields.

Please note:

If import script is being run from other system, make sure to copy this source_lh_export.json file from the system from where the export script was run.
If the input option is not used, by default source_lh_export.json file will be picked-up from the directory from where the script is run.
Any misconfiguration in this file will directly impact the endpoint onboarding on Target License Hub during the migration and Endpoint may remain in the NOT READY state causing license assignment failures.

Populating Endpoint Credentials in source_lh_export.json:

Certificate format: The certificate must be provided as a single-line JSON string with \n escape sequences in place of actual line breaks. Pasting a raw multi-line PEM certificate directly into the JSON file will cause a JSON parse error.

How to get endpoint certificate? Following REST APIs can be used to retrieve the API certificates to be used for onboarding an endpoint.

NSX Manager Endpoint:
- API: GET https://<NSX_MANAGER>/api/v1/trust-management/certificates
- Instruction: Locate the entry where "used_by[].service_types" contains "API". Its "pem_encoded" field contains the required certificate.
- Sample command to directly get Certificate:
  curl -sk -u '<USERNAME>:<PASSWORD>' "https://<NSX_MANAGER>/api/v1/trust-management/certificates" | jq '[.results[] | select(.used_by[]?.service_types[]? == "API")] | .[0].pem_encoded'

AVI Endpoint: Please refer to AVI Controller Certificate Guide for retrieving the AVI Endpoint Certificate.

Sample entry in auto-generated source_lh_export.json file vs Expected update:

Without updates:

[
{
"endpoint_id": "endpoint-1-id",
"onboard_request": {
"endpoint_type": "SSP",
"display_name": "SSP-1",
"connection_info": {
"connection_type": "STATIC",
"host_addresses": [
"endpoint-ssp-fqdn.internal"
],
"username": "",
"password": "",
"certificate": ""
}
},
"license_assignment": {
"operations": [
{
"operation": "CREATE",
"mapping": {
"license_id": "license-1-id",
"endpoint_id": "endpoint-1-id"
}
},
{
"operation": "CREATE",
"mapping": {
"license_id": "license-2-id",
"endpoint_id": "endpoint-1-id"
}
}
]
}
},
{
"endpoint_id": "endpoint-2-id",
"onboard_request": {
"endpoint_type": "NSX_MANAGER",
"display_name": "NSX-1",
"connection_info": {
"connection_type": "DYNAMIC",
"hostname": "endpoint-nsx-fqdn.internal",
"username": "",
"password": "",
"certificate": ""
}
},
"license_assignment": {
"operations": [
{
"operation": "CREATE",
"mapping": {
"license_id": "license-1-id",
"endpoint_id": "endpoint-2-id"
}
}
]
}
}
]

With updates:

[
{
"endpoint_id": "endpoint-1-id",
"onboard_request": {
"endpoint_type": "SSP",
"display_name": "SSP-1",
"connection_info": {
"connection_type": "STATIC",
"host_addresses": [
"endpoint-ssp-fqdn.internal"
],
"username": "admin",
"password": "PasswordText",
"certificate": "-----BEGIN CERTIFICATE-----\nMIID6DCCAt.....Nz0EJmavGCag==\n-----END CERTIFICATE-----"
}
},
"license_assignment": {
"operations": [
{
"operation": "CREATE",
"mapping": {
"license_id": "license-1-id",
"endpoint_id": "endpoint-1-id"
}
},
{
"operation": "CREATE",
"mapping": {
"license_id": "license-2-id",
"endpoint_id": "endpoint-1-id"
}
}
]
}
},
{
"endpoint_id": "endpoint-2-id",
"onboard_request": {
"endpoint_type": "NSX_MANAGER",
"display_name": "NSX-1",
"connection_info": {
"connection_type": "DYNAMIC",
"hostname": "endpoint-nsx-fqdn.internal",
"username": "admin",
"password": "PasswordText",
"certificate": "-----BEGIN CERTIFICATE-----\nMIID6DCCAt.....Nz0EJmavGCag==\n-----END CERTIFICATE-----"
}
},
"license_assignment": {
"operations": [
{
"operation": "CREATE",
"mapping": {
"license_id": "license-1-id",
"endpoint_id": "endpoint-2-id"
}
}
]
}
}
]

2. Run Import Script: Execute the import_config.py script.(If you are on the same Linux system where export was done, there is no need for copying any files and this can be executed from the same directory where export was done. If not, move all the files under migration directory to the machine/Target License Hub.

For more details about options, please refer to the README.md file from the migration bundle file.

python3 import_config.py

Sample Commands

python3 import_config.py [options]

Examples:

Fully interactive

python3 import_config.py

Provide FQDN and username as flags

python3 import_config.py --fqdn target-lh.corp.internal --username admin

Custom input file path and self-signed certificate environment

python3 import_config.py --fqdn target-lh.corp.internal --username admin --input /secured-directory/source_lh_export.json --no-verify-ssl

3. Important Notes:

Review migration.log present in the same directory from which the scripts were run for details and errors.
Any licenses missing from the Target License Hub must be assigned manually to License Hub first and then to the applicable endpoints.
If an endpoint migration fails, it can be reattempted via the Target License Hub UI.

Migration Verification

Verify the completeness and correctness of the migration by comparing the Target License Hub state against Source License Hub reference data.

Verification Item	Verification Method	Expected Result & Notes
Total endpoint count	Target License Hub UI → Endpoint Management section has information about total endpoints in the License Hub	Matches with Source License Hub endpoint count. This can be crosschecked against the endpoint count in exported configuration `source_lh_export.json` file
All endpoints in same state as Source License Hub	Target License Hub UI → Endpoint Management section shows current status of every endpoint	It is possible to observe the different state of the endpoint because it all depends on the point-in-time connectivity state of the endpoint with Target License Hub. If in case, endpoint is not in `READY` state, the reconnect endpoint operation can be attempted to complete the endpoint onboarding. After successful onboarding, license-assignment will have to be done manually.
License Assignment accuracy	Review the `source_lh_export.json` with Target License Hub UI license assignment details.	This data should match with Source Target License Hub. It is possible to see some differences here when some of the licenses (e.g. expired ones) are not migrated to Target License Hub during the migration.
Endpoint Alarms	Allow sufficient time to successfully run at least one license-refresh and usage-report cycle to be completed by Endpoint.	Upon successful connection with Target License Hub, these alarms should get resolved on Endpoint. Please note: Only the Endpoints those are in `READY` state will be able to clear the alarms.
Active Usage Reporting	Allow Endpoint a sufficient time to successfully report the usage to Target License Hub. Allow Target License Hub a sufficient time (if in connected mode) to successfully report the usage to Avi Cloud Console.	Usage reporting should work.

Migration Complete

Once all verification items pass, the migration is complete.

Rollback Procedure

Please follow the procedure mentioned in the Recovery of License Hub in case of crash or disaster KB. The exported data json file from Step # 2 above, contains the endpoint and license-assignment details.

Troubleshooting

Symptom	Likely cause	Resolution
Avi Cloud Console migration tool is unavailable	• Avi Cloud Console maintenance window • Network connectivity issue	• Contact Avi Cloud Console support • Do not proceed with migration steps
The export script fails with errors	• Insufficient permissions for script to execute APIs on Source License Hub	• Ensure the executing user has at-least a read access to License Hub data
The export script generates empty `source_lh_export.json` file	• No endpoints are registered and/or no licenses assignments made on Source License Hub.	• Verify endpoint registration and license assignments on Source License Hub UI. • Ensure the executing user has atleast a read access to License Hub data
The import script fails with errors	• Insufficient permissions for script to execute APIs on Target License Hub	• Ensure the executing user has write access to Target License Hub
Endpoint does not reach READY state after import	• Incorrect credentials in `source_lh_export.json` file. • Firewall blocking Target License Hub. • Network connectivity issues between Target License Hub and Endpoint.	• Verify username, password and certificate provided in `source_lh_export.json`. • Identify and fix the network connectivity issues (if any) between License Hub and Endpoint. • Use Target License Hub UI to trigger manual reconnect. • After resolving the issue, when endpoint enters into READY state, please assign the licenses to endpoint. The license assignment details are available in source_lh_export.json file.
Some licenses are not assigned to endpoints	• These licenses are not migrated to Target License Hub.	• Login to Avi Cloud Console and confirm whether these licenses are successfully migrated to Target License Hub • If they were migrated then make sure that they are also available on Target License Hub • If they were not migrated then probably they are no-more-valid (i.e. expired) licenses and hence cannot be migrated • Contact Avi Cloud Console support and share Source License Hub and Target License Hub details
Endpoint alarms persist after migration completes	• Endpoint does not reach `READY` state and hence not able to connect with Target License Hub. • Endpoint is still attempting to sync with Source License Hub.	• Confirm endpoint is in `READY` state on Target License Hub. If not, trigger manual force-onboard/reconnect from Target License Hub UI. After it reaches in `READY` state, ensure that licenses are manually assigned to this endpoint.

Additional Information

For issues not covered in this troubleshooting guide, contact Broadcom support via the SR.

Include the source_lh_export.json(raw without credentials) and migration.log file when engaging support.

Attachments

migration.zip get_app

Feedback

thumb_up Yes

thumb_down No