Skip to main content

Cluster And Storage Binding

Testudo connects source clusters, target clusters, and object storage through Cluster, StorageRepository, and Velero BackupStorageLocation. Understanding this binding explains why disaster recovery requires both source and target clusters to access the same backup storage.

Objects Involved​

ObjectLocationPurpose
ClusterManagement clusterDescribes access, status, and Velero installation settings for a business cluster
StorageRepositoryManagement clusterDescribes object storage endpoint, bucket, region, prefix, credentials, CA, and addressing style
DisasterConfigManagement clusterCombines source cluster, target cluster, storage repository, and sync policies
BackupStorageLocationvelero namespace in source and target clustersThe actual storage location consumed by Velero
AppBackup / AppRestoreManagement clusterTestudo wrappers that cause the operator to create Velero Backup and Restore objects in remote clusters

StorageRepository is the Testudo-level configuration. BackupStorageLocation is the Velero-level configuration used inside each business cluster. The operator converts one StorageRepository into BSL objects in remote clusters.

How DisasterConfig Binds Clusters And Storage​

A disaster configuration selects:

  • Source cluster.
  • Target cluster.
  • Storage repository.
  • DataSync policy.
  • ResourceSync policy.

This creates the relationship:

DisasterConfig
  sourceCluster: <sourceCluster>
  targetCluster: <targetCluster>
  storageRepository: <storageRepository>

When the operator reconciles the DisasterConfig, it reads the StorageRepository and applies it to both the source and target clusters.

BSL Naming Rule​

In disaster recovery sync, runtime BSL names use the source cluster as the suffix:

BSL name = <StorageRepository>-<sourceCluster>
prefix   = <sourceCluster>

Example:

StorageRepository = s3-default
sourceCluster     = prod-a
targetCluster     = dr-b

BSL name = s3-default-prod-a
prefix   = prod-a

The same BSL appears in the velero namespace of both source and target clusters:

source cluster / velero / BackupStorageLocation s3-default-prod-a
target cluster / velero / BackupStorageLocation s3-default-prod-a

Both BSL objects point to the same object storage location.

Why The Target Cluster Reads The Source BSL​

The DataSync path is:

Velero Backup in source cluster
  -> writes to object storage
  -> Velero Restore in target cluster
  -> restores data into target PVCs

The source cluster writes backup objects. The target cluster reads the same backup objects. The target cluster is not reading a separate target-side backup; it reads the backup written by the source cluster.

Therefore, the target cluster must have a BSL that can read the source backup:

BSL name = <StorageRepository>-<sourceCluster>
prefix   = <sourceCluster>

This allows Velero Restore to find the objects written by Velero Backup in the source cluster.

Why One Bucket Can Be Shared​

Several clusters can share one bucket because Testudo uses the source cluster name as the object storage prefix:

bucket/
  prod-a/
    backups/
    kopia/
    restic/
  prod-b/
    backups/
    kopia/
    restic/

Different source clusters write to different prefixes, so backup objects do not overwrite each other. A target cluster reads the prefix that belongs to the source cluster it is recovering from.

This model provides:

  • Direct reads of the latest source backup during failover.
  • A clear direction change during reprotect, where the new source cluster uses its own prefix.
  • Shared object storage for multiple disaster recovery directions while keeping data separated by prefix.
  • One place to manage storage credentials and lifecycle policies.

Network And Permission Requirements​

Both source and target clusters must:

  • Resolve and reach the object storage endpoint.
  • Use the same credentials or credentials with equivalent access.
  • Have permission to read the bucket and prefix.
  • Let the source cluster write, list, and read backup objects.
  • Let the target cluster list and read source backup objects; if reprotect is used, the target cluster also needs write permission.
  • Trust the private CA if the object store uses one.
  • Use the same path-style or virtual-host-style addressing mode.

For production, give both source and target clusters read and write access. Read-only access on the target can break reprotect, drills, or reverse sync.

Common Misunderstandings​

MisunderstandingCorrect Understanding
Source and target clusters should use different bucketsDisaster recovery requires the target cluster to read backups written by the source cluster; use the same bucket or another shared object storage location
The target cluster only needs its own BSLThe target cluster needs the source-cluster-suffixed BSL, for example <StorageRepository>-<sourceCluster>
A successful management-cluster connection test proves restore will workIt only proves the server can access object storage; Velero BSLs in source and target clusters must also become Available
The BSL name uses the target cluster suffixDisaster recovery restore reads source backups, so the runtime BSL uses the source cluster suffix
Multiple clusters cannot share one bucketThey can, as long as prefix, permissions, lifecycle, and audit policies are managed correctly

Verification​

Check BSLs in both clusters:

kubectl --context <source-cluster> -n velero get backupstoragelocation
kubectl --context <target-cluster> -n velero get backupstoragelocation

Confirm that the target cluster has the source-cluster-suffixed BSL:

kubectl --context <target-cluster> -n velero get backupstoragelocation <storageRepository>-<sourceCluster>

The BSL should be Available:

kubectl --context <target-cluster> -n velero describe backupstoragelocation <storageRepository>-<sourceCluster>

If the BSL is Unavailable, check:

  • Pod network connectivity from the target cluster to the object storage endpoint.
  • Bucket, region, prefix, and addressing style.
  • Access key and secret key permissions.
  • CA or TLS certificate configuration.
  • Velero Pod logs and events.