Skip to content

api.md

Latest commit

 

History

History
2232 lines (1289 loc) · 133 KB

api.md

File metadata and controls

2232 lines (1289 loc) · 133 KB
title API Reference
description Generated API reference for OpenBao Operator CRDs from api/v1alpha1.
pageType reference
journey reference

<PageHero variant="minimal" eyebrow="Reference / API Surface" title="Use the API reference when you need the exact CRD field contract." lede="This page is generated from api/v1alpha1 and is the source of truth for field-level schema, validation, and description details across the operator CRDs." actions={[ {label: 'Open compatibility matrix', docId: 'reference/compatibility', variant: 'primary'}, {label: 'Open status and events', docId: 'reference/status-and-events', variant: 'secondary'}, ]} />

This page is generated from api/v1alpha1 by make api-reference. Do not edit this file manually.

CRDs

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
domain string Domain is the domain name for which to obtain the certificate.
Deprecated: use Domains to request a certificate with multiple SANs.		 MinLength: 1
Optional: {}
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: {}

AdminOpsControllerStatus

AdminOpsControllerStatus holds status owned by the adminops controller.

Appears in:

Field Description Default Validation
lastError ControllerErrorStatus LastError is the last adminops-controller error observed for this cluster. Optional: {}

AuditDevice

AuditDevice defines a declarative audit device configuration. See: https://openbao.org/docs/configuration/audit/

Appears in:

Field Description Default Validation
type string Type is the type of audit device (e.g., "file", "syslog", "socket", "http"). Enum: [file syslog socket http]
MinLength: 1
path string Path is the path of the audit device in the root namespace. MinLength: 1
description string Description is an optional description for the audit device. Optional: {}
fileOptions FileAuditOptions FileOptions configures options for file audit devices.
Only used when Type is "file".		 Optional: {}
httpOptions HTTPAuditOptions HTTPOptions configures options for HTTP audit devices.
Only used when Type is "http".		 Optional: {}
syslogOptions SyslogAuditOptions SyslogOptions configures options for syslog audit devices.
Only used when Type is "syslog".		 Optional: {}
socketOptions SocketAuditOptions SocketOptions configures options for socket audit devices.
Only used when Type is "socket".		 Optional: {}
options JSON Options contains device-specific configuration options as a map.
This is a fallback for backward compatibility and advanced use cases.
If structured options (FileOptions, HTTPOptions, etc.) are provided, they take precedence.
The structure depends on the audit device type.		 Optional: {}

AutoRollbackConfig

AutoRollbackConfig defines conditions that trigger automatic rollback.

Appears in:

Field Description Default Validation
enabled boolean Enabled controls whether automatic rollback is active. true
onJobFailure boolean OnJobFailure triggers rollback when job failures exceed MaxJobFailures.
Only applies during early phases (before demoting Blue).		 true
onValidationFailure boolean OnValidationFailure triggers automatic abort/rollback if the pre-promotion
hook fails.		 true

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: {}

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: {}

BackendTLSConfig

BackendTLSConfig configures BackendTLSPolicy for Gateway API.

Appears in:

Field Description Default Validation
enabled boolean Enabled controls whether the Operator creates a BackendTLSPolicy.
When true (default when Gateway is enabled), the Operator creates a BackendTLSPolicy
that enables HTTPS and certificate validation for backend connections.
When false, no BackendTLSPolicy is created and the Gateway will use HTTP (or rely on
external configuration for TLS).		 true Optional: {}
hostname string Hostname is the hostname to verify in the backend certificate.
If not specified, defaults to the Service DNS name: <service-name>.<namespace>.svc
This should match the certificate SAN or the service DNS name.		 Optional: {}

BackupRetention

BackupRetention defines retention policy for backups.

Appears in:

Field Description Default Validation
maxCount integer MaxCount is the maximum number of backups to retain (0 = unlimited). Minimum: 0
Optional: {}
maxAge string MaxAge is the maximum age of backups to retain, e.g., "168h" for 7 days.
Backups older than this are deleted after successful new backup upload.		 Optional: {}

BackupSchedule

BackupSchedule defines when and where snapshots are stored.

Appears in:

Field Description Default Validation
schedule string Schedule is a cron-style schedule, for example "0 3 * * *". MinLength: 1
target BackupTarget Target is the object storage configuration for backups.
jwtAuthRole string JWTAuthRole is the name of the JWT Auth role configured in OpenBao
for backup operations. When set, the backup executor will use JWT Auth
(projected ServiceAccount token) instead of a static token. This is the preferred authentication
method as tokens are automatically rotated by Kubernetes.
The role must be configured in OpenBao and must grant the "read" capability on
sys/storage/raft/snapshot. The role must bind to the backup ServiceAccount
(<cluster-name>-backup-serviceaccount) in the cluster namespace.
If OIDC is enabled in SelfInit and this field is empty, a default role
named "openbao-operator-backup" will be assumed/created.		 Optional: {}
tokenSecretRef LocalObjectReference TokenSecretRef optionally references a Secret containing an OpenBao API
token to use for backup operations (fallback method).
The Secret must exist in the same namespace as the OpenBaoCluster.
Cross-namespace references are not allowed for security reasons.
For standard clusters (non self-init), this is typically omitted and the
operator uses the root token from <cluster>-root-token. For self-init
clusters (no root token Secret), this field must reference a token with
permission to read sys/storage/raft/snapshot.
If JWTAuthRole is set, this field is ignored in favor of JWT Auth.		 Optional: {}
retention BackupRetention Retention defines optional backup retention policy. Optional: {}
image string Image is the container image to use for backup operations.
If not specified, defaults to "<repo>:X.Y.Z" where <repo> is derived from OPERATOR_BACKUP_IMAGE_REPOSITORY
(default: "ghcr.io/dc-tec/openbao-backup") and the tag matches OPERATOR_VERSION.
This allows users to override the image for air-gapped environments or custom registries.		 Optional: {}

BackupStatus

BackupStatus tracks the state of backups for a cluster.

Appears in:

Field Description Default Validation
lastBackupTime Time LastBackupTime is the timestamp of the last successful backup. Optional: {}
lastAttemptTime Time LastAttemptTime is the timestamp of the last backup attempt, regardless of outcome.
This is used to avoid retry loops when a scheduled backup fails.		 Optional: {}
lastAttemptScheduledTime Time LastAttemptScheduledTime is the scheduled time of the last backup attempt.
It is derived from the cron schedule and used to ensure at-most-once execution
per scheduled window.		 Optional: {}
lastBackupSize integer LastBackupSize is the size in bytes of the last successful backup. Optional: {}
lastBackupDuration string LastBackupDuration is how long the last backup took (e.g., "45s"). Optional: {}
lastBackupName string LastBackupName is the object key/path of the last successful backup. Optional: {}
nextScheduledBackup Time NextScheduledBackup is when the next backup is scheduled. Optional: {}
consecutiveFailures integer ConsecutiveFailures is the number of consecutive backup failures. Optional: {}
lastFailureReason string LastFailureReason is the low-cardinality reason code for the last backup failure (if applicable). Optional: {}
lastFailureMessage string LastFailureMessage is the detailed message for the last backup failure (if applicable). 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".
Omit this field when relying on ambient workload identity or another default credential chain.		 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.		 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.
Leave this empty when relying on ambient workload identity or provider-managed default credentials instead.
Only used when Provider is "s3".		 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.		 Optional: {}

BlueGreenConfig

BlueGreenConfig configures the behavior when Type is BlueGreen.

Appears in:

Field Description Default Validation
autoPromote boolean AutoPromote controls whether newly started blue/green upgrades
automatically switch traffic and delete the old cluster after sync.
If false when an upgrade starts, that upgrade stays in the Syncing
phase waiting for an explicit promotion request via spec.upgrade.requests.promote.
Changing this field while an upgrade is already in progress affects only
future upgrades.		 true
verification VerificationConfig VerificationConfig allows defining custom health checks before promotion. Optional: {}
maxJobFailures integer MaxJobFailures is the maximum consecutive job failures before aborting/rolling back.
Defaults to 5 if not specified.		 5 Minimum: 1
Optional: {}
preUpgradeSnapshot boolean PreUpgradeSnapshot triggers a backup at the start of an upgrade.
Creates a recovery point before any changes are made.
Requires spec.backup to be configured.		 Optional: {}
autoRollback AutoRollbackConfig AutoRollback configures automatic rollback behavior. Optional: {}

BlueGreenPhase

Underlying type: string

BlueGreenPhase is a high-level summary of blue/green upgrade state.

