Use Rancher Projects with ClusterPair

Rancher has a concept of Projects that allow grouping of resources and Kubernetes namespaces. Depending on the resource and how it is created, Rancher adds the following label or annotation:

field.cattle.io/projectID: <project-short-UUID>

The projectID uniquely identifies the project, and the annotation or label on the Kubernetes object provides a way to tie a Kubernetes object back to a Rancher project.

From version 2.11.2 or newer, Stork has the capability to map projects from the source cluster to the destination cluster when it migrates Kubernetes resources. It will ensure that the following are transformed when migrating Kubernetes resources to a destination cluster:

• Labels and annotations for projectID field.cattle.io/projectID on any Kubernetes resource on the source cluster are transformed to their respective projectIDs on the destination cluster.
• Namespace Selectors on a NetworkPolicy object which refer to the field.cattle.io/projectID label will be transformed to their respective projectIDs on the destination cluster.
• Namespace Selectors on a Pod object (Kubernetes version 1.24 or newer) which refer to the field.cattle.io/projectID label will be transformed to their respective projectIDs on the destination cluster.

While creating the ClusterPair, use the argument --project-mappings to indicate which projectID on the source cluster maps to a projectID on the destination cluster. For example:

storkctl generate clusterpair -n <migrationnamespace> <your-clusterpair-name> --project-mappings  <projectID-A1>=<projectID-A2>,<projectID-B1>: <projectID-B2>

The project mappings are provided as a comma-separate key=value pairs. In this example, projectID-A1 on source cluster maps to projectID-A2 on the destination cluster, while projectID-B1 on the source cluster maps to projectID-B2 on the destination cluster.

For the projectIDs, you can also have a clusterID field added as a prefix to the projectID. Portworx recommends including both one-to-one mappings of the projectIDs and one-to-one mappings of the projectIDs prefixed with Rancher clusterIDs when providing project mappings.

For example:

storkctl generate clusterpair -n <migrationnamespace> <remotecluster> --project-mappings  p-xz4pd=p-fg5sd,c-7mv84:p-xz4pd=c-4kj32:p-fg5sd 

In the above example, there are following two mappings:

• A mapping with clusterIDs: c-7mv84:p-xz4pd containing the source clusterID c-7mv84 will map to c-4kj32:p-fg5sd containing the destination clusterID c-4kj32.
• A mapping without the clusterIDs: p-xz4pd will map to p-fg5sd.