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.

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> <remotecluster> --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. For example:

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

While providing the project mappings Portworx recommends to provide both: one-to-one mapping of just the projectIDs and one-to-one mapping of projectIDs which are prefixed with Rancher clusterIDs.

You can see that the source projectID c-7mv84:p-xz4pd containing the clusterID c-7mv84 maps to c-4kj32:p-fg5sd which contains the destination clusterID c-4kj32. You can also provide a mapping which skips the clusterID prefix and only uses the projectID. In this example project ID p-xz4pd will map to p-fg5sd destination projectID.