Federated Mode Specifications
Review the platform requirements, supported configurations, and limitations for Portworx Backup Federated mode. Use this information to check if your environment is ready before installing Federated mode.
For an overview of operation modes, see Operation Modes.
Architecture overview
The following figure provides an overview of the Portworx Backup Federated mode architecture:
Federated mode includes the following components:
- Management cluster (Backup cluster) Runs the Portworx Backup server, which sends instructions to application clusters but does not perform backup tasks itself.
- Application clusters (Shoot clusters) Each cluster runs Stork, which receives instructions and handles all backup tasks locally.
- Backup location Each application cluster connects directly to the backup location using Workload Identity. The Portworx Backup server is not involved in this connection.
Supported Kubernetes platforms
Federated mode supports application clusters on the following cloud providers. Gardener is the supported management interface for automated shoot cluster discovery, but it is not a requirement: you can also onboard clusters manually with a kubeconfig, including standalone Kubernetes clusters on these providers. For more information, see Onboard a standalone shoot cluster.
The table lists the Workload Identity mechanism for each provider and the minimum component versions required to use it.
| Cloud provider | Workload Identity mechanism | Portworx Backup | Portworx Enterprise | Stork | Portworx Operator |
|---|---|---|---|---|---|
| Azure (Azure Blob Storage) | Azure Managed Identity | 3.0.0 or later | 3.6.1 or later | 26.3.0 or later | 26.2.0 or later |
| AWS (AWS S3) | AWS IRSA (IAM Roles for Service Accounts) | 3.1.0 or later | 3.6.2 or later | 26.4.0 or later | 26.3.0 or later |
| GCP (Google Cloud Storage) | GCP Workload Identity Federation | 3.1.0 or later | 3.6.2 or later | 26.4.0 or later | 26.3.0 or later |
Supported backup location types:
- Azure Blob Storage — using Azure Managed Identity
- AWS S3 — using AWS IRSA (IAM Roles for Service Accounts)
- Google Cloud Storage (GCS) — using GCP Workload Identity Federation, including buckets with a retention policy (immutability) enabled
For a full comparison of features and storage support across Classic and Federated modes, see the Feature Matrix.
Multi-provider deployments
A single Portworx Backup instance in Federated mode can manage multiple backup locations of different types simultaneously. For example, some application clusters can use Azure Blob Storage while others use AWS S3 or Google Cloud Storage (GCS).
Because the Portworx Backup server does not access backup locations directly, each application cluster connects to its assigned backup location using its own Workload Identity. As a result, different backup location types can coexist within the same Portworx Backup instance. Each backup location uses a single provider (Azure Blob Storage, AWS S3, or GCS), and each application cluster reads from and writes to the backup locations assigned to it.
Deployment requirements
Stork must be deployed through the Portworx Operator as part of the Portworx Enterprise installation. Standalone Stork deployments — that is, Stork installed without Portworx Enterprise — are not supported in Federated mode. For the minimum Portworx Backup, Portworx Enterprise, Stork, and Portworx Operator versions per provider, see Supported Kubernetes platforms.
Before you deploy Portworx Backup in Federated mode, ensure that the following requirements are met. For hardware requirements (CPU, RAM, and storage for the backup cluster), see Requirements for Portworx Backup Installation.
Permissions and access
-
Each application cluster must have Workload Identity configured with the permissions required to access its backup location:
- Azure: an Azure Managed Identity bound to the Stork service account with the Storage Blob Data Contributor role (or a custom role for immutable containers).
- AWS: an IAM role bound to the Stork Kubernetes service account through IRSA, with the required S3 bucket and object permissions (plus additional permissions for object lock-enabled buckets).
- GCP: a GCP service account bound to the Stork Kubernetes service account through Workload Identity Federation, with the required GCS bucket permissions (typically the
roles/storage.objectAdminrole).
For the complete permission lists, resource scoping, and an example AWS IAM policy, see Prerequisites for configuring backup location.
-
The Portworx Backup server must be able to reach the Kubernetes API server endpoint of each application cluster over the network. In Federated mode, Portworx Backup drives backup operations by creating and updating custom resources (CRs) on each application cluster through its API server, so this connectivity is required. Ensure that any firewalls, security groups, or network policies between the backup cluster and each application cluster's API server allow this traffic. For the full set of ports and network prerequisites, see Network requirements.
Security model
Federated mode uses a secret-less approach:
- Cloud and backup location credentials are not stored on the Portworx Backup server. Each application cluster uses the Workload Identity mechanism (see Supported Kubernetes platforms) of its cloud provider to connect directly to the backup location. Stork authenticates using the identity bound to its Kubernetes service account:
- Azure: through the Azure Managed Identity associated with the Stork service account.
- AWS: through the IAM role assumed by the Stork service account using IRSA (IAM Roles for Service Accounts).
- GCP: through Application Default Credentials (ADC) provided by Workload Identity Federation.
- Backup location validation is handled locally by Stork on each cluster.
This approach reduces the attack surface because cloud and backup location credentials are never stored centrally on the Portworx Backup server. Other component credentials that Portworx Backup requires to operate (for example, database passwords for MySQL, MongoDB, and PostgreSQL) are still managed by Portworx Backup, as in Classic mode.
Cluster management
Application clusters can be onboarded in the following ways:
- Automatic discovery — Gardener-managed shoot clusters are discovered automatically through the Gardener API (the Gardener API server kubeconfig is required; individual shoot kubeconfigs are not).
- Manual addition — any cluster, including non-Gardener clusters, is added manually using a kubeconfig file. For more information, see Onboard a standalone shoot cluster.
- Manual discovery — Gardener-managed shoot clusters can be discovered on demand to retrieve the latest list. For more information, see Manual discovery of shoot clusters.
In all cases, the Portworx Backup server sends instructions to application clusters, and Stork handles all backup tasks locally.
Operation specifications
In Federated mode, several operations that the Portworx Backup server performs directly in Classic mode are instead carried out by Stork on the application clusters:
| Operation | Classic mode | Federated mode |
|---|---|---|
| Backup deletion | Portworx Backup server deletes the backup and removes data from the backup location | Stork on each application cluster deletes the backup locally using Workload Identity. Requires at least one valid cluster; otherwise the delete request is rejected. For the rejection and force-delete behavior, see Backup deletion behavior under Constraints and Forced deletion of backups. |
| Backup sync | Portworx Backup server periodically scans the backup location for new or updated backups | Backup sync is initiated when you enable the sync option and assign at least one cluster (with Workload Identity configured) to the backup location during backup location creation. The initial sync occurs after this configuration; subsequent syncs are not periodic and must be triggered manually from the Portworx Backup UI, CLI, or API. Stork on each cluster performs the sync using Workload Identity. For more information, see Sync Backups from a backup location. |
| Cloud file missing check | Portworx Backup server verifies that all backup data files referenced in the metadata are present in the backup location. If any files are missing, the backup is marked as invalid. | Stork on each application cluster performs the same check locally using Workload Identity to access the backup location and verify that all referenced files are present. |
| Backup location validation | Portworx Backup server checks connectivity to the backup location | Stork on each application cluster checks connectivity to the backup location using Workload Identity. You can trigger a manual validation from the Portworx Backup console. For more information, see Validate Cluster Connectivity to a backup location. |
Valid cluster
Because these operations are carried out by Stork on an application cluster, they require at least one valid cluster. A valid cluster is an application cluster that meets all of the following conditions:
- It is online and reachable by the Portworx Backup server through its Kubernetes API server.
- Stork is running on it with Workload Identity configured for the relevant cloud provider.
- It is assigned to the backup location that stores the backup being operated on.
If no valid cluster is available, the operation cannot be completed (for example, a delete request is rejected). To confirm that a cluster qualifies, run a validation as described in Validate Cluster Connectivity to a backup location.
Constraints
| Capability | Details |
|---|---|
| KubeVirt virtual machine backup | Not supported in this release. Only application-consistent namespace and volume backups are supported. |
| NFS backup locations | Not supported in Federated mode. Only object store backup locations are supported: Azure Blob Storage, AWS S3, and Google Cloud Storage (GCS). NFS backup locations are available in Classic mode only. |
| KDMP-based backups | KDMP-based backup types — Direct KDMP and CSI local snapshot with KDMP offload — are not available in Federated mode. |
| Classic-to-Federated conversion | You cannot convert an existing Classic mode deployment to Federated mode by upgrading. Federated mode must be installed as a new deployment; the pre-upgrade health check blocks an in-place Classic-to-Federated upgrade. See Upgrade Portworx Backup in Federated Mode. |
| Backup deletion behavior | When no valid cluster is available to process a backup deletion request, the delete request is rejected — no metadata or backup data is removed. To remove a backup in this state, you must explicitly perform a force delete, which removes only the backup metadata from the Portworx Backup database; the backup data in the backup location is not deleted and must be cleaned up manually. Force delete can only be performed on one backup at a time — bulk force delete is not supported. See Force Delete Backups. |
| Concurrent backup sync for shared bucket | If multiple backup locations point to the same storage bucket or container (Azure Blob Storage, AWS S3, or GCS), only one Sync Backups operation can run at a time. Additional sync attempts for the same bucket fail while a sync is in progress. The blocked user cannot see when the current sync completes and must retry manually. As a workaround, an administrator can coordinate sync operations across users to ensure that backup location syncs are performed sequentially without conflicts. |
Alerts and metrics
The following Prometheus alert rules are available for Gardener cluster discovery operations in Federated mode. These alerts follow the standard Portworx Backup alerting pattern and are raised when the relevant gauge metric indicates an error state.
ClusterDiscoveryConfigFailed
Severity: Critical
Description: Raised when a Cluster Discovery configuration enters a failed state.
- alert: ClusterDiscoveryConfigFailed
annotations:
description: 'Cluster discovery config "{{ $labels.config_name }}" (project: {{ $labels.project_name }}, selector: {{ $labels.label_selector }}) has failed. Reason: {{ $labels.error_reason }}. Error type: {{ $labels.error_type }}'
summary: Cluster discovery failed
expr: pxbackup_cluster_discovery_config_status == 3
for: 1m
labels:
severity: critical
GardenerConnectivityFailure
Severity: Critical
Description: Raised when communication with the Gardener API fails for a discovery configuration.
- alert: GardenerConnectivityFailure
annotations:
description: 'Gardener API communication failed for discovery config "{{ $labels.config_name }}" (type: {{ $labels.error_type }}). Reason: {{ $labels.error_reason }}'
summary: Gardener API connectivity failure
expr: pxbackup_gardener_connectivity_failure > 0
for: 1m
labels:
severity: critical
This alert may trigger multiple times within an hour, depending on the configured interval of the background jobs.
GardenerShootKubeconfigValidationFailure
Severity: Critical
Description: Fires when a shoot cluster kubeconfig fails validation.
- alert: GardenerShootKubeconfigValidationFailure
annotations:
description: 'Shoot kubeconfig validation failed for cluster "{{ $labels.cluster_name }}" in discovery config "{{ $labels.config_name }}"'
summary: Shoot kubeconfig validation failed
expr: pxbackup_gardener_shoot_kubeconfig_validation_failure > 0
for: 1m
labels:
severity: critical
For Federated mode-related metrics information, see Portworx Backup Metrics.