Validation:

  • Enum: [Idle DeployingGreen JoiningMesh Syncing Promoting DemotingBlue Cleanup RestoringReadReplicas RollingBack RollbackCleanup]

Appears in:

Field Description
Idle PhaseIdle indicates no blue/green upgrade is in progress.
DeployingGreen PhaseDeployingGreen indicates the Green StatefulSet is being created and pods are becoming ready.
This phase includes waiting for pods to be unsealed.
JoiningMesh PhaseJoiningMesh indicates Green pods are joining the Raft cluster as non-voters.
Syncing PhaseSyncing indicates waiting for Green nodes to catch up with Blue nodes.
Promoting PhasePromoting indicates Green nodes are being promoted to voters.
DemotingBlue PhaseDemotingBlue indicates Blue nodes are being demoted to non-voters.
Cleanup PhaseCleanup indicates Blue StatefulSet is being deleted.
RestoringReadReplicas PhaseRestoringReadReplicas indicates the steady-state read-replica pool is
being restored after cutover cleanup and must converge before the upgrade
returns to Idle.
RollingBack PhaseRollingBack indicates the upgrade is being rolled back.
Blue nodes are re-promoted and Green nodes are demoted.
RollbackCleanup PhaseRollbackCleanup indicates Green StatefulSet is being deleted after rollback.

BlueGreenStatus

BlueGreenStatus tracks the lifecycle of the "Green" revision during blue/green upgrades.

Appears in:

Field Description Default Validation
phase BlueGreenPhase Phase is the current phase of the blue/green upgrade. Enum: [Idle DeployingGreen JoiningMesh Syncing Promoting DemotingBlue Cleanup RestoringReadReplicas RollingBack RollbackCleanup]
blueRevision string BlueRevision is the hash/name of the currently active cluster.
blueImage string BlueImage is the container image used by the Blue cluster.
This ensures the Blue cluster is not actively upgraded when spec.image changes.
greenRevision string GreenRevision is the hash/name of the next cluster (if upgrade in progress).
manualPromotionRequired boolean ManualPromotionRequired snapshots whether the current in-flight blue/green
upgrade requires an explicit spec.upgrade.requests.promote request before
promotion can proceed. It is derived from spec.upgrade.blueGreen.autoPromote
when the upgrade starts.		 Optional: {}
startTime Time StartTime is when the current phase began.
jobFailureCount integer JobFailureCount tracks consecutive job failures in the current phase.
Reset to 0 on phase transition or successful job completion.		 Optional: {}
lastJobFailure string LastJobFailure records the name of the last failed job for debugging. Optional: {}
preUpgradeSnapshotJobName string PreUpgradeSnapshotJobName is the name of the backup job triggered at upgrade start. Optional: {}
rollbackReason string RollbackReason records why a rollback was triggered (if any). Optional: {}
rollbackStartTime Time RollbackStartTime is when the rollback was initiated. Optional: {}
rollbackAttempt integer RollbackAttempt increments each time rollback automation is retried.
It is used to produce stable, deterministic Job names per attempt.		 Optional: {}

BreakGlassReason

Underlying type: string

BreakGlassReason describes why the operator required manual intervention.

Validation:

  • Enum: [RollbackConsensusRepairFailed RollbackCleanupPeerRemovalFailed]

Appears in:

Field Description
RollbackConsensusRepairFailed
RollbackCleanupPeerRemovalFailed

BreakGlassStatus

BreakGlassStatus captures safe-mode / break-glass state and recovery guidance.

Appears in:

Field Description Default Validation
active boolean Active indicates whether break glass mode is currently active. Optional: {}
reason BreakGlassReason Reason is a stable, typed reason for entering break glass mode. Enum: [RollbackConsensusRepairFailed RollbackCleanupPeerRemovalFailed]
Optional: {}
message string Message provides a short summary of the detected unsafe state. Optional: {}
nonce string Nonce is the acknowledgment token required to resume automation. Optional: {}
enteredAt Time EnteredAt is when break glass mode became active. Optional: {}
steps string array Steps provides deterministic recovery guidance. Optional: {}
acknowledgedAt Time AcknowledgedAt records when break glass was acknowledged. Optional: {}

ClusterOperation

Underlying type: string

ClusterOperation identifies a mutually-exclusive operator operation.

Validation:

  • Enum: [Upgrade Backup Restore]

Appears in:

Field Description
Upgrade
Backup
Restore

ClusterPhase

Underlying type: string

ClusterPhase is a high-level summary of cluster state.

Validation:

  • Enum: [Initializing Running Upgrading BackingUp Failed]

Appears in:

Field Description
Initializing
Running
Upgrading
BackingUp
Failed

ControllerErrorStatus

ControllerErrorStatus captures a controller-scoped error signal that the status controller can translate into high-level conditions.

Appears in:

Field Description Default Validation
reason string Reason is a low-cardinality identifier for the error. Optional: {}
message string Message is a human-readable error message (best-effort). Optional: {}
at Time At is when the error was observed (best-effort). Optional: {}

DeletionPolicy

Underlying type: string

DeletionPolicy defines what happens to underlying resources when the CR is deleted.

Validation:

  • Enum: [Retain DeletePVCs DeleteAll]

Appears in:

Field Description
Retain DeletionPolicyRetain keeps StatefulSets, PVCs, and external backups.
DeletePVCs DeletionPolicyDeletePVCs deletes StatefulSets and PVCs, but retains external backups.
DeleteAll DeletionPolicyDeleteAll deletes StatefulSets, PVCs, and attempts to delete external backups.

FileAuditOptions

FileAuditOptions configures options for file audit devices. See: https://openbao.org/docs/audit/file/

Appears in:

Field Description Default Validation
filePath string FilePath is the path to where the audit log will be written.
Special keywords: "stdout" writes to standard output, "discard" discards output.		 MinLength: 1
mode string Mode is a string containing an octal number representing the bit pattern for the file mode.
Defaults to "0600" if not specified. Set to "0000" to prevent OpenBao from modifying the file mode.		 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: {}

GatewayConfig

GatewayConfig configures Kubernetes Gateway API access for the OpenBao cluster. This is an alternative to Ingress for external access, using the more modern and expressive Gateway API.

Appears in:

Field Description Default Validation
enabled boolean Enabled activates Gateway API support for this cluster.
When true, the Operator creates an HTTPRoute for the cluster.
listenerName string ListenerName optionally targets a specific listener (sectionName) on the referenced Gateway.
When set, the generated Route (HTTPRoute or TLSRoute) attaches only to that listener.
This is useful when a Gateway exposes multiple listeners for the same hostname (e.g. Traefik
"web" and "websecure") and you want deterministic attachment.		 Optional: {}
gatewayRef GatewayReference GatewayRef references an existing Gateway resource that will handle
traffic for this OpenBao cluster. The Gateway must already exist.
hostname string Hostname for routing traffic to this OpenBao cluster.
This hostname will be automatically added to the TLS SANs.		 MinLength: 1
path string Path prefix for the HTTPRoute (defaults to "/"). Optional: {}
annotations object (keys:string, values:string) Annotations to apply to the HTTPRoute resource. Optional: {}
backendTLS BackendTLSConfig BackendTLS configures BackendTLSPolicy for end-to-end TLS between the Gateway and OpenBao.
When enabled, the Operator creates a BackendTLSPolicy that configures the Gateway to use
HTTPS when communicating with the OpenBao backend service and validates the backend
certificate using the cluster's CA certificate.		 Optional: {}
tlsPassthrough boolean TLSPassthrough enables TLS passthrough mode using TLSRoute instead of HTTPRoute.
When true, the Operator creates a TLSRoute that routes encrypted TLS traffic based on SNI
without terminating TLS at the Gateway. OpenBao terminates TLS directly.
When false (default), the Operator creates an HTTPRoute with TLS termination at the Gateway.
Note: TLSRoute and HTTPRoute are mutually exclusive - only one can be used per cluster.
BackendTLSPolicy is not needed when TLSPassthrough is enabled since the Gateway does not
decrypt traffic. The Gateway listener must be configured with protocol: TLS and mode: Passthrough.		 Optional: {}

GatewayReference

GatewayReference identifies a Gateway resource.

Appears in:

Field Description Default Validation
name string Name of the Gateway resource. MinLength: 1
namespace string Namespace of the Gateway resource. If empty, uses the OpenBaoCluster namespace. Optional: {}

HTTPAuditOptions

HTTPAuditOptions configures options for HTTP audit devices. See: https://openbao.org/docs/audit/http/

Appears in:

Field Description Default Validation
uri string URI is the URI of the remote server where the audit logs will be written. MinLength: 1
headers JSON Headers is a JSON object describing headers. Must take the shape map[string][]string,
i.e., an object of headers, with each having one or more values.
Headers without values will be ignored.		 Optional: {}

