With the introduction of Policy model as primary NSX API starting NSX 2.4 (released in February 2019), NSX offers a declarative hierarchical API model that simplifies consumption. It also offers a Promotion feature to move the existing legacy configuration from the imperative NSX Manager API (called MP API) to NSX Policy without data path disruption or deletion or recreation of existing objects. With this feature, you can promote objects created on NSX Manager to NSX Policy and can then later interact with the same objects through NSX Policy UI or NSX Policy APIs.

An NSX Enterprise Admin should carry out the promotion. The promotion process has the following workflow:
  1. Collect all manager objects.
  2. Translate manager resources to corresponding policy resources intents and apply translated policy resources on policy.
  3. Link the obtained policy intents in Step 2 to corresponding existing manager objects.
  4. Report policy promotion progress and list the promoted objects.
Promotion of objects occurs based on their dependency order, for example, a group is promoted first and then any rule that consumes that group.
Note that the objects already in Policy and fabric configurations do not require this tool. The scope of the promotion tool is MP logical objects. Objects that are supported for promotion are as follows.
  • IPSET
  • MacSet
  • NS Group
  • NS Profile
  • NS Service groups
  • NS Services
  • Bridge endpoints
  • Bridge endpoint profiles
  • DAD profiles
  • NDRA profiles
  • Logical router
  • Logical router ports
  • NAT Rule
  • Logical port (InternalLogicalPort)
  • Logical switch
  • Switching profiles
  • DHCP relay
  • DHCP relay profiles
  • DHCP servers
  • DHCP server profiles
  • DNS forwarder
  • LB application profile
  • LbClientSslProfile
  • LbServerSslProfile
  • LB persistence profile
  • LB pools
  • LB rules
  • LB services
  • LB virtual servers
  • MD proxy
  • ServiceConfig
  • SystemHealthAgentProfile
  • DPD profile
  • IKE profile
  • Local endpoint
  • Peer endpoints
  • IPSEC services
  • IPSEC sessions
  • Tunnel profile
  • L2VPN services
  • L2VPN sessions
  • Edge Firewall
  • DFW
  • DFW Exclude List
  • Service config
  • IPFIX profile
  • IPFIX collector profile
  • IPFIX config
  • Port mirroring except Local Span and Remote Span
Note: The Bridge Firewall is a deprecated MP object that is not supported for Promotion in NSX 4.2.1.

Starting with NSX 4.2.1, mixed mode is also supported for promotion. Mixed mode is where configuration contains a combination of policy and manager objects, for example, NAT rules on manager attached to routers created through policy and groups created through policy used in MP DFW rules.

In case any object is not promoted successfully, you will see an error message related to its failed promotion. For example, the following error message is displayed if dependent objects are not promoted first.

LOGICAL_PORT is dependent on resource type: LOGICAL_SWITCH with id: 0cf04674-05f7-42a8-b5a6-96d51f63faa3. Please make sure that the dependent objects are promoted first or are not created by policy.

When you log in to NSX, an alert is displayed on the top of the page if objects are available for promotion along with a link to initiate the promotion. You can click the link to start the promotion. You can also start the promotion from the System tab.

You can run the Promotion feature as many times as you require and view history of the last five promotions and details of data of the last two successful promotions by clicking Recent Activity.

Once you initiate the promotion process and the process starts, the system displays a progress bar to show the percentage of promotion performed. It also displays manager objects that are promoted to policy objects and status of promotion whether objects succeeded or failed the promotion. You can view failure details by clicking the object failed link against failed objects. Also, if any object fails to get promoted, you can skip it and continue the promotion or you can choose to stop the promotion. If you stop the promotion, the system rollbacks promoted objects to their previous states.

Post MP to Policy promotion, you can also view the migration status and complete mapping of all resources by running the following API. For more details about the migration status API, see the NSX API Guide.

GET https://localhost/api/v1/migration/mp-to-policy/migrated-resource-status

Prerequisites

  • You must start the migration coordinator service by running the following command on any one node of manager cluster nodes.

    start service migration-coordinator

    Note: The entire promotion process will run only on that single node on which you start the migration coordinator service.

  • Take a backup before performing the manager to policy promotion. In case a promotion fails, we can revert the system to its original state using the backup.

Procedure

  1. Navigate to System > General Settings > Manager Objects Promotion.
  2. Click Start Objects Promotion.
    The system displays a summary of manager objects.
  3. Click Continue.
    The system starts the promotion and displays the progress and status of promotion. If any object fails to get promoted, the system displays an error. You can click Skip and Continue to continue the promotion, or you can click Cancel to stop the promotion.
  4. Once the promotion is completed successfully, the system displays the Manager to Policy Objects Promotion page.