API Reference

Use the API reference when you need the exact CRD field contract.

This page is generated from api/v1alpha1 and is the source of truth for field-level schema, validation, and description details across the operator CRDs.

Generated file

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

CRDs

OpenBaoCluster

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

ACMESharedCacheConfig

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

Appears in:

• ACMEConfig

Field	Description	Default	Validation
mode ACMESharedCacheMode	Mode selects whether the operator creates a dedicated RWX PVC or mounts an existing one.		Enum: [ManagedPVC ExistingPVC]
existingClaimName string	ExistingClaimName is the name of a pre-created RWX PVC in the same namespace. Required when Mode is ExistingPVC.		MinLength: 1 Optional: {}
size string	Size is the requested capacity for the managed ACME cache PVC. Required when Mode is ManagedPVC.		MinLength: 1 Optional: {}
storageClassName string	StorageClassName is an optional StorageClass for the managed ACME cache PVC.		Optional: {}

ACMESharedCacheMode

Underlying type: string

ACMESharedCacheMode controls how the operator provides a shared filesystem for OpenBao's ACME cache.

Validation:

• Enum: [ManagedPVC ExistingPVC]

Appears in:

• 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.

AWSKMSSealConfig

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

Appears in:

• UnsealConfig

Field	Description	Default	Validation
region string	Region is the AWS region where the encryption key lives.		MinLength: 1
kmsKeyID string	KMSKeyID is the AWS KMS key ID or ARN to use for encryption and decryption. An alias in the format "alias/key-alias-name" may also be used.		MinLength: 1
endpoint string	Endpoint is the KMS API endpoint to be used for AWS KMS requests. Useful when connecting to KMS over a VPC Endpoint.		Optional: {}
accessKey string	AccessKey is the AWS access key ID to use. Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity (IRSA) instead.		Optional: {}
secretKey string	SecretKey is the AWS secret access key to use. Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity (IRSA) instead.		Optional: {}
sessionToken string	SessionToken specifies the AWS session token.		Optional: {}

AdminOpsControllerStatus

AdminOpsControllerStatus holds status owned by the adminops controller.

Appears in:

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

AutoRollbackConfig

AutoRollbackConfig defines conditions that trigger automatic rollback.

Appears in:

• BlueGreenConfig

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

AzureKeyVaultSealConfig

AzureKeyVaultSealConfig configures the Azure Key Vault seal type. See: https://openbao.org/docs/configuration/seal/azurekeyvault/

Appears in:

• UnsealConfig

Field	Description	Default	Validation
vaultName string	VaultName is the name of the Azure Key Vault.		MinLength: 1
keyName string	KeyName is the name of the key in the Azure Key Vault.		MinLength: 1
tenantID string	TenantID is the Azure tenant ID.		Optional: {}
clientID string	ClientID is the Azure client ID.		Optional: {}
clientSecret string	ClientSecret is the Azure client secret. Note: It is strongly recommended to use CredentialsSecretRef or Managed Service Identity instead.		Optional: {}
resource string	Resource is the Azure AD resource endpoint. For Managed HSM, this should usually be "managedhsm.azure.net".		Optional: {}
environment string	Environment is the Azure environment (e.g., "AzurePublicCloud", "AzureUSGovernmentCloud").		Optional: {}

AzureTargetConfig

AzureTargetConfig holds Azure Blob Storage specific configuration.

Appears in:

• 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 the blob container name. If empty, uses the Bucket field value.		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).	true	Optional: {}
hostname string	Hostname is the hostname to verify in the backend certificate. If not specified, defaults to the Service DNS name: <service-name>.<namespace>.svc This should match the certificate SAN or the service DNS name.		Optional: {}

BackupRetention

BackupRetention defines retention policy for backups.

Appears in:

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

BackupSchedule

BackupSchedule defines when and where snapshots are stored.

Appears in:

• OpenBaoClusterSpec

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

BackupStatus

BackupStatus tracks the state of backups for a cluster.

Appears in:

• OpenBaoClusterStatus

Field	Description	Default	Validation
lastBackupTime Time	LastBackupTime is the timestamp of the last successful backup.		Optional: {}
lastAttemptTime Time	LastAttemptTime is the timestamp of the last backup attempt, regardless of outcome. This is used to avoid retry loops when a scheduled backup fails.		Optional: {}
lastAttemptScheduledTime Time	LastAttemptScheduledTime is the scheduled time of the last backup attempt. It is derived from the cron schedule and used to ensure at-most-once execution per scheduled window.		Optional: {}
lastBackupSize integer	LastBackupSize is the size in bytes of the last successful backup.		Optional: {}
lastBackupDuration string	LastBackupDuration is how long the last backup took (e.g., "45s").		Optional: {}
lastBackupName string	LastBackupName is the object key/path of the last successful backup.		Optional: {}
nextScheduledBackup Time	NextScheduledBackup is when the next backup is scheduled.		Optional: {}
consecutiveFailures integer	ConsecutiveFailures is the number of consecutive backup failures.		Optional: {}
lastFailureReason string	LastFailureReason describes why the last backup failed (if applicable).		Optional: {}

BackupTarget

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

Appears in:

• BackupSchedule
• RestoreSource

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

BlueGreenConfig

BlueGreenConfig configures the behavior when Type is BlueGreen.

Appears in:

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

BreakGlassReason

Underlying type: string

BreakGlassReason describes why the operator required manual intervention.

Validation:

• Enum: [RollbackConsensusRepairFailed]

Appears in:

• BreakGlassStatus

Field	Description
RollbackConsensusRepairFailed

BreakGlassStatus

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

Appears in:

• OpenBaoClusterStatus

Field	Description	Default	Validation
active boolean	Active indicates whether break glass mode is currently active.		Optional: {}
reason BreakGlassReason	Reason is a stable, typed reason for entering break glass mode.		Enum: [RollbackConsensusRepairFailed] 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

ControllerErrorStatus

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

Appears in:

• AdminOpsControllerStatus
• WorkloadControllerStatus

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

DeletionPolicy

Underlying type: string

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

Validation:

• Enum: [Retain DeletePVCs DeleteAll]

Appears in:

• OpenBaoClusterSpec

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

FileAuditOptions

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

Appears in:

• 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	Default	Validation
project string	Project is the GCP project ID.		MinLength: 1
region string	Region is the GCP region where the key ring lives.		MinLength: 1
keyRing string	KeyRing is the name of the GCP KMS key ring.		MinLength: 1
cryptoKey string	CryptoKey is the name of the GCP KMS crypto key.		MinLength: 1
credentials string	Credentials is the path to the GCP credentials JSON file. Note: It is strongly recommended to use CredentialsSecretRef or Workload Identity instead.		Optional: {}

GCSTargetConfig

GCSTargetConfig holds Google Cloud Storage specific configuration.

Appears in:

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

GatewayReference

GatewayReference identifies a Gateway resource.

Appears in:

• 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.		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/dc-tec/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: {}
tlsSecretName string	TLSSecretName is an optional TLS Secret name; when empty the cluster TLS Secret is used.		Optional: {}
annotations object (keys:string, values:string)	Annotations are additional annotations to apply to the Ingress.		Optional: {}

InitContainerConfig

InitContainerConfig configures the init container used to render OpenBao configuration. The init container is responsible for rendering the final config.hcl from a template using environment variables such as HOSTNAME and POD_IP.

The operator relies on this init container to render config.hcl at runtime. Disabling the init container is not supported and will be rejected by validation.

Appears in:

• OpenBaoClusterSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether the init container is used to render the configuration. The operator requires the init container; disabling it is not supported.	true	Optional: {}
image string	Image is the container image to use for the init container. If not specified, defaults to "<repo>:X.Y.Z" where <repo> is derived from OPERATOR_INIT_IMAGE_REPOSITORY (default: "ghcr.io/dc-tec/openbao-init") and the tag matches OPERATOR_VERSION.		Optional: {}

KMIPSealConfig

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

Appears in:

• UnsealConfig

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

ListenerConfig

ListenerConfig allows tuning the TCP listener configuration.

Appears in:

• OpenBaoConfiguration

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

LoggingConfig

LoggingConfig allows configuring logging behavior for OpenBao.

Appears in:

• OpenBaoConfiguration

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

MaintenanceConfig

MaintenanceConfig defines supported maintenance and restart 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: {}
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: {}

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
serviceMonitor ServiceMonitorConfig	ServiceMonitor controls whether to create a Prometheus Operator ServiceMonitor.		Optional: {}

NetworkConfig

NetworkConfig configures network-related settings for the OpenBaoCluster.

Appears in:

• OpenBaoClusterSpec

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

OCIKMSSealConfig

OCIKMSSealConfig configures the OCI KMS seal type. See: https://openbao.org/docs/configuration/seal/ocikms/

Appears in:

• UnsealConfig

Field	Description	Default	Validation
keyID string	KeyID is the OCID of the master encryption key.		MinLength: 1
cryptoEndpoint string	CryptoEndpoint is the OCI KMS crypto endpoint.		MinLength: 1
managementEndpoint string	ManagementEndpoint is the OCI KMS management endpoint.		MinLength: 1
authTypeAPIKey boolean	AuthTypeAPIKey enables OCI API key authentication through an OCI SDK config file. When false or omitted, OpenBao uses the default OCI principal flow for the runtime environment, such as instance principal.		Optional: {}
disabled boolean	Disabled disables this seal configuration, for example during seal migration.		Optional: {}

ObservabilityConfig

ObservabilityConfig configures observability features.

Appears in:

• 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	Default	Validation
apiVersion string	openbao.org/v1alpha1
kind string	OpenBaoCluster
spec OpenBaoClusterSpec	Spec defines the desired state of OpenBaoCluster.
status OpenBaoClusterStatus	Status defines the observed state of OpenBaoCluster.		Optional: {}

OpenBaoClusterSpec

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

Appears in:

• 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
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 OpenBao pods.	3	Minimum: 1
paused boolean	Paused, when true, pauses reconciliation for this OpenBaoCluster (except delete and finalizers).		Optional: {}
maintenance MaintenanceConfig	Maintenance configures supported maintenance and restart workflows.		Optional: {}
breakGlassAck string	BreakGlassAck is an explicit acknowledgment token used to exit Break Glass / Safe Mode. When the operator enters break glass mode, it writes a nonce to status.breakGlass.nonce. To acknowledge and allow the operator to resume quorum-risk automation, set this field to match that nonce. Example: kubectl -n <ns> patch openbaocluster <name> --type merge -p '{"spec":{"breakGlassAck":"<nonce>"}}'		Optional: {}
tls TLSConfig	TLS configures TLS for the cluster.
storage StorageConfig	Storage configures persistent storage for the cluster.
service ServiceConfig	Service configures the primary Service used to expose OpenBao inside or outside the cluster.		Optional: {}
ingress IngressConfig	Ingress configures optional HTTP(S) ingress in front of the OpenBao Service.		Optional: {}
configuration OpenBaoConfiguration	Configuration defines the server configuration.		Optional: {}
backup BackupSchedule	Backup configures scheduled backups for the cluster.		Optional: {}
restore RestoreConfig	Restore configures optional restore authentication bootstrap for the cluster.		Optional: {}
deletionPolicy DeletionPolicy	DeletionPolicy controls what happens to underlying resources when the CR is deleted.		Enum: [Retain DeletePVCs DeleteAll] Optional: {}
selfInit SelfInitConfig	SelfInit configures OpenBao's native self-initialization feature. When enabled, OpenBao initializes itself on first start using the configured requests, and the root token is automatically revoked. See: https://openbao.org/docs/configuration/self-init/		Optional: {}
gateway GatewayConfig	Gateway configures Kubernetes Gateway API access (alternative to Ingress). When enabled, the Operator creates an HTTPRoute that routes traffic through a user-managed Gateway resource.		Optional: {}
network NetworkConfig	Network configures network-related settings for the cluster.		Optional: {}
initContainer InitContainerConfig	InitContainer configures the init container used to render OpenBao configuration. The init container renders the final config.hcl from a template using environment variables such as HOSTNAME and POD_IP.		Optional: {}
audit AuditDevice array	Audit configures declarative audit devices for the OpenBao cluster. See: https://openbao.org/docs/configuration/audit/		Optional: {}
plugins Plugin array	Plugins configures declarative plugins for the OpenBao cluster. See: https://openbao.org/docs/configuration/plugins/		Optional: {}
telemetry TelemetryConfig	Telemetry configures telemetry reporting for the OpenBao cluster. See: https://openbao.org/docs/configuration/telemetry/		Optional: {}
upgrade UpgradeConfig	Upgrade configures upgrade operations. Built-in upgrade executor Jobs authenticate with JWT auth using the upgrade ServiceAccount (<cluster-name>-upgrade-serviceaccount). If spec.selfInit.oidc.enabled is true and spec.upgrade.jwtAuthRole is empty, the operator assumes or bootstraps the default "openbao-operator-upgrade" role. Pre-upgrade snapshots use spec.backup configuration and backup authentication rather than spec.upgrade credentials.		Optional: {}
unseal UnsealConfig	Unseal defines the auto-unseal configuration. If omitted, defaults to "static" mode managed by the operator.		Optional: {}
imageVerification ImageVerificationConfig	ImageVerification configures supply chain security checks.		Optional: {}
operatorImageVerification ImageVerificationConfig	OperatorImageVerification configures supply chain security checks for operator-managed helper images (init container, backup/upgrade/restore executors). These images are typically signed by the operator project (e.g., dc-tec/openbao-operator) rather than the OpenBao upstream project. If omitted, helper image verification does not fall back to ImageVerification. In Development, omitted means disabled. In Hardened, omitted means enabled.		Optional: {}
workloadHardening WorkloadHardeningConfig	WorkloadHardening configures opt-in workload hardening features.		Optional: {}
securityContext PodSecurityContext	SecurityContext allows specifying the PodSecurityContext for the OpenBao Pods. If set, these values override the default security context generated by the operator. This is useful for OpenShift (SCC) compatibility or custom security requirements.		Optional: {}
profile Profile	Profile defines the security posture for this cluster. When set to "Hardened", the operator enforces strict security requirements: - TLS must be External (cert-manager/CSI managed) - Unseal must use external KMS (no static unseal) - SelfInit must be enabled (no root token) When set to "Development", relaxed security is allowed but a security warning condition is set.		Enum: [Hardened Development]

OpenBaoClusterStatus

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

Appears in:

• OpenBaoCluster

Field	Description	Default	Validation
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: {}
currentVersion string	CurrentVersion is the OpenBao version currently running on the cluster.		Optional: {}
initialized boolean	Initialized indicates whether the OpenBao cluster has been initialized. This is set to true after the first pod is initialized using bao operator init or after self-initialization completes.		Optional: {}
selfInitialized boolean	SelfInitialized indicates whether the cluster was initialized using OpenBao's self-initialization feature. When true, no root token Secret exists for this cluster (the root token was auto-revoked).		Optional: {}
lastBackupTime Time	LastBackupTime is the timestamp of the last successful backup, if configured. Deprecated: Use Backup.LastBackupTime instead.		Optional: {}
upgrade UpgradeProgress	Upgrade tracks the state of an in-progress upgrade (if any). When non-nil, an upgrade is in progress and the UpgradeManager is orchestrating the pod-by-pod rolling update with leader step-down.		Optional: {}
upgradeRequests UpgradeRequestStatus	UpgradeRequests tracks which explicit upgrade request values have already been handled so one-shot requests are edge-triggered instead of level-triggered.		Optional: {}
backup BackupStatus	Backup tracks the state of backups for this cluster.		Optional: {}
blueGreen BlueGreenStatus	BlueGreen tracks the state of blue/green upgrades (if enabled).		Optional: {}
operationLock OperationLockStatus	OperationLock prevents concurrent long-running operations (upgrade/backup/restore) from acting on the same cluster at the same time.		Optional: {}
breakGlass BreakGlassStatus	BreakGlass records when the operator has halted quorum-risk automation and requires explicit operator acknowledgment to continue.		Optional: {}
workload WorkloadControllerStatus	Workload holds signals owned by the workload controller (infrastructure reconciliation).		Optional: {}
adminOps AdminOpsControllerStatus	AdminOps holds signals owned by the adminops controller (upgrade + backup).		Optional: {}
conditions Condition array	Conditions represent the current state of the OpenBaoCluster resource.		Optional: {}

OpenBaoConfiguration

OpenBaoConfiguration defines the server configuration for OpenBao.

Appears in:

• 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.		Optional: {}
rawStorageEndpoint boolean	RawStorageEndpoint enables the raw storage endpoint. This is an experimental feature that exposes raw storage operations.		Optional: {}
introspectionEndpoint boolean	IntrospectionEndpoint enables the introspection endpoint. This is an experimental feature for debugging and introspection.		Optional: {}
impreciseLeaseRoleTracking boolean	ImpreciseLeaseRoleTracking enables imprecise lease role tracking. This is an experimental feature that may improve performance in some scenarios.		Optional: {}
unsafeAllowAPIAuditCreation boolean	UnsafeAllowAPIAuditCreation allows API-based audit device creation. This bypasses the normal audit device configuration validation. Use with caution.		Optional: {}
allowAuditLogPrefixing boolean	AllowAuditLogPrefixing allows audit log prefixing. This enables custom prefixes in audit log entries.		Optional: {}
enableResponseHeaderHostname boolean	EnableResponseHeaderHostname enables the hostname in response headers. When true, OpenBao includes the hostname in HTTP response headers.		Optional: {}
enableResponseHeaderRaftNodeID boolean	EnableResponseHeaderRaftNodeID enables the Raft node ID in response headers. When true, OpenBao includes the Raft node ID in HTTP response headers.		Optional: {}

OperationLockStatus

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

Appears in:

• OpenBaoClusterStatus

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

PKCS11SealConfig

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

Appears in:

• UnsealConfig

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

Plugin

Plugin defines a declarative plugin configuration. See: https://openbao.org/docs/configuration/plugins/

Appears in:

• OpenBaoClusterSpec

Field	Description	Default	Validation
type string	Type is the plugin type (e.g., "secret", "auth").		MinLength: 1
name string	Name is the name of the plugin.		MinLength: 1
image string	Image is the OCI image URL including registry and repository. Required if Command is not set. Conflicts with Command.		Optional: {}
command string	Command is the command name of a manually downloaded plugin. Required if Image is not set. Conflicts with Image.		Optional: {}
version string	Version is the image version or tag.		MinLength: 1
binaryName string	BinaryName is the name of the plugin binary file within the OCI image.		MinLength: 1
sha256sum string	SHA256Sum is the expected SHA256 checksum of the plugin binary. Must be a 64-character hexadecimal string.		MaxLength: 64 MinLength: 64 Pattern: ^[0-9a-fA-F]\{64\}$
args string array	Args are arguments to pass to the running plugin. Only used if plugin_auto_register=true is set.		Optional: {}
env string array	Env are environment variables to pass to the running plugin. Only used if plugin_auto_register=true is set.		Optional: {}

PluginConfig

PluginConfig allows configuring plugin behavior.

Appears in:

• OpenBaoConfiguration

Field	Description	Default	Validation
fileUID integer	FileUID is the UID to use for plugin files.		Optional: {}
filePermissions string	FilePermissions are the file permissions for plugin files (e.g., "0755").		Optional: {}
autoDownload boolean	AutoDownload controls automatic plugin downloads from OCI registries.		Optional: {}
autoRegister boolean	AutoRegister controls automatic plugin registration.		Optional: {}
downloadBehavior string	DownloadBehavior specifies how plugins are downloaded.		Enum: [standard direct] Optional: {}

PodMetadataConfig

PodMetadataConfig configures additional metadata for the OpenBao Pod template.

Appears in:

• OpenBaoClusterSpec

Field	Description	Default	Validation
labels object (keys:string, values:string)	Labels are merged into the generated OpenBao Pod template labels. Operator-managed labels take precedence if the same key is specified here.		Optional: {}
annotations object (keys:string, values:string)	Annotations are merged into the generated OpenBao Pod template annotations. Operator-managed annotations take precedence if the same key is specified here.		Optional: {}

Profile

Underlying type: string

Profile defines the security posture for an OpenBaoCluster.

Validation:

• Enum: [Hardened Development]

Appears in:

• OpenBaoClusterSpec

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

RaftAutopilotConfig

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

Appears in:

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

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

SelfInitAuthMethod

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

Appears in:

• SelfInitRequest

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

SelfInitConfig

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

Appears in:

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

SelfInitOIDCConfig

SelfInitOIDCConfig configures OIDC identity for the cluster.

Appears in:

• SelfInitConfig

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

SelfInitOperation

Underlying type: string

SelfInitOperation defines valid operations for self-initialization requests.

Validation:

• Enum: [create read update delete list patch]

Appears in:

• 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/policies-acl/

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

SelfInitSecretEngine

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

Appears in:

• SelfInitRequest

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

ServiceAccountConfig

ServiceAccountConfig configures the ServiceAccount used by OpenBao pods.

Appears in:

• OpenBaoClusterSpec

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	Default	Validation
type ServiceType	Type is the Kubernetes Service type, for example "ClusterIP" or "LoadBalancer".		Optional: {}
annotations object (keys:string, values:string)	Annotations are additional annotations to apply to the Service.		Optional: {}

ServiceMonitorConfig

ServiceMonitorConfig configures the Prometheus ServiceMonitor.

Appears in:

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

SocketAuditOptions

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

Appears in:

• AuditDevice
• SelfInitAuditDevice

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

StaticSealConfig

StaticSealConfig configures the static seal type. This is the default seal type managed by the operator. See: https://openbao.org/docs/configuration/seal/static-key/

Appears in:

• 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

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

Field	Description	Default	Validation
enabled boolean	Enabled controls whether TLS is enabled for the cluster.		Required: {}
mode TLSMode	Mode controls who manages the certificate lifecycle.	OperatorManaged	Enum: [OperatorManaged External ACME] Optional: {}
acme ACMEConfig	ACME configures settings when Mode is 'ACME'.		Optional: {}
rotationPeriod string	RotationPeriod is a duration string (for example, "720h") controlling certificate rotation. Only used when Mode is OperatorManaged.		MinLength: 1 Optional: {}
extraSANs string array	ExtraSANs lists additional subject alternative names to include in server certificates. Only used when Mode is OperatorManaged.		Optional: {}

TLSMode

Underlying type: string

TLSMode controls who manages the certificate lifecycle.

Validation:

• Enum: [OperatorManaged External ACME]

Appears in:

• 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.

TelemetryConfig

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

Appears in:

• OpenBaoClusterSpec

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

TransitSealConfig

TransitSealConfig configures the Transit seal type. See: https://openbao.org/docs/configuration/seal/transit/

Appears in:

• UnsealConfig

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

UnsealConfig

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

Appears in:

• OpenBaoClusterSpec

Field	Description	Default	Validation
type string	Type specifies the seal type. Defaults to "static".	static	Enum: [static awskms gcpckms azurekeyvault transit kmip ocikms pkcs11]
static StaticSealConfig	Static configures the static seal type. Optional when Type is "static" (operator provides defaults if omitted).		Optional: {}
transit TransitSealConfig	Transit configures the Transit seal type. Required when Type is "transit".		Optional: {}
awskms AWSKMSSealConfig	AWSKMS configures the AWS KMS seal type. Required when Type is "awskms".		Optional: {}
azureKeyVault AzureKeyVaultSealConfig	AzureKeyVault configures the Azure Key Vault seal type. Required when Type is "azurekeyvault".		Optional: {}
gcpCloudKMS GCPCloudKMSSealConfig	GCPCloudKMS configures the GCP Cloud KMS seal type. Required when Type is "gcpckms".		Optional: {}
kmip KMIPSealConfig	KMIP configures the KMIP seal type. Required when Type is "kmip".		Optional: {}
ocikms OCIKMSSealConfig	OCIKMS configures the OCI KMS seal type. Required when Type is "ocikms".		Optional: {}
pkcs11 PKCS11SealConfig	PKCS11 configures the PKCS#11 seal type. Required when Type is "pkcs11".		Optional: {}
credentialsSecretRef LocalObjectReference	CredentialsSecretRef references a Secret containing provider credentials (for example AWS access keys, GCP credentials.json, Azure client-secret keys, or OCI SDK config for authTypeAPIKey mode). If using Workload Identity (IRSA, GKE WI, Azure MSI), this can be omitted. The Secret must exist in the same namespace as the OpenBaoCluster. Cross-namespace references are not allowed for security reasons.		Optional: {}

UpdateStrategyType

Underlying type: string

UpdateStrategyType defines the type of update strategy to use.

Validation:

• Enum: [RollingUpdate BlueGreen]

Appears in:

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

UpgradeProgress

UpgradeProgress tracks the state of an in-progress upgrade.

Appears in:

• OpenBaoClusterStatus

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

UpgradeRequestConfig

UpgradeRequestConfig defines one-shot operator requests for upgrade workflows.

Appears in:

• UpgradeConfig

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

UpgradeRequestStatus

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

Appears in:

• OpenBaoClusterStatus

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

ValidationHookConfig

ValidationHookConfig defines a user-supplied validation Job.

Appears in:

• 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.		Optional: {}

WorkloadControllerStatus

WorkloadControllerStatus holds status owned by the workload controller.

Appears in:

• OpenBaoClusterStatus

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

WorkloadHardeningConfig

WorkloadHardeningConfig configures optional workload hardening features.

Appears in:

• 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

Field	Description	Default	Validation
serviceAccountAnnotations object (keys:string, values:string)	ServiceAccountAnnotations are merged into the generated backup or restore ServiceAccount. This is typically used for provider-specific bindings such as GKE Workload Identity or webhook-based AWS/Azure workload identity integrations.		Optional: {}
podLabels object (keys:string, values:string)	PodLabels are merged into the generated backup or restore Job pod template. This is typically used for provider-specific selectors such as Azure Workload Identity. Operator-managed labels take precedence if the same key is specified here.		Optional: {}

OpenBaoRestore

Packages

• openbao.org/v1alpha1

openbao.org/v1alpha1

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

Resource Types

• OpenBaoRestore

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 the blob container name. If empty, uses the Bucket field value.		Optional: {}

BackupTarget

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

Appears in:

• BackupSchedule
• RestoreSource

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

GCSTargetConfig

GCSTargetConfig holds Google Cloud Storage specific configuration.

Appears in:

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

OpenBaoRestore

OpenBaoRestore represents a request to restore an OpenBao cluster from a snapshot. This resource is immutable after creation - it acts as a "job request".

Field	Description	Default	Validation
apiVersion string	openbao.org/v1alpha1
kind string	OpenBaoRestore
spec OpenBaoRestoreSpec
status OpenBaoRestoreStatus

OpenBaoRestoreSpec

OpenBaoRestoreSpec defines the desired state for a restore operation. An OpenBaoRestore acts as a "job request" - it is immutable after creation.

Appears in:

• OpenBaoRestore

