Skip to main content
Version: 3.0

Manage Clusters (Federated Mode)

Applicable to Federated mode only

In Federated mode (also referred to as Managed Service Provider mode or Workload Identity mode), Portworx Backup supports two ways to onboard clusters:

  • Gardener shoot clusters — discovered automatically through the Gardener API. The Gardener API server kubeconfig is required for discovery; individual shoot cluster kubeconfigs are not needed.
  • Standalone shoot clusters — any standalone shoot cluster that is not managed by a Gardener configuration can be onboarded manually using a kubeconfig.

In both cases, once onboarded, the Portworx Backup server sends instructions to the cluster, and Stork on the cluster handles all backup operations locally.

In Federated mode, Gardener shoot clusters are auto-discovered through the Gardener API. You can also onboard standalone shoot cluster manually using a kubeconfig. For more information, see Onboard a standalone shoot cluster.

Prerequisites​

To manage clusters in Federated mode, ensure that the following prerequisites are met:

  • Portworx Backup 3.0.0 or later is installed in Federated mode. For installation instructions, see Install Portworx Backup in Federated Mode.

  • Portworx Enterprise version 3.6.1 or later is installed on each application cluster.

  • Stork 26.3.0 or later is installed on each application cluster, deployed through the Portworx Operator 26.2.0 or later as part of a Portworx Enterprise installation. Standalone Stork deployments are not supported in Federated mode.

    note

    In Federated mode, Azure Workload Identity (WLI) for Stork is configured through the StorageCluster (STC) custom resource, not through the Stork deployment manifest. Ensure that the Managed Identity client ID and required labels are set in the STC specification before onboarding the cluster. For setup instructions, see Prepare your AKS Cluster in the Portworx Enterprise documentation.

  • An Azure Managed Identity is configured on each shoot cluster, bound to the Stork service account, and assigned the Storage Blob Data Contributor role on the target Azure Blob Storage account.

    note

    The Owner role on the Azure Storage account does not grant access to blob data. The Storage Blob Data Contributor role must be explicitly assigned. Without this, Stork cannot read or write backup data even if the identity has Owner-level access.

  • The Portworx Backup server has network connectivity to the Kubernetes API server of each shoot cluster for pushing CRs.

  • The Gardener project and shoot clusters you want to manage are accessible from the backup cluster (where Portworx Backup is installed).

  • All the application clusters must meet the requirements listed in Cluster prerequisites.

Onboard Gardener shoot clusters​

When Portworx Backup is running in Federated mode, it connects to the Gardener API server and discovers all available shoot clusters. No manual kubeconfig import is required.

To onboard Gardener shoot clusters, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Clusters > Cluster Configs.

    The Clusters > Cluster Configs page displays all the Gardener cluster configurations added to Portworx Backup. If no clusters have been connected yet, the page shows:

    Connect your first Kubernetes Cluster, standalone (or) Gardener managed.

    No Kubernetes cluster is connected yet. Onboard a cluster to get started.

  3. Click Connect cluster

    The system prompts you to select the cluster type.

  4. Click Gardener Cluster.

  5. Specify the following information on the Add Gardener Cluster page, and click Connect.

    FieldDescription
    Enter Gardener Config NameA unique name for this Gardener configuration within Portworx Backup. Used to identify the configuration in the UI — does not need to match the Gardener project name.
    Enter Project NameThe name of the Gardener project that contains the shoot clusters you want to manage. Must match the project name exactly as it appears in the Gardener dashboard.
    Gardener Cluster KubeconfigThe kubeconfig for the Gardener API server (not a shoot cluster kubeconfig). Portworx Backup uses this to authenticate with the Gardener API and discover the shoot clusters in the specified project.
    The service account referenced in this kubeconfig must have the following permissions on the Gardener API server:
    • Get/List Projects
    • Get/List Shoots
    • Create Token
    • Create shoots/adminkubeconfig (required to obtain shoot cluster kubeconfigs)
    Enter Cluster LabelA Kubernetes label (for example, px-backup_allotment=<value>) that filters which shoot clusters in the project are discovered and managed by Portworx Backup. Only clusters matching this label are onboarded.
    Auto SyncWhen enabled, Portworx Backup periodically updates the list of shoot clusters based on cluster labels. New matching clusters are added automatically. Shoot clusters that no longer exist in Gardener are deleted from Portworx Backup (existing backup data is retained in the backup location, but no new backups are created for the deleted cluster). Shoot clusters whose labels no longer match the configured label filter are marked as unmanaged.
    For example, if a shoot cluster with label px-backup_allotment=one is changed to px-backup_allotment=two or the label is removed altogether, then the cluster is marked as unmanaged. You can remove unmanaged clusters manually from the Portworx Backup web console.
    Important: Backup schedules associated with an unmanaged cluster stop executing. Existing backups are retained in the backup location, but no new backups are created until the cluster is returned to a managed state (by restoring the matching label) or re-onboarded.
    When disabled, you must update the cluster list manually using the Manual Shoot Discovery option. For more information, see Manual discovery of shoot clusters.
    Auto Sync ScheduleThe interval at which shoot clusters are automatically discovered or synchronized (for example, Every 24 hours). Applicable when Auto Sync is enabled. When using Custom, the minimum configurable value is 15 minutes and the maximum is 90 days.
    For more information, see Configure auto sync schedule for Gardener clusters.

    Portworx Backup lists all discovered shoot clusters on the Clusters page.

  6. Assign a backup location to each newly discovered cluster. For more information, see Configure Backup Locations in Federated Mode.

