OpenBao (openbao)
Secrets manager of the platform: KV store of provider credentials (read by LiteLLM and the Control Plane, never by agents) and Transit keys for audit signing, with integrated Raft storage.
Generated from catalog/services/openbao.yaml: do not edit by hand.
Summary
| Version | 2.7.2 |
| Use | install and configure |
| Layer | infrastructure (shown apart) |
| Category | Identity and secrets |
| Installation methods | binary |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | MPL-2.0 |
| Licence policy | licence exception |
| Licence exception | LEX-006 (pending, awaiting the client) |
| Platform component | openbao |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| binary archive | openbao_2.7.2_linux_amd64.tar.gz | 2.7.2 | MPL-2.0 | https://github.com/openbao/openbao/releases/download/v2.7.2/openbao_2.7.2_linux_amd64.tar.gz, x86_64, checksum sha256 |
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64 (architecture of the artifacts of the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- at least 1024 MB of memory (blocking,
memory). - a synchronized clock (warning,
time_sync).
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
openbao-server | api | 8200/tcp | yes |
openbao-server | cluster | 8201/tcp | yes |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
OpenBao server (openbao-server) | master | binary | 8200/tcp, 8201/tcp |
Single node (Raft) (standalone) (default)
One node with integrated Raft storage.
What the mode deploys:
| Component | Placement |
|---|---|
openbao-server | min 1, max 1 |
High availability (Raft) (ha)
Three or five Raft nodes; one active, the others standby.
What the mode deploys:
| Component | Placement |
|---|---|
openbao-server | min 3, max 5, odd number, recommended 3 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select OpenBao. The card shows the licence
MPL-2.0. -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
standalone(default),ha. Each mode deploys the components listed in Installation methods and modes. -
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
High availability
| Cluster | native (native) |
| High availability | native (native) |
| Failover | native (native) |
| Replication | native (native) |
| Quorum | Raft (raft) |
| Discovery | static (static) |
| Entry point | load balancer (load-balancer) |
| Official documentation | https://openbao.org/docs/configuration/storage/raft/ |
| Peer TLS parameter | tls_enabled |
| Cluster status command | raft_peers |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
standalone | standalone (standalone) | single (single) | - | 1 | One node with integrated Raft storage. |
ha | cluster (cluster) | active-passive (active-passive) | openbao-server | 3 | 3 or 5 Raft nodes: one active, the standbys forward to it and take over when it fails. |
Notes
- A restarted node stays sealed until it is unsealed (no auto unseal is configured by the catalog).
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
API port (port) | port | 8200 | - | no | no | yes | Port of the HTTP API and of the web interface. |
Cluster port (cluster_port) | port | 8201 | - | no | no | yes | Port of Raft replication and request forwarding between nodes. |
TLS (tls_enabled) | bool | false | - | no | no | yes | Serve the API over TLS with a certificate issued by the manager CA (required in production). |
Web interface (ui_enabled) | bool | true | - | no | no | no | Serve the web interface on the API port. |
Initialisation and unsealing
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Key shares (key_shares) | int | 5 | min 1, max 10 | no | no | no | Number of unseal key shares created at initialisation. |
Key threshold (key_threshold) | int | 3 | min 1, max 10 | no | no | no | Shares needed to unseal. |
Logging
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Log level (log_level) | enum | info | trace, debug, info, warn, error | no | no | no | Verbosity of the server log. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
api | http | openbao-server | 8200 (port) | - | tls_enabled | - | - | - |
Client configuration files
Files rendered for the client configuration download:
openbao.env(client.env.j2)
Commands
| Command | Component | Target | Description |
|---|---|---|---|
Initialise (init) | openbao-server | first host | Initialises the cluster once. The unseal keys and the root token are written to the 0600 file init.json under the configuration directory of the first node, never printed in task logs or outputs: move them to the bank key custody, then delete the file. (asks for confirmation) |
Unseal (unseal) | openbao-server | every host | Unseals every node with the keys of init.json (piped on stdin, never in argv or logs). |
Raft peers (raft_peers) | openbao-server | every host | Shows the seal status of the node (peers need a token: use the CLI). |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
openbao-server | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.port }}/v1/sys/health?standbyok=true&perfstandbyok=true&uninitcode=200&sealedcode=200 | Expected 200; 30 retries; interval 2 s; timeout 3 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
memory | memory_mb {"min": 1024} | at least 1024 MB of memory | blocking | every component |
api_port_free | port_free {"param": "port"} | port 8200 free on the host | blocking | every component |
cluster_port_free | port_free {"param": "cluster_port"} | port 8201 free on the host | blocking | every component |
time_sync | time_sync {} | a synchronized clock | warning | every component |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Quick links
- Web interface:
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/ui/
Upstream documentation
- Homepage: https://openbao.org
- Source: https://github.com/openbao/openbao
- High availability: https://openbao.org/docs/configuration/storage/raft/