Field	Description	Default	Validation
cluster string	Cluster is the name of the OpenBaoCluster to restore INTO. Must exist in the same namespace as the OpenBaoRestore.		MinLength: 1
source RestoreSource	Source defines where the snapshot comes from.
jwtAuthRole string	JWTAuthRole is the name of the JWT Auth role configured in OpenBao for restore operations. When set, the restore executor will use JWT Auth (projected ServiceAccount token) instead of a static token. The role must be configured in OpenBao and must grant the "update" capability on sys/storage/raft/snapshot-force. The role must bind to the restore ServiceAccount (<cluster-name>-restore-serviceaccount) in the cluster namespace. If this field is empty and the target OpenBaoCluster has OIDC enabled, the operator will default to using the "openbao-operator-restore" role.		Optional: {}
tokenSecretRef LocalObjectReference	TokenSecretRef optionally references a Secret containing an OpenBao API token to use for restore operations (fallback method). The Secret must exist in the same namespace as the OpenBaoRestore. Cross-namespace references are not allowed for security reasons. The token must have permission to update sys/storage/raft/snapshot-force. If JWTAuthRole is set, this field is ignored in favor of JWT Auth.		Optional: {}
image string	Image is the container image to use for restore operations. Defaults to the same image used for backup operations if not specified. If the target OpenBaoCluster has image verification enabled, the operator will verify this image and pin the restore Job to the verified digest.		MinLength: 1 Optional: {}
force boolean	Force allows restore even if the cluster appears unhealthy. This is required for disaster recovery scenarios where the cluster may be in a degraded state.	false	Optional: {}
overrideOperationLock boolean	OverrideOperationLock allows the restore controller to clear an active cluster operation lock (upgrade/backup) and proceed with restore. This is a break-glass escape hatch intended for disaster recovery. For safety, this requires force: true. When used, the controller emits a Warning event and records a Condition on the OpenBaoRestore.	false	Optional: {}

OpenBaoRestoreStatus

OpenBaoRestoreStatus defines the observed state of OpenBaoRestore.

Appears in:

• OpenBaoRestore

Field	Description	Default	Validation
phase RestorePhase	Phase represents the current phase of the restore operation.	Pending	Enum: [Pending Validating Running Completed Failed]
startTime Time	StartTime is when the restore operation started.		Optional: {}
completionTime Time	CompletionTime is when the restore operation completed (success or failure).		Optional: {}
snapshotKey string	SnapshotKey is the key of the snapshot that was restored.		Optional: {}
snapshotSize integer	SnapshotSize is the size of the restored snapshot in bytes.		Optional: {}
message string	Message provides additional details about the current phase.		Optional: {}
conditions Condition array	Conditions represent the latest available observations of the restore's state.		Optional: {}

RestorePhase

Underlying type: string

RestorePhase represents the current phase of a restore operation.

Validation:

• Enum: [Pending Validating Running Completed Failed]

Appears in:

• OpenBaoRestoreStatus

Field	Description
Pending	RestorePhasePending indicates the restore has been created but not yet started.
Validating	RestorePhaseValidating indicates the controller is validating preconditions.
Running	RestorePhaseRunning indicates the restore job is executing.
Completed	RestorePhaseCompleted indicates the restore completed successfully.
Failed	RestorePhaseFailed indicates the restore failed.

RestoreSource

RestoreSource defines where the snapshot comes from.

Appears in:

• OpenBaoRestoreSpec

Field	Description	Default	Validation
target BackupTarget	Target reuses BackupTarget for storage connection details. This includes endpoint, bucket, region, credentials, etc.
key string	Key is the full path to the snapshot object in the bucket. For example, "clusters/prod/2025-10-14-120000.snap".		MinLength: 1

WorkloadIdentityConfig

WorkloadIdentityConfig configures cloud workload identity metadata for backup and restore workloads.

Appears in:

• BackupTarget

Field	Description	Default	Validation
serviceAccountAnnotations object (keys:string, values:string)	ServiceAccountAnnotations are merged into the generated backup or restore ServiceAccount. This is typically used for provider-specific bindings such as GKE Workload Identity or webhook-based AWS/Azure workload identity integrations.		Optional: {}
podLabels object (keys:string, values:string)	PodLabels are merged into the generated backup or restore Job pod template. This is typically used for provider-specific selectors such as Azure Workload Identity. Operator-managed labels take precedence if the same key is specified here.		Optional: {}

OpenBaoTenant

Packages

• openbao.org/v1alpha1

openbao.org/v1alpha1

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

Resource Types

• OpenBaoTenant

OpenBaoTenant

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

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

OpenBaoTenantSpec

OpenBaoTenantSpec defines the desired state of OpenBaoTenant.

Appears in:

• OpenBaoTenant

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

OpenBaoTenantStatus

OpenBaoTenantStatus defines the observed state of OpenBaoTenant.

Appears in:

• OpenBaoTenant

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