Tune the server runtime without turning this page into a dump of every field.

Use this page for the settings that shape how the OpenBao server itself runs: listener and lease behavior, Raft autopilot, audit devices, and plugin registration. Exposure, observability, and mirrored-image strategy each have their own configuration paths.

Decision matrix

What this page owns

What this page owns.

Surface	Use it for	Do not use it for
spec.configuration	Listener behavior, UI, cache and lease settings, and Raft/autopilot tuning.	Edge exposure patterns or gateway wiring.
spec.audit	Declarative audit-device setup that should exist when the cluster starts.	General telemetry or metrics wiring.
spec.plugins and plugin download settings	Explicit OpenBao plugin registration and plugin fetch behavior.	Mirrored base images or disconnected-registry strategy for the whole deployment.
Raft autopilot	Membership safety, dead-peer cleanup, and quorum behavior.	Application-level backup, upgrade, or restore workflows.

Use the focused pages for adjacent concerns

• External access owns exposure and ingress patterns.
• Observability owns telemetry, scraping, and monitoring surfaces.
• Air-gapped and private registries owns mirrored-image and disconnected-environment strategy.

Core server runtime

Configure

Start from the core server settings

yaml

spec:
configuration:
  ui: true
  cacheSize: 134217728
  disableCache: false
  defaultLeaseTTL: "720h"
  maxLeaseTTL: "8760h"
  listener:
    proxyProtocolBehavior: "use_proxy_protocol"
  raft:
    performanceMultiplier: 2

Reference table

Common server knobs

Common server knobs.

Field	Why you change it	Operational note
ui	Enable or disable the web UI intentionally.	This is a service-boundary decision only if you also expose the route appropriately.
listener	Adjust listener behavior such as proxy-protocol handling.	Keep listener-level TLS assumptions aligned with the external-access path you selected.
defaultLeaseTTL / maxLeaseTTL	Set sensible lease bounds for the workloads that depend on the cluster.	Treat very long leases as an operational contract, not just a convenience setting.
raft.performanceMultiplier	Compensate for high-latency or slower control-plane environments.	Change this deliberately and observe cluster behavior rather than cargo-culting larger values.

Audit devices and plugins

Audit devices

Configure

Enable declarative audit devices

yaml

spec:
audit:
  - type: file
    path: secure-audit
    description: "Secure audit logging"
    options:
      file_path: "/var/log/openbao/audit.log"
      format: "json"

Audit devices belong in the cluster baseline so the service does not come up “temporarily unaudited” and stay that way by accident.

Plugins

Configure

Register OCI-based plugins declaratively

yaml

spec:
configuration:
  plugin:
    autoDownload: true
    downloadBehavior: "direct"
plugins:
  - type: secret
    name: aws
    image: "ghcr.io/openbao/openbao-plugin-secrets-aws"
    version: "v1.0.0"
    binaryName: "openbao-plugin-secrets-aws"
    sha256sum: "9fdd8be7947e4a4caf7cce4f0e02695081b6c85178aa912df5d37be97363144c"

Raft autopilot defaults

Diagram

Autopilot ownership

The operator keeps autopilot aligned with the cluster profile and replica count so peer cleanup and quorum behavior stay in bounds as the cluster changes.

Reference table

Autopilot defaults

Autopilot defaults.

Setting	Default	Why it exists
cleanupDeadServers	true	Dead peers should not linger indefinitely in a Kubernetes-managed environment.
deadServerLastContactThreshold	5m	The operator uses a shorter threshold than the generic upstream default because cluster nodes and Pods are expected to churn faster in Kubernetes.
serverStabilizationTime	10s	New servers should prove they are healthy before becoming stable voters.
minQuorum	Calculated from profile and replica count	Hardened favors HA safety; Development favors flexibility for small clusters.

Override defaults

Configure

Customize autopilot explicitly

yaml

spec:
profile: Hardened
replicas: 5
configuration:
  raft:
    autopilot:
      minQuorum: 4
      deadServerLastContactThreshold: "10m"
      lastContactThreshold: "30s"
      maxTrailingLogs: 2000
      serverStabilizationTime: "30s"

Override only when you have a concrete reason. Most clusters should start with the operator defaults and change them only after observing real failure or latency behavior.

Disable cleanup

Configure

Disable automatic dead-peer cleanup

yaml

spec:
configuration:
  raft:
    autopilot:
      cleanupDeadServers: false

If you disable cleanup, you are taking manual ownership of peer removal. That is usually a temporary operational exception, not a steady-state recommendation.

Inspect

Inspect the full configuration schema

bash

kubectl explain openbaocluster.spec.configuration

Use this when you need the exact field tree. Keep this page for the defaults and decision boundaries, not as a full API dump.

Continue cluster baseline

ObservabilityMove to the telemetry and scraping page when you need monitoring rather than server-runtime tuning.Air-gapped and private registriesUse the disconnected-environment guide for mirrored images and private registry behavior.OperateCarry the resulting baseline into upgrades, backups, and troubleshooting once the cluster is live.