Packages
openbao.org/v1alpha1
Package v1alpha1 contains API Schema definitions for the openbao v1alpha1 API group.
Resource Types
AzureTargetConfig
AzureTargetConfig holds Azure Blob Storage specific configuration.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
storageAccount string | StorageAccount is the Azure storage account name. Required when using Azure provider. | MinLength: 1 | |
container string | Container is the blob container name. If empty, uses the Bucket field value. | Optional: {} |
BackupTarget
BackupTarget describes a generic, cloud-agnostic object storage destination.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
provider string | Provider selects the storage backend. Defaults to “s3” for backward compatibility. | s3 | Enum: [s3 gcs azure] Optional: {} |
endpoint string | Endpoint is the HTTP(S) endpoint for the object storage service. For S3: Required (e.g., “https://s3.amazonaws.com” or MinIO endpoint). For GCS: Optional (defaults to googleapis.com). For Azure: Optional (derived from StorageAccount if not specified). | Optional: {} | |
bucket string | Bucket is the bucket or container name. | MinLength: 1 | |
pathPrefix string | PathPrefix is an optional prefix within the bucket for this cluster’s snapshots. | Optional: {} | |
credentialsSecretRef LocalObjectReference | CredentialsSecretRef optionally references a Secret containing credentials for the object store. The Secret must exist in the same namespace as the owning OpenBao resource. Cross-namespace references are not allowed for security reasons. For S3: Expected keys are “accessKeyId” and “secretAccessKey” (optional: “sessionToken”, “region”, “caCert”). For GCS: Expected key is “credentials.json” containing a service account JSON key. For Azure: Expected keys are “accountKey” or “connectionString”. Hardened clusters require an explicit storage identity path: credentialsSecretRef, workloadIdentity metadata, or roleArn for S3 targets. Omitting those paths relies on ambient/default credentials and is rejected for Hardened clusters. | Optional: {} | |
workloadIdentity WorkloadIdentityConfig | WorkloadIdentity optionally applies provider-specific metadata required by cloud workload identity integrations. Use this for ambient identity setups such as EKS Pod Identity or IRSA, GKE Workload Identity, or Azure Workload Identity. When omitted, backup and restore workloads can still use any credentials exposed through the pod’s default provider chain. Hardened clusters reject that ambient/default path unless credentialsSecretRef is set, workloadIdentity metadata is present, or an S3 target uses roleArn. | Optional: {} | |
partSize integer | PartSize is the size of each part in multipart uploads (in bytes). Defaults to 10MB (10485760 bytes). Larger values may improve performance for large snapshots on fast networks, while smaller values may be better for slow or unreliable networks. | 10485760 | Minimum: 5.24288e+06 Optional: {} |
concurrency integer | Concurrency is the number of concurrent parts to upload during multipart uploads. Defaults to 3. Higher values may improve throughput on fast networks but increase memory usage and may overwhelm slower storage backends. | 3 | Maximum: 10 Minimum: 1 Optional: {} |
region string | Region is the AWS region to use for S3-compatible clients. For AWS, this should match the bucket region (for example, “eu-west-1”). For many S3-compatible stores (MinIO/Ceph), this can be any non-empty value. Only used when Provider is “s3”. | us-east-1 | Optional: {} |
roleArn string | RoleARN is the IAM role ARN (or S3-compatible equivalent) to assume via Web Identity. When set, backup and restore Jobs mount a projected ServiceAccount token and set the AWS Web Identity environment variables explicitly. Only used when Provider is “s3”. Outside Hardened S3 targets, leave this empty when relying on ambient workload identity or provider-managed default credentials instead. For Hardened S3 targets, roleArn is one accepted explicit identity path. It does not satisfy Hardened identity requirements for GCS or Azure. | Optional: {} | |
usePathStyle boolean | UsePathStyle controls whether to use path-style addressing (bucket.s3.amazonaws.com/object) or virtual-hosted-style addressing (bucket.s3.amazonaws.com/object). Set to true for MinIO and S3-compatible stores that require path-style. Set to false for AWS S3 (default, as AWS is deprecating path-style). Only used when Provider is “s3”. | false | Optional: {} |
gcs GCSTargetConfig | GCS contains Google Cloud Storage specific configuration. Only used when Provider is “gcs”. | Optional: {} | |
azure AzureTargetConfig | Azure contains Azure Blob Storage specific configuration. Only used when Provider is “azure”. | Optional: {} | |
insecureSkipVerify boolean | InsecureSkipVerify allows skipping TLS verification (useful for MinIO/LocalStack/Azurite with self-signed certs). This applies to all providers that support TLS. Hardened clusters reject insecureSkipVerify. | Optional: {} |
GCSTargetConfig
GCSTargetConfig holds Google Cloud Storage specific configuration.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
project string | Project is the GCP project ID. Optional if using ADC with default project or if the credentials JSON includes the project. | Optional: {} |
OpenBaoRestore
OpenBaoRestore represents a request to restore an OpenBao cluster from a snapshot. This resource is immutable after creation - it acts as a “job request”.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | openbao.org/v1alpha1 | ||
kind string | OpenBaoRestore | ||
spec OpenBaoRestoreSpec | |||
status OpenBaoRestoreStatus |
OpenBaoRestoreSpec
OpenBaoRestoreSpec defines the desired state for a restore operation. An OpenBaoRestore acts as a “job request” - it is immutable after creation.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
cluster string | Cluster is the name of the OpenBaoCluster to restore INTO. Must exist in the same namespace as the OpenBaoRestore. | MinLength: 1 | |
source RestoreSource | Source defines where the snapshot comes from. | ||
jwtAuthRole string | JWTAuthRole is the name of the JWT Auth role configured in OpenBao for restore operations. When set, the restore executor will use JWT Auth (projected ServiceAccount token) instead of a static token. The role must be configured in OpenBao and must grant the “update” capability on sys/storage/raft/snapshot. To support force: true, it must also grant “update” on sys/storage/raft/snapshot-force. The role must bind to the restore ServiceAccount (<cluster-name>-restore-serviceaccount) in the cluster namespace. If this field is empty and the target OpenBaoCluster has OIDC enabled, the operator will default to using the “openbao-operator-restore” role. | Optional: {} | |
tokenSecretRef LocalObjectReference | TokenSecretRef optionally references a Secret containing an OpenBao API token to use for restore operations (fallback method). The Secret must exist in the same namespace as the OpenBaoRestore. Cross-namespace references are not allowed for security reasons. The token must have permission to update sys/storage/raft/snapshot. To support force: true, it must also have permission to update sys/storage/raft/snapshot-force. If JWTAuthRole is set, this field is ignored in favor of JWT Auth. | Optional: {} | |
image string | Image is the container image to use for restore operations. Defaults to the same image used for backup operations if not specified. If the target OpenBaoCluster has image verification enabled, the operator will verify this image and pin the restore Job to the verified digest. | MinLength: 1 Optional: {} | |
force boolean | Force uses OpenBao’s force-restore endpoint. This bypasses verification that the snapshot is compatible with the target cluster’s Shamir or auto-unseal configuration. It also skips the controller checks that require the target cluster to be initialized and not upgrading. Use this break-glass option only when the normal verified restore cannot run and the snapshot source and target seal compatibility have been validated by another trusted process. | false | Optional: {} |
overrideOperationLock boolean | OverrideOperationLock allows the restore controller to clear an active cluster operation lock (upgrade/backup) and proceed with restore. This is a break-glass escape hatch intended for disaster recovery. For safety, this requires force: true. When used, the controller emits a Warning event and records a Condition on the OpenBaoRestore. | false | Optional: {} |
OpenBaoRestoreStatus
OpenBaoRestoreStatus defines the observed state of OpenBaoRestore.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
phase RestorePhase | Phase represents the current phase of the restore operation. | Pending | Enum: [Pending Validating Running Completed Failed Unknown] |
startTime Time | StartTime is when the restore operation started. | Optional: {} | |
completionTime Time | CompletionTime is when the restore operation completed (success or failure). | Optional: {} | |
execution RestoreExecutionStatus | Execution records the stable operation identity and durable lifecycle receipts. | Optional: {} | |
snapshotKey string | SnapshotKey is the key of the snapshot that was restored. | Optional: {} | |
snapshotSize integer | SnapshotSize is the size of the restored snapshot in bytes. | Optional: {} | |
message string | Message provides additional details about the current phase. | Optional: {} | |
conditions Condition array | Conditions represent the latest available observations of the restore’s state. | Optional: {} |
RestoreExecutionResult
Underlying type: string
RestoreExecutionResult is the persisted terminal result of a restore Job.
Validation:
- Enum: [Succeeded Failed]
Appears in:
| Field | Description |
|---|---|
Succeeded | RestoreExecutionResultSucceeded indicates the restore Job succeeded. |
Failed | RestoreExecutionResultFailed indicates the restore Job failed. |
RestoreExecutionStage
Underlying type: string
RestoreExecutionStage identifies the durable execution boundary reached by a restore.
Validation:
- Enum: [Prepared Committed Created TerminalObserved FollowThroughComplete Unknown]
Appears in:
| Field | Description |
|---|---|
Prepared | RestoreExecutionStagePrepared indicates validation and resource preparation completed, but Job creation has not been committed. |
Committed | RestoreExecutionStageCommitted indicates the controller durably committed to one Job creation attempt. A missing Job after this point is ambiguous and is not recreated automatically. |
Created | RestoreExecutionStageCreated indicates the controller persisted the created Job identity. |
TerminalObserved | RestoreExecutionStageTerminalObserved indicates the controller persisted the terminal Job result. |
FollowThroughComplete | RestoreExecutionStageFollowThroughComplete indicates post-restore voter and read-replica recovery completed. |
Unknown | RestoreExecutionStageUnknown indicates the controller cannot prove whether the committed execution ran. |
RestoreExecutionStatus
RestoreExecutionStatus records the identity and durable receipts for one restore execution.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
operationID string | OperationID identifies this immutable restore execution. | ||
stage RestoreExecutionStage | Stage is the latest durable execution boundary observed by the controller. | Enum: [Prepared Committed Created TerminalObserved FollowThroughComplete Unknown] | |
jobName string | JobName is the expected restore Job name for this execution. | ||
jobUID UID | JobUID is the UID returned for the created restore Job. | Optional: {} | |
preparedAt Time | PreparedAt is when validation and execution preparation completed. | Optional: {} | |
committedAt Time | CommittedAt is when the controller committed to one Job creation attempt. | Optional: {} | |
createdAt Time | CreatedAt is when the controller persisted the created Job receipt. | Optional: {} | |
terminalResult RestoreExecutionResult | TerminalResult is the persisted terminal Job result. | Enum: [Succeeded Failed] Optional: {} | |
terminalObservedAt Time | TerminalObservedAt is when the controller persisted the terminal Job result. | Optional: {} | |
followThroughCompletedAt Time | FollowThroughCompletedAt is when post-restore recovery completed. | Optional: {} |
RestorePhase
Underlying type: string
RestorePhase represents the current phase of a restore operation.
Validation:
- Enum: [Pending Validating Running Completed Failed Unknown]
Appears in:
| Field | Description |
|---|---|
Pending | RestorePhasePending indicates the restore has been created but not yet started. |
Validating | RestorePhaseValidating indicates the controller is validating preconditions. |
Running | RestorePhaseRunning indicates the restore job is executing. |
Completed | RestorePhaseCompleted indicates the restore completed successfully. |
Failed | RestorePhaseFailed indicates the restore failed. |
Unknown | RestorePhaseUnknown indicates the controller cannot determine whether the destructive restore operation ran. The controller does not retry an execution in this phase. |
RestoreSource
RestoreSource defines where the snapshot comes from.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
target BackupTarget | Target reuses BackupTarget for storage connection details. This includes endpoint, bucket, region, credentials, etc. | ||
key string | Key is the full path to the snapshot object in the bucket. For example, “clusters/prod/2025-10-14-120000.snap”. | MinLength: 1 |
WorkloadIdentityConfig
WorkloadIdentityConfig configures cloud workload identity metadata for backup and restore workloads.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
serviceAccountAnnotations object (keys:string, values:string) | ServiceAccountAnnotations are merged into the generated backup or restore ServiceAccount. This is typically used for provider-specific bindings such as GKE Workload Identity or webhook-based AWS/Azure workload identity integrations. | Optional: {} | |
podLabels object (keys:string, values:string) | PodLabels are merged into the generated backup or restore Job pod template. This is typically used for provider-specific selectors such as Azure Workload Identity. Operator-managed labels take precedence if the same key is specified here. | Optional: {} |