Add Rancher clusters

Portworx Backup now extends its support on Rancher and enables you to add a Rancher cloud account and map Rancher projects. You can create a backup of namespaces and resources on a Rancher source cluster and restore them on a Rancher destination cluster.

Besides, you can also map a source cluster project with that of the destination cluster for custom restores. This project mapping facilitates to pick the required projects and map their namespaces and resources to specific projects during restore.


  • Kubernetes version - 1.24 and above
  • Rancher web UI version - 2.0 and above
  • Stork version - 23.2.0 and above
  • Active and valid Rancher web UI credentials
  • User permissions to create Rancher API keys

Add Rancher Account

You need to add a Rancher cloud account in Portworx Backup before adding a Rancher cluster if you need to map projects for Rancher clusters.

To add a Rancher cloud account:

  1. From the home page, navigate to Settings >> Cloud Settings and click Add.

  2. In the Add Cloud Account page, select Rancher from the Please choose a cloud provider drop-down.

  3. Provide a cloud account name of your choice.

  4. Enter a valid endpoint and secret key. Refer Create users and Create API keys for instructions to fetch endpoint and secret key.

  5. Click Add.

    Portworx Backup successfully adds a Rancher cloud account and displays it in the Cloud Accounts section of Cloud Settings page.

    You can also edit the Rancher cloud account to update the endpoint (when there is change in setup) and secret key (if the secret key expires) details when needed:

Add Rancher Cluster

To add a Rancher Cluster in Portworx Backup:

  1. In the home page, click Add Cluster.

  2. In the Add Cluster page, under Select Kubernetes Platform, click Rancher icon.

  3. Under Cluster Details: a. Provide a name for your cluster. b. Copy the kubeconfig details from the CLI and paste it in the Kubeconfig field. c. Choose the required type of Kubernetes service (where your Rancher is deployed) from Kubernetes service radio group.

  4. In the Rancher Account Information section, choose the required Rancher account you created recently.

  5. Click Add Cluster.

    Home page displays the newly created Rancher cluster and now you can utilize this cluster to create and restore backup of your namespaces and resources.

    You can also edit the Rancher cluster to update kubeconfig (when the cluster details change) and/or Rancher cloud account (if cloud account differs) details if the need arises:

    NOTE: Portworx Backup currently supports configuration and addition of RKE2 version clusters.

Project Mapping in Rancher Cluster

Project mapping is associating a project of a Rancher source cluster with that of a Rancher destination cluster while restoring backups from one cluster to another.

Project mapping involves the below tasks:

  1. Creation of projects in source cluster with required configuration parameters and then associating namespaces and/or resources with these projects using Rancher UI.

  2. Creation of destination cluster and projects with the required configuration.

  3. Creating backup of the required namespaces and resources in Portworx Backup UI and then mapping these two projects during custom restore.

    Project mapping assists you for effective management of namespaces and resources of a Rancher cluster. In addition, it enables you to seamlessly restore your namespaces and resources residing on a Rancher source cluster to a destination cluster.

To map the projects residing on source and destination Rancher clusters in Portworx Backup during restore, refer Step 4 in Restore from a backup.


To map the projects during custom restore, ensure that you have:

  • Valid cloud credentials

  • View/create permissions to create projects in Rancher UI

  • Ensure a project exists in the destination cluster with the required configuration parameters

  • Backup contains the namespace associated with a project

  • Project list of the destination cluster is accessible for Portworx Backup

To restore a namespace or resource from a source cluster to destination cluster, you should have all the necessary details of the source cluster project to perform project mapping.

To backup and restore a namespace or resource residing on Rancher cluster, refer the following topics:

Rancher web console

You need to create users, restrict permissions when needed, create API keys in the Rancher web console. All these serve as prerequisites to add cloud account and to manage Rancher clusters in Portworx Backup.

Create users and restrict permissions

  1. Click on the left navigation pane and select Users and Authentication.

  2. Create a new user, provide the required Username, Display name, Description and Password.

  3. Under Global Permissions, select User-Base and then click Create.

  4. From the left navigation pane, navigate to the destination cluster under EXPLORE CLUSTER.

  5. From the left navigation pane, go to Cluster > Cluster Members.

  6. Click Add, select the user created in step 3 for Select Member.

  7. Select Custom under Cluster Permissions.

  8. Choose only View All Projects and click Create.

This allows a specific user to only view all the projects.

Create API keys

  1. Log in to Rancher web UI as a local user with valid credentials of the user created in Create users and restrict permissions

  2. Refer API Keys to create API keys.

    NOTE: PureStorage recommends setting no expiry option to avoid updating the secret key in Portworx Backup UI frequently.

Last edited: Thursday, Mar 9, 2023