Configure the server runtime

Use this page for the settings that shape how the OpenBao server runs: listener and lease behavior, Raft autopilot, audit devices, and plugin registration. Exposure, observability, and mirrored-image settings are documented separately.

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.	Very long leases change the operational contract for the workloads that depend on the cluster.
raft.performanceMultiplier	Compensate for high-latency or slower control-plane environments.	Change this deliberately and verify that measured latency or failure behavior requires the larger value.

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"

Include audit devices in the cluster baseline so the service starts with the expected audit configuration.

Plugins

Configure

Register OCI-based plugins declaratively

yaml

spec:
configuration:
  plugin:
    autoDownload: true
    downloadBehavior: "continue"
plugins:
  - type: secret
    name: aws
    image: "ghcr.io/openbao/openbao-plugin-secrets-aws"
    version: "v0.0.1"
    binaryName: "openbao-plugin-secrets-aws"
    sha256sum: "b98cb1cbfd0f567d7b614efb0621aaba10c4deda865f5e5b3d155609ada2482e"

Use an image plugin when OpenBao should download the plugin from an OCI registry as part of server startup. The operator renders plugin_directory = "/openbao/plugins" and mounts a writable, pod-local volume at that path for OCI auto-download.

Configure

Register preinstalled plugins

yaml

spec:
plugins:
  - type: secret
    name: local-example
    command: "openbao-plugin-secrets-example"
    version: "v1.0.0"
    binaryName: "openbao-plugin-secrets-example"
    sha256sum: "9fdd8be7947e4a4caf7cce4f0e02695081b6c85178aa912df5d37be97363144c"

Use a command plugin when the binary is already available inside the OpenBao runtime image or another explicitly managed runtime path.

Reference table

Plugin fields

Plugin fields.

Surface	Use it for	Operational note
spec.plugins[].image	OCI-based plugin binaries that OpenBao downloads at startup.	Set spec.configuration.plugin.autoDownload: true; OpenBao pods need registry egress or access to a reachable mirror.
spec.plugins[].command	Plugin binaries already present in the OpenBao runtime environment.	The operator does not create a plugin-download volume for command-only plugins.
spec.configuration.plugin.autoRegister	Automatic plugin catalog registration.	args and env on each plugin are only used when auto-register is enabled.
spec.configuration.plugin.downloadBehavior	Startup behavior when an OCI plugin download fails.	Use fail to stop startup or continue to log and keep starting; plugin auto-download settings require OpenBao 2.5.0 or newer.

Downloaded plugins are runtime cache

OCI-downloaded plugins are stored under /openbao/plugins on an ephemeral pod-local volume. Treat that directory as a writable startup cache, not durable storage. If the cluster runs in a private or disconnected environment, mirror the plugin image and make sure OpenBao's runtime OCI client can authenticate to that registry; Kubernetes imagePullSecrets only cover Kubernetes image pulls.

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"

Start with the operator defaults and override them only after measuring behavior that requires a change.

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. This is usually a temporary operational exception rather than the steady-state configuration.

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 defaults and decision boundaries rather than exhaustive field-by-field reference.

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.