NCP 4.1.2 or Later

Requirements

  • The NSX version is 3.2.0 or later.
  • The NCP version is 4.1.2 or later.
  • The nsx-ncp deployment must be scaled down to 0 replicas manually.

Migration Steps

A new YAML file named migrate-mp2p-job.yaml is provided that contains the following Kubernetes resources:
  1. Two config maps named nsx-ncp-migrate-mp2p-config (also called mp2p-config) and nsx-ncp-migrate-mp2p-user-spec (also called mp2p-user-spec).
  2. One PersistentVolume with the name nsx-ncp-mp2p-shared-pv and size 500 MB.
  3. One PersistentVolumeClaim with the name nsx-ncp-mp2p-shared-pvc that requires 500 MB storage.
  4. One Job with the name nsx-ncp-migrate-mp2p.

Before using the job to migrate a cluster, note that you must scale down the number of nsx-ncp deployment replicas to 0 in all the clusters that share the same NSX network.

Perform the following steps to migrate your vanilla Kubernetes cluster to NSX Policy mode:
  1. Refactor manually-created DFW sections, if needed. See Dealing with DFW Sections Created by NSX Admin.
  2. For each cluster to be migrated:
    1. Add label "dedicated-nsx-ncp-migrate-mp2p=true" to one of the master nodes that has at least 500MB of free disk space. Ensure that only 1 master node has this label.
    2. Edit migrate-mp2p-job.yaml provided with the build and make the following changes:
      1. Under the config map nsx-ncp-migrate-mp2p-config: No changes
      2. Under the config map nsx-ncp-migrate-mp2p-user-spec: Add all the shared resources to be migrated and add the cluster name under "k8s-clusters" (see Migrating Shared Resources and Migrating NCP-Created NSX Resources for the Kubernetes Cluster).
      3. Add the nsx-secret under "projected-volume" volume under the Job with name nsx-ncp-migrate-mp2p. This is similar to the steps done in nsx-ncp spec (see Edit the NCP YAML File).
  3. For each cluster to be migrated that shares the same NSX network:
    1. Scale down the nsx-ncp deployment replicas in nsx-system namespace to 0 wait for nsx-ncp pods to terminate. This can be done in all the clusters in parallel.
  4. Create an NSX backup.
  5. For each cluster to be migrated that shares the same NSX network:
    1. Apply the migrate-mp2p-job.yaml. This should be done in one cluster at a time.
    2. Once the job nsx-ncp-migrate-mp2p completes successfully, the cluster is migrated to Policy. Otherwise, follow the steps in Failure and Recovery. Migrate the next cluster only after the job nsx-ncp-migrate-mp2p has completed execution for the current cluster.
    3. Update ncp.ini if required for this cluster. See Migrating Shared Resources.
    4. Edit the nsx-ncp YAML file or config map and make sure that policy_nsxapi is set to true.
  6. For each cluster that was migrated to Policy in step 5, follow these steps in parallel:
    1. If there are Gateway Firewall rules on the top Tier-0 that can block traffic from containers, setting the cfg.CONF.nsx_v3.natfirewallmatch property to BYPASS will avoid firewall enforcement on NCP-created SNAT rules. Otherwise, gateway firewall rules will need to be reviewed to ensure that traffic from containers is not accidentally blocked.
    2. Apply the nsx-ncp deployment and scale up the nsx-ncp deployment replicas in the nsx-system namespace to the previous state (before step 3)
    3. Delete the config maps with the names nsx-ncp-migrate-mp2p-config and nsx-ncp-migrate-mp2p-user-spec and Job with the name nsx-ncp-migrate-mp2p under the nsx-system namespace. Delete the PersistentVolumeClaim with the name nsx-ncp-mp2p-shared-pvc and PersistentVolume with the name nsx-ncp-mp2p-shared-pv after the nsx-ncp deployment/pods have been running successfully for at least 12 weeks.

NCP 4.1.1 or Earlier

Requirements

  • The NSX version is 3.2.0 or later.
  • The NCP version is between 4.0 and 4.1.0.x, inclusive.
  • Python3 is installed on the master VM.
  • pyyaml is installed on the master VM.
  • The script must have execution access to "kubectl".
  • NCP must not be running. This will result in control-plane downtime. You must stop NCP manually. The script will not do it.

Migration Steps

The Python3 script that performs the import, mp_to_policy_importer.py, is located in the directory scripts/mp_to_policy_import. It is also referred as mp_to_policy_importer in this document. mp_to_policy_importer must be run on one Kubernetes master node at a time. If it needs to be run again, it must be done on the same master node. mp_to_policy_importer can terminate with the following exit codes:
  • 0 - Successful migration to Policy
  • 1 - Unsuccessful migration to Policy. NCP should not be run in Manager mode.
  • 2 - Unsuccessful migration to Policy. NCP should be restarted in Manager mode.
After the requirements are met, the cluster can be imported to Policy. The steps are:
  1. In the NCP config file ncp.ini, make sure that policy_nsxapi is set to false.
  2. Start the migration coordinator on any of the NSX Managers with the following command:
    /etc/init.d/migration-coordinator start
    Verify that it is successfully running with the following command: 
    /etc/init.d/migration-coordinator status

    Be sure to use this Manager's IP address when importing Manager objects to Policy.

  3. Refactor manually-created DFW sections, if needed. See Dealing with DFW Sections Created by NSX Admin.
  4. For each cluster to be migrated that share the same NSX network,
    1. Scale down the nsx-ncp deployment replicas in nsx-system namespace to 0 wait for nsx-ncp pods to terminate. This can be done in all the clusters in parallel.
  5. Create an NSX backup.
  6. Do the following for each cluster to be imported:
    1. Import shared resources. See Migrating Shared Resources. Verify that mp_to_policy_importer terminated with exit code 0. If not, see Failure and Recovery.
    2. Import the Kubernetes cluster related resources. See Migrating NCP-Created NSX Resources for the Kubernetes Cluster. Verify that mp_to_policy_importer terminated with exit code 0. If not, see Failure and Recovery.
    3. Update ncp.ini if required for this cluster. See Migrating Shared Resources.
    4. In the NCP YAML file, make sure that policy_nsxapi is set to true.
  7. For each cluster that was migrated to Policy in step 6, follow these steps in parallel:
    1. Apply the nsx-ncp deployment and scale up the nsx-ncp deployment replicas in nsx-system namespace to previous state (before step 4).

For limitations and workarounds, see Limitations and Workarounds. For information on how to handle errors, see Failure and Recovery.