Skip to main content
Version: 1.18

Space Backups Workload ID

Business Critical Plan Feature

This is a Business Critical Plan feature. For more information, see our pricing plans or contact our sales team.

Prerequisites​

To set up a workload identity for Space Backups, you'll need:

  • A self-hosted Space cluster with the Space Backups feature enabled. Spaces enables it by default from v1.14.0. See Disaster Recovery for earlier versions.
  • Administrator access in your cloud provider
  • Helm and kubectl

SpaceBackupConfig has accepted credentials.source: InjectedIdentity for as long as Space Backups has existed, so the AWS and GCP paths below work on any Space that has the feature. Only Azure needs v1.19.0 or later.

About the Space Backups component​

The spaces-controller component handles Space Backups. It runs in the upbound-system namespace, uses the spaces-controller service account, and reads the storage details from a SpaceBackupConfig.

This component is separate from the mxp-controller component that handles per-control-plane backups. Configuring one doesn't configure the other. For per-control-plane backups, see Backup and Restore Workload ID.

The names below assume the default spaces Helm release name. The Deployment and the service account are both <release>-controller, so substitute your own release name if it differs. The pod label app: spaces-controller doesn't change.

Configuration​

Configure the SpaceBackupConfig​

A SpaceBackupConfig with spec.objectStorage.credentials.source set to InjectedIdentity tells Space Backups to authenticate with the identity of the spaces-controller pod rather than a Secret.

Restart workload​

You must manually restart the spaces-controller pod when you add the workload identity configuration to a running deployment.

kubectl rollout restart deployment spaces-controller -n upbound-system

Verify your configuration​

Verify the service account carries the annotation you set:

kubectl get serviceaccount spaces-controller -n upbound-system -o yaml

Then create a backup and confirm it completes. With no spec.match selector this backs up every group and control plane in the Space, so treat it as a real backup rather than a cheap probe. deletionPolicy: Delete removes the uploaded objects when you delete the resource. The default is Orphan, which would leave the test data in the bucket:

kubectl apply -f - <<EOF
apiVersion: admin.spaces.upbound.io/v1alpha1
kind: SpaceBackup
metadata:
  name: workload-id-check
spec:
  configRef:
    kind: SpaceBackupConfig
    name: default
  deletionPolicy: Delete
EOF

Watch the PHASE column until it reads Completed:

kubectl get spacebackup workload-id-check -w

Completed means the component authenticated and wrote to the bucket. Failed means it couldn't. See Troubleshooting below. Then clean up:

kubectl delete spacebackup workload-id-check

Troubleshooting​

A backup that reaches Failed records the reason on the resource, and the component logs the underlying object storage error:

kubectl describe spacebackup workload-id-check
kubectl logs -n upbound-system deployment/spaces-controller -c spaces

An authentication problem shows up as a permission or token error from the cloud provider's client. Spaces also rejects a missing or misspelled key in spec.objectStorage.config outright rather than ignoring it, so check that too.

Restoring a Space​

Restore runs hyperspace restore inside the spaces-controller pod, so it uses the identity you configured here and needs no extra credentials. See Disaster Recovery for the procedure.

Recovering into a freshly installed Space means configuring that installation the same way before restoring, since the identity belongs to the pod rather than to the backup. The new Space needs read access to the same bucket, and on Azure it needs the pod label as well.

Use cases​

Configuring Space Backups with workload identity removes static credentials from your cluster along with the overhead of rotating them. These benefits are helpful in:

  • Disaster recovery scenarios
  • Compliance requirements
  • Migrating a Space between clusters

Next steps​

Now that you have a workload identity configured for Space Backups, visit the Disaster Recovery documentation to configure backup schedules.

Other workload identity guides are: