OpenBaoCluster API · Next · OpenBao Operator

Packages

openbao.org/v1alpha1

openbao.org/v1alpha1

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

Resource Types

OpenBaoCluster

ACMEConfig

ACMEConfig configures ACME certificate management for OpenBao. See: https://openbao.org/docs/configuration/listener/tcp/#acme-parameters

Appears in:

TLSConfig

Field	Description	Validation
`directoryURL` string	DirectoryURL is the ACME directory URL (e.g., `https://acme-v02.api.letsencrypt.org/directory`).	MinLength: 1
`domains` string array	Domains is the list of domain names for which to obtain the certificate. This maps to OpenBao’s listener `tls_acme_domains` field. When empty, the operator will default to an internal Service name suitable for private ACME CAs running inside the cluster (e.g., “<cluster>-acme.<namespace>.svc”).	MinItems: 1 Optional: {}
`email` string	Email is the email address to use for ACME registration.	Optional: {}
`sharedCache` ACMESharedCacheConfig	SharedCache configures a filesystem cache shared across OpenBao replicas for ACME account and certificate state. This is required for HA ACME topologies where more than one Pod can serve the same hostname concurrently.	Optional: {}

ACMESharedCacheConfig

ACMESharedCacheConfig configures the shared filesystem cache for ACME account and certificate state. See: https://openbao.org/docs/configuration/listener/tcp/#acme-parameters

Appears in:

ACMEConfig

Field	Description	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:

ACMESharedCacheConfig

Field	Description
`ManagedPVC`	ACMESharedCacheModeManagedPVC instructs the operator to create a dedicated RWX PVC.
`ExistingPVC`	ACMESharedCacheModeExistingPVC instructs the operator to mount an existing RWX PVC.

APIServerEgressConfig

APIServerEgressConfig selects an additional Kubernetes API egress policy.

Appears in:

NetworkConfig

Field	Description	Default	Validation
`mode` string	Mode selects the Cilium kube-apiserver entity policy. This requires Cilium and its namespaced cilium.io/v2 CiliumNetworkPolicy API.		Enum: [Cilium]
`port` integer	Port is the API server’s TCP backend port after Service translation. Set this to the cluster’s actual backend port, which can differ from 443.	6443	Maximum: 65535 Minimum: 1 Optional: {}

AWSKMSSealConfig

AWSKMSSealConfig configures the AWS KMS seal type. See: https://openbao.org/docs/configuration/seal/awskms/

Appears in:

UnsealConfig

Field	Description	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:

OpenBaoClusterStatus

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:

OpenBaoClusterSpec

Field	Description	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 string map. This is a fallback for backward compatibility and advanced use cases. If structured options (FileOptions, HTTPOptions, etc.) are provided, they take precedence. OpenBao audit options are string-to-string; scalar JSON values are rendered as strings, while nested objects and arrays are rejected. For HTTP headers, prefer httpOptions.headers.	Optional: {}

AuditFileStorageConfig

AuditFileStorageConfig configures the shared filesystem integration point for file audit devices.

The operator mounts the selected PVC into each OpenBao Pod. Each Pod uses a pod-specific subPath under the same PVC so all Pods can render the same audit file path while collectors can mount the PVC read-only and read per-Pod audit files from the backing directories. This storage is intended as a collector handoff and replay buffer, not as the authoritative compliance archive.

Appears in:

OpenBaoClusterSpec

Field	Description	Default	Validation
`mode` AuditFileStorageMode	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 audit file storage PVC. Required when Mode is ManagedPVC.		MinLength: 1 Optional: {}
`storageClassName` string	StorageClassName is an optional StorageClass for the managed audit file storage PVC.		Optional: {}
`mountPath` string	MountPath is where the audit file storage PVC is mounted in OpenBao Pods. File audit device paths must be under this path when auditFileStorage is configured.	/openbao/audit	Optional: {}

AuditFileStorageMode

Underlying type: string

AuditFileStorageMode controls how the operator provides shared filesystem storage for file audit logs.

Validation:

Enum: [ManagedPVC ExistingPVC]

Appears in:

AuditFileStorageConfig

Field	Description
`ManagedPVC`	AuditFileStorageModeManagedPVC instructs the operator to create a dedicated RWX PVC.
`ExistingPVC`	AuditFileStorageModeExistingPVC instructs the operator to mount an existing RWX PVC.

AutoRollbackConfig

AutoRollbackConfig defines conditions that trigger automatic rollback.

Appears in:

BlueGreenConfig

Field	Description	Default
`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:

UnsealConfig

Field	Description	Validation
`vaultName` string	VaultName is the name of the Azure Key Vault.	MinLength: 1
`keyName` string	KeyName is the name of the key in the Azure Key Vault.	MinLength: 1
`tenantID` string	TenantID is the Azure tenant ID.	Optional: {}
`clientID` string	ClientID is the Azure client ID.	Optional: {}
`clientSecret` string	ClientSecret is the Azure client secret. Note: It is strongly recommended to use CredentialsSecretRef or Managed Service Identity instead.	Optional: {}
`resource` string	Resource is the Azure AD resource endpoint. For Managed HSM, this should usually be “managedhsm.azure.net”.	Optional: {}
`environment` string	Environment is the Azure environment (e.g., “AzurePublicCloud”, “AzureUSGovernmentCloud”).	Optional: {}
`authMethod` string	AuthMethod selects how the seal authenticates to Azure, rendered as the seal’s auth_method. When empty, OpenBao chooses: a client ID without a client secret selects managed_identity, which uses the instance metadata service. Set workload_identity for Azure Workload Identity, where the workload identity webhook also injects AZURE_CLIENT_ID.	Enum: [workload_identity managed_identity client_secret environment default] Optional: {}

AzureTargetConfig

AzureTargetConfig holds Azure Blob Storage specific configuration.

Appears in:

BackupTarget

Field	Description	Default	Validation
`storageAccount` string	StorageAccount is the Azure storage account name. Required when using Azure provider.		MinLength: 1
`container` string	Container is a compatibility alias for Bucket. A nonempty value takes precedence over Bucket. Use Bucket alone for new configurations.		Optional: {}

BackendTLSConfig

BackendTLSConfig configures BackendTLSPolicy for Gateway API.

Appears in:

GatewayConfig

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). Hardened clusters reject backendTLS.enabled=false.	true	Optional: {}
`hostname` string	Hostname is the hostname to verify in the backend certificate. If not specified, defaults to the stable TLS server name used by operator-managed clients (for example, openbao-cluster-<cluster-name>.local). This must match a DNS SAN in the backend certificate.		Optional: {}

BackupRetention

BackupRetention defines retention policy for backups.

Appears in:

BackupRetentionRun
BackupSchedule

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

BackupRetentionOutcome

Underlying type: string

BackupRetentionOutcome separates cleanup results from snapshot results.

Validation:

Enum: [Succeeded Failed Skipped]

Appears in:

BackupRetentionResult

Field	Description
`Succeeded`
`Failed`
`Skipped`

BackupRetentionResult

BackupRetentionResult is the last independently observed cleanup outcome.

Appears in:

BackupRetentionStatus

Field	Description	Validation
`sourceJobUID` UID
`name` string
`key` string	Key identifies the successful snapshot that triggered this attempt.
`startedAt` Time
`finishedAt` Time
`outcome` BackupRetentionOutcome		Enum: [Succeeded Failed Skipped]
`reason` string	Reason is a stable reason code. Message describes the outcome and next action.
`message` string
`deletedByCount` integer	DeletedByCount and DeletedByAge count confirmed successful batch deletions. A failed batch can have partial effects; its unknown partial count is not reported as success.	Minimum: 0
`deletedByAge` integer		Minimum: 0

BackupRetentionRun

BackupRetentionRun records the immutable deletion boundary and workload identity.

Appears in:

BackupRetentionStatus

Field	Description	Validation
`name` string	Name is the deterministic retention Job name.
`uid` UID	UID binds the observed Job. Absence after submission is uncertain, not permission to retry.	Optional: {}
`sourceJobName` string	SourceJobName identifies the successful scheduled backup Job.
`sourceJobUID` UID	SourceJobUID pins the successful backup Job.
`generation` integer	Generation pins the source configuration used by the backup Job.
`key` string	Key protects the last successful snapshot throughout retention.
`prefix` string	Prefix confines deletion to scheduled snapshots directly under this cluster prefix.
`restoreTestKey` string	RestoreTestKey protects a previously reserved restore-test snapshot.	Optional: {}
`policy` BackupRetention	Policy is the frozen retention policy.
`startedAt` Time	StartedAt records reservation time.
`deadlineAt` Time	DeadlineAt is the absolute worker deadline, including time spent awaiting submission.
`submittedAt` Time	SubmittedAt records the single permitted Create attempt before the API call.	Optional: {}

BackupRetentionStatus

BackupRetentionStatus holds one active workload and one last result.

Appears in:

BackupStatus

Field	Description	Validation
`active` BackupRetentionRun	Active pins the retention plan until its workload has stopped.	Optional: {}
`last` BackupRetentionResult	Last records the last finished or skipped retention attempt.	Optional: {}
`conditions` Condition array	Conditions report retention progress independently of snapshot success.	Optional: {}

BackupSchedule

BackupSchedule defines when and where snapshots are stored.

Appears in:

OpenBaoClusterSpec

Field	Description	Validation
`restoreTest` RestoreTest	RestoreTest periodically restores the latest successful snapshot into a disposable target.	Optional: {}
`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 references a Secret containing an OpenBao API token to use for backup operations when JWT Auth is not effective. The Secret must exist in the same namespace as the OpenBaoCluster. Cross-namespace references are not allowed for security reasons. If an effective JWT role exists through JWTAuthRole or the SelfInit OIDC default, this field is ignored in favor of JWT Auth. Otherwise this field is required and must reference a token with permission to read sys/storage/raft/snapshot. The operator does not infer or fall back to a <cluster>-root-token Secret.	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, OPERATOR_BACKUP_IMAGE can supply a complete image reference, including a digest. Otherwise, defaults to “<repo>:X.Y.Z” where <repo> is derived from OPERATOR_BACKUP_IMAGE_REPOSITORY (default: “ghcr.io/kubebao/openbao-backup”) and the tag matches OPERATOR_VERSION. This allows users to override the image for air-gapped environments or custom registries.	Optional: {}