Onboard a standalone shoot cluster​

In Federated mode, you can also onboard standalone shoot clusters that are not managed by a Gardener instance. These clusters are added manually using a kubeconfig.

Once onboarded, all backup operations are handled locally on the cluster by Stork. This behavior is the same for all clusters in Federated mode, regardless of how they are onboarded into Portworx Backup.

To add a standalone shoot cluster in Federated mode, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Clusters > All Clusters.

    The Clusters > All Clusters page displays all the discovered shoot clusters and standalone Kubernetes clusters registered by Portworx Backup. If no clusters have been connected yet, the page shows:

    Connect your first Kubernetes Cluster, standalone (or) Gardener managed.

    No Kubernetes cluster is connected yet. Onboard a cluster to get started.

  3. Click Connect cluster.

    The system prompts you to Select the cluster type.

  4. Select Kubernetes Clusters as the cluster type.
    No Kubernetes provider selection (such as AKS, EKS, or GCP) is required in Federated mode.

  5. In the Connect Kubernetes Cluster form, specify the following information:

    note

    Ensure that the Stork version 26.3.0 or higher is active on the cluster before connecting it. Use the install commands provided in the UI for PX clusters or non-PX clusters as applicable.

    FieldRequiredDescription
    Cluster NameYesA unique name to identify this cluster in Portworx Backup.
    KubeconfigYesThe kubeconfig for the cluster. Paste the output of kubectl config view --flatten --minify into the text area, or drag and drop (or upload) the kubeconfig file using the file upload option below the text area.

  6. Click Connect.

    The cluster is added to the Clusters page. Portworx Backup pushes the necessary CRs to the cluster, and Stork on the cluster begins managing backup operations locally.

  7. Assign a backup location to the cluster. In the Backup location column, click the assignment indicator or select Edit from the Actions menu, choose a backup location, and click Save. For more information, see Configure Backup Locations in Federated Mode.

Manual discovery of shoot clusters​

note

Manual Shoot Discovery is not available while the Gardener Cluster Config status is In Progress. Wait for the current operation to complete before running a manual discovery.

You can manually discover Gardener shoot clusters at any time to retrieve the latest list of shoot clusters.

If cluster labels are added or removed, or project mappings are changed after the Gardener instance is connected to Portworx Backup, the list of shoot clusters may become outdated. Use the Manual Shoot Discovery option to update the list of associated shoot clusters in Portworx Backup.

To manually discover shoot clusters, follow these steps:

  1. Log in to the Portworx Backup web console.
  2. From the left navigation pane, click Clusters > Cluster Configs.
  3. Locate the Gardener cluster instance, and click the options menu (⋮) in its row.
  4. Click Manual Shoot Discovery.

Manual reauthentication of shoot clusters​

Use Manual Shoot Reauthentication to refresh the kubeconfig for all shoot clusters associated with the Gardener cluster. This ensures that kubeconfig, tokens, and permissions remain valid and up to date.

If kubeconfig settings are modified (for example, due to security updates), performing this action immediately refreshes access for all associated shoot clusters.

