OpenBao 实战笔记：从上手到生产部署（已更新至 v2.7.2） – 张善友

Sensitive information such as database passwords, API Keys, and TLS certificates are scattered in environment variables, configuration files, and CI/CD Pipelines. They are the first target of almost all attackers. Key management must be done sooner or later, and it is better to do it sooner than later.

OpenBao is an open source fork of HashiCorp Vault, hanging under the Linux Foundation’s LF Edge, under the MPL-2.0 license. The reason is that in August 2023, HashiCorp changed Vault from MPL-2.0 to BSL, restricting competitive use, and the community forked a copy in anger. Now its API is highly compatible with Vault, and the CLI command is baothe usage is almost copied from Vault.

This article is my record of running through OpenBao from getting started to production, covering installation, various Secret Engines, authentication and authorization, Seal/Unseal, HA cluster and Kubernetes integration. Content clicked OpenBao v2.7.2(Published on October 26, 2026) Checked, breaking changes between 2.6 and 2.7 have been written.

Before upgrading, take a look at what has been changed in 2.6 → 2.7.2

If you are already running 2.5.x or 2.6.x, you must go through these steps before upgrading, otherwise you will encounter pitfalls.

Breaking changes:

• Cloud vendor Auto Unseal is no longer built-in。awskms、gcpckms、azurekeyvault、alicloudkms、ocikms、pkcs11 All have been removed from the main binary. Go to openbao-plugins to install the corresponding KMS plug-in, and then use plugin "kms" Declarative registration. The independent HSM distribution has also been discontinued.
• LDAP / Kerberos / RADIUS authentication engine, LDAP key engine moved out of main binarywhich also requires external plug-ins.
• file Storage backend removedthe new replacement is the non-HA PebbleDB backend, and the default configuration of the Linux package has been switched away. Still using it storage "file" The configuration cannot be started on 2.7.
• Container images default to non-root openbao User runs(Since 2.6), custom startup scripts that rely on root need to be adapted.
• PKI no longer accepts . The domain name ending in (example.com. This will be rejected).

New stuff worth using:

• External Keys: PKI and Transit can directly call the key in KMS/HSM to perform operations, and the key material does not enter OpenBao.
• ML-DSA post-quantum signature: PKI issuance and Transit signature both support NIST FIPS 204 ML-DSA (three parameter sets 44/65/87). The listener can also be configured for pure PQC TLS key exchange.
• Strong consistency control: Write request response band X-Vault-Index Header, the read request can declare the latest write that it has seen. When the node data falls behind, you can choose to directly 429, forward it to the active node, or wait for the local catch-up. Solve the old problem of “reading the old value from Standby immediately after writing”.
• Control Groups: Approval control can be written in the ACL policy, and operations on sensitive paths must be approved by a second person before they are executed.
• PebbleDB storage backend:replacement filethe performance is much better.
• Declarative self-initialization enhancements(2.6): Support CEL expressions and templates, Dev mode can also be used.
• tls_auto_reload: The certificate file will be automatically reloaded if it changes, and there is no need to send a SIGHUP again.

Why upgrade to 2.7.2 immediately: 2.7.1 and 2.7.2 have fixed a total of 11 security vulnerabilities, including AppRole’s Secret ID that can still be authenticated after expiration, Kubernetes Auth’s lease can be renewed after the Service Account is revoked, path traversal when Transit imports backup, SSH certificate template allows wildcards by default, etc. Deployments below 2.7.2 should be upgraded as soon as possible.

core concepts

There are not many terms, just remember these few first:

the term	illustrate
Secret Engine	Plug-in components that store, generate or encrypt data, mounted by path (secret/、database/、pki/）
Auth Method	Authentication method, Token is issued after identity verification.
Token	The certificate obtained after successful authentication, with policy information
Policy	ACL policy, which defines the Token’s permissions on the path
Lease	The key is valid for a period of time, automatically revoked upon expiration, and can be renewed.
Seal / Unseal	Encryption protection mechanism, in Sealed state at startup, requires Unseal Key to decrypt data
Barrier	Encryption barrier, data written to storage is encrypted through it
Integrated Storage	Built-in Raft consensus storage, does not rely on external components
PebbleDB	2.7 New non-HA persistence backend
External Key	2.7 Newly added, keys stored in external KMS/HSM and called by OpenBao

Architecture

The core of OpenBao’s security is multi-layer encryption. Understanding this chain is basically half of it:

Unseal Key（操作员持有 / 外部 KMS 插件托管）
    └── 加密 → Root Key
            └── 加密 → Encryption Keyring
                    └── 加密 → 存储里的所有数据

A few key points:

1. Unseal Key doesn’t exist anywhere. It is distributed among multiple people in Shamir mode, and hosted by an external KMS plug-in in Auto Unseal mode.
2. Even if an attacker drags away the entire storage backend data, it cannot be unlocked without the Unseal Key.
3. Data encryption keys can be rotated online, and old keys remain in the Keyring to decrypt historical data without downtime.

The processing path when the request comes in is: Listener terminates TLS (2.7 optional pure PQC key exchange) → Consistency check (X-Vault-Index) → Audit → Token verification → ACL evaluation (may trigger Control Group approval) → Secret Engine processing → Barrier encryption placement. There is a complete architecture diagram at the end of the article.

Install

macOS is the easiest:

brew install openbao
bao version
# OpenBao v2.7.2 ...

Linux：

# Arch
pacman -Sy openbao

# Fedora / RHEL
dnf install -y epel-release
dnf install -y openbao

# Debian / Ubuntu：从  下载
wget 
sudo dpkg -i bao_2.7.2_linux_amd64.deb

By the way, the naming of Release products has been unified starting from 2.6 (unified architecture amd64the checksums are merged into one checksums.txt), be careful when writing automatic download scripts.

Docker：

docker pull ghcr.io/openbao/openbao:latest

docker run --rm -p 8200:8200 \
  --memory-swappiness=0 \
  --name openbao-dev \
  ghcr.io/openbao/openbao:latest server -dev

Remember to reinforce after installation: disable Swap (key data cannot enter the swap space), the systemd service file has MemorySwapMax=0Docker needs to be added --memory-swappiness=0. Swap in macOS is encrypted by default, so don’t worry about it. In addition, starting from 2.6, containers run non-root by default, which is not included in the image. VOLUME command, the data directory must be explicitly mounted by itself.

Getting started with Dev mode

Dev mode memory storage, automatic Unseal, and pre-generated Root Token are very suitable for learning, butNever use it for production。

bao server -dev
# ==> OpenBao server configuration:
#                  Storage: inmem
#                  Version: OpenBao v2.7.2
# ...
# Root Token: hvs.xxxxxxxxxxxxxxxxxxxxxxxx

Open another terminal:

export BAO_ADDR='
export BAO_TOKEN='hvs.xxxxxxxxxxxxxxxxxxxxxxxx'
bao status
bao status -field=version   # 2.7 起 status 支持 -field

Starting from 2.6, Dev mode also supports declarative self-initialization. It can automatically execute a series of predefined API requests at startup, which is very convenient for setting up a demonstration environment.

KV engine: the first Secret

Dev mode has KV v2 disabled by default. secret/ Path, run the most commonly used commands:

# 写入
bao kv put secret/myapp/config \
  db_host="postgres.prod.internal" \
  db_port="5432" \
  db_user="app_user" \
  db_password="S3cur3P@ssw0rd!"

# 读取
bao kv get secret/myapp/config

# 只取一个字段
bao kv get -field=db_password secret/myapp/config

# JSON 输出给脚本用
bao kv get -format=json secret/myapp/config | jq '.data.data'

# 更新（会产生新版本）
bao kv put secret/myapp/config db_password="N3wS3cur3P@ss!"

# 读历史版本
bao kv get -version=1 secret/myapp/config

# 列出路径
bao kv list secret/myapp/

# 软删除 / 恢复 / 永久销毁
bao kv delete secret/myapp/config
bao kv undelete -versions=2 secret/myapp/config
bao kv destroy -versions=1 secret/myapp/config

The difference between KV v1 and v2: v2 has version control, soft deletion, metadata and CAS (check-and-set to prevent concurrent writes from overwriting each other), and one more layer of API paths secret/data/. Use v2 directly in production, v1 is only suitable for small scenarios where the version does not matter.

If you don’t use the CLI, all operations have HTTP API:

curl -s \
  --header "X-Vault-Token: $BAO_TOKEN" \
  --request POST \
  --data '{"data": {"api_key": "sk-abc123def456"}}' \
  $BAO_ADDR/v1/secret/data/myapp/api-keys | jq

Let’s talk about the strong consistency header of 2.7: writing request response will bring X-Vault-Indexsubsequent read requests bring this value and add X-Vault-Inconsistent Declaration of policy——fail(If the data is not tied, 429 + Retry-After will be returned),forward-active-node(forwarded to active nodes),await-state(Local waiting to tie), can also be combined. The problem of “cannot read just after writing” in the HA cluster can be alleviated by this method.

Secret Engines

Take a look at the panorama first:

engine	type	use	2.7 Status
KV	storage	key value pair	built-in
Database	dynamic	Database temporary account	Built-in, MySQL 2.6 supports multi-host failover
PKI	dynamic	X.509 certificate issuance	Built-in, 2.7 supports ML-DSA and external keys
Transit	encryption	Encryption as a Service	Built-in, 2.7 supports ML-DSA and external keys
SSH	dynamic	SSH certificate issuance	Built-in, templates disable wildcards by default starting from 2.7.2
TOTP	dynamic	TOTP code	built-in
Transform	encryption	FPE / Desensitization	built-in
LDAP	dynamic	LDAP credentials	Moved out of main binary, requires external plugin

Database: dynamic database credentials

Dynamic keys are the most valuable capability of this type of system – generating time-sensitive database accounts on demand and automatically deleting them upon expiration, eliminating the need to post a universal password everywhere.

bao secrets enable database

# 配置 PostgreSQL 连接
bao write database/config/my-postgresql-db \
  plugin_name="postgresql-database-plugin" \
  allowed_roles="readonly,readwrite" \
  connection_url="postgresql://{{username}}:{{password}}@postgres.internal:5432/myapp?sslmode=require" \
  username="vault_admin" \
  password="vault_admin_password"

# 只读角色
bao write database/roles/readonly \
  db_name="my-postgresql-db" \
  creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; \
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
  revocation_statements="DROP ROLE IF EXISTS \"{{name}}\";" \
  default_ttl="1h" \
  max_ttl="24h"

# 动态获取凭证
bao read database/creds/readonly
# lease_id           database/creds/readonly/abcd1234...
# lease_duration     1h
# username           v-token-readonly-xxxxxxxxx
# password           A1a-xxxxxxxxxxxxxxxxx

# 续租 / 撤销
bao lease renew database/creds/readonly/abcd1234...
bao lease revoke database/creds/readonly/abcd1234...

A few experiences:default_ttl Control it within 1 hour; the application must actively renew the lease before the lease expires, or simply hand it over to the Agent; run it immediately after configuring the connection bao write -force database/rotate-root/my-postgresql-db Rotate the administrator password to prevent someone from logging into the database directly with the original password.

PKI: Internal CA

OpenBao can be used as an internal CA to issue and manage TLS certificates. The typical approach is Root CA + Intermediate CA two layers:

# Root CA
bao secrets enable pki
bao secrets tune -max-lease-ttl=87600h pki
bao write -field=certificate pki/root/generate/internal \
  common_name="My Organization Root CA" \
  issuer_name="root-2026" \
  ttl=87600h > root_ca.crt

# Intermediate CA：开第二个挂载点，生成 CSR，拿 Root 签，再导回去
bao secrets enable -path=pki_int pki
bao secrets tune -max-lease-ttl=43800h pki_int
bao write -field=csr pki_int/intermediate/generate/internal \
  common_name="My Organization Intermediate CA" \
  issuer_name="intermediate-2026" > pki_intermediate.csr
bao write -field=certificate pki/root/sign-intermediate \
  csr=@pki_intermediate.csr format=pem_bundle ttl=43800h > intermediate_ca.crt
bao write pki_int/intermediate/set-signed certificate=@intermediate_ca.crt

# 定义可签发的证书规范
bao write pki_int/roles/internal-service \
  allowed_domains="internal.mycompany.com,svc.cluster.local" \
  allow_subdomains=true max_ttl="720h" key_type="ec" key_bits=256

# 签发
bao write pki_int/issue/internal-service \
  common_name="api.internal.mycompany.com" ttl="72h"
# 返回里的 private_key 只有这一次能拿到，丢了只能重签

Two new capabilities in 2.7: First, the entire PKI process supports ML-DSA post-quantum signature (FIPS 204, please note that Go’s OCSP does not yet support ML-DSA, and this type of issuer cannot use OCSP); second, it can be signed with an external key, the private key remains in the HSM, and OpenBao only takes the signature result.

Transit: Encryption as a Service

The application does not need to manage the encryption key itself, just adjust the API to encrypt and decrypt, and the data itself does not fall on OpenBao:

bao secrets enable transit
bao write -f transit/keys/my-app-key

# 加密（输入要 base64）
bao write transit/encrypt/my-app-key plaintext=$(echo -n "my-secret-data" | base64)
# ciphertext     vault:v1:xxxxxxxxxxxxxxxxxxxxxx

# 解密
bao write transit/decrypt/my-app-key ciphertext="vault:v1:xxxxxxxxxxxxxxxxxxxxxx"

# 轮换密钥、用新版本重加密旧密文
bao write -f transit/keys/my-app-key/rotate
bao write transit/rewrap/my-app-key ciphertext="vault:v1:..."

2.7 Added ML-DSA signature key to Transit, and all three parameter sets 44/65/87 support generation, import and export:

bao write -f transit/keys/pqc-signing-key type=mldsa-65
bao write transit/sign/pqc-signing-key input=$(echo -n "message" | base64)

A reminder: The route traversal vulnerability of Transit’s imported key backup (which can overwrite any key) was only fixed in 2.7.2. Those who use this function must upgrade it.

External Keys (new in 2.7)

PKI and Transit can now directly use keys in external KMS/HSM to perform operations, and the key materials do not enter OpenBao. pass /sys/external-keys API configuration mapping:

# 需要先装对应的 KMS 插件（比如 kms-pkcs11）
bao write sys/external-keys/pki/hsm-root-ca \
  plugin_name="kms-pkcs11" \
  # ... 插件自己的密钥引用参数

Transit backend keys are supported built-in, PKCS#11 goes kms-pkcs11 The plug-in and interface itself have nothing to do with the provider. If you want to connect to your own KMS, you can write your own plug-in.

Authentication and Authorization

Commonly used authentication methods: Token (the end point of everything), UserPass (for testing, pre-hashed bcrypt passwords are supported starting from 2.6), AppRole (preferred for applications), Kubernetes (Pod is authenticated with ServiceAccount), JWT/OIDC, TLS certificate (2.7 supports parsing Envoy’s XFCC header). LDAP, Kerberos, and RADIUS have all removed external plug-ins starting from 2.7.

AppRole

AppRole is the preferred choice for application access, two factors: Role ID (can be generously placed in the configuration) plus Secret ID (it must be delivered through a secure channel, and it is recommended to use it only once):

bao auth enable approle

bao write auth/approle/role/my-app \
  token_policies="my-app-policy" \
  token_ttl=1h token_max_ttl=4h \
  secret_id_ttl=10m \
  secret_id_num_uses=1

# 拿 Role ID
bao read auth/approle/role/my-app/role-id

# 生成 Secret ID
bao write -f auth/approle/role/my-app/secret-id

# 应用侧登录
bao write auth/approle/login \
  role_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  secret_id="yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"

2.7.1 Fixed an AppRole hole: after the Secret ID expired, tidy could still use it to log in before it was cleaned up. 2.7.2 Fixed the problem that the Role ID path was not standardized. So again, the version must keep up.

Kubernetes Auth

bao auth enable kubernetes

bao write auth/kubernetes/config \
  kubernetes_host="

bao write auth/kubernetes/role/my-app \
  bound_service_account_names=my-app-sa \
  bound_service_account_namespaces=production \
  policies=my-app-policy ttl=1h

2.7.1 There was a problem here before: the ServiceAccount JWT would not be re-verified when the Token lease was renewed, and the SA could still be renewed if it was revoked. Lease renewal now requires mandatory verification.

Token

Two types: Service Token is renewable and revocable, and has persistent storage; Batch Token is lightweight and non-renewable, and is suitable for high-throughput short tasks. Root Token permissions are equal to the root user, immediately after initialization bao token revoke Drop it, use it when you really need it bao operator generate-root Temporarily generated (requires authorization from multiple Unseal Key holders).

ACL policy

OpenBao is a whitelist model, and all paths that are not included in the policy will be rejected:

# my-app-policy.hcl
path "secret/data/myapp/*" {
  capabilities = ["read", "list"]
}

path "secret/data/myapp/config" {
  capabilities = ["create", "read", "update"]
}

path "database/creds/readonly" {
  capabilities = ["read"]
}

path "sys/leases/renew"  { capabilities = ["update"] }
path "sys/leases/revoke" { capabilities = ["update"] }
path "auth/token/lookup-self" { capabilities = ["read"] }
path "auth/token/renew-self"  { capabilities = ["update"] }

# deny 优先级最高，可以覆盖其他策略
path "secret/metadata/*" {
  capabilities = ["deny"]
}

There are seven types of permissions:create、read、update、delete、list、sudo(access root level path),deny。

2.7 The new Control Groups are worth mentioning separately: Approval control can be added to the strategy, similar to the two-person rule of a bank vault. Operations such as reading the production root certificate, changing the Root CA, and exporting the Transit key are very suitable for this:

path "secret/data/prod/root-credentials" {
  capabilities = ["read"]

  control_group {
    factor "approver" {
      identity {
        group_names = ["security-approvers"]
        approvals   = 1
      }
    }
  }
}

Policy management commands:

bao policy write my-app-policy my-app-policy.hcl
bao policy list
bao policy read my-app-policy
bao token create -policy="my-app-policy" -ttl=2h
bao token lookup -field=policies   # 2.7 起支持 -field

Templating strategies are also supported,{{identity.entity.name}} This type of variable can be used for dynamic permissions based on identity, and each user can only touch his or her own namespace.

Seal / Unseal

Shamir Sharding

In the default mode, use Shamir’s Secret Sharing to cut the Unseal Key into multiple parts and collect enough thresholds to rebuild:

bao operator init -key-shares=5 -key-threshold=3

# Unseal 要凑 3 片
bao operator unseal   # Progress: 1/3
bao operator unseal   # Progress: 2/3
bao operator unseal   # Sealed: false

How to distribute shards: Production recommends 5 shards with a threshold of 3, and distribute them to different people for physical isolation and storage; 3/2 is also acceptable for a small team; 1/1 for the development environment is fine.

Auto Unseal: 2.7 changed to plug-in (key point)

This is the biggest architectural change in 2.7. The seals of cloud vendors KMS and PKCS#11 have all been removed from the main binary, and only the Transit Seal is still built-in. The configuration of 2.7 needs to be divided into two steps – first register the plug-in, and then write it as before seal：

# /etc/openbao/config.hcl

# 插件二进制先放到 plugin_directory
# 官方预构建：
plugin "kms" "awskms" {
  # 2.7 起手动安装的插件不再强制要求 sha256sum
}

seal "awskms" {
  region     = "ap-southeast-1"
  kms_key_id = "arn:aws:kms:ap-southeast-1:123456789:key/abcd-1234-..."
}

There are several practical benefits after being removed: the plug-in will automatically restart if it crashes, without the need to restart the entire instance (especially useful when the PKCS#11 library is out of breath); SIGHUP can hot-load KMS plug-in configurations and upgrade plug-ins during operation; there is also an SDK for those who want to implement their own Seal. In addition, 2.7 also adds configuration items to the Auto Seal health check, which can disable or customize the interval and timeout.

Please note when upgrading: If the old version is using the cloud vendor Seal, the plug-in must be installed and registered before upgrading to 2.7, otherwise the upgrade to Unseal will not be completed. The two risk reminders are still the same – if the KMS key is unavailable, you will not be able to get up. If the key is permanently deleted, the data will be lost forever. Remember to use a mechanism such as SCP to lock the KMS key.

Migration between seal types (such as Shamir to Auto Unseal) can be done, but it requires downtime.

Production deployment

Configuration file

A production-grade configuration, Raft storage plus plug-in AWS KMS Auto Unseal:

# /etc/openbao/config.hcl（OpenBao v2.7.2）
cluster_name = "prod-openbao-cluster"

api_addr     = "
cluster_addr = "

ui         = true
log_level  = "info"
log_format = "json"

listener "tcp" {
  address         = "0.0.0.0:8200"
  cluster_address = "0.0.0.0:8201"

  tls_cert_file = "/etc/openbao/tls/server.crt"
  tls_key_file  = "/etc/openbao/tls/server.key"

  # 证书文件变了自动重载，不用 SIGHUP
  tls_auto_reload = true

  tls_min_version    = "tls12"
  tls_cipher_suites  = "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"

  # 想上后量子 TLS 的话：
  # tls_key_exchange_preferences = "X25519MLKEM768,SecP256r1MLKEM768"

  # 强一致性（可选）：
  # consistency_missing_header_forward = true
  # consistency_fallback_behavior      = "forward-active-node"
  # consistency_max_index_wait         = "10s"

  max_request_duration = "90s"
  max_request_size     = 33554432
}

storage "raft" {
  path    = "/opt/openbao/data"
  node_id = "node-1"

  performance_multiplier = 1

  autopilot {
    cleanup_dead_servers               = true
    dead_server_last_contact_threshold = "24h"
    min_quorum                         = 3
  }

  retry_join {
    leader_api_addr     = "
    leader_ca_cert_file = "/etc/openbao/tls/ca.crt"
  }
  retry_join {
    leader_api_addr     = "
    leader_ca_cert_file = "/etc/openbao/tls/ca.crt"
  }
}

plugin "kms" "awskms" {
}

seal "awskms" {
  region     = "ap-southeast-1"
  kms_key_id = "arn:aws:kms:ap-southeast-1:123456789:key/abcd-1234-..."
}

telemetry {
  prometheus_retention_time = "24h"
  disable_hostname          = true
}

default_lease_ttl = "768h"
max_lease_ttl     = "768h"

If HA is not required for stand-alone or edge scenarios, use PebbleDB (storage "pebbledb"），file The backend is gone. If the team already has a PostgreSQL cluster being maintained, you can also directly use PostgreSQL as the storage backend. See the “PostgreSQL Storage Backend” section below.

PostgreSQL storage backend

In addition to Raft, another production-level HA backend officially supported by OpenBao is PostgreSQL (reintroduced in v2.1, minimum requirement is PostgreSQL 9.5). Suitable for teams that already have a mature PG operation and maintenance system and do not want to maintain a Raft set:

storage "postgresql" {
  connection_url = "postgres://openbao:secret@postgres.internal:5432/openbao?sslmode=verify-full"
  ha_enabled     = true                  # 开启 HA（基于 openbao_ha_locks 表抢锁选主）
  max_parallel   = 128                   # 最大并发请求数
  # skip_create_table = true             # 连接账号没有建表权限时要手动建表并打开这个
}

The connection string can also be used BAO_PG_CONNECTION_URL environment variables or criteria PGHOST Series variables and passwords do not need to be written into the configuration file. OpenBao will build the table structure by itself (openbao_kv_store and openbao_ha_locks Two tables), if the database account does not have CREATE permission, manually build it according to the DDL in the official document and then set it up. skip_create_table=true。

How to choose between Raft:

• Raft: The data is local, one less network hop away, and the read performance is good; but writing requires majority voting, is sensitive to inter-node delay, and requires understanding of Raft’s node management and failover.
• PostgreSQL: The OpenBao node itself is stateless, and expansion and contraction and failover only require a connection string, without the need for raft join/remove-peer operations; write performance is often better (single active node write, physical copy to slave library); HA and backup recovery directly reuse the PG ecosystem (such as CloudNativePG + physical copy). The price is one more external dependency, and the default read cache.

An important enhancement in 2.7: the PostgreSQL backend is supported starting from v2.7.0Reading level expansion(Aligned with Raft’s capabilities in 2.5), Standby nodes can handle read-only requests locally. need ha_enabled = true And Standby can pass cluster_addr Connect to the active node; when the Leader is lost for a long time, Standby will start in read-only mode. Note that only PG physical replication is supported, not logical replication. To turn it off, add it in the configuration disable_standby_reads=true。

The backup method is also different: Raft uses bao operator raft snapshotthe PostgreSQL backend does not have a corresponding snapshot API, and directly uses PG’s own backup system (pg_dump, WAL archive, cloud database snapshot, etc.).

systemd

# /etc/systemd/system/openbao.service
[Unit]
Description=OpenBao - A tool for managing secrets
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/openbao/config.hcl

[Service]
Type=notify
User=openbao
Group=openbao
ProtectSystem=full
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
SecureBits=keep-caps
AmbientCapabilities=CAP_IPC_LOCK
NoNewPrivileges=yes
ExecStart=/usr/bin/bao server -config=/etc/openbao/config.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
LimitNOFILE=65536
LimitMEMLOCK=infinity
MemorySwapMax=0

[Install]
WantedBy=multi-user.target

Initialization and first boot

sudo mkdir -p /opt/openbao/data
sudo chown openbao:openbao /opt/openbao/data

sudo mkdir -p /etc/openbao/tls
sudo cp server.crt server.key ca.crt /etc/openbao/tls/
sudo chown openbao:openbao /etc/openbao/tls/*
sudo chmod 600 /etc/openbao/tls/server.key

sudo systemctl enable --now openbao

export BAO_ADDR='
export BAO_CACERT='/etc/openbao/tls/ca.crt'

bao operator init -key-shares=5 -key-threshold=3
# Unseal Key 和 Root Token 立刻收好

bao operator unseal
bao operator unseal
bao operator unseal

bao login $ROOT_TOKEN
bao audit enable file file_path=/var/log/openbao/audit.log
bao token revoke $ROOT_TOKEN

If you don’t want to manually init, declarative self-initialization supports CEL expressions, template reference pre-order response values,when Conditional execution, a fully automated deployment of IaC can go this route.

HA cluster

Integrated Storage (Raft) is recommended for production, and there is no need to raise an additional Consul. Take three nodes as an example, Node 1:

storage "raft" {
  path    = "/opt/openbao/data"
  node_id = "node-1"

  retry_join {
    leader_api_addr     = "
    leader_ca_cert_file = "/etc/openbao/tls/ca.crt"
  }
  retry_join {
    leader_api_addr     = "
    leader_ca_cert_file = "/etc/openbao/tls/ca.crt"
  }
}

Modify Node 2 and 3 node_id Just use the retry_join list. After each node starts, Unseal independently, and then confirm the members on the Leader:

bao operator raft list-peers
# node-1     10.0.1.10:8201     leader      true
# node-2     10.0.1.11:8201     follower    true
# node-3     10.0.1.12:8201     follower    true

Daily operation and maintenance:

bao status                                     # 看 HA 模式
bao operator step-down                         # 手动移交领导权
bao operator raft snapshot save backup-$(date +%Y%m%d).snap
bao operator raft snapshot restore backup-20261105.snap
bao operator raft remove-peer node-3

2.7 has fixed a lot of things in Raft:auto_join The problems with port address failure, secondary transaction performance regression in batch applications, and the problem of infinite log growth when the amount of writes is insufficient for snapshot_threshold have all been fixed. In addition, cooperate with X-Vault-IndexSSCT can now use storage layer indexes for precise read consistency control.

Experience: Use 3 or 5 (odd numbers) for the number of nodes, and the delay between nodes deployed in the same Region is within 10ms; read requests can be processed by all nodes, and writes will be automatically transferred to the Leader; snapshot backups are run regularly every day.

Audit log

Three types of audit devices: file, syslog, and socket. Most commonly used:

bao audit enable file file_path=/var/log/openbao/audit.log
bao audit list -detailed

All requests and responses will be recorded. Sensitive fields are hashed with HMAC-SHA256. It cannot be deduced, but it can be used if you know the original value. bao audit hash Calculate the hash and compare.

Two key points: at least one audit device must be available. If all requests fail, OpenBao will refuse to process all requests (it would rather not serve than leave an audit blind spot); audit logs must be forwarded to a centralized log system in real time. 2.7.1 Fixed a corner issue – the unauthenticated Root Token Generation / Rekey endpoint (closed by default) will actually return a response when the audit fails. Now it will be directly rejected if the audit fails.

Kubernetes integration

Helm deployment

helm repo add openbao 
helm repo update

values.yaml：

global:
  enabled: true
  tlsDisable: false

server:
  image:
    repository: ghcr.io/openbao/openbao
    tag: "2.7.2"

  ha:
    enabled: true
    replicas: 3
    raft:
      enabled: true
      config: |
        ui = true

        listener "tcp" {
          address = "[::]:8200"
          cluster_address = "[::]:8201"
          tls_cert_file = "/vault/tls/tls.crt"
          tls_key_file = "/vault/tls/tls.key"
          tls_auto_reload = true
        }

        storage "raft" {
          path = "/vault/data"
          retry_join {
            leader_api_addr = "
            leader_ca_cert_file = "/vault/tls/ca.crt"
          }
          retry_join {
            leader_api_addr = "
            leader_ca_cert_file = "/vault/tls/ca.crt"
          }
          retry_join {
            leader_api_addr = "
            leader_ca_cert_file = "/vault/tls/ca.crt"
          }
        }

        service_registration "kubernetes" {}

  dataStorage:
    enabled: true
    size: 10Gi
    storageClass: "gp3"

  resources:
    requests:
      cpu: 500m
      memory: 256Mi
    limits:
      cpu: 2000m
      memory: 1Gi

  auditStorage:
    enabled: true
    size: 5Gi

injector:
  enabled: true
  replicas: 2

ui:
  enabled: true
  serviceType: ClusterIP

helm install openbao openbao/openbao -n openbao --create-namespace -f openbao-values.yaml

Agent Injector

Add annotations to the Pod, and the Webhook automatically injects the Sidecar pull key and writes the file:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      annotations:
        vault.hashicorp.com/agent-inject: "true"
        vault.hashicorp.com/role: "my-app"
        vault.hashicorp.com/agent-inject-secret-db-creds: "database/creds/readonly"
        vault.hashicorp.com/agent-inject-template-db-creds: |
          {{- with secret "database/creds/readonly" -}}
          DB_USER={{ .Data.username }}
          DB_PASSWORD={{ .Data.password }}
          {{- end }}
        vault.hashicorp.com/agent-inject-secret-app-config: "secret/data/myapp/config"
        vault.hashicorp.com/agent-inject-template-app-config: |
          {{- with secret "secret/data/myapp/config" -}}
          API_KEY={{ .Data.data.api_key }}
          {{- end }}
    spec:
      serviceAccountName: my-app-sa
      containers:
        - name: my-app
          image: my-app:latest
          command: ["/bin/sh", "-c"]
          args:
            - |
              source /vault/secrets/db-creds
              source /vault/secrets/app-config
              exec ./my-app-binary

The key will be placed in the Pod’s /vault/secrets/ Table of contents.

CSI Provider

Another way of thinking is to mount the key directly as a volume and use standard secrets-store CSI:

volumes:
  - name: secrets
    csi:
      driver: secrets-store.csi.k8s.io
      readOnly: true
      volumeAttributes:
        secretProviderClass: "openbao-secrets"
---
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: openbao-secrets
spec:
  provider: vault   # 兼容 Vault CSI Provider
  parameters:
    roleName: "my-app"
    vaultAddress: "
    objects: |
      - objectName: "db-password"
        secretPath: "secret/data/myapp/config"
        secretKey: "db_password"

Agent / Proxy

Agent is a client daemon that does four things: Auto Auth automatically obtains tokens, local cache, template rendering, and API proxy.

# /etc/openbao/agent.hcl
auto_auth {
  method "approle" {
    config = {
      role_id_file_path   = "/etc/openbao/role-id"
      secret_id_file_path = "/etc/openbao/secret-id"
      remove_secret_id_file_after_reading = true
    }
  }

  sink "file" {
    config = {
      path = "/tmp/openbao-token"
      mode = 0640
      # 2.6 起可以指定属主：
      # uid = 1000
      # gid = 1000
    }
  }
}

cache {
  use_auto_auth_token = true
}

listener "tcp" {
  address     = "127.0.0.1:8100"
  tls_disable = true
}

vault {
  address     = "
  tls_ca_cert = "/etc/openbao/tls/ca.crt"
}

template {
  source      = "/etc/openbao/templates/db-config.tpl"
  destination = "/app/config/database.env"
  perms       = 0640
  command     = "systemctl reload my-app"
}

The template file looks like this:

{{ with secret "database/creds/readonly" }}
DB_USER={{ .Data.username }}
DB_PASSWORD={{ .Data.password }}
{{ end }}

Proxy is a simplified version of Agent, which only acts as an API proxy and is suitable for use as a Sidecar. Small change in 2.6/2.7: SIGHUP will reload client TLS configuration; turned on require_request_header after /quit and /cache-clear Request to bring X-Vault-Request head.

Operation and maintenance

Monitoring indicators

Just keep an eye on these:

index	illustrate	Alarm reference
vault.core.handle_request	request delay	P99 > 500ms
vault.barrier.get / put	Barrier read and write latency	P99 > 100ms / 200ms
vault.raft.leader.lastContact	Follower to Leader last contact	> 500ms
vault.raft.commitTime	Raft submission time	P99 > 50ms
vault.expire.num_leases	Number of active leases	Plan by capacity
vault.core.unsealed	Whether it has been Unsealed	If equal to 0, alert immediately

From 2.7 vault.core.unsealed=0 Independent indicators are reported in a cyclical manner, and the indicators in the Sealed state are more reliable.

Prometheus crawling configuration:

scrape_configs:
  - job_name: "openbao"
    metrics_path: "/v1/sys/metrics"
    params:
      format: ["prometheus"]
    scheme: "https"
    tls_config:
      ca_file: "/etc/prometheus/openbao-ca.crt"
    authorization:
      credentials_file: "/etc/prometheus/openbao-token"
    static_configs:
      - targets: ["openbao-0.internal:8200", "openbao-1.internal:8200", "openbao-2.internal:8200"]

backup

Daily snapshot plus off-site archiving:

#!/bin/bash
# /opt/openbao/scripts/backup.sh
BACKUP_DIR="/opt/openbao/backups"
DATE=$(date +%Y%m%d-%H%M%S)

bao operator raft snapshot save "${BACKUP_DIR}/openbao-${DATE}.snap"

aws s3 cp "${BACKUP_DIR}/openbao-${DATE}.snap" \
  "s3://my-backups/openbao/openbao-${DATE}.snap" \
  --sse aws:kms

find "${BACKUP_DIR}" -name "*.snap" -mtime +30 -delete

echo "0 3 * * * /opt/openbao/scripts/backup.sh >> /var/log/openbao/backup.log 2>&1" | crontab -

Key rotation

bao operator rotate          # 在线轮换，不影响服务
bao read sys/key-status      # 看当前 term

2.7 Fixed the rotation configuration disabled Field updates are not persisted.

Application integration

There are four connection methods, choose according to the environment: direct API adjustment (the strongest control, but you have to manage the token life cycle yourself), Agent (preferred for virtual machines/bare metal), K8s Injector (zero intrusion of annotation drivers), CSI Provider (standard volume interface).

Go：

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    vault "github.com/openbao/openbao/api/v2"
)

func main() {
    config := vault.DefaultConfig()
    config.Address = "

    client, err := vault.NewClient(config)
    if err != nil {
        log.Fatalf("init client: %v", err)
    }

    resp, err := client.Logical().Write("auth/approle/login", map[string]interface{}{
        "role_id":   "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "secret_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    })
    if err != nil {
        log.Fatalf("login: %v", err)
    }
    client.SetToken(resp.Auth.ClientToken)

    secret, err := client.KVv2("secret").Get(context.Background(), "myapp/config")
    if err != nil {
        log.Fatalf("read secret: %v", err)
    }
    fmt.Printf("DB Host: %s\n", secret.Data["db_host"].(string))

    // 后台续租；2.7 修了 LifetimeWatcher 续租失败不遵守退避间隔的问题
    go func() {
        for {
            time.Sleep(30 * time.Minute)
            if _, err := client.Auth().Token().RenewSelf(3600); err != nil {
                log.Printf("renew failed: %v", err)
            }
        }
    }()

    select {}
}

Python (using hvac, compatible with OpenBao API):

import hvac
import os
import threading
import time


class SecretsManager:
    def __init__(self):
        self.client = hvac.Client(
            url=os.environ.get('BAO_ADDR', '),
            verify='/etc/openbao/tls/ca.crt'
        )
        self._login()
        self._start_renewal()

    def _login(self):
        result = self.client.auth.approle.login(
            role_id=os.environ['BAO_ROLE_ID'],
            secret_id=os.environ['BAO_SECRET_ID']
        )
        self.client.token = result['auth']['client_token']
        self.lease_duration = result['auth']['lease_duration']

    def get_secret(self, path, key=None):
        response = self.client.secrets.kv.v2.read_secret_version(
            path=path, mount_point="secret"
        )
        data = response['data']['data']
        return data[key] if key else data

    def get_db_credentials(self, role="readonly"):
        response = self.client.read(f'database/creds/{role}')
        return {
            'username': response['data']['username'],
            'password': response['data']['password'],
            'lease_id': response['lease_id'],
        }

    def _start_renewal(self):
        def renew():
            while True:
                time.sleep(self.lease_duration * 0.7)
                try:
                    self.client.auth.token.renew_self()
                except Exception as e:
                    print(f"renew failed: {e}")
                    self._login()
        threading.Thread(target=renew, daemon=True).start()

Check it before production

Basic security: TLS enabled (can be turned on easily tls_auto_reload); the version is not lower than 2.7.2; Swap is disabled; Root Token is revoked; Unseal Key is stored separately; Auto Unseal uses a registered KMS plug-in and the KMS key is protected against deletion.

Storage and HA: Raft starts with three nodes, odd number; or reuses existing PostgreSQL cluster (ha_enabled=truesupports read horizontal expansion starting from 2.7); uses PebbleDB on a single machine; Raft takes snapshots every day, and the PG backend uses the database’s own backup system, and the recovery process has been really drilled.

Audit monitoring: at least one audit device; logs enter the centralized system; Prometheus indicators and alarms are configured.

Access control: policy minimum permissions; high-risk paths include Control Group; applications use AppRole or K8s Auth; Secret ID limits the number of uses and TTL; Token TTL should not exceed 24h; there is a “read immediately after writing” scenario to consider X-Vault-Index。

Key management: KV uses v2; database credentials are dynamically generated; periodically bao operator rotate;Dynamic certificate TTL is reduced to within 1 hour; those who are under compliance pressure can start to evaluate ML-DSA and PQC TLS.

Architecture diagram

The following is the overall architecture of OpenBao v2.7.2

---

References