BackupSnapshotSummary

BackupSnapshotSummary is the latest successful executor’s bounded observation. Identity and version are observed before and after streaming the snapshot.

Appears in:

BackupStatus

Field	Description	Validation
`digest` string	Digest is sha256: followed by the lowercase digest of the uploaded snapshot.	Pattern: `^sha256:[a-f0-9]\{64\}$`
`clusterID` string	ClusterID is the source native cluster ID observed during the backup.	MaxLength: 128
`version` string	Version is the source OpenBao version observed during the backup.	MaxLength: 64
`size` integer	Size is the snapshot size in bytes.	Maximum: 8.589934592e+09 Minimum: 1

BackupStatus

BackupStatus tracks the state of backups for a cluster.

Appears in:

OpenBaoClusterStatus

Field	Description	Validation
`retention` BackupRetentionStatus	Retention stores the active cleanup workload and its last independent outcome.	Optional: {}
`successfulBackups` integer	SuccessfulBackups counts newly observed successful backup Jobs.	Optional: {}
`latestSnapshot` BackupSnapshotSummary	LatestSnapshot contains the latest executor’s source observation.	Optional: {}
`restoreTest` RestoreTestStatus	RestoreTest stores one active run and one last result.	Optional: {}
`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: {}
`lastHandledManualTrigger` string	LastHandledManualTrigger is the last observed manual trigger token that has progressed into an actual backup attempt.	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: {}
`lastFailureTime` Time	LastFailureTime is when the last backup failure was recorded.	Optional: {}

BackupTarget

BackupTarget describes a generic, cloud-agnostic object storage destination.

Appears in:

Field	Description	Default	Validation
`provider` string	Provider selects the storage backend. Defaults to “s3” for backward compatibility.	s3	Enum: [s3 gcs azure] Optional: {}
`endpoint` string	Endpoint is the HTTP(S) endpoint for the object storage service. For S3: Required (e.g., “https://s3.amazonaws.com” or MinIO endpoint). For GCS: Optional (defaults to googleapis.com). For Azure: Optional (derived from StorageAccount if not specified).		Optional: {}
`bucket` string	Bucket is the bucket or container name for every provider. For Azure, a nonempty azure.container compatibility alias takes precedence.		MinLength: 1
`pathPrefix` string	PathPrefix is an optional prefix within the bucket for this cluster’s snapshots.		Optional: {}
`credentialsSecretRef` LocalObjectReference	CredentialsSecretRef optionally references a Secret containing credentials for the object store. The Secret must exist in the same namespace as the owning OpenBao resource. Cross-namespace references are not allowed for security reasons. For S3: Expected keys are “accessKeyId” and “secretAccessKey” (optional: “sessionToken”, “region”, “caCert”). For GCS: Expected key is “credentials.json” containing a service account JSON key. For Azure: Expected keys are “accountKey” or “connectionString”. Hardened clusters require an explicit storage identity path: credentialsSecretRef, workloadIdentity metadata, or the effective S3 roleArn. Omitting those paths relies on ambient/default credentials and is rejected for Hardened clusters.		Optional: {}
`workloadIdentity` WorkloadIdentityConfig	WorkloadIdentity optionally applies provider-specific metadata required by cloud workload identity integrations. Use this for ambient identity setups such as EKS Pod Identity or IRSA, GKE Workload Identity, or Azure Workload Identity. When omitted, backup and restore workloads can still use any credentials exposed through the pod’s default provider chain. Hardened clusters reject that ambient/default path unless credentialsSecretRef is set, workloadIdentity metadata is present, or an S3 target uses the effective roleArn.		Optional: {}
`partSize` integer	PartSize is the size of each part in multipart uploads (in bytes). Defaults to 10MB (10485760 bytes). Larger values may improve performance for large snapshots on fast networks, while smaller values may be better for slow or unreliable networks.	10485760	Minimum: 5.24288e+06 Optional: {}
`concurrency` integer	Concurrency is the number of concurrent parts to upload during multipart uploads. Defaults to 3. Higher values may improve throughput on fast networks but increase memory usage and may overwhelm slower storage backends.	3	Maximum: 10 Minimum: 1 Optional: {}
`s3` S3TargetConfig	S3 groups S3-specific configuration. Each configured field takes precedence over its top-level compatibility field. Omitted fields use the top-level value. Only used when Provider is “s3”.		Optional: {}
`region` string	Region is the AWS region to use for S3-compatible clients. For AWS, this should match the bucket region (for example, “eu-west-1”). For many S3-compatible stores (MinIO/Ceph), this can be any non-empty value. Only used when Provider is “s3”. Compatibility field: use s3.region for new configurations.	us-east-1	Optional: {}
`roleArn` string	RoleARN is the IAM role ARN (or S3-compatible equivalent) to assume via Web Identity. When set, backup and restore Jobs mount a projected ServiceAccount token and set the AWS Web Identity environment variables explicitly. Only used when Provider is “s3”. Outside Hardened S3 targets, leave this empty when relying on ambient workload identity or provider-managed default credentials instead. For Hardened S3 targets, roleArn is one accepted explicit identity path. It does not satisfy Hardened identity requirements for GCS or Azure. Compatibility field: use s3.roleArn for new configurations.		Optional: {}
`usePathStyle` boolean	UsePathStyle controls whether to use path-style addressing (s3.amazonaws.com/bucket/object) or virtual-hosted-style addressing (bucket.s3.amazonaws.com/object). Set to true for MinIO and S3-compatible stores that require path-style. Set to false for AWS S3 (default, as AWS is deprecating path-style). Only used when Provider is “s3”. Compatibility field: use s3.usePathStyle for new configurations.	false	Optional: {}
`gcs` GCSTargetConfig	GCS contains Google Cloud Storage specific configuration. Only used when Provider is “gcs”.		Optional: {}
`azure` AzureTargetConfig	Azure contains Azure Blob Storage specific configuration. Only used when Provider is “azure”.		Optional: {}
`insecureSkipVerify` boolean	InsecureSkipVerify allows skipping TLS verification (useful for MinIO/LocalStack/Azurite with self-signed certs). This applies to all providers that support TLS. Hardened clusters reject insecureSkipVerify.		Optional: {}

BlueGreenConfig

BlueGreenConfig configures the behavior when Type is BlueGreen.

Appears in:

UpgradeConfig

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:

BlueGreenStatus

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:

OpenBaoClusterStatus

Field	Description	Validation
`phase` BlueGreenPhase	Phase is the current phase of the blue/green upgrade.	Enum: [Idle DeployingGreen JoiningMesh Syncing Promoting DemotingBlue Cleanup RestoringReadReplicas RollingBack RollbackCleanup]
`operationID` string	OperationID identifies the current blue/green upgrade attempt.	Optional: {}
`blueRevision` string	BlueRevision is the hash/name of the currently active cluster.
`blueControllerRevision` string	BlueControllerRevision is the Kubernetes StatefulSet controller revision of Blue. It identifies an unrevisioned rolling workload after switching to BlueGreen without requiring the existing Pods to be restarted or relabeled.	Optional: {}
`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.
`blueReplicas` integer	BlueReplicas is the voter population captured when the upgrade starts. It remains fixed until Green becomes the stable workload.	Minimum: 1 Optional: {}
`greenImage` string	GreenImage is the image selected for the in-flight target.	Optional: {}
`greenVersion` string	GreenVersion is the version selected for the in-flight target.	Optional: {}
`greenReplicas` integer	GreenReplicas is the replica count selected for the in-flight target.	Minimum: 1 Optional: {}
`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: {}
`validationHook` BlueGreenValidationHookStatus	ValidationHook records the expected identity and durable execution receipts for the current pre-promotion validation hook.	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: {}

BlueGreenValidationHookResult

Underlying type: string

BlueGreenValidationHookResult is the persisted terminal result of a pre-promotion validation hook Job.

Validation:

Enum: [Succeeded Failed]

Appears in:

BlueGreenValidationHookStatus

Field	Description
`Succeeded`	BlueGreenValidationHookResultSucceeded indicates that the validation hook Job succeeded.
`Failed`	BlueGreenValidationHookResultFailed indicates that the validation hook Job failed.

BlueGreenValidationHookStage

Underlying type: string

BlueGreenValidationHookStage identifies the durable execution boundary reached by a pre-promotion validation hook.

Validation:

Enum: [Prepared Committed Created TerminalObserved Unknown]

Appears in:

BlueGreenValidationHookStatus

Field	Description
`Prepared`	BlueGreenValidationHookStagePrepared indicates that the expected Job identity is durable, but Job creation has not been committed.
`Committed`	BlueGreenValidationHookStageCommitted indicates that the controller durably committed to one Job creation attempt. A missing Job after this point is ambiguous and is not recreated automatically.
`Created`	BlueGreenValidationHookStageCreated indicates that the controller persisted the created Job identity.
`TerminalObserved`	BlueGreenValidationHookStageTerminalObserved indicates that the controller persisted the terminal Job result.
`Unknown`	BlueGreenValidationHookStageUnknown indicates that the controller cannot prove whether the committed validation hook ran.

BlueGreenValidationHookStatus

BlueGreenValidationHookStatus records the expected identity and durable receipts for one pre-promotion validation hook execution.

Appears in:

BlueGreenStatus

Field	Description	Validation
`operationID` string	OperationID identifies the blue/green upgrade attempt that owns this hook.
`greenRevision` string	GreenRevision identifies the Green revision validated by this hook.
`specHash` string	SpecHash identifies the normalized validation hook specification.
`stage` BlueGreenValidationHookStage	Stage is the latest durable execution boundary observed by the controller.	Enum: [Prepared Committed Created TerminalObserved Unknown]
`jobName` string	JobName is the expected validation hook Job name.
`jobUID` UID	JobUID is the UID returned for the created validation hook Job.	Optional: {}
`preparedAt` Time	PreparedAt is when the expected hook identity became durable.	Optional: {}
`committedAt` Time	CommittedAt is when the controller committed to one Job creation attempt.	Optional: {}
`createdAt` Time	CreatedAt is when the controller persisted the created Job receipt.	Optional: {}
`terminalResult` BlueGreenValidationHookResult	TerminalResult is the persisted terminal Job result.	Enum: [Succeeded Failed] Optional: {}
`terminalObservedAt` Time	TerminalObservedAt is when the controller persisted the terminal Job result.	Optional: {}

BreakGlassReason

Underlying type: string

BreakGlassReason describes why the operator required manual intervention.

Validation:

Enum: [RollbackConsensusRepairFailed RollbackCleanupPeerRemovalFailed]

Appears in:

BreakGlassStatus

Field	Description
`RollbackConsensusRepairFailed`
`RollbackCleanupPeerRemovalFailed`

BreakGlassStatus

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

Appears in:

OpenBaoClusterStatus

Field	Description	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:

OperationLockStatus

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:

OpenBaoClusterStatus

Field	Description
`Initializing`
`Running`
`Upgrading`
`BackingUp`
`Failed`

ClusterRestoreStatus

ClusterRestoreStatus retains restart observations from earlier operator releases. New restores report status, including managed restarts, on OpenBaoRestore.

Appears in:

OpenBaoClusterStatus

Field	Description	Validation
`name` string	Name identifies the OpenBaoRestore recorded by an earlier release.	Optional: {}
`uid` string	UID identifies the OpenBaoRestore recorded by an earlier release.	Optional: {}
`restartCompletedAt` Time	RestartCompletedAt is the legacy timestamp for a controller-observed voter restart. Administrator-led recovery does not update this field.	Optional: {}

ControllerErrorStatus

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

Appears in:

AdminOpsControllerStatus
PolicyReconciliationStatus
UpgradeProgress
WorkloadControllerStatus

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

ControllerJWTMode

Underlying type: string

ControllerJWTMode selects shared or target-specific controller credentials.

Validation:

Enum: [Shared Target]

Appears in:

OpenBaoClusterSpec

Field	Description
`Shared`	ControllerJWTModeShared uses the installation’s projected ServiceAccount JWT.
`Target`	ControllerJWTModeTarget requests a JWT for this OpenBaoCluster’s UID.

DeletionPolicy

Underlying type: string

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

Validation:

Enum: [Retain DeletePVCs DeleteAll]

Appears in:

OpenBaoClusterSpec

Field	Description
`Retain`	DeletionPolicyRetain removes operator-managed compute and keeps PVCs and external backups.
`DeletePVCs`	DeletionPolicyDeletePVCs removes operator-managed compute and PVCs, but retains external backups.
`DeleteAll`	DeletionPolicyDeleteAll removes operator-managed compute and PVCs, but retains external object-store backups.

FileAuditOptions

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

Appears in:

AuditDevice
SelfInitAuditDevice

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:

UnsealConfig

Field	Description	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:

BackupTarget

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:

OpenBaoClusterSpec

Field	Description	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:

GatewayConfig

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:

AuditDevice
SelfInitAuditDevice

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. The operator renders this object as OpenBao’s expected JSON-encoded options.headers string.		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:

OpenBaoClusterSpec

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/kubebao/openbao-operator/.github/workflows/release.yml@refs/tags/<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:

OpenBaoClusterSpec

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: {}
`pathType` IngressPathType	PathType identifies how the ingress controller should interpret Path.	Prefix	Enum: [Prefix Exact ImplementationSpecific] 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: {}
`readinessMode` IngressReadinessMode	ReadinessMode identifies when the operator should consider ingress integration ready for endpoint publication.	LoadBalancerPublished	Enum: [Created LoadBalancerPublished] Optional: {}

IngressPathType

Underlying type: string

IngressPathType identifies how a Kubernetes Ingress path should match requests.

Validation:

Enum: [Prefix Exact ImplementationSpecific]

Appears in:

IngressConfig

Field	Description
`Prefix`	IngressPathTypePrefix uses prefix path matching.
`Exact`	IngressPathTypeExact uses exact path matching.
`ImplementationSpecific`	IngressPathTypeImplementationSpecific defers path matching to the controller.

IngressReadinessMode

Underlying type: string

IngressReadinessMode identifies how the operator decides whether ingress integration is ready for endpoint publication.

Validation:

Enum: [Created LoadBalancerPublished]

Appears in:

IngressConfig

Field	Description
`Created`	IngressReadinessModeCreated considers ingress integration ready once the managed Ingress object exists.
`LoadBalancerPublished`	IngressReadinessModeLoadBalancerPublished considers ingress integration ready only after the managed Ingress reports a published load balancer address in status.

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:

OpenBaoClusterSpec
RestoreClusterTemplate

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether the init container is used to render the configuration. The operator requires the init container; disabling it is not supported.	true	Optional: {}
`image` string	Image is the container image to use for the init container. If not specified, OPERATOR_INIT_IMAGE can supply a complete image reference, including a digest. Otherwise, defaults to “<repo>:X.Y.Z” where <repo> is derived from OPERATOR_INIT_IMAGE_REPOSITORY (default: “ghcr.io/kubebao/openbao-init”) and the tag matches OPERATOR_VERSION.		Optional: {}

InitialRecoveryKeysConfig

InitialRecoveryKeysConfig declares the first recovery-key set that OpenBao should create through the authenticated recovery-key rotation endpoint during self-initialization.

The Operator always renders this request with backup=true so encrypted recovery shares can be retrieved through OpenBao’s recovery backup endpoint after bootstrap. Decrypted recovery shares must stay outside Kubernetes and outside the Operator.

Appears in:

RecoveryKeysConfig

Field	Description	Validation
`shares` integer	Shares is the total number of recovery-key shares to create.	Maximum: 255 Minimum: 1
`threshold` integer	Threshold is the number of recovery-key shares required for recovery operations such as generate-root.	Maximum: 255 Minimum: 1
`recipients` RecoveryKeyRecipient array	Recipients lists the public OpenPGP recipients for encrypted recovery shares. Each recipient is passed to OpenBao as one pgp_keys entry; use fingerprints for custody mapping instead of relying on share numbering.	MaxItems: 255 MinItems: 1

KMIPSealConfig

KMIPSealConfig configures the KMIP seal type. See: https://openbao.org/docs/configuration/seal/kmip/

Appears in:

UnsealConfig

Field	Description	Validation
`endpoint` string	Endpoint is the KMIP server endpoint.	MinLength: 1
`kmsKeyID` string	KMSKeyID is the unique identifier of the KMIP key to use.	MinLength: 1
`clientCert` string	ClientCert is the path to the client certificate used for KMIP communication.	MinLength: 1
`clientKey` string	ClientKey is the path to the private key used for KMIP communication.	MinLength: 1
`caCert` string	CACert is the path to the CA certificate for KMIP communication.	Optional: {}
`serverName` string	ServerName is the TLS server name to use when connecting to the KMIP endpoint.	Optional: {}
`timeout` integer	Timeout is the timeout in seconds for KMIP requests.	Minimum: 1 Optional: {}
`encryptAlg` string	EncryptAlg is the encryption algorithm used for KMIP requests.	Enum: [AES_GCM RSA_OAEP_SHA256 RSA_OAEP_SHA384 RSA_OAEP_SHA512] Optional: {}
`tls12Ciphers` string	TLS12Ciphers configures the TLS 1.2 cipher suites to use when connecting to the KMIP endpoint.	Optional: {}
`disabled` boolean	Disabled disables this seal configuration, for example during seal migration.	Optional: {}

KMSPluginSealConfig

KMSPluginSealConfig configures a plugin-backed KMS seal. The referenced plugin must be declared in spec.plugins with type “kms”.

Appears in:

UnsealConfig

Field	Description	Default	Validation
`pluginName` string	PluginName is the name of the plugin registered through a matching plugin “kms” stanza. OpenBao uses this value as the seal stanza label.		MinLength: 1
`config` object (keys:string, values:string)	Config contains plugin-specific seal configuration rendered as string attributes inside seal “<pluginName>”. Keys must be valid HCL identifiers. Values are stored in the OpenBaoCluster resource; use file paths to credentialsSecretRef-mounted files for sensitive material instead of inline secrets.		MaxProperties: 64 Optional: {}

KubernetesServiceAccountSubject

Underlying type: string

KubernetesServiceAccountSubject is the exact subject claim in a projected Kubernetes ServiceAccount token.

Validation:

MaxLength: 340
Pattern: ^system:serviceaccount:[a-z0-9]([-a-z0-9]*[a-z0-9])?:[a-z0-9]([-a-z0-9.]*[a-z0-9])?$

Appears in:

SelfInitOIDCAdditionalSubjects

ListenerConfig

ListenerConfig allows tuning the API and metrics TCP listeners.

Appears in:

OpenBaoConfiguration

Field	Description	Validation
`tlsDisable` boolean	TLSDisable controls TLS on the listener. Note: This is typically managed by the operator based on spec.tls.enabled. Hardened clusters reject tlsDisable=true.	Optional: {}
`tlsMinVersion` TLSVersion	TLSMinVersion sets the minimum TLS version on the API and metrics listeners. If omitted, OpenBao uses TLS 1.2. TLS must be enabled.	Enum: [tls12 tls13] Optional: {}
`tlsMaxVersion` TLSVersion	TLSMaxVersion sets the maximum TLS version on the API and metrics listeners. If omitted, OpenBao uses TLS 1.3. TLS must be enabled.	Enum: [tls12 tls13] Optional: {}
`tlsKeyExchangePreferences` TLSKeyExchangeGroup array	TLSKeyExchangePreferences selects allowed key exchange groups on the API and metrics listeners. List order does not control preference; Go uses its internal preference order. If omitted, OpenBao uses Go’s default groups. Requires OpenBao >= 2.7.0 and TLS enabled. A list containing only hybrid PQ groups requires TLSMinVersion=tls13 and rejects classical-only clients. This setting does not configure cluster traffic on port 8201.	Enum: [CurveP256 CurveP384 CurveP521 X25519 X25519MLKEM768 SecP256r1MLKEM768 SecP384r1MLKEM1024] MaxItems: 7 MinItems: 1 Optional: {}
`proxyProtocolBehavior` string	ProxyProtocolBehavior configures PROXY protocol on the API listener. Supported values are use_always, allow_authorized, and deny_unauthorized. The legacy allow_any value remains in the schema for compatibility but is rejected by the operator. Use allow_authorized to trust selected proxies.	Enum: [use_always allow_any allow_authorized deny_unauthorized] Optional: {}
`proxyProtocolAuthorizedAddrs` string array	ProxyProtocolAuthorizedAddrs lists trusted proxy source IP addresses or CIDRs. Required for allow_authorized and deny_unauthorized. With allow_authorized, connections from other sources use the peer IP address instead of PROXY metadata. This setting applies only to the API listener, not the metrics listener.	MinItems: 1 items:MinLength: 1 Optional: {}

LoggingConfig

LoggingConfig allows configuring logging behavior for OpenBao.

Appears in:

OpenBaoConfiguration

Field	Description	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:

OpenBaoClusterSpec

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

MetricsConfig

MetricsConfig configures metrics collection.

Appears in:

ObservabilityConfig

Field	Description	Default	Validation
`enabled` boolean	Enabled configures the OpenBao telemetry stanza and creates a ServiceMonitor.	false
`scrapeProfile` string	ScrapeProfile selects which OpenBao pods are targeted by generated scrape resources. Active targets only the active OpenBao pod. AllNodes targets every OpenBao pod and requires a dedicated metrics-only listener.	Active	Enum: [Active AllNodes] Optional: {}
`metricsOnlyListener` MetricsOnlyListenerConfig	MetricsOnlyListener configures a dedicated listener for metrics scraping. It is enabled automatically when scrapeProfile is AllNodes.		Optional: {}
`serviceMonitor` ServiceMonitorConfig	ServiceMonitor controls whether to create a Prometheus Operator ServiceMonitor.		Optional: {}

MetricsOnlyListenerConfig

MetricsOnlyListenerConfig configures a dedicated metrics-only TCP listener.

Appears in:

MetricsConfig

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether to render the dedicated metrics-only listener. When omitted, the listener is enabled automatically for the AllNodes scrape profile.		Optional: {}
`port` integer	Port is the dedicated metrics listener port.	8202	Maximum: 65535 Minimum: 1 Optional: {}
`unauthenticatedMetricsAccess` boolean	UnauthenticatedMetricsAccess allows unauthenticated access to /v1/sys/metrics on the metrics-only listener. AllNodes scraping needs this so standby nodes can expose metrics. Restrict this listener with NetworkPolicy.		Optional: {}

NetworkConfig

NetworkConfig configures network-related settings for the OpenBaoCluster.

Appears in:

OpenBaoClusterSpec

Field	Description	Default	Validation
`apiServerEgress` APIServerEgressConfig	APIServerEgress adds a CNI-specific Kubernetes API egress policy alongside the standard NetworkPolicies. Omit this field for standard IP-based rules.		Optional: {}
`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. Use this on 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. Hardened clusters require every user-provided egress rule to be port-scoped and to target explicit non-wildcard peers. 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 and operator-managed jobs) are always included and cannot be overridden. User-provided rules are appended to the operator-managed rules. Gateway or ingress-controller data-plane reachability should be modeled with trustedIngressPeers. Hardened clusters reject raw ingress rules; use trustedIngressPeers or managed Gateway/Ingress integration for application access. 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. Hardened clusters require trusted ingress peers to select explicit non-wildcard sources. 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:

UnsealConfig

Field	Description	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:

OpenBaoClusterSpec

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

OpenBaoCluster

OpenBaoCluster is the Schema for the openbaoclusters API.

Field	Description	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:

OpenBaoCluster

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 Pattern: `^v?(0\|[1-9][0-9])\.(0\|[1-9][0-9])\.(0\|[1-9][0-9])(-(0\|[1-9][0-9]\|[0-9][A-Za-z-][0-9A-Za-z-])(\.(0\|[1-9][0-9]\|[0-9][A-Za-z-][0-9A-Za-z-])))?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$`
`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
`resources` ResourceRequirements	Resources defines resource requests and limits for voter OpenBao containers. Read replicas use spec.readReplicas.template.resources instead.		Optional: {}
`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: {}
`reconcilePolicies` boolean	ReconcilePolicies restores the built-in operational policies after initialization. Administrator-managed JWT authentication and exact-content approval are required. OpenBao must independently approve their exact contents through the openbao-operator-policy-approval policy. Bootstrap installs the initial approval; existing clusters and later permission changes require administrator approval. Auth methods, roles, and the approval policy are not reconciled.		Optional: {}
`controllerJWTMode` ControllerJWTMode	ControllerJWTMode selects the credential used by the controller for OpenBao. Shared (also the behavior when omitted) preserves the installation-wide projected JWT. Target requests a short-lived JWT whose sole audience is urn:openbao:controller:<metadata.uid>. Prepare the OpenBao controller role before switching an initialized cluster to Target. Target never falls back to the shared JWT. Target requires self-init and self-init OIDC to be enabled. Executor Job authentication is unchanged. Enforced admission prevents removal or downgrade after selecting Target.		Enum: [Shared Target] 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: {}
`recoveryKeys` RecoveryKeysConfig	RecoveryKeys configures Operator-assisted recovery-key bootstrap surfaces. The Operator creates recovery keys only during initial self-initialization; recovery share custody and proof ceremonies remain user-owned processes.		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: {}
`auditFileStorage` AuditFileStorageConfig	AuditFileStorage configures a shared filesystem integration point for file audit devices. When configured, file audit device paths must be under auditFileStorage.mountPath.		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 during initial SelfInit bootstrap and spec.upgrade.jwtAuthRole is empty, the operator creates the default “openbao-operator-upgrade” role. Already-initialized clusters must keep that role or configure spec.upgrade.jwtAuthRole explicitly. 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 and backup/upgrade/restore executors) and custom BlueGreen validation-hook images. Helper images are typically signed by the operator project (e.g., kubebao/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 use External or ACME trust, with no TLS disablement or skip-verify paths - Unseal must use external KMS (no static unseal) - SelfInit must be enabled (no root token) - Network additions must be explicit and least-privilege - Backup/restore storage identity must be explicit - Dangerous runtime flags and backend HTTP are rejected 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:

OpenBaoCluster

Field	Description	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: {}
`acceptedUpgradeStrategy` UpdateStrategyType	AcceptedUpgradeStrategy is the upgrade strategy the operator has accepted after applying idle-state transition guards. While a requested strategy change is blocked, controllers continue using this strategy so an existing operation can finish safely.	Enum: [RollingUpdate BlueGreen] 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: {}
`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: {}
`restore` ClusterRestoreStatus	Restore retains post-restore restart status written by earlier releases. It is deprecated: new restores report status on OpenBaoRestore, and the operator reads this field only to preserve legacy Pod templates.	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:

OpenBaoClusterSpec

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. Hardened clusters reject detectDeadlocks=true.		Optional: {}
`rawStorageEndpoint` boolean	RawStorageEndpoint enables the raw storage endpoint. This is an experimental feature that exposes raw storage operations. Hardened clusters reject rawStorageEndpoint=true.		Optional: {}
`introspectionEndpoint` boolean	IntrospectionEndpoint enables the introspection endpoint. This is an experimental feature for debugging and introspection. Hardened clusters reject introspectionEndpoint=true.		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. Hardened clusters reject unsafeAllowAPIAuditCreation=true.		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:

OpenBaoClusterStatus

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

PKCS11RuntimeConfig

PKCS11RuntimeConfig configures local runtime wiring needed by PKCS#11 vendor libraries. It is intentionally scoped to environment variables and library lookup paths so HSM integrations do not require custom wrapper scripts.

Appears in:

PKCS11SealConfig

Field	Description	Validation
`libraryPath` string	LibraryPath sets LD_LIBRARY_PATH for the OpenBao process. Use this when the configured PKCS#11 module depends on sibling vendor libraries that are not in the image’s default dynamic linker search path.	Optional: {}
`env` PKCS11RuntimeEnvVar array	Env exposes literal environment variables from keys in spec.unseal.credentialsSecretRef. Use this for vendor runtime settings such as HSM endpoints or authentication key references.	MaxItems: 16 Optional: {}
`fileEnv` PKCS11RuntimeFileEnvVar array	FileEnv exposes environment variables whose values are paths to files mounted from keys in spec.unseal.credentialsSecretRef. Use this for vendor settings that expect a config file path, for example SOFTHSM2_CONF or vendor-specific PKCS#11 client configuration variables.	MaxItems: 16 Optional: {}

PKCS11RuntimeEnvVar

Underlying type: struct{Name string "json:\"name\""; SecretKey string "json:\"secretKey\""}

PKCS11RuntimeEnvVar maps a PKCS#11 runtime environment variable to a key in spec.unseal.credentialsSecretRef.

Appears in:

PKCS11RuntimeConfig

PKCS11RuntimeFileEnvVar

Underlying type: struct{Name string "json:\"name\""; SecretKey string "json:\"secretKey\""}

PKCS11RuntimeFileEnvVar maps a PKCS#11 runtime environment variable to the mounted file path for a key in spec.unseal.credentialsSecretRef.

Appears in:

PKCS11RuntimeConfig

PKCS11SealConfig

PKCS11SealConfig configures the PKCS#11 seal type. See: https://openbao.org/docs/configuration/seal/pkcs11/

Appears in:

UnsealConfig

Field	Description	Validation
`lib` string	Lib is the path to the PKCS#11 library provided by the HSM vendor.	MinLength: 1
`slot` string	Slot is the slot number where the HSM token is located.	Optional: {}
`tokenLabel` string	TokenLabel is the token label of the HSM slot to use instead of Slot.	Optional: {}
`pin` string	PIN is the PIN for accessing the HSM token. Note: It is strongly recommended to use CredentialsSecretRef instead of setting this directly.	Optional: {}
`keyLabel` string	KeyLabel is the label for the encryption key used by OpenBao.	MinLength: 1
`keyID` string	KeyID is the PKCS#11 key identifier to use instead of KeyLabel.	Optional: {}
`mechanism` string	Mechanism overrides the PKCS#11 wrapping or encryption mechanism.	Optional: {}
`disableSoftwareEncryption` boolean	DisableSoftwareEncryption disables the software encryption fallback.	Optional: {}
`disabled` boolean	Disabled disables this seal configuration, for example during seal migration.	Optional: {}
`rsaOAEPHash` string	RSAOAEPHash specifies the hash algorithm to use for RSA with OAEP padding. Valid values: sha1, sha224, sha256, sha384, sha512.	Enum: [sha1 sha224 sha256 sha384 sha512] Optional: {}
`runtime` PKCS11RuntimeConfig	Runtime configures local PKCS#11 vendor runtime wiring such as library lookup paths and environment variables sourced from credentialsSecretRef.	Optional: {}

Plugin

Plugin defines a declarative plugin configuration. Declarative plugins require OpenBao 2.5.0 or newer; KMS plugins require 2.6.0 or newer. During upgrades, declarations must also meet the recorded running version’s requirements. See: https://openbao.org/docs/configuration/plugins/

Appears in:

OpenBaoClusterSpec
RestoreClusterTemplate

Field	Description	Validation
`type` string	Type is the plugin type (e.g., “secret”, “auth”).	MinLength: 1
`name` string	Name is the name of the plugin.	MinLength: 1
`image` string	Image is the OCI image URL including registry and repository. Before OpenBao 2.7.0, use an untagged repository and set Version separately. Required if Command is not set. Conflicts with Command.	Optional: {}
`command` string	Command is the command name of a manually downloaded plugin. Required if Image is not set. Conflicts with Image.	Optional: {}
`version` string	Version is the plugin version and, when Image has no tag, the image tag. OpenBao 2.7 and later can infer it from the image tag. Command-based KMS plugins on OpenBao 2.7 and later do not require a version.	MinLength: 1 Optional: {}
`binaryName` string	BinaryName is the name of the plugin binary file within the OCI image. OpenBao 2.7 and later can infer it from the image ENTRYPOINT or CMD.	MinLength: 1 Optional: {}
`sha256sum` string	SHA256Sum is the expected SHA256 checksum of the plugin binary. Must be a 64-character hexadecimal string. OpenBao 2.7 and later allow omission for digest-pinned OCI images and command-based plugins. Earlier versions require this field.	MaxLength: 64 MinLength: 64 Pattern: `^[0-9a-fA-F]\{64\}$` Optional: {}
`args` string array	Args are arguments to pass to the running plugin. Only used if plugin_auto_register=true is set.	Optional: {}
`env` string array	Env are environment variables to pass to the running plugin. Only used if plugin_auto_register=true is set.	Optional: {}

PluginConfig

PluginConfig allows configuring plugin behavior.

Appears in:

OpenBaoConfiguration
RestoreTargetConfiguration

Field	Description	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:

OpenBaoClusterSpec
ReadReplicaTemplateConfig
RestoreClusterTemplate

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

PolicyReconciliationStatus

PolicyReconciliationStatus records progress without granting OpenBao permissions.

Appears in:

WorkloadControllerStatus

Field	Description	Validation
`revisions` object (keys:string, values:string)	Revisions contains the last verified content digest for each observed policy. An empty digest means the policy was observed missing or different and awaits repair. An absent entry means the policy has not been observed; it does not block operations. Failed reads retain the last observation; OpenBao still authorizes every operation.	Optional: {}
`attemptedRevision` string	AttemptedRevision identifies the bundle used for the last attempt. A desired bundle change bypasses the previous retry delay.	Optional: {}
`lastVerified` Time	LastVerified is when the complete desired bundle was last verified or repaired. Unchanged successful observations are refreshed at most once every five minutes.	Optional: {}
`retryAfter` Time	RetryAfter delays policy requests after a failure, including during unrelated reconciles.	Optional: {}
`lastError` ControllerErrorStatus	LastError reports policy failures independently of infrastructure and Autopilot errors.	Optional: {}

Profile

Underlying type: string

Profile defines the security posture for an OpenBaoCluster.

Validation:

Enum: [Hardened Development]

Appears in:

OpenBaoClusterSpec

Field	Description
`Hardened`	ProfileHardened enforces strict security requirements and rejects unsafe escape hatches.
`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:

RaftConfig

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:

OpenBaoConfiguration

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:

OpenBaoClusterSpec

Field	Description	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:

ReadReplicaTemplateConfig

Field	Description	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:

ReadReplicaConfig

Field	Description	Validation
`ipFamilyPolicy` IPFamilyPolicy	IPFamilyPolicy selects single-stack or dual-stack Service allocation. When omitted, Kubernetes uses its default Service policy. Two IP families require PreferDualStack or RequireDualStack.	Enum: [SingleStack PreferDualStack RequireDualStack] Optional: {}
`ipFamilies` IPFamily array	IPFamilies selects the Service IP families in primary-first order. The primary family cannot change after the Service is created.	MaxItems: 2 items:Enum: [IPv4 IPv6] Optional: {}
`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:

OpenBaoClusterStatus

Field	Description	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:

ReadReplicaConfig

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:

ReadReplicaStatus

Field	Description	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:

ReadReplicaConfig

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

RecoveryKeyRecipient

RecoveryKeyRecipient describes one public OpenPGP recipient for an encrypted recovery-key share. The public key material is not secret, but it must be fingerprint-verified before production use.

Appears in:

InitialRecoveryKeysConfig

Field	Description	Validation
`name` string	Name is a stable ceremony-local recipient identifier used only for review and status/evidence mapping.	MaxLength: 64 MinLength: 1 Pattern: `^[A-Za-z0-9][A-Za-z0-9_.-]*$`
`fingerprint` string	Fingerprint is the expected OpenPGP public-key fingerprint for the recipient. It is informational for the Operator and should be verified out of band by the ceremony participants.	Pattern: `^([0-9A-Fa-f]\{40\}\|[0-9A-Fa-f]\{64\})$` Optional: {}
`pgpPublicKey` string	PGPPublicKey is the base64-encoded binary OpenPGP public key material expected by OpenBao’s sys/rotate/recovery/init pgp_keys field.	MinLength: 1

RecoveryKeysConfig

RecoveryKeysConfig configures OpenBao recovery-key bootstrap surfaces.

The Operator only creates recovery keys during first self-initialization. It does not distribute encrypted shares, collect decrypted shares, escrow share material, or run generate-root ceremonies.

Appears in:

OpenBaoClusterSpec

Field	Description	Default	Validation
`initial` InitialRecoveryKeysConfig	Initial configures the first recovery-key generation request for a self-initialized cluster using auto-unseal.		Optional: {}

RestoreClusterTemplate

RestoreClusterTemplate is the supported fresh recovery target profile. Administrators must prepare the destination namespace network boundary.

Appears in:

Field	Description	Validation
`version` string	Version must match the administrator-observed snapshot source version.	Enum: [2.7.0 2.7.1]
`image` string	Image defaults to the version-derived image.	Optional: {}
`storage` StorageConfig
`tls` TLSConfig
`service` RestoreTargetServiceConfig	Service configures an optional ClusterIP Service for the destination. When omitted, the target has only its internal headless Service.	Optional: {}
`unseal` UnsealConfig	Unseal uses the same provider configuration as OpenBaoCluster. The target must be able to decrypt the snapshot with the original seal key material.
`serviceAccount` ServiceAccountConfig	ServiceAccount configures credentials supplied through workload identity.	Optional: {}
`podMetadata` PodMetadataConfig	PodMetadata supplies provider-specific workload identity metadata.	Optional: {}
`plugins` Plugin array	Plugins declares KMS seal plugins required by Unseal. OpenBao 2.7 requires plugins for AWS, Azure, GCP, OCI, and PKCS#11 seals.	Optional: {}
`configuration` RestoreTargetConfiguration	Configuration configures KMS plugin behavior for the target server.	Optional: {}
`resources` ResourceRequirements		Optional: {}
`initContainer` InitContainerConfig		Optional: {}
`imagePullSecrets` LocalObjectReference array		MaxItems: 2 Optional: {}

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:

OpenBaoClusterSpec

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 and sys/storage/raft/snapshot-force. The force endpoint supports explicitly requested break-glass restores.		Optional: {}

RestoreTargetConfiguration

RestoreTargetConfiguration exposes server settings needed by KMS seal plugins.

Appears in:

RestoreClusterTemplate

Field	Description	Default	Validation
`plugin` PluginConfig	Plugin controls downloads, registration, and file ownership for Plugins. Set autoDownload to true to download declared OCI plugins on startup.		Optional: {}

RestoreTargetServiceConfig

RestoreTargetServiceConfig selects destination client Service IP families. These settings do not change Pod IP allocation or the internal peer Service.

Appears in:

RestoreClusterTemplate

Field	Description	Default	Validation
`ipFamilyPolicy` IPFamilyPolicy	IPFamilyPolicy selects single-stack or dual-stack Service allocation. When omitted, Kubernetes uses its default Service policy. Two IP families require PreferDualStack or RequireDualStack.		Enum: [SingleStack PreferDualStack RequireDualStack] Optional: {}
`ipFamilies` IPFamily array	IPFamilies selects the Service IP families in primary-first order. The primary family cannot change after the Service is created.		MaxItems: 2 items:Enum: [IPv4 IPv6] Optional: {}

RestoreTest

RestoreTest schedules one disposable restore at a time. The destination must be an administrator-prepared operator-managed namespace.

Appears in:

BackupSchedule

Field	Description	Validation
`schedule` string	Schedule uses five-field cron syntax and UTC.	MaxLength: 128 MinLength: 1 Optional: {}
`everySuccessfulBackups` integer		Maximum: 10000 Minimum: 1 Optional: {}
`namespace` string		MaxLength: 63 MinLength: 1
`clusterTemplate` RestoreClusterTemplate
`credentialsSecretRef` LocalObjectReference	CredentialsSecretRef is the existing destination storage credential Secret. Storage connection settings are inherited from the source backup target.	Optional: {}
`serviceAccountName` string	ServiceAccountName selects an existing executor ServiceAccount in Namespace. The operator does not create, modify, or delete this account. It must have its own storage-reader identity; backup writer identities are not inherited.	MaxLength: 253 Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$` Optional: {}
`roleArn` string	RoleARN selects the S3 reader role independently of the backup writer role.	MinLength: 1 Optional: {}
`workloadIdentity` WorkloadIdentityConfig	WorkloadIdentity supplies destination reader metadata. ServiceAccount annotations must already exist on ServiceAccountName; PodLabels apply to the executor Pod. The operator does not update the existing account.	Optional: {}
`cleanupAfterSeconds` integer	CleanupAfterSeconds delays deletion after snapshot application to permit inspection.	Maximum: 86400 Minimum: 0 Optional: {}

RestoreTestOutcome

Underlying type: string

RestoreTestOutcome reports whether a disposable restore test passed or failed.

Validation:

Enum: [Passed Failed]

Appears in:

RestoreTestResult

Field	Description
`Passed`
`Failed`

RestoreTestResult

RestoreTestResult contains no secret data or authentication tokens.

Appears in:

RestoreTestStatus

Field	Description	Validation
`name` string	Name is the child OpenBaoRestore that produced this result.
`finishedAt` Time	FinishedAt records when the result was recorded.
`namespace` string	Namespace identifies the destination namespace.	Optional: {}
`key` string	Key identifies the tested snapshot object in backup storage.	Optional: {}
`digest` string	Digest is the pinned snapshot digest, when available.	Optional: {}
`reason` string	Reason and Message retain a bounded summary after the child is deleted. They contain operator-defined diagnostics, never provider responses or logs.	MaxLength: 64 Optional: {}
`message` string	Message contains the operator-defined diagnostic for this result.	MaxLength: 512 Optional: {}
`outcome` RestoreTestOutcome	Outcome is Passed or Failed.	Enum: [Passed Failed]

RestoreTestRun

RestoreTestRun reserves one child request and protects its source key.

Appears in:

RestoreTestStatus

Field	Description	Validation
`namespace` string	Namespace is the destination namespace of the child OpenBaoRestore.
`name` string	Name is the generated name of the child OpenBaoRestore.
`key` string	Key is the snapshot object under test; retention protects it until the run ends.
`startedAt` Time	StartedAt records when the run was reserved.
`uid` UID	UID identifies the child OpenBaoRestore once its creation is observed.	Optional: {}

RestoreTestStatus

RestoreTestStatus stores at most one active request and one last result.

Appears in:

BackupStatus

Field	Description	Validation
`active` RestoreTestRun		Optional: {}
`last` RestoreTestResult		Optional: {}
`lastSuccessTime` Time	LastSuccessTime survives later failures and controller restarts.	Optional: {}
`lastScheduledAt` Time	LastScheduledAt records the last time a restore test was started.	Optional: {}
`lastBackupCount` integer	LastBackupCount is the successful-backup count at the last started test.	Optional: {}
`conditions` Condition array	Conditions reports scheduling and restore test outcomes without secret data. The Passed condition summarizes the current state.	Optional: {}

RuntimeConfig

RuntimeConfig defines explicit runtime control requests for the OpenBao workload.

Appears in:

OpenBaoClusterSpec

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

S3TargetConfig

S3TargetConfig holds S3-specific configuration. Omitted fields use their top-level BackupTarget compatibility values; this block has no defaults.

Appears in:

BackupTarget

Field	Description	Validation
`region` string	Region is the AWS region for S3-compatible requests. It overrides region when configured. An empty value uses the default region, us-east-1.	Optional: {}
`usePathStyle` boolean	UsePathStyle selects path-style addressing. A configured false value overrides a true top-level usePathStyle value.	Optional: {}
`roleArn` string	RoleARN selects the IAM role assumed with the projected ServiceAccount token. It overrides roleArn when configured. An empty value disables the top-level roleArn path; other configured credentials still apply. A nonempty value is an explicit storage identity for the Hardened profile.	Optional: {}

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:

SelfInitRequest

Field	Description	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:

SelfInitRequest

Field	Description	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:

OpenBaoClusterSpec

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

SelfInitDataSource

SelfInitDataSource supplies one string field of a raw self-init request.

Appears in:

SelfInitRequest

Field	Description	Default	Validation
`secretKeyRef` SelfInitSecretKeyReference	SecretKeyRef selects a required Secret key in the OpenBaoCluster namespace.

SelfInitOIDCAdditionalSubjects

SelfInitOIDCAdditionalSubjects adds recovery-target identities to the generated Operator JWT roles without combining their policies.

Appears in:

SelfInitOIDCConfig

Field	Description	Validation
`operator` KubernetesServiceAccountSubject array	Operator lists additional controller ServiceAccount subjects.	MaxItems: 32 MaxLength: 340 Pattern: `^system:serviceaccount:[a-z0-9]([-a-z0-9][a-z0-9])?:[a-z0-9]([-a-z0-9.][a-z0-9])?$` Optional: {}
`backup` KubernetesServiceAccountSubject array	Backup lists additional backup Job ServiceAccount subjects.	MaxItems: 32 MaxLength: 340 Pattern: `^system:serviceaccount:[a-z0-9]([-a-z0-9][a-z0-9])?:[a-z0-9]([-a-z0-9.][a-z0-9])?$` Optional: {}
`restore` KubernetesServiceAccountSubject array	Restore lists additional restore Job ServiceAccount subjects.	MaxItems: 32 MaxLength: 340 Pattern: `^system:serviceaccount:[a-z0-9]([-a-z0-9][a-z0-9])?:[a-z0-9]([-a-z0-9.][a-z0-9])?$` Optional: {}
`upgrade` KubernetesServiceAccountSubject array	Upgrade lists additional upgrade Job ServiceAccount subjects.	MaxItems: 32 MaxLength: 340 Pattern: `^system:serviceaccount:[a-z0-9]([-a-z0-9][a-z0-9])?:[a-z0-9]([-a-z0-9.][a-z0-9])?$` Optional: {}

SelfInitOIDCConfig

SelfInitOIDCConfig configures OIDC identity for the cluster.

Appears in:

SelfInitConfig

Field	Description	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: {}
`additionalSubjects` SelfInitOIDCAdditionalSubjects	AdditionalSubjects adds exact Kubernetes ServiceAccount subjects to the generated Operator JWT roles. Use these bindings when a snapshot must remain operable after restore to a target with different ServiceAccount subjects. Configure the source cluster before self-initialization so the bindings are present in each snapshot. These bindings do not configure JWT issuer or signature verification for another Kubernetes control plane. The jwt-operator auth method must also trust the target’s projected ServiceAccount tokens.	Optional: {}

SelfInitOperation

Underlying type: string

SelfInitOperation defines valid operations for self-initialization requests.

Validation:

Enum: [create read update delete list patch]

Appears in:

SelfInitRequest

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/policy/

Appears in:

SelfInitRequest

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:

SelfInitConfig

Field	Description	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
`headers` object (keys:string, values:string array)	Headers contains additional HTTP headers to send with this self-init request. Requires OpenBao 2.6.0 or newer. Header names must not be empty. Values are rendered into OpenBao’s profile-engine `headers` request field as map[string][]string.	Optional: {}
`when` JSON	When controls whether OpenBao executes this request. Requires OpenBao 2.6.0 or newer. Omit it to execute the request. Set it to a JSON boolean for static gating or to an OpenBao profile value object for dynamic evaluation, for example {“eval_source”:“cel”,“eval_type”:“bool”,“expression”:“true”}.	Optional: {}
`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: {}
`dataFrom` object (keys:string, values:SelfInitDataSource)	DataFrom maps top-level request fields to required keys in same-namespace Secrets. Values are read as strings during first self-initialization. Requires OpenBao 2.6.0 or newer. Use only with raw request payloads, not auditDevice, authMethod, secretEngine, policy, or their reserved API paths. Field names must match ^[A-Za-z_][A-Za-z0-9_-]*$. A field must not occur in both data and dataFrom. All requests together can reference at most two distinct Secrets. Mappings, including their request and field names, are immutable after cluster creation. Self-init must be enabled at creation and until initialization completes. Missing inputs block startup before OpenBao initializes, including when when is false or allowFailure is true. Changes after initialization do not update OpenBao. The operator does not read or copy the Secret values.	MaxProperties: 64 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:

SelfInitRequest

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

SelfInitSecretKeyReference

SelfInitSecretKeyReference identifies a bootstrap input without containing its value.

Appears in:

SelfInitDataSource

Field	Description	Default	Validation
`name` string	Name is the Secret name. The submitting identity must be authorized to get it.		MaxLength: 253 MinLength: 1 Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`
`key` string	Key is the Secret data key. Its exact contents are used without trimming.		MaxLength: 253 MinLength: 1 Pattern: `^[-._a-zA-Z0-9]+$`

ServiceAccountConfig

ServiceAccountConfig configures the ServiceAccount used by OpenBao pods.

Appears in:

OpenBaoClusterSpec
RestoreClusterTemplate

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:

OpenBaoClusterSpec

Field	Description	Validation
`ipFamilyPolicy` IPFamilyPolicy	IPFamilyPolicy selects single-stack or dual-stack Service allocation. When omitted, Kubernetes uses its default Service policy. Two IP families require PreferDualStack or RequireDualStack.	Enum: [SingleStack PreferDualStack RequireDualStack] Optional: {}
`ipFamilies` IPFamily array	IPFamilies selects the Service IP families in primary-first order. The primary family cannot change after the Service is created.	MaxItems: 2 items:Enum: [IPv4 IPv6] Optional: {}
`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: {}

ServiceMonitorAuthorizationConfig

ServiceMonitorAuthorizationConfig configures Prometheus Operator endpoint authorization.

Appears in:

ServiceMonitorConfig

Field	Description	Default	Validation
`type` string	Type is the authorization type. Defaults to Bearer when credentialsSecret is set.		Optional: {}
`credentialsSecret` ServiceMonitorKeySelector	CredentialsSecret references a Secret key containing the authorization credentials. The Secret must exist in the same namespace as the ServiceMonitor.

ServiceMonitorConfig

ServiceMonitorConfig configures the Prometheus ServiceMonitor.

Appears in:

MetricsConfig

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: {}
`labels` object (keys:string, values:string)	Labels are added to the ServiceMonitor metadata. Use this for Prometheus selectors, such as release labels used by kube-prometheus-stack.		Optional: {}
`annotations` object (keys:string, values:string)	Annotations are added to the ServiceMonitor metadata.		Optional: {}
`jobLabel` string	JobLabel selects the Service label Prometheus uses as the job label. Defaults to app.kubernetes.io/name.		Optional: {}
`authorization` ServiceMonitorAuthorizationConfig	Authorization configures an optional ServiceMonitor authorization block. Use this for authenticated /v1/sys/metrics scraping.		Optional: {}
`tlsConfig` ServiceMonitorTLSConfig	TLSConfig configures TLS verification for the OpenBao scrape endpoint.		Optional: {}

ServiceMonitorKeySelector

ServiceMonitorKeySelector identifies a key in a Secret or ConfigMap.

Appears in:

ServiceMonitorAuthorizationConfig
ServiceMonitorTLSConfig

Field	Description	Default	Validation
`name` string	Name is the Secret or ConfigMap name.		MinLength: 1
`key` string	Key is the key within the Secret or ConfigMap. Defaults to token for authorization credentials and ca.crt for CA references.		Optional: {}

ServiceMonitorTLSConfig

ServiceMonitorTLSConfig configures TLS settings for the Prometheus Operator endpoint.

Appears in:

ServiceMonitorConfig

Field	Description	Validation
`serverName` string	ServerName verifies the hostname in the OpenBao serving certificate.	Optional: {}
`insecureSkipVerify` boolean	InsecureSkipVerify disables TLS certificate verification. Use only for temporary non-production environments. Hardened clusters reject insecureSkipVerify=true.	Optional: {}
`caConfigMap` ServiceMonitorKeySelector	CAConfigMap references a ConfigMap key containing the CA certificate. Mutually exclusive with CASecret.	Optional: {}
`caSecret` ServiceMonitorKeySelector	CASecret references a Secret key containing the CA certificate. Mutually exclusive with CAConfigMap.	Optional: {}

SocketAuditOptions

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

Appears in:

AuditDevice
SelfInitAuditDevice

Field	Description	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/

Appears in:

UnsealConfig

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:

OpenBaoClusterSpec
RestoreClusterTemplate

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:

AuditDevice
SelfInitAuditDevice

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:

OpenBaoClusterSpec
RestoreClusterTemplate

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether TLS is enabled for the cluster.		Required: {}
`mode` TLSMode	Mode controls who manages the certificate lifecycle.	OperatorManaged	Enum: [OperatorManaged External ACME] Optional: {}
`acme` ACMEConfig	ACME configures settings when Mode is ‘ACME’.		Optional: {}
`rotationPeriod` string	RotationPeriod is a duration string (for example, “720h”) controlling certificate rotation. Only used when Mode is OperatorManaged.		MinLength: 1 Optional: {}
`extraSANs` string array	ExtraSANs lists additional subject alternative names for server certificates. In OperatorManaged mode, the operator includes these names when issuing the certificate. In External mode, the operator requires the supplied certificate to contain them. Values that parse as IP addresses are treated as IP SANs; all other values are DNS SANs.		Optional: {}

TLSKeyExchangeGroup

Underlying type: string

TLSKeyExchangeGroup identifies a classical or hybrid post-quantum TLS group. Pure MLKEM1024 is not supported by the operator’s default TLS clients.

Validation:

Enum: [CurveP256 CurveP384 CurveP521 X25519 X25519MLKEM768 SecP256r1MLKEM768 SecP384r1MLKEM1024]

Appears in:

ListenerConfig

Field	Description
`CurveP256`
`CurveP384`
`CurveP521`
`X25519`
`X25519MLKEM768`
`SecP256r1MLKEM768`
`SecP384r1MLKEM1024`

TLSMode

Underlying type: string

TLSMode controls who manages the certificate lifecycle.

Validation:

Enum: [OperatorManaged External ACME]

Appears in:

TLSConfig

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.

TLSVersion

Underlying type: string

TLSVersion identifies a supported TLS protocol version.

Validation:

Enum: [tls12 tls13]

Appears in:

ListenerConfig

Field	Description
`tls12`	TLSVersion12 selects TLS 1.2.
`tls13`	TLSVersion13 selects TLS 1.3.

TelemetryConfig

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

Appears in:

OpenBaoClusterSpec

Field	Description	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:

UnsealConfig

Field	Description	Validation
`address` string	Address is the full HTTPS address to the OpenBao cluster providing the Transit seal.	MinLength: 1
`token` string	Token is the OpenBao token to use for authentication. Note: It is strongly recommended to use CredentialsSecretRef instead of setting this directly.	Optional: {}
`keyName` string	KeyName is the transit key to use for encryption and decryption.	MinLength: 1
`mountPath` string	MountPath is the mount path to the transit secret engine.	MinLength: 1
`namespace` string	Namespace is the namespace path to the transit secret engine.	Optional: {}
`disableRenewal` boolean	DisableRenewal disables automatic token renewal. Set to true if token lifecycle is managed externally (e.g., by OpenBao Agent).	Optional: {}
`tlsCACert` string	TLSCACert is the path to the CA certificate file for TLS communication.	Optional: {}
`tlsClientCert` string	TLSClientCert is the path to the client certificate for TLS communication.	Optional: {}
`tlsClientKey` string	TLSClientKey is the path to the private key for TLS communication.	Optional: {}
`tlsServerName` string	TLSServerName is the SNI host name to use when connecting via TLS.	Optional: {}
`tlsSkipVerify` boolean	TLSSkipVerify disables verification of TLS certificates. Using this option is highly discouraged and decreases security.	Optional: {}

UnsealConfig

UnsealConfig defines the auto-unseal configuration for an OpenBaoCluster. If omitted, defaults to “static” mode managed by the operator.

Appears in:

OpenBaoClusterSpec
RestoreClusterTemplate

Field	Description	Default	Validation
`type` string	Type specifies the seal type. Defaults to “static”.	static	Enum: [static awskms gcpckms azurekeyvault transit kmip kms ocikms pkcs11]
`static` StaticSealConfig	Static configures the static seal type. Optional when Type is “static” (operator provides defaults if omitted).		Optional: {}
`transit` TransitSealConfig	Transit configures the Transit seal type. Required when Type is “transit”.		Optional: {}
`awskms` AWSKMSSealConfig	AWSKMS configures the AWS KMS seal type. Required when Type is “awskms”.		Optional: {}
`azureKeyVault` AzureKeyVaultSealConfig	AzureKeyVault configures the Azure Key Vault seal type. Required when Type is “azurekeyvault”.		Optional: {}
`gcpCloudKMS` GCPCloudKMSSealConfig	GCPCloudKMS configures the GCP Cloud KMS seal type. Required when Type is “gcpckms”.		Optional: {}
`kmip` KMIPSealConfig	KMIP configures the KMIP seal type. Required when Type is “kmip”.		Optional: {}
`kms` KMSPluginSealConfig	KMS configures a plugin-backed KMS seal. Required when Type is “kms”.		Optional: {}
`ocikms` OCIKMSSealConfig	OCIKMS configures the OCI KMS seal type. Required when Type is “ocikms”.		Optional: {}
`pkcs11` PKCS11SealConfig	PKCS11 configures the PKCS#11 seal type. Required when Type is “pkcs11”.		Optional: {}
`credentialsSecretRef` LocalObjectReference	CredentialsSecretRef references a Secret containing provider credentials (for example AWS access keys, GCP credentials.json, Azure client-secret keys, OCI SDK config for authTypeAPIKey mode, or plugin-backed KMS runtime files). If using Workload Identity (IRSA, GKE WI, Azure MSI), this can be omitted. For static unseal, the Secret supplies the original key instead of an operator-generated key. Its files are mounted at /etc/bao/unseal; the default currentKey reads its “key” entry. The operator does not create, modify, or take ownership of this Secret. A cluster that already owns an operator-generated unseal key keeps that key and ignores this reference. The Secret must exist in the same namespace as the OpenBaoCluster. Cross-namespace references are not allowed for security reasons.		Optional: {}

UpdateStrategyType

Underlying type: string

UpdateStrategyType defines the type of update strategy to use.

Validation:

Enum: [RollingUpdate BlueGreen]

Appears in:

OpenBaoClusterStatus
UpgradeConfig

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:

OpenBaoClusterSpec

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, OPERATOR_UPGRADE_IMAGE can supply a complete image reference, including a digest. Otherwise, defaults to “<repo>:X.Y.Z” where <repo> is derived from OPERATOR_UPGRADE_IMAGE_REPOSITORY (default: “ghcr.io/kubebao/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 during initial SelfInit bootstrap and this field is empty, a default role named “openbao-operator-upgrade” will be created. For already-initialized clusters, configure this role explicitly or keep the default role created during initial bootstrap. This is the supported authentication mechanism for built-in upgrade orchestration.		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:

OpenBaoClusterStatus

Field	Description	Validation
`executionID` string	ExecutionID identifies the current rolling upgrade attempt. It remains stable across controller restarts and changes when a retry is accepted. Older in-flight upgrades can omit it until an explicit retry is accepted.	Optional: {}
`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: {}

UpgradeRequestConfig

UpgradeRequestConfig defines one-shot operator requests for upgrade workflows.

Appears in:

UpgradeConfig

Field	Description	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:

OpenBaoClusterStatus

Field	Description	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:

VerificationConfig

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:

BlueGreenConfig

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. The operator assigns the hook a stable identity for each upgrade attempt. It does not recreate a missing Job after Job creation is committed.		Optional: {}

WorkloadControllerStatus

WorkloadControllerStatus holds status owned by the workload controller.

Appears in:

OpenBaoClusterStatus

Field	Description	Validation
`policyRevision` string	PolicyRevision identifies the last complete built-in policy bundle verified or repaired successfully. This records reconciliation progress, not authorization.	Optional: {}
`policyReconciliation` PolicyReconciliationStatus	PolicyReconciliation records individual policy observations and retry scheduling.	Optional: {}
`lastError` ControllerErrorStatus	LastError is the last workload-controller error observed for this cluster.	Optional: {}

WorkloadHardeningConfig

WorkloadHardeningConfig configures optional workload hardening features.

Appears in:

OpenBaoClusterSpec

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:

BackupTarget
RestoreTest

Field	Description	Default	Validation
`serviceAccountAnnotations` object (keys:string, values:string)	ServiceAccountAnnotations are merged into the generated backup or restore ServiceAccount. An existing restore executor ServiceAccount must already have these annotations; the operator validates them without modifying that account. This is typically used for provider-specific bindings such as GKE Workload Identity or webhook-based AWS/Azure workload identity integrations.		Optional: {}
`podLabels` object (keys:string, values:string)	PodLabels are merged into the generated backup or restore Job pod template. This is typically used for provider-specific selectors such as Azure Workload Identity. Operator-managed labels take precedence if the same key is specified here.		Optional: {}