ImageVerificationConfig

ImageVerificationConfig configures supply chain security checks for container images. When enabled, verification applies to all operator-managed images for this cluster (StatefulSets, Deployments, and Jobs).

Appears in:

Field Description Default Validation
enabled boolean Enabled controls whether image verification is enforced.
publicKey string PublicKey is the Cosign public key content used to verify the signature.
Required for static key verification. If empty, keyless verification will be used
(requires Issuer and Subject to be set).		 Optional: {}
issuer string Issuer is the OIDC issuer for keyless verification (e.g., https://token.actions.githubusercontent.com).
Required for keyless verification when PublicKey is not provided.
For GitHub Actions keyless verification, use: https://token.actions.githubusercontent.com		 Optional: {}
subject string Subject is the OIDC subject for keyless verification.
Required for keyless verification when PublicKey is not provided.
Example (GitHub Actions): https://github.com/dc-tec/openbao-operator/.github/workflows/release.yml@refs/tags/&lt;VERSION>
The version in the subject MUST match the image tag version.		 Optional: {}
issuerRegExp string IssuerRegExp is a regular expression for the OIDC issuer when using keyless verification.
Use this to allow a controlled set of issuers instead of a single exact issuer string.
Requires SubjectRegExp when PublicKey is not provided.		 Optional: {}
subjectRegExp string SubjectRegExp is a regular expression for the OIDC subject when using keyless verification.
Use this to allow a controlled set of workflow identities instead of a single exact subject.
Requires IssuerRegExp when PublicKey is not provided.		 Optional: {}
failurePolicy string FailurePolicy defines behavior on verification failure.
"Block" blocks reconciliation of the affected workload when verification fails.
"Warn" logs an error and emits a Kubernetes Event but proceeds.		 Block Enum: [Warn Block]
ignoreTlog boolean IgnoreTlog controls whether to verify against the Rekor transparency log.
When false (default), signatures are verified against Rekor for non-repudiation.
When true, only signature verification is performed without transparency log checks.		 false Optional: {}
imagePullSecrets LocalObjectReference array ImagePullSecrets is a list of references to secrets in the same namespace
to use for pulling images from private registries during verification.
These secrets must be of type kubernetes.io/dockerconfigjson or kubernetes.io/dockercfg.		 Optional: {}

IngressConfig

IngressConfig controls optional HTTP(S) ingress in front of the OpenBao Service.

Appears in:

Field Description Default Validation
enabled boolean Enabled controls whether the Operator manages an Ingress for external access. Optional: {}
className string ClassName is an optional IngressClassName (for example, "nginx", "traefik"). Optional: {}
host string Host is the primary host for external access, for example "bao.example.com". MinLength: 1
path string Path is the HTTP path to route to OpenBao, defaulting to "/". Optional: {}
tlsSecretName string TLSSecretName is an optional TLS Secret name; when empty the cluster TLS Secret is used. Optional: {}
annotations object (keys:string, values:string) Annotations are additional annotations to apply to the Ingress. 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, defaults to "<repo>:X.Y.Z" where <repo> is derived from OPERATOR_INIT_IMAGE_REPOSITORY
(default: "ghcr.io/dc-tec/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: {}

ListenerConfig

ListenerConfig allows tuning the TCP listener configuration.

Appears in:

Field Description Default Validation
tlsDisable boolean TLSDisable controls TLS on the listener.
Note: This is typically managed by the operator based on spec.tls.enabled.		 Optional: {}
proxyProtocolBehavior string ProxyProtocolBehavior allows configuring proxy protocol (e.g. for LoadBalancers). Enum: [use_always allow_any deny_unauthorized]
Optional: {}

LoggingConfig

LoggingConfig allows configuring logging behavior for OpenBao.

Appears in:

Field Description Default Validation
format string Format specifies the log format. Enum: [standard json]
Optional: {}
file string File is the path to the log file.
If not specified, logs are written to stderr.		 Optional: {}
rotateDuration string RotateDuration specifies how often to rotate logs (e.g., "24h", "7d"). Optional: {}
rotateBytes integer RotateBytes specifies the maximum size in bytes before rotating logs. Minimum: 0
Optional: {}
rotateMaxFiles integer RotateMaxFiles is the maximum number of rotated log files to keep. Minimum: 0
Optional: {}
pidFile string PIDFile is the path to write the PID file. Optional: {}

MaintenanceConfig

MaintenanceConfig defines supported maintenance operations. This is intended to provide a first-class workflow for day-2 operations in clusters that enforce managed-resource mutation locks via admission policy.

Appears in:

Field Description Default Validation
enabled boolean Enabled enables maintenance mode for this cluster.
When true, the operator annotates managed resources (Pods/StatefulSet) with
openbao.org/maintenance=true to allow controlled restarts/deletes where
admission policies require an explicit maintenance signal.		 Optional: {}
restartAt string RestartAt triggers a rolling restart when changed.
The operator propagates this value as a Pod template annotation; any change
results in a new StatefulSet revision and a controlled restart.
Recommended value is an RFC3339 timestamp string.
Deprecated: use spec.runtime.restartAt instead. spec.runtime.restartAt
takes precedence when both fields are set.		 MinLength: 1
Optional: {}

MetricsConfig

MetricsConfig configures metrics collection.

Appears in:

Field Description Default Validation
enabled boolean Enabled configures the OpenBao telemetry stanza and creates a ServiceMonitor. false
serviceMonitor ServiceMonitorConfig ServiceMonitor controls whether to create a Prometheus Operator ServiceMonitor. Optional: {}

NetworkConfig

NetworkConfig configures network-related settings for the OpenBaoCluster.

Appears in:

Field Description Default Validation
apiServerCIDR string APIServerCIDR is an optional CIDR block for the Kubernetes API server.
When specified, this value is used instead of auto-detection for NetworkPolicy egress rules.
This is useful when you want an explicit allow-list (or when the in-cluster service VIP
injected into pods is unavailable/unusable in your environment).
Example: "10.43.0.0/16" for service network or "192.168.1.0/24" for control plane nodes.		 Optional: {}
apiServerEndpointIPs string array APIServerEndpointIPs is an optional list of Kubernetes API server endpoint IPs.
When set, the operator adds least-privilege NetworkPolicy egress rules for these IPs on port 6443.
This is required on some CNI implementations where egress enforcement happens on the post-NAT
destination (the API server endpoint) rather than the kubernetes Service IP (10.43.0.1:443).
The operator does not auto-detect these endpoint IPs because doing so reliably requires broader
cluster permissions (list/watch). Configure this field explicitly when needed.
Example (k3d): ["192.168.166.2"]		 Optional: {}
dnsNamespace string DNSNamespace specifies the namespace where the cluster DNS service resides.
Defaults to "kube-system" if not specified.		 kube-system Optional: {}
dnsEndpointIPs string array DNSEndpointIPs is an optional list of DNS resolver endpoint IPs that should be
allow-listed directly in the operator-managed NetworkPolicy on TCP/UDP port 53.
Use this for clusters that resolve DNS through node-local or host-networked caches
instead of pod-backed DNS Services in a namespace. These IP-based rules are additive
to the namespace-based allow-list controlled by DNSNamespace.
The operator does not auto-detect these endpoint IPs because doing so reliably would
require environment-specific node or DNS discovery logic outside the current trust model.
Example: ["169.254.20.10"]		 Optional: {}
egressRules NetworkPolicyEgressRule array EgressRules allows users to specify additional egress rules that will be merged into
the operator-managed NetworkPolicy. This is useful for allowing access to external
services such as transit seal backends, object storage endpoints, or other dependencies.
The operator's default egress rules (DNS, API server, cluster pods) are always included
and cannot be overridden. User-provided rules are appended to the operator-managed rules.
Example: Allow egress to a transit seal backend in another namespace:
egressRules:
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: transit-namespace
ports:
- protocol: TCP
port: 8200		 Optional: {}
ingressRules NetworkPolicyIngressRule array IngressRules allows users to specify additional ingress rules that will be merged into
the operator-managed NetworkPolicy. This is useful for allowing access from external
services, monitoring tools, or other components that need to reach OpenBao pods.
The operator's default ingress rules (cluster pods, kube-system, operator, gateway)
are always included and cannot be overridden. User-provided rules are appended to
the operator-managed rules.
Example: Allow ingress from a monitoring namespace:
ingressRules:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: monitoring
ports:
- protocol: TCP
port: 8200		 Optional: {}
trustedIngressPeers NetworkPolicyPeer array TrustedIngressPeers allows users to declare ingress-controller or passthrough-proxy peers
that should be allowed to reach OpenBao on the API port without writing full raw
NetworkPolicy ingress rules.
This is useful for user-managed TCP passthrough or external ingress components that the
operator does not manage directly. The operator adds least-privilege ingress rules for
port 8200 using these peers.
Example: Allow a Traefik namespace to reach OpenBao on port 8200:
trustedIngressPeers:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: traefik
Example: Allow only specific ingress-controller pods in another namespace:
trustedIngressPeers:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: ingress-system
podSelector:
matchLabels:
app.kubernetes.io/name: traefik		 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: {}

ObservabilityConfig

ObservabilityConfig configures observability features.

Appears in:

Field Description Default Validation
metrics MetricsConfig Metrics configures integration with Prometheus/OpenMetrics. Optional: {}

OpenBaoCluster

OpenBaoCluster is the Schema for the openbaoclusters API.

Field Description Default Validation
apiVersion string openbao.org/v1alpha1
kind string OpenBaoCluster
spec OpenBaoClusterSpec Spec defines the desired state of OpenBaoCluster.
status OpenBaoClusterStatus Status defines the observed state of OpenBaoCluster. Optional: {}

OpenBaoClusterSpec

OpenBaoClusterSpec defines the desired state of an OpenBaoCluster. The Operator owns certain protected OpenBao configuration stanzas (for example, listener "tcp", storage "raft", and seal "static" when using default unseal). Users must not override these via spec.configuration.

Appears in:

Field Description Default Validation
version string Version is the semantic OpenBao version, used for upgrade orchestration.
The Operator uses static auto-unseal, which requires OpenBao v2.4.0 or later.
Versions below 2.4.0 do not support the static seal feature and will fail to start.		 MinLength: 1
image string Image is the container image to run; defaults may be derived from Version. Optional: {}
serviceAccount ServiceAccountConfig ServiceAccount configures the Kubernetes ServiceAccount used by the OpenBao Pods. Optional: {}
podMetadata PodMetadataConfig PodMetadata configures additional labels and annotations for the OpenBao Pod template.
This is useful for platform integrations that select Pods via metadata, such as
Azure Workload Identity. Operator-managed Pod metadata takes precedence.		 Optional: {}
imagePullSecrets LocalObjectReference array ImagePullSecrets is a list of references to secrets in the same namespace
to use for pulling any images used by this Cluster (server, init, sidecars).		 Optional: {}
observability ObservabilityConfig Observability configures telemetry and metrics integration. Optional: {}
replicas integer Replicas is the desired number of quorum-carrying voter Pods. 3 Minimum: 1
readReplicas ReadReplicaConfig ReadReplicas configures the steady-state non-voter read-replica pool. Optional: {}
paused boolean Paused, when true, pauses reconciliation for this OpenBaoCluster (except delete and finalizers). Optional: {}
maintenance MaintenanceConfig Maintenance configures supported maintenance workflows. Optional: {}
runtime RuntimeConfig Runtime configures explicit runtime control requests for the OpenBao workload. Optional: {}
breakGlassAck string BreakGlassAck is an explicit acknowledgment token used to exit Break Glass / Safe Mode.
When the operator enters break glass mode, it writes a nonce to status.breakGlass.nonce.
To acknowledge and allow the operator to resume quorum-risk automation, set this field
to match that nonce.
Example:
kubectl -n <ns> patch openbaocluster <name> --type merge -p '{"spec":{"breakGlassAck":"<nonce>"}}'		 Optional: {}
tls TLSConfig TLS configures TLS for the cluster.
storage StorageConfig Storage configures persistent storage for the cluster.
service ServiceConfig Service configures the primary Service used to expose OpenBao inside or outside the cluster. Optional: {}
ingress IngressConfig Ingress configures optional HTTP(S) ingress in front of the OpenBao Service. Optional: {}
configuration OpenBaoConfiguration Configuration defines the server configuration. Optional: {}
backup BackupSchedule Backup configures scheduled backups for the cluster. Optional: {}
restore RestoreConfig Restore configures optional restore authentication bootstrap for the cluster. Optional: {}
deletionPolicy DeletionPolicy DeletionPolicy controls what happens to underlying resources when the CR is deleted. Enum: [Retain DeletePVCs DeleteAll]
Optional: {}
selfInit SelfInitConfig SelfInit configures OpenBao's native self-initialization feature.
When enabled, OpenBao initializes itself on first start using the configured
requests, and the root token is automatically revoked.
See: https://openbao.org/docs/configuration/self-init/		 Optional: {}
gateway GatewayConfig Gateway configures Kubernetes Gateway API access (alternative to Ingress).
When enabled, the Operator creates an HTTPRoute that routes traffic through
a user-managed Gateway resource.		 Optional: {}
network NetworkConfig Network configures network-related settings for the cluster. Optional: {}
initContainer InitContainerConfig InitContainer configures the init container used to render OpenBao configuration.
The init container renders the final config.hcl from a template using environment
variables such as HOSTNAME and POD_IP.		 Optional: {}
audit AuditDevice array Audit configures declarative audit devices for the OpenBao cluster.
See: https://openbao.org/docs/configuration/audit/		 Optional: {}
plugins Plugin array Plugins configures declarative plugins for the OpenBao cluster.
See: https://openbao.org/docs/configuration/plugins/		 Optional: {}
telemetry TelemetryConfig Telemetry configures telemetry reporting for the OpenBao cluster.
See: https://openbao.org/docs/configuration/telemetry/		 Optional: {}
upgrade UpgradeConfig Upgrade configures upgrade operations.
Built-in upgrade executor Jobs authenticate with JWT auth using the
upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount). If
spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty,
the operator assumes or bootstraps the default "openbao-operator-upgrade"
role.
Pre-upgrade snapshots use spec.backup configuration and backup
authentication rather than spec.upgrade credentials.		 Optional: {}
unseal UnsealConfig Unseal defines the auto-unseal configuration.
If omitted, defaults to "static" mode managed by the operator.		 Optional: {}
imageVerification ImageVerificationConfig ImageVerification configures supply chain security checks. Optional: {}
operatorImageVerification ImageVerificationConfig OperatorImageVerification configures supply chain security checks for operator-managed helper images
(init container, backup/upgrade/restore executors). These images are typically signed
by the operator project (e.g., dc-tec/openbao-operator) rather than the OpenBao upstream project.
If omitted, helper image verification does not fall back to ImageVerification.
In Development, omitted means disabled. In Hardened, omitted means enabled.		 Optional: {}
workloadHardening WorkloadHardeningConfig WorkloadHardening configures opt-in workload hardening features. Optional: {}
securityContext PodSecurityContext SecurityContext allows specifying the PodSecurityContext for the OpenBao Pods.
If set, these values override the default security context generated by the operator.
This is useful for OpenShift (SCC) compatibility or custom security requirements.		 Optional: {}
profile Profile Profile defines the security posture for this cluster.
When set to "Hardened", the operator enforces strict security requirements:
- TLS must be External (cert-manager/CSI managed)
- Unseal must use external KMS (no static unseal)
- SelfInit must be enabled (no root token)
When set to "Development", relaxed security is allowed but a security warning
condition is set.		 Enum: [Hardened Development]

OpenBaoClusterStatus

DriftStatus tracks drift detection and correction events for a cluster. OpenBaoClusterStatus defines the observed state of an OpenBaoCluster.

Appears in:

Field Description Default Validation
observedGeneration integer ObservedGeneration is the most recent metadata.generation that has been
reconciled into this status.		 Optional: {}
phase ClusterPhase Phase is a high-level summary of the cluster state. Enum: [Initializing Running Upgrading BackingUp Failed]
Optional: {}
activeLeader string ActiveLeader is the current Raft leader pod name, for example "prod-cluster-0". Optional: {}
readyReplicas integer ReadyReplicas is the number of replicas that are currently Ready. Optional: {}
readReplicas ReadReplicaStatus ReadReplicas captures observed state for the read-replica pool. Optional: {}
currentVersion string CurrentVersion is the OpenBao version currently running on the cluster. Optional: {}
initialized boolean Initialized indicates whether the OpenBao cluster has been initialized.
This is set to true after the first pod is initialized using bao operator init
or after self-initialization completes.		 Optional: {}
selfInitialized boolean SelfInitialized indicates whether the cluster was initialized using
OpenBao's self-initialization feature. When true, no root token Secret
exists for this cluster (the root token was auto-revoked).		 Optional: {}
lastBackupTime Time LastBackupTime is the timestamp of the last successful backup, if configured.
Deprecated: Use Backup.LastBackupTime instead.		 Optional: {}
upgrade UpgradeProgress Upgrade tracks the state of an in-progress upgrade (if any).
When non-nil, an upgrade is in progress and the UpgradeManager is orchestrating
the pod-by-pod rolling update with leader step-down.		 Optional: {}
upgradeRequests UpgradeRequestStatus UpgradeRequests tracks which explicit upgrade request values have already
been handled so one-shot requests are edge-triggered instead of level-triggered.		 Optional: {}
backup BackupStatus Backup tracks the state of backups for this cluster. Optional: {}
blueGreen BlueGreenStatus BlueGreen tracks the state of blue/green upgrades (if enabled). Optional: {}
operationLock OperationLockStatus OperationLock prevents concurrent long-running operations (upgrade/backup/restore)
from acting on the same cluster at the same time.		 Optional: {}
breakGlass BreakGlassStatus BreakGlass records when the operator has halted quorum-risk automation and requires
explicit operator acknowledgment to continue.		 Optional: {}
workload WorkloadControllerStatus Workload holds signals owned by the workload controller (infrastructure reconciliation). Optional: {}
adminOps AdminOpsControllerStatus AdminOps holds signals owned by the adminops controller (upgrade + backup). Optional: {}
conditions Condition array Conditions represent the current state of the OpenBaoCluster resource. Optional: {}

OpenBaoConfiguration

OpenBaoConfiguration defines the server configuration for OpenBao.

Appears in:

Field Description Default Validation
ui boolean UI enables the built-in web interface. true Optional: {}
logLevel string LogLevel specifies the log level. info Enum: [trace debug info warn err]
Optional: {}
listener ListenerConfig Listener allows tuning the TCP listener.
Note: Address and ClusterAddress are managed by the operator and cannot be changed.		 Optional: {}
raft RaftConfig Raft allows tuning the Raft storage backend. Optional: {}
acmeCARoot string ACMECARoot is the path to the ACME CA root certificate file.
This is used when TLS mode is ACME to specify a custom CA root for ACME certificate validation.		 Optional: {}
logging LoggingConfig Logging allows configuring logging behavior. Optional: {}
plugin PluginConfig Plugin allows configuring plugin behavior.
Note: This is separate from spec.plugins which defines plugin instances.		 Optional: {}
defaultLeaseTTL string DefaultLeaseTTL is the default lease TTL for tokens and secrets (e.g., "720h", "30m").
If not specified, OpenBao uses its default.		 Optional: {}
maxLeaseTTL string MaxLeaseTTL is the maximum lease TTL for tokens and secrets (e.g., "8760h", "1y").
This must be greater than or equal to DefaultLeaseTTL.
If not specified, OpenBao uses its default.		 Optional: {}
cacheSize integer CacheSize is the size of the cache in bytes.
If not specified, OpenBao uses its default cache size.		 Minimum: 0
Optional: {}
disableCache boolean DisableCache disables the cache entirely.
When true, all caching is disabled.		 Optional: {}
detectDeadlocks boolean DetectDeadlocks enables deadlock detection in OpenBao.
This is an experimental feature for debugging.		 Optional: {}
rawStorageEndpoint boolean RawStorageEndpoint enables the raw storage endpoint.
This is an experimental feature that exposes raw storage operations.		 Optional: {}
introspectionEndpoint boolean IntrospectionEndpoint enables the introspection endpoint.
This is an experimental feature for debugging and introspection.		 Optional: {}
impreciseLeaseRoleTracking boolean ImpreciseLeaseRoleTracking enables imprecise lease role tracking.
This is an experimental feature that may improve performance in some scenarios.		 Optional: {}
unsafeAllowAPIAuditCreation boolean UnsafeAllowAPIAuditCreation allows API-based audit device creation.
This bypasses the normal audit device configuration validation.
Use with caution.		 Optional: {}
allowAuditLogPrefixing boolean AllowAuditLogPrefixing allows audit log prefixing.
This enables custom prefixes in audit log entries.		 Optional: {}
enableResponseHeaderHostname boolean EnableResponseHeaderHostname enables the hostname in response headers.
When true, OpenBao includes the hostname in HTTP response headers.		 Optional: {}
enableResponseHeaderRaftNodeID boolean EnableResponseHeaderRaftNodeID enables the Raft node ID in response headers.
When true, OpenBao includes the Raft node ID in HTTP response headers.		 Optional: {}

OperationLockStatus

OperationLockStatus represents a status-based lock held by the operator.

Appears in:

Field Description Default Validation
operation ClusterOperation Operation is the operation currently holding the lock. Enum: [Upgrade Backup Restore]
Optional: {}
holder string Holder is a stable identifier for the lock holder (controller/component). Optional: {}
message string Message provides human-readable context for why the lock is held. Optional: {}
acquiredAt Time AcquiredAt is when the lock was first acquired. Optional: {}
renewedAt Time RenewedAt is updated when the holder reasserts the lock during reconciliation. Optional: {}

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: {}

Plugin

Plugin defines a declarative plugin configuration. 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.
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 image version or tag. MinLength: 1
binaryName string BinaryName is the name of the plugin binary file within the OCI image. MinLength: 1
sha256sum string SHA256Sum is the expected SHA256 checksum of the plugin binary.
Must be a 64-character hexadecimal string.		 MaxLength: 64
MinLength: 64
Pattern: ^[0-9a-fA-F]\{64\}$
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: {}

Profile

Underlying type: string

Profile defines the security posture for an OpenBaoCluster.

Validation:

  • Enum: [Hardened Development]

Appears in:

Field Description
Hardened ProfileHardened enforces strict security requirements (production-ready).
Development ProfileDevelopment allows relaxed security for development/testing.

RaftAutopilotConfig

RaftAutopilotConfig configures Raft Autopilot behavior for dead server cleanup. See: https://openbao.org/docs/concepts/integrated-storage/autopilot/

Appears in:

Field Description Default Validation
cleanupDeadServers boolean CleanupDeadServers enables automatic removal of dead Raft peers.
When enabled, Autopilot periodically removes servers that have been
unhealthy for longer than DeadServerLastContactThreshold.
Requires MinQuorum to be set (defaults to replicas/2 + 1).		 true Optional: {}
deadServerLastContactThreshold string DeadServerLastContactThreshold is the duration after which a server
is considered dead if it hasn't contacted the leader.
Minimum: "1m". Default: "5m" (operator default, shorter than OpenBao's 24h).		 5m Optional: {}
minQuorum integer MinQuorum is the minimum number of servers before Autopilot can prune
dead servers. This prevents removing so many servers that quorum is lost.
If not specified, defaults to max(3, replicas/2 + 1).		 Minimum: 3
Optional: {}
serverStabilizationTime string ServerStabilizationTime is the minimum time a server must be healthy
before being promoted to voter. Default: "10s".		 Optional: {}
lastContactThreshold string LastContactThreshold is the limit on the amount of time a server can
go without leader contact before being considered unhealthy.
Default: "10s".		 Optional: {}
maxTrailingLogs integer MaxTrailingLogs is the amount of entries in the Raft Log that a server
can be behind before being considered unhealthy. Default: 1000.		 Optional: {}

RaftConfig

RaftConfig allows tuning the Raft storage backend.

Appears in:

Field Description Default Validation
performanceMultiplier integer PerformanceMultiplier scales the Raft timing parameters. Minimum: 0
Optional: {}
autopilot RaftAutopilotConfig Autopilot configures Raft Autopilot settings.
By default, dead server cleanup is enabled with a 5-minute threshold.		 Optional: {}

ReadReplicaConfig

ReadReplicaConfig defines the steady-state read-replica pool.

Appears in:

Field Description Default Validation
replicas integer Replicas is the desired number of permanent non-voters. Minimum: 0
Optional: {}
service ReadReplicaServiceConfig Service configures an optional dedicated Service for read traffic. Optional: {}
template ReadReplicaTemplateConfig Template configures read-replica-specific Pod template overrides. Optional: {}
storage ReadReplicaStorageConfig Storage configures read-replica-specific storage overrides. Optional: {}

ReadReplicaSchedulingConfig

ReadReplicaSchedulingConfig defines scheduling overrides for read replicas.

Appears in:

Field Description Default Validation
nodeSelector object (keys:string, values:string) NodeSelector defines node-selection constraints for read-replica Pods. Optional: {}
tolerations Toleration array Tolerations defines Pod tolerations for read-replica Pods. Optional: {}
affinity Affinity Affinity defines Pod affinity / anti-affinity rules for read-replica Pods. Optional: {}
topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints defines topology spread constraints for
read-replica Pods.		 Optional: {}

ReadReplicaServiceConfig

ReadReplicaServiceConfig controls the optional read-only Service for the read-replica pool.

Appears in:

Field Description Default Validation
enabled boolean Enabled controls whether the operator creates a dedicated Service for the
read-replica pool.		 Optional: {}
type ServiceType Type is the Kubernetes Service type, for example "ClusterIP" or
"LoadBalancer".		 Optional: {}
annotations object (keys:string, values:string) Annotations are additional annotations to apply to the read Service. Optional: {}

ReadReplicaStatus

ReadReplicaStatus captures observed state for the read-replica pool.

Appears in:

Field Description Default Validation
desiredReplicas integer DesiredReplicas is the desired number of read replicas. Optional: {}
readyReplicas integer ReadyReplicas is the number of Ready read-replica Pods observed. Optional: {}
registeredReplicas integer RegisteredReplicas is the number of observed non-voter peers registered in
Raft membership.		 Optional: {}
healthyReplicas integer HealthyReplicas is the number of read-replica peers that are currently
healthy according to the Raft Autopilot state endpoint.		 Optional: {}
storage ReadReplicaStorageStatus Storage captures read-replica-specific storage observation state. Optional: {}

ReadReplicaStorageConfig

ReadReplicaStorageConfig defines storage overrides for the read-replica StatefulSet.

Appears in:

Field Description Default Validation
size Quantity Size is the requested persistent volume size for read replicas. Optional: {}
storageClassName string StorageClassName is an optional StorageClass for read-replica PVCs. Optional: {}

ReadReplicaStorageStatus

ReadReplicaStorageStatus captures observed storage state for the read-replica pool.

Appears in:

Field Description Default Validation
desiredPVCs integer DesiredPVCs is the number of data PVCs expected for the read-replica pool. Optional: {}
boundPVCs integer BoundPVCs is the number of observed data PVCs for the read-replica pool. Optional: {}
storageClassName string StorageClassName is the effective StorageClass observed for the
read-replica PVCs when it is consistent.		 Optional: {}

ReadReplicaTemplateConfig

ReadReplicaTemplateConfig defines Pod-template overrides for read replicas.

Appears in:

Field Description Default Validation
metadata PodMetadataConfig Refer to Kubernetes API documentation for fields of metadata. Optional: {}
resources ResourceRequirements Resources defines container resource requests and limits for read replicas. Optional: {}
scheduling ReadReplicaSchedulingConfig Scheduling defines node-placement and topology overrides for read replicas. Optional: {}

RestoreConfig

RestoreConfig defines optional configuration for restore operations.

This is primarily used with self-init JWT bootstrap to pre-create a JWT role that can be referenced by OpenBaoRestore resources.

Appears in:

Field Description Default Validation
jwtAuthRole string JWTAuthRole is the name of the JWT Auth role configured in OpenBao
for restore operations. When set, and when spec.selfInit.oidc.enabled is true,
the operator bootstraps a restore policy and JWT role bound to the restore ServiceAccount
(<cluster-name>-restore-serviceaccount).
If OIDC is enabled in SelfInit and this field is empty, a default role
named "openbao-operator-restore" will be assumed/created.
The role must grant "update" capability on sys/storage/raft/snapshot-force.		 Optional: {}

RuntimeConfig

RuntimeConfig defines explicit runtime control requests for the OpenBao workload.

Appears in:

Field Description Default Validation
restartAt string RestartAt triggers a rolling restart when changed.
The operator propagates this value as a Pod template annotation; any change
results in a new StatefulSet revision and a controlled restart.
Recommended value is an RFC3339 timestamp string.		 MinLength: 1
Optional: {}

SelfInitAuditDevice

SelfInitAuditDevice provides structured configuration for enabling audit devices via self-init requests. This replaces the need for raw JSON in the Data field. See: https://openbao.org/api-docs/system/audit/

Appears in:

Field Description Default Validation
type string Type is the type of audit device (e.g., "file", "syslog", "socket", "http"). Enum: [file syslog socket http]
MinLength: 1
description string Description is an optional description for the audit device. Optional: {}
fileOptions FileAuditOptions FileOptions configures options for file audit devices.
Only used when Type is "file".		 Optional: {}
httpOptions HTTPAuditOptions HTTPOptions configures options for HTTP audit devices.
Only used when Type is "http".		 Optional: {}
syslogOptions SyslogAuditOptions SyslogOptions configures options for syslog audit devices.
Only used when Type is "syslog".		 Optional: {}
socketOptions SocketAuditOptions SocketOptions configures options for socket audit devices.
Only used when Type is "socket".		 Optional: {}

SelfInitAuthMethod

SelfInitAuthMethod provides structured configuration for enabling auth methods via self-init requests. This replaces the need for raw JSON in the Data field. See: https://openbao.org/api-docs/system/auth/

Appears in:

Field Description Default Validation
type string Type is the type of auth method (e.g., "jwt", "kubernetes", "userpass", "ldap"). MinLength: 1
description string Description is an optional description for the auth method. Optional: {}
config object (keys:string, values:string) Config contains optional configuration for the auth method mount.
Common fields include: default_lease_ttl, max_lease_ttl, listing_visibility, etc.		 Optional: {}

SelfInitConfig

SelfInitConfig enables OpenBao's self-initialization feature. When enabled, OpenBao initializes itself on first start using the configured requests, and the root token is automatically revoked. See: https://openbao.org/docs/configuration/self-init/

Appears in:

Field Description Default Validation
enabled boolean Enabled activates OpenBao's self-initialization feature.
When true, the Operator injects initialize stanzas into config.hcl
and does NOT create a root token Secret (root token is auto-revoked).
WARNING: The root token is auto-revoked during initialization. You MUST
configure user authentication (e.g., userpass, JWT, Kubernetes auth) via
spec.selfInit.requests before enabling this. spec.selfInit.oidc.enabled
only provides Operator authentication for lifecycle tasks, NOT user access.
Enabling without user authentication results in permanent lockout.		 false
oidc SelfInitOIDCConfig OIDC configures JWT authentication for the Operator to perform cluster
lifecycle operations (backups, upgrades, restores). When enabled, this
sets up the jwt-operator auth method, OIDC discovery, and operator roles.
This is for Operator authentication only - users must configure their own
authentication methods via spec.selfInit.requests.		 Optional: {}
requests SelfInitRequest array Requests defines the API operations to execute during self-initialization.
Each request becomes a named request block inside an initialize stanza.		 Optional: {}

SelfInitOIDCConfig

SelfInitOIDCConfig configures OIDC identity for the cluster.

Appears in:

Field Description Default Validation
enabled boolean Enabled triggers the bootstrap logic.
audience string Audience, if set, must match the operator installation audience used for
projected OpenBao auth tokens.
This field does not create a per-cluster TokenRequest audience override.		 Optional: {}
issuer string Issuer overrides the auto-discovered K8s issuer URL.
Critical for scenarios where OpenBao sees a different K8s URL than the Operator.		 Optional: {}

SelfInitOperation

Underlying type: string

SelfInitOperation defines valid operations for self-initialization requests.

Validation:

  • Enum: [create read update delete list patch]

Appears in:

Field Description
create SelfInitOperationCreate creates a new resource.
read SelfInitOperationRead reads an existing resource.
update SelfInitOperationUpdate updates an existing resource.
patch SelfInitOperationPatch performs a partial update to an existing resource.
delete SelfInitOperationDelete deletes an existing resource.
list SelfInitOperationList lists resources.

SelfInitPolicy

SelfInitPolicy provides structured configuration for creating/updating policies via self-init requests. This replaces the need for raw JSON in the Data field. See: https://openbao.org/api-docs/system/policies-acl/

Appears in:

Field Description Default Validation
policy string Policy is the HCL or JSON policy content.
This is the actual policy rules that will be applied.		 MinLength: 1

SelfInitRequest

SelfInitRequest defines a single API operation to execute during self-initialization.

Appears in:

Field Description Default Validation
name string Name is a unique identifier for this request (used as the block name).
Must match regex ^[A-Za-z_][A-Za-z0-9_-]*$		 MaxLength: 64
MinLength: 1
Pattern: ^[A-Za-z_][A-Za-z0-9_-]*$
operation SelfInitOperation Operation is the API operation type: create, read, update, delete, or list. Enum: [create read update delete list patch]
path string Path is the API path to call (e.g., "sys/audit/stdout", "auth/kubernetes/config"). MinLength: 1
auditDevice SelfInitAuditDevice AuditDevice configures an audit device when Path starts with "sys/audit/".
This provides structured configuration for audit devices instead of raw JSON.
Only used when Path matches the pattern "sys/audit/*".		 Optional: {}
authMethod SelfInitAuthMethod AuthMethod configures an auth method when Path starts with "sys/auth/".
This provides structured configuration for enabling auth methods.
Only used when Path matches the pattern "sys/auth/*".		 Optional: {}
secretEngine SelfInitSecretEngine SecretEngine configures a secret engine when Path starts with "sys/mounts/".
This provides structured configuration for enabling secret engines.
Only used when Path matches the pattern "sys/mounts/*".		 Optional: {}
policy SelfInitPolicy Policy configures a policy when Path starts with "sys/policies/".
This provides structured configuration for creating/updating policies.
Only used when Path matches the pattern "sys/policies/*".		 Optional: {}
data JSON Data contains the request payload for paths that don't have structured types.
This must be a JSON/YAML object whose shape matches the target API endpoint.
Nested maps and lists are supported and are rendered into the initialize stanza as HCL objects.
Note: For common paths, use structured types instead:
- sys/audit/* → use auditDevice
- sys/auth/* → use authMethod
- sys/mounts/* → use secretEngine
- sys/policies/* → use policy
This payload is stored in the OpenBaoCluster resource and persisted in etcd;
it must not contain sensitive values such as tokens, passwords, or unseal keys.		 Optional: {}
allowFailure boolean AllowFailure allows this request to fail without blocking initialization.
Defaults to false.		 Optional: {}

SelfInitSecretEngine

SelfInitSecretEngine provides structured configuration for enabling secret engines via self-init requests. This replaces the need for raw JSON in the Data field. See: https://openbao.org/api-docs/system/mounts/

Appears in:

Field Description Default Validation
type string Type is the type of secret engine (e.g., "kv", "pki", "transit", "database"). MinLength: 1
description string Description is an optional description for the secret engine. Optional: {}
options object (keys:string, values:string) Options contains optional configuration specific to the secret engine type.
For KV engines, common options include: version ("1" or "2").
For other engines, options vary by type.		 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: {}

ServiceConfig

ServiceConfig controls how the main OpenBao Service is exposed.

Appears in:

Field Description Default Validation
type ServiceType Type is the Kubernetes Service type, for example "ClusterIP" or "LoadBalancer". Optional: {}
annotations object (keys:string, values:string) Annotations are additional annotations to apply to the Service. Optional: {}

ServiceMonitorConfig

ServiceMonitorConfig configures the Prometheus ServiceMonitor.

Appears in:

Field Description Default Validation
enabled boolean Enabled controls whether to create the ServiceMonitor.
Defaults to true if Metrics are enabled.		 true
interval string Interval is the scrape interval. 30s Optional: {}
scrapeTimeout string ScrapeTimeout is the scrape timeout. 10s Optional: {}

SocketAuditOptions

SocketAuditOptions configures options for socket audit devices. See: https://openbao.org/docs/audit/socket/

Appears in:

Field Description Default Validation
address string Address is the socket server address to use.
Example: "127.0.0.1:9090" or "/tmp/audit.sock".		 Optional: {}
socketType string SocketType is the socket type to use, any type compatible with net.Dial is acceptable.
Defaults to "tcp" if not specified.		 Optional: {}
writeTimeout string WriteTimeout is the (deadline) time in seconds to allow writes to be completed over the socket.
A zero value means that write attempts will not time out.
Defaults to "2s" if not specified.		 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-key/

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: {}

SyslogAuditOptions

SyslogAuditOptions configures options for syslog audit devices. See: https://openbao.org/docs/audit/syslog/

Appears in:

Field Description Default Validation
facility string Facility is the syslog facility to use.
Defaults to "AUTH" if not specified.		 Optional: {}
tag string Tag is the syslog tag to use.
Defaults to "openbao" if not specified.		 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 to include in server certificates.
Only used when Mode is OperatorManaged.		 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.

TelemetryConfig

TelemetryConfig defines telemetry reporting configuration. See: https://openbao.org/docs/configuration/telemetry/

Appears in:

Field Description Default Validation
usageGaugePeriod string Common telemetry options
UsageGaugePeriod specifies the interval at which high-cardinality usage data is collected.		 Optional: {}
maximumGaugeCardinality integer MaximumGaugeCardinality is the maximum cardinality of gauge labels. Optional: {}
disableHostname boolean DisableHostname specifies if gauge values should be prefixed with the local hostname. Optional: {}
enableHostnameLabel boolean EnableHostnameLabel specifies if all metric values should contain the host label. Optional: {}
metricsPrefix string MetricsPrefix specifies the prefix used for metric values. Optional: {}
leaseMetricsEpsilon string LeaseMetricsEpsilon specifies the size of the bucket used to measure future lease expiration. Optional: {}
prometheusRetentionTime string Prometheus-specific options
PrometheusRetentionTime specifies how long to retain metrics in Prometheus format.		 Optional: {}
statsiteAddress string Statsite-specific options
StatsiteAddress is the address of the statsite server.		 Optional: {}
statsdAddress string StatsD-specific options
StatsdAddress is the address of the StatsD server.		 Optional: {}
dogStatsdAddress string DogStatsD-specific options
DogStatsdAddress is the address of the DogStatsD server.		 Optional: {}
dogStatsdTags string array DogStatsdTags are tags to add to all metrics. Optional: {}
circonusAPIKey string Circonus-specific options
CirconusAPIKey is the API key for Circonus.		 Optional: {}
circonusAPIApp string CirconusAPIApp is the API app name for Circonus. Optional: {}
circonusAPIURL string CirconusAPIURL is the API URL for Circonus. Optional: {}
circonusSubmissionInterval string CirconusSubmissionInterval is the submission interval for Circonus. Optional: {}
circonusCheckID string CirconusCheckID is the check ID for Circonus. Optional: {}
circonusCheckForceMetricActivation string CirconusCheckForceMetricActivation forces metric activation in Circonus. Optional: {}
circonusCheckInstanceID string CirconusCheckInstanceID is the instance ID for Circonus. Optional: {}
circonusCheckSearchTag string CirconusCheckSearchTag is the search tag for Circonus. Optional: {}
circonusCheckDisplayName string CirconusCheckDisplayName is the display name for Circonus. Optional: {}
circonusCheckTags string CirconusCheckTags is the tags for Circonus. Optional: {}
circonusBrokerID string CirconusBrokerID is the broker ID for Circonus. Optional: {}
circonusBrokerSelectTag string CirconusBrokerSelectTag is the broker select tag for Circonus. Optional: {}
stackdriverProjectID string Stackdriver-specific options
StackdriverProjectID is the Google Cloud Project ID.		 Optional: {}
stackdriverLocation string StackdriverLocation is the GCP or AWS region. Optional: {}
stackdriverNamespace string StackdriverNamespace is a namespace identifier for the telemetry data. Optional: {}
stackdriverDebugLogs boolean StackdriverDebugLogs specifies if OpenBao writes additional stackdriver debug logs. Optional: {}

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 address to the OpenBao cluster. 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 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: {}
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,
or OCI SDK config for authTypeAPIKey mode).
If using Workload Identity (IRSA, GKE WI, Azure MSI), this can be omitted.
The Secret must exist in the same namespace as the OpenBaoCluster.
Cross-namespace references are not allowed for security reasons.		 Optional: {}

UpdateStrategyType

Underlying type: string

UpdateStrategyType defines the type of update strategy to use.

Validation:

  • Enum: [RollingUpdate BlueGreen]

Appears in:

Field Description
RollingUpdate UpdateStrategyRollingUpdate uses a rolling update strategy (default).
BlueGreen UpdateStrategyBlueGreen uses a blue/green deployment strategy.

UpgradeConfig

UpgradeConfig defines configuration for upgrade operations.

Appears in:

Field Description Default Validation
image string Image is the container image to use for upgrade operations.
This image is used by Kubernetes Jobs created during upgrades (for example, blue/green
cluster orchestration actions). The executor runs inside the tenant namespace and
authenticates to OpenBao using a projected ServiceAccount token (JWT auth).
If not specified, defaults to "<repo>:X.Y.Z" where <repo> is derived from OPERATOR_UPGRADE_IMAGE_REPOSITORY
(default: "ghcr.io/dc-tec/openbao-upgrade") and the tag matches OPERATOR_VERSION.		 Optional: {}
preUpgradeSnapshot boolean PreUpgradeSnapshot, when true, triggers a backup before any upgrade.
When enabled, the upgrade manager will create a backup using the backup
configuration (spec.backup.target, spec.backup.image, etc.) and
wait for it to complete before proceeding with the upgrade.
If the backup fails, the upgrade will be blocked and a Degraded condition
will be set with Reason=PreUpgradeBackupFailed.
Requires spec.backup to be configured with target, image, and
authentication (jwtAuthRole or tokenSecretRef).		 Optional: {}
jwtAuthRole string JWTAuthRole is the name of the JWT Auth role configured in OpenBao
for upgrade executor Jobs. The executor authenticates with a projected
ServiceAccount token from <cluster-name>-upgrade-serviceaccount.
The role must be configured in OpenBao and must grant the permissions
required by the selected upgrade strategy, including:
- "read" capability on sys/health
- "sudo" and "update" capability on sys/step-down
- "read" capability on sys/storage/raft/autopilot/state
- for Blue/Green, raft join/configuration/remove-peer/promote/demote operations
The role must bind to the upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount),
which is automatically created by the operator.
If OIDC is enabled in SelfInit and this field is empty, a default role
named "openbao-operator-upgrade" will be assumed/created.
This is the supported authentication mechanism for built-in upgrade orchestration.		 Optional: {}
tokenSecretRef LocalObjectReference TokenSecretRef optionally references a Secret containing an OpenBao API
token for future non-JWT upgrade authentication flows.
Built-in rolling and blue/green upgrade orchestration does not support
token-based authentication. Configure spec.upgrade.jwtAuthRole or enable
spec.selfInit.oidc.enabled instead.		 Optional: {}
strategy UpdateStrategyType Strategy defines the update strategy to use. RollingUpdate Enum: [RollingUpdate BlueGreen]
requests UpgradeRequestConfig Requests defines explicit one-shot operator requests for the current
upgrade workflow. The operator acts only when a request value changes.		 Optional: {}
blueGreen BlueGreenConfig BlueGreen configures the behavior when Strategy is BlueGreen. Optional: {}

UpgradeProgress

UpgradeProgress tracks the state of an in-progress upgrade.

Appears in:

Field Description Default Validation
targetVersion string TargetVersion is the version being upgraded to.
fromVersion string FromVersion is the version being upgraded from.
startedAt Time StartedAt is when the upgrade began. Optional: {}
currentPartition integer CurrentPartition is the current StatefulSet partition value.
completedPods integer array CompletedPods lists ordinals of pods that have been successfully upgraded. Optional: {}
lastStepDownTime Time LastStepDownTime records when the last leader step-down was performed. Optional: {}
failure ControllerErrorStatus Failure is the structured rolling-upgrade failure status.
When Failure.Reason is non-empty, the upgrade is considered failed.		 Optional: {}
lastErrorReason string LastErrorReason is a low-cardinality reason describing why the upgrade failed (if it did).
Deprecated: use Failure.Reason.
When set, the status controller should consider the cluster Degraded.		 Optional: {}
lastErrorMessage string LastErrorMessage is a human-readable failure message (best-effort).
Deprecated: use Failure.Message.		 Optional: {}
lastErrorAt Time LastErrorAt is when the last upgrade error was recorded (best-effort).
Deprecated: use Failure.At.		 Optional: {}

UpgradeRequestConfig

UpgradeRequestConfig defines one-shot operator requests for upgrade workflows.

Appears in:

Field Description Default Validation
retry string Retry requests a retry of the current failed rolling upgrade when changed
to a new non-empty value.
The operator compares this value against status.upgradeRequests.lastHandledRetry
and acts only when the value changes. Recommended value is an RFC3339
timestamp string.		 MinLength: 1
Optional: {}
promote string Promote requests promotion of a held blue/green upgrade when changed to a
new non-empty value while spec.upgrade.blueGreen.autoPromote=false.
The operator compares this value against
status.upgradeRequests.lastHandledPromote and acts only when the value
changes. Recommended value is an RFC3339 timestamp string.		 MinLength: 1
Optional: {}
rollback string Rollback requests a manual abort or rollback of the current blue/green
upgrade when changed to a new non-empty value.
The operator compares this value against
status.upgradeRequests.lastHandledRollback and acts only when the value
changes. Recommended value is an RFC3339 timestamp string.		 MinLength: 1
Optional: {}

UpgradeRequestStatus

UpgradeRequestStatus tracks which explicit upgrade request values have already been handled.

Appears in:

Field Description Default Validation
lastHandledRetry string LastHandledRetry is the last observed spec.upgrade.requests.retry value
that the operator has handled.		 Optional: {}
lastHandledPromote string LastHandledPromote is the last observed spec.upgrade.requests.promote
value that the operator has handled.		 Optional: {}
lastHandledRollback string LastHandledRollback is the last observed spec.upgrade.requests.rollback
value that the operator has handled.		 Optional: {}

ValidationHookConfig

ValidationHookConfig defines a user-supplied validation Job.

Appears in:

Field Description Default Validation
image string Image is the container image for the validation job. MinLength: 1
command string array Command is the command to run. Optional: {}
args string array Args are arguments passed to the command. Optional: {}
timeoutSeconds integer TimeoutSeconds is the job timeout (default: 300s). 300 Optional: {}

VerificationConfig

VerificationConfig allows defining custom health checks before promotion.

Appears in:

Field Description Default Validation
minSyncDuration string MinSyncDuration ensures the Green cluster stays healthy as a non-voter
for at least this duration before promotion (e.g., "5m").		 Optional: {}
prePromotionHook ValidationHookConfig PrePromotionHook specifies a Job template to run before promoting Green.
The job must complete successfully (exit 0) for promotion to proceed.
If the job fails, the operator either aborts or rolls back automatically
when blueGreen.autoRollback.onValidationFailure is enabled; otherwise it
holds for manual resolution.		 Optional: {}

WorkloadControllerStatus

WorkloadControllerStatus holds status owned by the workload controller.

Appears in:

Field Description Default Validation
lastError ControllerErrorStatus LastError is the last workload-controller error observed for this cluster. Optional: {}

WorkloadHardeningConfig

WorkloadHardeningConfig configures optional workload hardening features.

Appears in:

Field Description Default Validation
appArmorEnabled boolean AppArmorEnabled controls whether the operator sets AppArmor profiles on
generated Pods and Jobs. Some Kubernetes environments do not support AppArmor;
this is opt-in to avoid scheduling failures.		 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.
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: {}

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".
Omit this field when relying on ambient workload identity or another default credential chain.		 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.		 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.
Leave this empty when relying on ambient workload identity or provider-managed default credentials instead.
Only used when Provider is "s3".		 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.		 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-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-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 allows restore even if the cluster appears unhealthy.
This is required for disaster recovery scenarios where the cluster
may be in a degraded state.		 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]
startTime Time StartTime is when the restore operation started. Optional: {}
completionTime Time CompletionTime is when the restore operation completed (success or failure). 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: {}

RestorePhase

Underlying type: string

RestorePhase represents the current phase of a restore operation.

Validation:

  • Enum: [Pending Validating Running Completed Failed]

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.

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: {}

Packages

openbao.org/v1alpha1

Package v1alpha1 contains API Schema definitions for the openbao v1alpha1 API group.

Resource Types

OpenBaoTenant

OpenBaoTenant is the Schema for the openbaotenants API. OpenBaoTenant is a governance CRD that explicitly declares which namespace should be provisioned with tenant RBAC. This replaces the previous label-based approach (openbao.org/tenant=true) to improve security by eliminating the need for the Provisioner to have list/watch permissions on namespaces.

Field Description Default Validation
apiVersion string openbao.org/v1alpha1
kind string OpenBaoTenant
spec OpenBaoTenantSpec
status OpenBaoTenantStatus

OpenBaoTenantSpec

OpenBaoTenantSpec defines the desired state of OpenBaoTenant.

Appears in:

Field Description Default Validation
targetNamespace string TargetNamespace is the name of the namespace to provision with tenant RBAC.
The Provisioner will create Role and RoleBinding resources in this namespace
to grant the OpenBaoCluster controller permission to manage OpenBaoCluster
resources in that namespace.		 MinLength: 1
quota ResourceQuotaSpec Quota defines the resource quota to apply to the tenant namespace. Optional: {}
limitRange LimitRangeSpec LimitRange defines the limit range to apply to the tenant namespace. Optional: {}

OpenBaoTenantStatus

OpenBaoTenantStatus defines the observed state of OpenBaoTenant.

Appears in:

Field Description Default Validation
provisioned boolean Provisioned indicates if the RBAC has been successfully applied to the target namespace. Optional: {}
lastError string LastError reports any issues finding the namespace or applying RBAC. Optional: {}
conditions Condition array Conditions represent the latest available observations of the tenant's state. Optional: {}