This topic provides an overview of migrating VMware Tanzu Kubernetes Grid Integrated Edition (TKGI) from the NSXManagement Plane API to NSX Policy API.
To migrate a TKGI from NSX Management Plane API to NSX Policy API, see Migrating the NSX Management Plane API to NSX Policy API.
Warning: The NSX Policy API feature is available at 50% of NSX Management Plane API scale. For detailed scale numbers, see NSX 4.0.1 Configuration Limits.
Overview
The NSX Management Plane API has been deprecated. VMware recommends that you instead use the NSX Policy API. For more information about the deprecation of the NSX Management Plane API, see Deprecation announcement for NSX Manager APIs and NSX Advanced UIs in VMware NSX-T Data Center 3.2 Release Notes.
The NSX Management Plane API to NSX Policy API (MP2P) Migration feature switches TKGI environments using the NSX Management Plane API to the NSX Policy API.
Note: TKGI supports NSX Management Plane API to NSX Policy API Migration only. You cannot return TKGI to the NSX Management Plane API after starting TKGI MP2P Migration.
NSX Management Plane API to NSX Policy API Migration Features
TKGI NSX Management Plane API to NSX Policy API Migration provides the following advantages over manual migration:
-
Supports TKGI MP2P Migration in most environments.
-
Reduces a complex manual workflow to a few procedures:
- Automates most NSX Manager and TKGI configuration steps.
- Migrates cluster NSX resources to NSX Policy API objects without disrupting NSX data path.
- Migrates all cluster deployment NSX resources to Policy IDs, including Network Profile configurations and BOSH deployment properties.
-
Reduces the impact on the workloads in your environment:
- By promoting clusters to NSX Policy API one by one, the MP2P Migration procedure affects only the cluster being promoted. Other clusters continue to operate as usual.
-
Supports migrating common topologies.
For more information, see:
TKGI MP2P Migration Configurations
Before initiating TKGI MP2P, consider the following supported and unsupported configurations:
Supported Configurations
TKGI MP2P Migration supports migrating TKGI in only NSX environments dedicated to TKGI. Do not start TKGI MP2P Migration if TKGI shares your NSX environment with other products, for example, Tanzu Application Service or VMware Aria Automation.
TKGI MP2P Migration supports the following topologies:
- All deployment topologies defined in NSX-T Deployment Topologies for TKGI except vSAN Stretched Cluster topology.
- All Tier-1 Router topologies defined in Shared and Dedicated Tier-1 Router Topologies.
- All Multi-Tier-0 topologies defined in Isolating Tenants.
Contact VMware Support before initiating MP2P Migration if your TKGI environment uses a customized topology or is a multi-foundation deployment of TKGI.
Unsupported Configurations
The following are not supported by TKGI MP2P Migration or TKGI using the NSX Policy API:
-
Do not start TKGI MP2P Migration if TKGI shares your NSX environment with other products, for example, Tanzu Application Service or VMware Aria Automation.
-
TKGI MP2P Migration does not support clusters configured with NSGroups, including Bootstrap Security Group and BOSH VM Extensions NSGroup configurations.
-
The TKGI Management Console can not be used to manage TKGI after TKGI MP2P Migration.
TKGI MP2P Migration Operational Limitations
Review the following and resolve concerns before initiating TKGI MP2P Migration:
Note: To reduce the possibility of unexpected issues, VMware recommends that you minimize the duration of your MP2P Migration mix-mode maintenance window by promoting all clusters as soon as possible.
Before MP2P Migration
Consider the following before initiating TKGI MP2P Migration:
- Evaluate the complexity of your TKGI environment. PSO assistance might be required to migrate some complex environments.
- You cannot rotate cluster certificates during TKGI MP2P Migration. Verify your cluster cluster certificates, including the NSX-T certificate, are valid for the entire duration of your TKGI MP2P Migration before starting MP2P Migration.
- When planning your TKGI MP2P Migration, include redefining DFW rules in your cluster promotion procedure. For more information, see Dealing with DFW Sections Created by NSX Admin in the VMware NSX Container Plugin documentation.
During MP2P Migration
During your MP2P Migration mixed-mode maintenance window:
- You cannot roll back your TKGI environment to the NSX Management Plane API.
- Migrate clusters serially. Do not attempt to migrate multiple clusters in parallel. NSX does not support multiple simultaneous MP2P Migration requests.
VMware recommends that you migrate your entire TKGI environment to NSX Policy API as quickly as possible to avoid the extra complexity of an NSX Management Plane/Policy API mixed-mode environment.
Warning: Limit upgrading NSX and TKGI to only resolving critical issues while your environment is in MP2P Migration mixed-mode.
DFW Migration
Policy API supports new firewall sections. The new firewall sections have a higher priority than existing Management Plane-based firewall rules, including existing top firewall rules.
The DFW migration procedure described in Migrating the NSX Management Plane API to NSX Policy API documents the recommended two-step MP2P firewall migration procedure for typical DFW firewall configurations:
- Re-create the top firewall rules before promoting clusters.
- Re-create the bottom firewall rules immediately after promoting clusters.
Adhering to the recommended DFW migration sequence is critical to maintaining security and cluster workload network connectivity. If a TKGI cluster is:
- Promoted before existing Management Plane API top firewall rules have been recreated in the Policy API section: Cluster network policies will be enforced before the top firewall rules.
- Promoted after existing Management Plane API bottom firewall rules have been recreated in the Policy API section: The top firewall rules will be enforced before Kubernetes network policies and might override them.
An example result of failing to migrate DFW rules correctly is clusters with access to CIDRs that had been intended to be globally blocked.
Warning: If you do not configure your DFW Rules correctly, cluster workloads will lose network connectivity.
For information about migrating DFW rules for specific edge case configurations, see Dealing with DFW Sections Created by NSX Admin in the VMware NSX Container Plugin documentation.
During Cluster Promotion to NSX Policy API
Promoting a cluster to NSX Policy API migrates the cluster’s NSX resources and updates the cluster. Promote your clusters to the NSX Policy API serially only while the MP2P Migration mixed-mode maintenance window is active. If a cluster promotion fails, the only affected cluster is the one being promoted.
While promoting a cluster to NSX Policy API:
- Do not manage the cluster.
- Do not update or delete any of the cluster’s existing workloads.
- Do not create new workloads on the cluster.
Workloads run as usual while promoting the cluster.
Clusters that are not actively being promoted:
- Can be managed as usual.
- Workloads on these clusters continue to run as usual and can be managed as usual.
The amount of time it takes to promote a cluster depends on the scale of resources NSX needs to migrate the cluster, and the time it takes to update the cluster.
