Packages
openbao.org/v1alpha1
Package v1alpha1 contains API Schema definitions for the openbao v1alpha1 API group.
Resource Types
ACMEConfig
ACMEConfig configures ACME certificate management for OpenBao. See: https://openbao.org/docs/configuration/listener/tcp/#acme-parameters
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
directoryURL string | DirectoryURL is the ACME directory URL (e.g., https://acme-v02.api.letsencrypt.org/directory). | MinLength: 1 | |
domains string array | Domains is the list of domain names for which to obtain the certificate. This maps to OpenBao’s listener tls_acme_domains field.When empty, the operator will default to an internal Service name suitable for private ACME CAs running inside the cluster (e.g., “<cluster>-acme.<namespace>.svc”). | MinItems: 1 Optional: {} | |
email string | Email is the email address to use for ACME registration. | Optional: {} | |
sharedCache ACMESharedCacheConfig | SharedCache configures a filesystem cache shared across OpenBao replicas for ACME account and certificate state. This is required for HA ACME topologies where more than one Pod can serve the same hostname concurrently. | Optional: {} |
ACMESharedCacheConfig
ACMESharedCacheConfig configures the shared filesystem cache for ACME account and certificate state. See: https://openbao.org/docs/configuration/listener/tcp/#acme-parameters
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
mode ACMESharedCacheMode | Mode selects whether the operator creates a dedicated RWX PVC or mounts an existing one. | Enum: [ManagedPVC ExistingPVC] | |
existingClaimName string | ExistingClaimName is the name of a pre-created RWX PVC in the same namespace. Required when Mode is ExistingPVC. | MinLength: 1 Optional: {} | |
size string | Size is the requested capacity for the managed ACME cache PVC. Required when Mode is ManagedPVC. | MinLength: 1 Optional: {} | |
storageClassName string | StorageClassName is an optional StorageClass for the managed ACME cache PVC. | Optional: {} |
ACMESharedCacheMode
Underlying type: string
ACMESharedCacheMode controls how the operator provides a shared filesystem for OpenBao’s ACME cache.
Validation:
- Enum: [ManagedPVC ExistingPVC]
Appears in:
| Field | Description |
|---|---|
ManagedPVC | ACMESharedCacheModeManagedPVC instructs the operator to create a dedicated RWX PVC. |
ExistingPVC | ACMESharedCacheModeExistingPVC instructs the operator to mount an existing RWX PVC. |
AWSKMSSealConfig
AWSKMSSealConfig configures the AWS KMS seal type. See: https://openbao.org/docs/configuration/seal/awskms/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
region string | Region is the AWS region where the encryption key lives. | MinLength: 1 | |
kmsKeyID string | KMSKeyID is the AWS KMS key ID or ARN to use for encryption and decryption. An alias in the format “alias/key-alias-name” may also be used. | MinLength: 1 | |
endpoint string | Endpoint is the KMS API endpoint to be used for AWS KMS requests. Useful when connecting to KMS over a VPC Endpoint. | Optional: {} | |
accessKey string | AccessKey is the AWS access key ID to use. Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity (IRSA) instead. | Optional: {} | |
secretKey string | SecretKey is the AWS secret access key to use. Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity (IRSA) instead. | Optional: {} | |
sessionToken string | SessionToken specifies the AWS session token. | Optional: {} |
AzureKeyVaultSealConfig
AzureKeyVaultSealConfig configures the Azure Key Vault seal type. See: https://openbao.org/docs/configuration/seal/azurekeyvault/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
vaultName string | VaultName is the name of the Azure Key Vault. | MinLength: 1 | |
keyName string | KeyName is the name of the key in the Azure Key Vault. | MinLength: 1 | |
tenantID string | TenantID is the Azure tenant ID. | Optional: {} | |
clientID string | ClientID is the Azure client ID. | Optional: {} | |
clientSecret string | ClientSecret is the Azure client secret. Note: It is strongly recommended to use CredentialsSecretRef or Managed Service Identity instead. | Optional: {} | |
resource string | Resource is the Azure AD resource endpoint. For Managed HSM, this should usually be “managedhsm.azure.net”. | Optional: {} | |
environment string | Environment is the Azure environment (e.g., “AzurePublicCloud”, “AzureUSGovernmentCloud”). | Optional: {} | |
authMethod string | AuthMethod selects how the seal authenticates to Azure, rendered as the seal’s auth_method. When empty, OpenBao chooses: a client ID without a client secret selects managed_identity, which uses the instance metadata service. Set workload_identity for Azure Workload Identity, where the workload identity webhook also injects AZURE_CLIENT_ID. | Enum: [workload_identity managed_identity client_secret environment default] Optional: {} |
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 a compatibility alias for Bucket. A nonempty value takes precedence over Bucket. Use Bucket alone for new configurations. | 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 for every provider. For Azure, a nonempty azure.container compatibility alias takes precedence. | 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 the effective S3 roleArn. 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 the effective 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: {} |
s3 S3TargetConfig | S3 groups S3-specific configuration. Each configured field takes precedence over its top-level compatibility field. Omitted fields use the top-level value. Only used when Provider is “s3”. | 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”. Compatibility field: use s3.region for new configurations. | 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. Compatibility field: use s3.roleArn for new configurations. | Optional: {} | |
usePathStyle boolean | UsePathStyle controls whether to use path-style addressing (s3.amazonaws.com/bucket/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”. Compatibility field: use s3.usePathStyle for new configurations. | 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: {} |
GCPCloudKMSSealConfig
GCPCloudKMSSealConfig configures the GCP Cloud KMS seal type. See: https://openbao.org/docs/configuration/seal/gcpckms/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
project string | Project is the GCP project ID. | MinLength: 1 | |
region string | Region is the GCP region where the key ring lives. | MinLength: 1 | |
keyRing string | KeyRing is the name of the GCP KMS key ring. | MinLength: 1 | |
cryptoKey string | CryptoKey is the name of the GCP KMS crypto key. | MinLength: 1 | |
credentials string | Credentials is the path to the GCP credentials JSON file. Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity instead. | 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: {} |
InitContainerConfig
InitContainerConfig configures the init container used to render OpenBao configuration. The init container is responsible for rendering the final config.hcl from a template using environment variables such as HOSTNAME and POD_IP.
The operator relies on this init container to render config.hcl at runtime. Disabling the init container is not supported and will be rejected by validation.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean | Enabled controls whether the init container is used to render the configuration. The operator requires the init container; disabling it is not supported. | true | Optional: {} |
image string | Image is the container image to use for the init container. If not specified, OPERATOR_INIT_IMAGE can supply a complete image reference, including a digest. Otherwise, defaults to “<repo>:X.Y.Z” where <repo> is derived from OPERATOR_INIT_IMAGE_REPOSITORY (default: “ghcr.io/kubebao/openbao-init”) and the tag matches OPERATOR_VERSION. | Optional: {} |
KMIPSealConfig
KMIPSealConfig configures the KMIP seal type. See: https://openbao.org/docs/configuration/seal/kmip/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
endpoint string | Endpoint is the KMIP server endpoint. | MinLength: 1 | |
kmsKeyID string | KMSKeyID is the unique identifier of the KMIP key to use. | MinLength: 1 | |
clientCert string | ClientCert is the path to the client certificate used for KMIP communication. | MinLength: 1 | |
clientKey string | ClientKey is the path to the private key used for KMIP communication. | MinLength: 1 | |
caCert string | CACert is the path to the CA certificate for KMIP communication. | Optional: {} | |
serverName string | ServerName is the TLS server name to use when connecting to the KMIP endpoint. | Optional: {} | |
timeout integer | Timeout is the timeout in seconds for KMIP requests. | Minimum: 1 Optional: {} | |
encryptAlg string | EncryptAlg is the encryption algorithm used for KMIP requests. | Enum: [AES_GCM RSA_OAEP_SHA256 RSA_OAEP_SHA384 RSA_OAEP_SHA512] Optional: {} | |
tls12Ciphers string | TLS12Ciphers configures the TLS 1.2 cipher suites to use when connecting to the KMIP endpoint. | Optional: {} | |
disabled boolean | Disabled disables this seal configuration, for example during seal migration. | Optional: {} |
KMSPluginSealConfig
KMSPluginSealConfig configures a plugin-backed KMS seal. The referenced plugin must be declared in spec.plugins with type “kms”.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
pluginName string | PluginName is the name of the plugin registered through a matching plugin “kms” stanza. OpenBao uses this value as the seal stanza label. | MinLength: 1 | |
config object (keys:string, values:string) | Config contains plugin-specific seal configuration rendered as string attributes inside seal “<pluginName>”. Keys must be valid HCL identifiers. Values are stored in the OpenBaoCluster resource; use file paths to credentialsSecretRef-mounted files for sensitive material instead of inline secrets. | MaxProperties: 64 Optional: {} |
OCIKMSSealConfig
OCIKMSSealConfig configures the OCI KMS seal type. See: https://openbao.org/docs/configuration/seal/ocikms/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
keyID string | KeyID is the OCID of the master encryption key. | MinLength: 1 | |
cryptoEndpoint string | CryptoEndpoint is the OCI KMS crypto endpoint. | MinLength: 1 | |
managementEndpoint string | ManagementEndpoint is the OCI KMS management endpoint. | MinLength: 1 | |
authTypeAPIKey boolean | AuthTypeAPIKey enables OCI API key authentication through an OCI SDK config file. When false or omitted, OpenBao uses the default OCI principal flow for the runtime environment, such as instance principal. | Optional: {} | |
disabled boolean | Disabled disables this seal configuration, for example during seal migration. | 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 |
|---|---|---|---|
cleanupAfterSeconds integer | CleanupAfterSeconds delays disposable target cleanup after snapshot application is confirmed. | Maximum: 86400 Minimum: 0 Optional: {} | |
clusterTemplate RestoreClusterTemplate | ClusterTemplate creates a new single-voter target. Existing targets are rejected. | Optional: {} | |
targetLifecycle RestoreTargetLifecycle | TargetLifecycle retains recovery targets or deletes disposable test resources. | Enum: [Retain Disposable] Optional: {} | |
cluster string | Cluster is the name of the OpenBaoCluster to restore INTO. Must be in the request namespace. ClusterTemplate requires a new name. | MinLength: 1 | |
source RestoreSource | Source defines where the snapshot comes from. | ||
serviceAccountName string | ServiceAccountName selects an existing executor ServiceAccount in this namespace. The operator does not create, modify, or delete this account. When omitted, it creates <cluster-name>-restore-serviceaccount. JWT authentication must authorize the selected account. Fresh targets add its subject to their generated restore role before snapshot submission. | MaxLength: 253 Pattern: ^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$Optional: {} | |
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 selected by serviceAccountName, or <cluster-name>-restore-serviceaccount when serviceAccountName is omitted, 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 |
|---|---|---|---|
target RestoreTargetStatus | Target binds the fresh cluster and storage to this request. | Optional: {} | |
submissionClaim RestoreSubmissionClaim | SubmissionClaim reserves the only permitted snapshot submission. | Optional: {} | |
restart RestoreRestartStatus | Restart records managed workload recovery after administrator Resume. | Optional: {} | |
administratorDisposition RestoreAdministratorDisposition | AdministratorDisposition records an operation-bound recovery acknowledgement. | Enum: [Resume Abandon] Optional: {} | |
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: {} |
PKCS11RuntimeConfig
PKCS11RuntimeConfig configures local runtime wiring needed by PKCS#11 vendor libraries. It is intentionally scoped to environment variables and library lookup paths so HSM integrations do not require custom wrapper scripts.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
libraryPath string | LibraryPath sets LD_LIBRARY_PATH for the OpenBao process. Use this when the configured PKCS#11 module depends on sibling vendor libraries that are not in the image’s default dynamic linker search path. | Optional: {} | |
env PKCS11RuntimeEnvVar array | Env exposes literal environment variables from keys in spec.unseal.credentialsSecretRef. Use this for vendor runtime settings such as HSM endpoints or authentication key references. | MaxItems: 16 Optional: {} | |
fileEnv PKCS11RuntimeFileEnvVar array | FileEnv exposes environment variables whose values are paths to files mounted from keys in spec.unseal.credentialsSecretRef. Use this for vendor settings that expect a config file path, for example SOFTHSM2_CONF or vendor-specific PKCS#11 client configuration variables. | MaxItems: 16 Optional: {} |
PKCS11RuntimeEnvVar
Underlying type: struct{Name string "json:\"name\""; SecretKey string "json:\"secretKey\""}
PKCS11RuntimeEnvVar maps a PKCS#11 runtime environment variable to a key in spec.unseal.credentialsSecretRef.
Appears in:
PKCS11RuntimeFileEnvVar
Underlying type: struct{Name string "json:\"name\""; SecretKey string "json:\"secretKey\""}
PKCS11RuntimeFileEnvVar maps a PKCS#11 runtime environment variable to the mounted file path for a key in spec.unseal.credentialsSecretRef.
Appears in:
PKCS11SealConfig
PKCS11SealConfig configures the PKCS#11 seal type. See: https://openbao.org/docs/configuration/seal/pkcs11/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
lib string | Lib is the path to the PKCS#11 library provided by the HSM vendor. | MinLength: 1 | |
slot string | Slot is the slot number where the HSM token is located. | Optional: {} | |
tokenLabel string | TokenLabel is the token label of the HSM slot to use instead of Slot. | Optional: {} | |
pin string | PIN is the PIN for accessing the HSM token. Note: It is strongly recommended to use CredentialsSecretRef instead of setting this directly. | Optional: {} | |
keyLabel string | KeyLabel is the label for the encryption key used by OpenBao. | MinLength: 1 | |
keyID string | KeyID is the PKCS#11 key identifier to use instead of KeyLabel. | Optional: {} | |
mechanism string | Mechanism overrides the PKCS#11 wrapping or encryption mechanism. | Optional: {} | |
disableSoftwareEncryption boolean | DisableSoftwareEncryption disables the software encryption fallback. | Optional: {} | |
disabled boolean | Disabled disables this seal configuration, for example during seal migration. | Optional: {} | |
rsaOAEPHash string | RSAOAEPHash specifies the hash algorithm to use for RSA with OAEP padding. Valid values: sha1, sha224, sha256, sha384, sha512. | Enum: [sha1 sha224 sha256 sha384 sha512] Optional: {} | |
runtime PKCS11RuntimeConfig | Runtime configures local PKCS#11 vendor runtime wiring such as library lookup paths and environment variables sourced from credentialsSecretRef. | Optional: {} |
Plugin
Plugin defines a declarative plugin configuration. Declarative plugins require OpenBao 2.5.0 or newer; KMS plugins require 2.6.0 or newer. During upgrades, declarations must also meet the recorded running version’s requirements. See: https://openbao.org/docs/configuration/plugins/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type string | Type is the plugin type (e.g., “secret”, “auth”). | MinLength: 1 | |
name string | Name is the name of the plugin. | MinLength: 1 | |
image string | Image is the OCI image URL including registry and repository. Before OpenBao 2.7.0, use an untagged repository and set Version separately. Required if Command is not set. Conflicts with Command. | Optional: {} | |
command string | Command is the command name of a manually downloaded plugin. Required if Image is not set. Conflicts with Image. | Optional: {} | |
version string | Version is the plugin version and, when Image has no tag, the image tag. OpenBao 2.7 and later can infer it from the image tag. Command-based KMS plugins on OpenBao 2.7 and later do not require a version. | MinLength: 1 Optional: {} | |
binaryName string | BinaryName is the name of the plugin binary file within the OCI image. OpenBao 2.7 and later can infer it from the image ENTRYPOINT or CMD. | MinLength: 1 Optional: {} | |
sha256sum string | SHA256Sum is the expected SHA256 checksum of the plugin binary. Must be a 64-character hexadecimal string. OpenBao 2.7 and later allow omission for digest-pinned OCI images and command-based plugins. Earlier versions require this field. | MaxLength: 64 MinLength: 64 Pattern: ^[0-9a-fA-F]\{64\}$Optional: {} | |
args string array | Args are arguments to pass to the running plugin. Only used if plugin_auto_register=true is set. | Optional: {} | |
env string array | Env are environment variables to pass to the running plugin. Only used if plugin_auto_register=true is set. | Optional: {} |
PluginConfig
PluginConfig allows configuring plugin behavior.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
fileUID integer | FileUID is the UID to use for plugin files. | Optional: {} | |
filePermissions string | FilePermissions are the file permissions for plugin files (e.g., “0755”). | Optional: {} | |
autoDownload boolean | AutoDownload controls automatic plugin downloads from OCI registries. | Optional: {} | |
autoRegister boolean | AutoRegister controls automatic plugin registration. | Optional: {} | |
downloadBehavior string | DownloadBehavior controls whether OpenBao startup fails or continues when declarative OCI plugin downloads fail. Valid values are “fail” and “continue”; OpenBao defaults to “fail” when unset. | Enum: [fail continue] Optional: {} |
PodMetadataConfig
PodMetadataConfig configures additional metadata for the OpenBao Pod template.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
labels object (keys:string, values:string) | Labels are merged into the generated OpenBao Pod template labels. Operator-managed labels take precedence if the same key is specified here. | Optional: {} | |
annotations object (keys:string, values:string) | Annotations are merged into the generated OpenBao Pod template annotations. Operator-managed annotations take precedence if the same key is specified here. | Optional: {} |
RestoreAdministratorDisposition
Underlying type: string
RestoreAdministratorDisposition records the administrator’s recovery decision.
Appears in:
| Field | Description |
|---|---|
Resume | |
Abandon |
RestoreClusterTemplate
RestoreClusterTemplate is the supported fresh recovery target profile. Administrators must prepare the destination namespace network boundary.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
version string | Version must match the administrator-observed snapshot source version. | Enum: [2.7.0 2.7.1] | |
image string | Image defaults to the version-derived image. | Optional: {} | |
storage StorageConfig | |||
tls TLSConfig | |||
service RestoreTargetServiceConfig | Service configures an optional ClusterIP Service for the destination. When omitted, the target has only its internal headless Service. | Optional: {} | |
unseal UnsealConfig | Unseal uses the same provider configuration as OpenBaoCluster. The target must be able to decrypt the snapshot with the original seal key material. | ||
serviceAccount ServiceAccountConfig | ServiceAccount configures credentials supplied through workload identity. | Optional: {} | |
podMetadata PodMetadataConfig | PodMetadata supplies provider-specific workload identity metadata. | Optional: {} | |
plugins Plugin array | Plugins declares KMS seal plugins required by Unseal. OpenBao 2.7 requires plugins for AWS, Azure, GCP, OCI, and PKCS#11 seals. | Optional: {} | |
configuration RestoreTargetConfiguration | Configuration configures KMS plugin behavior for the target server. | Optional: {} | |
resources ResourceRequirements | Optional: {} | ||
initContainer InitContainerConfig | Optional: {} | ||
imagePullSecrets LocalObjectReference array | MaxItems: 2 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 |
|---|---|---|---|
targetUID UID | TargetUID prevents a replacement cluster from inheriting this execution. | Optional: {} | |
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. |
RestoreRestartPod
RestoreRestartPod binds a managed restart to an original Pod and its StatefulSet.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name is the original Pod name. | ||
uid UID | UID identifies the original Pod; a different UID marks a replacement. | ||
statefulSetUID UID | StatefulSetUID identifies the StatefulSet that owned the original Pod. |
RestoreRestartStatus
RestoreRestartStatus records Resume before restarting workloads. Replacement Pod UIDs provide retry evidence; this status does not prove snapshot application.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
pods RestoreRestartPod array | Pods contains the original voters and read replicas. | MinItems: 1 | |
completedAt Time | CompletedAt records that all bound Pods were replaced and became ready. | Optional: {} |
RestoreSource
RestoreSource defines where the snapshot comes from.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
expectedClusterID string | ExpectedClusterID is the native ID observed on the snapshot source. Required for a fresh target; supplied metadata is an administrator assertion. | MaxLength: 128 Optional: {} | |
expectedVersion string | ExpectedVersion is the source version observed when taking the snapshot. | MaxLength: 64 Optional: {} | |
expectedDigest string | ExpectedDigest pins the staged bytes before submission. | Pattern: ^sha256:[a-f0-9]\{64\}$Optional: {} | |
expectedSize integer | Maximum: 8.589934592e+09 Minimum: 1 Optional: {} | ||
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 |
RestoreSubmissionClaim
RestoreSubmissionClaim is a one-way submission reservation. A persisted claim never authorizes a restarted executor to submit again.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
podUID UID | PodUID identifies the executor Pod that won the claim. | ||
targetPodName string | TargetPodName is the OpenBao Pod that received the snapshot. | ||
targetPodUID UID | TargetPodUID identifies the OpenBao Pod that received the snapshot. | ||
targetPodIP string | TargetPodIP is the address the executor connected to. | ||
targetContainerID string | TargetContainerID identifies the OpenBao container that received the snapshot. | ||
digest string | Digest is sha256: followed by the lowercase digest of the staged snapshot bytes. | Pattern: ^sha256:[a-f0-9]\{64\}$ | |
size integer | Size is the staged snapshot size in bytes. | Maximum: 8.589934592e+09 Minimum: 1 | |
claimedAt Time | ClaimedAt records when submission was reserved. |
RestoreTargetCleanup
Underlying type: string
RestoreTargetCleanup describes deletion of a disposable target’s resources.
Appears in:
| Field | Description |
|---|---|
Pending | |
Complete | |
Failed |
RestoreTargetConfiguration
RestoreTargetConfiguration exposes server settings needed by KMS seal plugins.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
plugin PluginConfig | Plugin controls downloads, registration, and file ownership for Plugins. Set autoDownload to true to download declared OCI plugins on startup. | Optional: {} |
RestoreTargetLifecycle
Underlying type: string
RestoreTargetLifecycle determines whether a fresh target is retained or deleted.
Appears in:
| Field | Description |
|---|---|
Retain | |
Disposable |
RestoreTargetServiceConfig
RestoreTargetServiceConfig selects destination client Service IP families. These settings do not change Pod IP allocation or the internal peer Service.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
ipFamilyPolicy IPFamilyPolicy | IPFamilyPolicy selects single-stack or dual-stack Service allocation. When omitted, Kubernetes uses its default Service policy. Two IP families require PreferDualStack or RequireDualStack. | Enum: [SingleStack PreferDualStack RequireDualStack] Optional: {} | |
ipFamilies IPFamily array | IPFamilies selects the Service IP families in primary-first order. The primary family cannot change after the Service is created. | MaxItems: 2 items:Enum: [IPv4 IPv6] Optional: {} |
RestoreTargetStatus
RestoreTargetStatus records the single creation attempt and original identities. Cleanup reports Kubernetes object deletion, never physical process fencing.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
reservedAt Time | ReservedAt records the single target creation attempt. | ||
uid UID | UID identifies the target OpenBaoCluster created for this request. | Optional: {} | |
dataPVCUID UID | DataPVCUID identifies the target’s original data PersistentVolumeClaim. | Optional: {} | |
bootstrapClusterID string | BootstrapClusterID is the native cluster ID of the empty target before restore. | Optional: {} | |
appliedAt Time | AppliedAt records when the target reported the expected source identity. | Optional: {} | |
cleanup RestoreTargetCleanup | Cleanup is Pending, Complete, or Failed. A failed ownership check preserves the refused resource; cleanup can still delete the original bound cluster. | Enum: [Pending Complete Failed] Optional: {} |
S3TargetConfig
S3TargetConfig holds S3-specific configuration. Omitted fields use their top-level BackupTarget compatibility values; this block has no defaults.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
region string | Region is the AWS region for S3-compatible requests. It overrides region when configured. An empty value uses the default region, us-east-1. | Optional: {} | |
usePathStyle boolean | UsePathStyle selects path-style addressing. A configured false value overrides a true top-level usePathStyle value. | Optional: {} | |
roleArn string | RoleARN selects the IAM role assumed with the projected ServiceAccount token. It overrides roleArn when configured. An empty value disables the top-level roleArn path; other configured credentials still apply. A nonempty value is an explicit storage identity for the Hardened profile. | Optional: {} |
ServiceAccountConfig
ServiceAccountConfig configures the ServiceAccount used by OpenBao pods.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name overrides the generated ServiceAccount name. If not specified, defaults to “<cluster-name>-serviceaccount”. | Optional: {} | |
annotations object (keys:string, values:string) | Annotations to add to the ServiceAccount. Useful for cloud provider Workload Identity (e.g. eks.amazonaws.com/role-arn). | Optional: {} |
StaticSealConfig
StaticSealConfig configures the static seal type. This is the default seal type managed by the operator. See: https://openbao.org/docs/configuration/seal/static/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
currentKey string | CurrentKey is the path to the static unseal key file. Defaults to “file:///etc/bao/unseal/key” (operator-managed). | Optional: {} | |
currentKeyID string | CurrentKeyID is the identifier for the current unseal key. Defaults to “operator-generated-v1” (operator-managed). | Optional: {} |
StorageConfig
StorageConfig captures storage-related configuration for the StatefulSet.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
size string | Size is the requested persistent volume size, for example “10Gi”. | MinLength: 1 | |
storageClassName string | StorageClassName is an optional StorageClass for the PVCs. | Optional: {} |
TLSConfig
TLSConfig captures TLS configuration for an OpenBaoCluster.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean | Enabled controls whether TLS is enabled for the cluster. | Required: {} | |
mode TLSMode | Mode controls who manages the certificate lifecycle. | OperatorManaged | Enum: [OperatorManaged External ACME] Optional: {} |
acme ACMEConfig | ACME configures settings when Mode is ‘ACME’. | Optional: {} | |
rotationPeriod string | RotationPeriod is a duration string (for example, “720h”) controlling certificate rotation. Only used when Mode is OperatorManaged. | MinLength: 1 Optional: {} | |
extraSANs string array | ExtraSANs lists additional subject alternative names for server certificates. In OperatorManaged mode, the operator includes these names when issuing the certificate. In External mode, the operator requires the supplied certificate to contain them. Values that parse as IP addresses are treated as IP SANs; all other values are DNS SANs. | Optional: {} |
TLSMode
Underlying type: string
TLSMode controls who manages the certificate lifecycle.
Validation:
- Enum: [OperatorManaged External ACME]
Appears in:
| Field | Description |
|---|---|
OperatorManaged | TLSModeOperatorManaged: The operator acts as the CA, generating keys and rotating certs (Current Behavior). |
External | TLSModeExternal: The operator assumes Secrets are managed by an external entity (cert-manager, user, or CSI driver). The operator will mount them but NOT modify/rotate them. |
ACME | TLSModeACME: OpenBao uses its native ACME client to fetch certificates. No Secrets are mounted. No sidecar is injected. Best for Zero Trust. |
TransitSealConfig
TransitSealConfig configures the Transit seal type. See: https://openbao.org/docs/configuration/seal/transit/
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
address string | Address is the full HTTPS address to the OpenBao cluster providing the Transit seal. | MinLength: 1 | |
token string | Token is the OpenBao token to use for authentication. Note: It is strongly recommended to use CredentialsSecretRef instead of setting this directly. | Optional: {} | |
keyName string | KeyName is the transit key to use for encryption and decryption. | MinLength: 1 | |
mountPath string | MountPath is the mount path to the transit secret engine. | MinLength: 1 | |
namespace string | Namespace is the namespace path to the transit secret engine. | Optional: {} | |
disableRenewal boolean | DisableRenewal disables automatic token renewal. Set to true if token lifecycle is managed externally (e.g., by OpenBao Agent). | Optional: {} | |
tlsCACert string | TLSCACert is the path to the CA certificate file for TLS communication. | Optional: {} | |
tlsClientCert string | TLSClientCert is the path to the client certificate for TLS communication. | Optional: {} | |
tlsClientKey string | TLSClientKey is the path to the private key for TLS communication. | Optional: {} | |
tlsServerName string | TLSServerName is the SNI host name to use when connecting via TLS. | Optional: {} | |
tlsSkipVerify boolean | TLSSkipVerify disables verification of TLS certificates. Using this option is highly discouraged and decreases security. | Optional: {} |
UnsealConfig
UnsealConfig defines the auto-unseal configuration for an OpenBaoCluster. If omitted, defaults to “static” mode managed by the operator.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
type string | Type specifies the seal type. Defaults to “static”. | static | Enum: [static awskms gcpckms azurekeyvault transit kmip kms ocikms pkcs11] |
static StaticSealConfig | Static configures the static seal type. Optional when Type is “static” (operator provides defaults if omitted). | Optional: {} | |
transit TransitSealConfig | Transit configures the Transit seal type. Required when Type is “transit”. | Optional: {} | |
awskms AWSKMSSealConfig | AWSKMS configures the AWS KMS seal type. Required when Type is “awskms”. | Optional: {} | |
azureKeyVault AzureKeyVaultSealConfig | AzureKeyVault configures the Azure Key Vault seal type. Required when Type is “azurekeyvault”. | Optional: {} | |
gcpCloudKMS GCPCloudKMSSealConfig | GCPCloudKMS configures the GCP Cloud KMS seal type. Required when Type is “gcpckms”. | Optional: {} | |
kmip KMIPSealConfig | KMIP configures the KMIP seal type. Required when Type is “kmip”. | Optional: {} | |
kms KMSPluginSealConfig | KMS configures a plugin-backed KMS seal. Required when Type is “kms”. | Optional: {} | |
ocikms OCIKMSSealConfig | OCIKMS configures the OCI KMS seal type. Required when Type is “ocikms”. | Optional: {} | |
pkcs11 PKCS11SealConfig | PKCS11 configures the PKCS#11 seal type. Required when Type is “pkcs11”. | Optional: {} | |
credentialsSecretRef LocalObjectReference | CredentialsSecretRef references a Secret containing provider credentials (for example AWS access keys, GCP credentials.json, Azure client-secret keys, OCI SDK config for authTypeAPIKey mode, or plugin-backed KMS runtime files). If using Workload Identity (IRSA, GKE WI, Azure MSI), this can be omitted. For static unseal, the Secret supplies the original key instead of an operator-generated key. Its files are mounted at /etc/bao/unseal; the default currentKey reads its “key” entry. The operator does not create, modify, or take ownership of this Secret. A cluster that already owns an operator-generated unseal key keeps that key and ignores this reference. The Secret must exist in the same namespace as the OpenBaoCluster. Cross-namespace references are not allowed for security reasons. | Optional: {} |
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. An existing restore executor ServiceAccount must already have these annotations; the operator validates them without modifying that account. 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: {} |