This action also synchronizes the state between the Portworx Backup server and the shoot clusters. It is useful after network interruptions, configuration changes, or when cluster status appears outdated.

To refresh credentials for shoot clusters, follow these steps:

  1. Log in to the Portworx Backup web console.
  2. From the left navigation pane, click Clusters > Cluster Configs.
  3. Locate the Gardener cluster and click the options menu (⋮) in its row.
  4. Click Manual Shoot Reauthentication.

Configure auto sync schedule for Gardener clusters​

When you add a Gardener cluster configuration to Portworx Backup, you can set an Auto Sync Schedule to control how often the list of shoot clusters is refreshed automatically. This ensures that newly added or removed shoot clusters are detected and updated without manual intervention.

The Auto Sync Schedule is only active when Auto Sync is enabled for the Gardener cluster configuration.

To configure the auto sync schedule, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Clusters > Cluster Configs.

  3. Click Connect Cluster Config.

  4. In the Add Gardener Cluster page, enable the Auto Sync toggle.

  5. In the Auto Sync Schedule field, select the sync interval.

    Available intervals: Every 24 hours, Every 7 days, Every 30 days, or Custom.

    If you select Custom, the Custom Auto Sync Schedule dialog appears. Enter the frequency value in the Every field and select the unit from the drop-down, then click Set. The minimum configurable value is 15 minutes and the maximum is 90 days.

  6. Complete the remaining fields and click Connect. For field information, see Onboard Gardener shoot clusters.

To update the auto sync schedule for an existing Gardener cluster configuration, use the Edit option. For more information, see Edit Gardener cluster configuration.

Edit Gardener cluster configuration​

note

Editing a Gardener Cluster Config is not available while its status is In Progress or Deleting. Wait for the current operation to complete before making changes.

Use the edit operation to update the Gardener cluster configuration.

To edit a Gardener cluster configuration, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Clusters > Cluster Configs.

  3. Locate the Gardener cluster instance and click the options menu (⋮) in its row.

  4. Select Edit.

  5. In the Edit Gardener Cluster page, update the required fields:

    FieldEditable/Non-EditableDescription
    Gardener config nameNon-EditableA unique name for this Gardener configuration within Portworx Backup. Used to identify the configuration in the UI — does not need to match the Gardener project name.
    Project nameNon-editableThe name of the Gardener project that contains the shoot clusters you want to manage. Must match the project name exactly as it appears in the Gardener dashboard.
    Gardener Cluster KubeconfigPartially editableThe kubeconfig for the Gardener API server (not a shoot cluster kubeconfig). Portworx Backup uses this to authenticate with the Gardener API and discover the shoot clusters in the specified project. You can update the kubeconfig (for example, to refresh credentials), but the updated kubeconfig must point to the same Gardener API server endpoint. Changing the endpoint is not supported.
    The service account referenced in this kubeconfig must have the following permissions on the Gardener API server:
    • Get/List Projects
    • Get/List Shoots
    • Create Token
    • Create shoots/adminkubeconfig (required to obtain shoot cluster kubeconfigs)
    Cluster LabelNon-editableA Kubernetes cluster label (for example, px-backup_allotment=<value>) that filters which shoot clusters in the project are discovered and managed by Portworx Backup. Only clusters matching this label are onboarded.
    Auto SyncEditableWhen enabled, Portworx Backup periodically updates the list of shoot clusters based on cluster labels. New matching clusters are added automatically. Shoot clusters that no longer exist in Gardener are deleted from Portworx Backup (backups remain in the backup location). Shoot clusters whose labels no longer match the configured label filter are marked as unmanaged.
    For example, if a shoot cluster with label px-backup_allotment=one is changed to px-backup_allotment=two or the label is removed altogether, then the cluster is marked as unmanaged. You can remove unmanaged clusters manually from the Portworx Backup web console.
    When disabled, you must update the cluster list manually using the Manual Shoot Discovery option. For more information, see Manual discovery of shoot clusters.
    Auto Sync ScheduleEditableThe interval at which shoot clusters are automatically discovered or synchronized (for example, Every 24 hours). Applicable when Auto Sync is enabled. When using Custom, the minimum configurable value is 15 minutes and the maximum is 90 days.
    For more information, see Configure auto sync schedule for Gardener clusters.

  6. Select the acknowledgment checkbox, and click Update.

