Federated Mode Specifications

Applicable to Federated mode only

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.

Supported Kubernetes platforms

Federated mode is supported for Gardener Kubernetes deployments using Garden Linux on Azure.

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 that receives instructions and handles all backup tasks locally.
• Backup location Each cluster connects directly to the backup location using Workload Identity. The Portworx Backup server is not involved in this connection. Currently, only Azure Blob Storage is supported. GCS and AWS S3 support is planned for future releases.

Security model

Federated mode uses a secret-less approach:

• Cloud credentials are not stored on the Portworx Backup server.
• Each cluster uses Workload Identity to connect directly to the backup location.
• Currently, Azure Managed Identity is supported for authentication.
• Backup location validation is handled locally by Stork on each cluster.

This approach improves security because credentials are never stored centrally.

Supported backup location types

Only Azure Blob Storage is supported in Federated mode.

Cluster management

In Federated mode, application clusters can be added to Portworx Backup in the following ways:

• Automatic discovery — Gardener-managed shoot clusters are discovered automatically through the Gardener API. The Gardener API server kubeconfig is required for discovery; individual shoot cluster kubeconfigs are not needed.
• Manual addition — Any cluster, including Gardener shoot clusters not managed through a Gardener configuration or non-Gardener Kubernetes clusters, can be added manually using a kubeconfig file. For more information, see Onboard a standalone shoot cluster.
• Manual discovery — Gardener-managed shoot clusters can be manually discovered at any time to retrieve the latest list of shoot clusters. 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

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. If no valid cluster is available to process the deletion, the delete request is rejected. Metadata-only removal is available only when the user explicitly performs a force delete. For more information, see Forced deletion of backups.
Backup sync	Portworx Backup server periodically scans the backup location for new or updated backups	Performed automatically and periodically by the Portworx Backup server. 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. For more information, see Add a backup location in Federated mode. The initial sync occurs after this configuration. Subsequent sync operations are not periodic and must be triggered manually using the Portworx Backup UI, CLI, or API. For more information, see Sync Backups from a backup location. Stork on each cluster performs the sync using Workload Identity.
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.

Deployment requirements

important

Federated mode requires Portworx Enterprise version 3.6.1 or later to be installed on every application cluster. Stork must be deployed through the Portworx Operator (version 26.2.0 or later) as part of the Portworx Enterprise installation. Standalone Stork deployments — that is, Stork installed without Portworx Enterprise — are not supported in Federated mode.

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.

Software requirements

• Portworx Backup version 3.0.0 or later
• Portworx Enterprise version 3.6.1 or later on each application cluster. This is the minimum version that supports Azure Workload Identity (WLI) for Stork.
• Stork 26.3.0 or later on each application cluster (shoot or non-Gardener), 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.
• Portworx Operator version 26.2.0 or later.

Permissions and access

• Each application cluster must have Workload Identity configured with the appropriate permissions to access the backup location.
• The Portworx Backup server must have network access to the Kubernetes API server of each application cluster to send instructions.

For detailed installation steps, prerequisites, and permission requirements, see Install Portworx Backup in Federated Mode.

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

note

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.

Constraints

Capability	Details
KubeVirt virtual machine backup	Not supported in this release. Only application-consistent namespace and volume backups are supported.
Backup deletion behavior	When no valid application 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 Azure Blob Storage bucket, 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.

Related topics

• Operation Modes
• Install Portworx Backup in Federated Mode
• Manage Clusters (Federated Mode)
• Configure Backup Locations in Federated Mode
• Delete Backups