Skip to main content
Version: 3.2

Use Rancher Projects with ClusterPair

Summary and Key concepts

Summary​

This article provides guidelines for migrating Kubernetes resources between clusters managed with Rancher, focusing on maintaining project associations using project mappings. The migration process uses ClusterPair configurations, where project IDs from the source cluster are mapped to corresponding project IDs on the destination cluster. The guide includes prerequisites for setting up Rancher projects on both clusters, detailed steps for creating project mappings with and without cluster ID prefixes, and optional steps for including cluster IDs in project mappings for environments with multiple clusters.

Kubernetes Concepts​

  • Namespaces: Used in both source and destination clusters to logically group resources in each cluster for separation and migration purposes.
  • NetworkPolicy: Namespace-based security controls that allow/deny traffic within the Kubernetes cluster, modified here to update project-based selectors during migration.

Portworx Concepts​

  • ClusterPair: A Portworx custom resource used for managing configurations across clusters in a DR setup. Here, it includes project mapping for associating Rancher projects from source to destination clusters.
  • storkctl: Portworx command-line tool for configuring and managing migrations, including project mappings via ClusterPair setup.

note

If you are not using Rancher, skip to the Schedule your migration section.

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 ClusterPair with these project mappings will ensure that Rancher projects are effectively managed and associated during the migration process.

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 allows you to map projects from the source cluster to the destination cluster during migration. 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.
  • The transformation of Namespace Selectors on a NetworkPolicy object that reference the field.cattle.io/projectID label to use the correct projectIDs on the destination cluster.
  • The transformation of Namespace Selectors on a Pod object (Kubernetes version 1.24 or newer) that reference the field.cattle.io/projectID label to the correct projectIDs on the destination cluster.

Prerequisites​

  • All the Rancher projects are created on both the source and the destination cluster.

Create project mapping​

While creating the ClusterPair, use the argument --project-mappings to indicate how projectIDs on the source cluster should map to projectIDs on the destination cluster. Project mappings are provided as comma-separated key-value pairs.

For example:

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

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.

Include ClusterIDs in project mappings (Optional)​

For the projectIDs, you can also include clusterID prefixes in project mappings. Including clusterID prefixes ensures precise mapping, especially in scenarios with multiple clusters.

For example:

storkctl generate clusterpair \
-n <migrationnamespace> <remotecluster> \
--project-mappings \
p-58q4n=p-jjk2q c-m-wthc7l5q:p-58q4n=c-m-5sftdjns:p-jjk2q

In the above example, there are following two mappings:

  • A mapping with clusterIDs: c-m-wthc7l5q:p-58q4n containing the source clusterID c-m-wthc7l5q will map to c-m-5sftdjns:p-jjk2q containing the destination clusterID c-m-5sftdjns.
  • A mapping without the clusterIDs: p-58q4n will map to p-jjk2q.

To view the information, click on the respective tabs, which provide details on how the projectIDs on the source cluster correlate with projectIDs on the destination cluster during resource migration.

spec:
 platformOptions:
  rancher:
    projectMappings:
        c-m-wthc7l5q:p-58q4n: c-m-5sftdjns:p-jjk2q
        c-m-wthc7l5q:p-dmx28: c-m-5sftdjns:p-6nk5r
        c-m-wthc7l5q:p-hvxqm: c-m-5sftdjns:p-7cx4c
        c-m-wthc7l5q:p-fkth5: c-m-5sftdjns:p-w5z2s
        p-58q4n: p-jjk2q
        p-dmx28: p-6nk5r
        p-hvxqm: p-7cx4c
        p-xz4pd: p-fg5sd
Last updated on