Edit a standalone shoot cluster​

Use the edit option to update the kubeconfig for a standalone shoot cluster. This is useful when cluster credentials change or the kubeconfig has expired.

To edit a standalone shoot cluster, follow these steps:

  1. Log in to the Portworx Backup web console.

  2. From the left navigation pane, click Clusters > All Clusters.

  3. Locate the cluster and click the options menu (⋮) in its row.

  4. Click Edit.

  5. In the Edit Kubernetes Cluster page, update the required fields:

    FieldEditable/Non-EditableDescription
    Cluster NameNon-editableThe name used to identify this cluster in Portworx Backup.
    KubeconfigEditableThe kubeconfig for the cluster. Paste the updated kubeconfig content or upload a new kubeconfig file.

  6. Click Update.

Delete a Gardener shoot cluster or a standalone shoot cluster​

To delete a Gardener shoot cluster or a standalone shoot cluster from Portworx Backup, follow these steps:

  1. Log in to the Portworx Backup web console.
  2. From the left navigation pane, click Clusters > All Clusters.
  3. Locate the Gardener shoot cluster or standalone shoot cluster, and click the options menu (⋮) in its row.
  4. Click Remove.
  5. Select the acknowledgment checkbox, and click Delete to confirm.
note

If the Gardener configuration is retained, the shoot cluster can be rediscovered and re-added during the next discovery cycle (manual or automatic, if Auto Sync is enabled). It appears with the same name but as a new cluster object with a new UUID.
For information on manual discovery, see Manual discovery of shoot clusters.
You can also add the cluster manually using a kubeconfig. For more information, see Onboard a standalone shoot cluster.

note

When a shoot cluster is deleted from Gardener (not from Portworx Backup), Portworx Backup handles the removal automatically through the Cluster Discovery configuration:

  • If Auto Sync is enabled, the next Auto Sync cycle detects that the shoot cluster no longer exists in Gardener and removes it from Portworx Backup automatically.
  • If Auto Sync is disabled, you must manually trigger Manual Shoot Discovery to update the cluster list. The deleted shoot cluster is removed from Portworx Backup after discovery completes.

Backups already stored in the backup location are not deleted when a shoot cluster is removed from Portworx Backup.

Delete a Gardener cluster configuration​

note

Deleting a Gardener Cluster Config is not available while its status is In Progress. Wait for the current operation to complete before deleting.

Before deleting a Gardener cluster configuration, ensure that all associated shoot clusters have been removed from Portworx Backup. Portworx Backup prevents deletion of a Gardener cluster configuration if it still has associated shoot clusters. For more information on removing shoot clusters, see Delete a Gardener shoot cluster or a standalone shoot cluster.

To delete the Gardener cluster configuration from Portworx Backup, follow these steps:

  1. Log in to the Portworx Backup web console.
  2. From the left navigation pane, click Clusters > Cluster Configs.
  3. Locate the Gardener cluster and click the options menu (⋮) in its row.
  4. Click Remove.
  5. In the Delete Gardener Config dialog, select the acknowledgement checkbox, and click Delete.
note

Deleting a Gardener cluster configuration removes it from Portworx Backup and stops automatic discovery of new shoot clusters for that project. Any backups already stored in the backup location are not deleted.

Cluster states​

When Portworx Backup discovers shoot clusters through a Gardener cluster configuration, each cluster is assigned a state that reflects whether it is actively tracked by the discovery configuration.

StateDescription
ManagedThe cluster was discovered through the Gardener API and its Kubernetes labels match the label filter configured in the CDC. Portworx Backup actively tracks this cluster and includes it in Auto Sync cycles.
UnmanagedThe cluster was previously discovered through the Gardener cluster configuration, but its labels no longer match the configured label filter. For example, the label was changed or removed. Portworx Backup no longer actively tracks this cluster, but it remains visible in the UI until you remove it manually.
note

A shoot cluster that no longer exists in Gardener is deleted from Portworx Backup entirely and is not marked as unmanaged. Backups already stored in the backup location are retained in both cases.

To remove an unmanaged cluster, go to Clusters > All Clusters, locate the cluster, and select Remove from the actions menu. For more information, see Delete a Gardener shoot cluster or a standalone shoot cluster.

Next steps​

Add a backup location. For more information, see Configure Backup Locations in Federated Mode.

Last updated on