Restore from a snapshot

The operator restores snapshot state through an explicit OpenBaoRestore request. That request validates the target, acquires the restore operation lock, launches a dedicated restore Job, and records the outcome for audit. Use this page when snapshot restore is the right recovery workflow for the target cluster.

Restore overwrites the target cluster

Restore replaces the target cluster state with the contents of the selected snapshot. All current secrets, policies, auth methods, and keys in that cluster are treated as replaceable state. Verify the target namespace, target cluster, and snapshot key as part of the restore request.

Decision matrix

First successful restore path

First successful restore path.

Step	What to do first	What proves you are ready
1. Prove the backup path first	Confirm the snapshot exists and that the backup storage and auth path already succeeded in the backup workflow.	You know the exact snapshot key and can point to a successful backup object in storage.
2. Prepare the target cluster deliberately	Keep the target OpenBaoCluster in the same namespace, make sure it already exists, and confirm the restore Job can reach it.	The target cluster resource exists, the namespace is correct, and the restore Job can reach object storage.
3. Choose restore auth	Prefer JWT auth through spec.selfInit.oidc.enabled=true or a deliberate restore role. Use a static token only as a compatibility fallback.	You know whether the restore Job will use jwtAuthRole or tokenSecretRef and the referenced auth path already exists.
4. Watch the restore and cluster together	Apply the OpenBaoRestore, then inspect both the restore resource and the target cluster until the destructive step and follow-up recovery state are clear.	The restore reaches a terminal phase and you know whether the next step is normal service, unseal recovery, or Raft repair.

Decision matrix

Choose the restore auth path

Choose the restore auth path.

Path	Use it when	Operator behavior	Watch for
JWT auth	You already use selfInit.oidc or can provision a dedicated restore JWT role on the target cluster.	The restore Job uses a projected ServiceAccount token and authenticates with a short-lived, scoped identity.	Keep the JWT audience and bound ServiceAccount subject aligned with the restore role.
Static token	JWT auth is not available yet and you need a compatibility path for recovery.	The restore Job reads a long-lived OpenBao token from a Secret in the same namespace.	Store the token as a high-sensitivity credential and rotate it intentionally.

Diagram

Restore execution path

The controller validates the request, acquires the restore lock, launches a restore Job, downloads the selected snapshot, and then forces the snapshot into the target cluster leader.

Prepare the restore request

• Make sure the snapshot you want already exists in object storage and has been validated as usable.
• Create or keep the target OpenBaoCluster in the same namespace as the restore request. The target cluster must exist and be initialized, even if it is otherwise empty.
• Verify the restore Job can reach the object storage endpoint. In hardened environments, this usually means explicit spec.network.egressRules.
• Choose the restore auth path before the incident starts. The restore Job does not automatically inherit the cloud identity or auth material from the main OpenBao Pods.

Same-namespace requirement

The OpenBaoRestore, the target OpenBaoCluster, and any referenced token Secrets all live in the same namespace. Cross-namespace references are intentionally blocked for security reasons.

For most first-time restores

If the target cluster already uses spec.selfInit.oidc.enabled=true, start with jwtAuthRole: openbao-operator-restore and the same object-storage provider shape you already validated in the backup flow. That keeps the restore path aligned with the backup path you have already proven.

Restore drains and restores steady read replicas deliberately

When the target cluster has steady read replicas enabled, restore first drains that pool to zero, then launches the restore Job. After the snapshot is forced into the cluster, the operator restores the steady read pool and only marks the OpenBaoRestore as Completed once the read-replica conditions are healthy again.

Configure the snapshot source

S3

Configure

Configure an S3 or S3-compatible restore source

yaml

spec:
cluster: prod-cluster
source:
  target:
    provider: s3
    endpoint: https://s3.amazonaws.com
    bucket: openbao-backups
    region: us-east-1
    usePathStyle: false
    credentialsSecretRef:
      name: s3-credentials
  key: clusters/prod/backup-2026-03-20.snap

The Secret can provide accessKeyId, secretAccessKey, sessionToken, region, and an optional caCert for custom trust chains.

GCS

Configure

Configure a Google Cloud Storage restore source

yaml

spec:
cluster: prod-cluster
source:
  target:
    provider: gcs
    bucket: openbao-backups
    gcs:
      project: my-gcp-project
    credentialsSecretRef:
      name: gcs-credentials
  key: clusters/prod/backup-2026-03-20.snap

The Secret typically contains credentials.json. You can also use a provider-default identity path when your environment already supports it.

Azure

Configure

Configure an Azure Blob Storage restore source

yaml

spec:
cluster: prod-cluster
source:
  target:
    provider: azure
    bucket: openbao-backups
    azure:
      storageAccount: mystorageaccount
      container: openbao-backups
    credentialsSecretRef:
      name: azure-credentials
  key: clusters/prod/backup-2026-03-20.snap

The Secret can provide an accountKey or a connectionString. For workload identity or managed identity, omit the credentials Secret and rely on the platform-native path intentionally.

Configure restore auth

JWT auth (Recommended)

Configure

Use a JWT role for restore

yaml

spec:
jwtAuthRole: openbao-operator-restore

When spec.selfInit.oidc.enabled=true on the target cluster, the operator can create and use the default restore role automatically. Otherwise, create the role deliberately and keep the JWT audience aligned with OPENBAO_JWT_AUDIENCE.

Static token

Configure

Use a static token Secret for restore

yaml

spec:
tokenSecretRef:
  name: restore-token

Use this path if JWT auth is not available. The Secret must be in the same namespace as the restore request.

Apply the restore request

Configure

Create a full restore request

yaml

apiVersion: openbao.org/v1alpha1
kind: OpenBaoRestore
metadata:
name: prod-restore
namespace: security
spec:
cluster: prod-cluster
source:
  target:
    provider: s3
    endpoint: https://s3.amazonaws.com
    bucket: openbao-backups
    region: us-east-1
    credentialsSecretRef:
      name: s3-credentials
  key: clusters/prod/backup-2026-03-20.snap
jwtAuthRole: openbao-operator-restore

The restore spec is immutable. If you need to change the target, snapshot key, or auth path, create a new OpenBaoRestore resource instead of editing the existing one.

Apply

Apply the restore

bash

kubectl apply -f restore.yaml

Watch the restore phases

Verify

Inspect restore status

bash

kubectl get openbaorestore <name> -n <namespace> -o yaml
kubectl get jobs -n <namespace>
kubectl describe openbaocluster <cluster> -n <namespace>

Watch the restore resource and the target cluster together. The restore phase tells you what the restore controller is doing, while the cluster status shows what still needs follow-up after the destructive step finishes.

Reference table

Restore phases to expect

Restore phases to expect.

Phase	What it means
Pending / Validating	The operator is checking the target cluster, storage source, auth path, and conflicting operations before it starts destructive work.
Running	The restore Job owns the cluster operation lock and is actively downloading or applying the snapshot.
Completed	The restore workflow finished and the operator recorded the result. The cluster may still need unseal or follow-up recovery work.
Failed	The restore did not succeed. Inspect the restore resource, related Job, and target cluster state before retrying with a new request.

After the restore

Recover a sealed clusterGo here when the restored cluster starts but remains sealed because the trust or unseal path still needs attention.Recover from no leaderGo here when the restored cluster needs Raft peer or leadership repair before it can return to service.Recover after upgrade restoreUse the override-lock path if a failed upgrade or rollback blocks the normal restore request.