Generate installation files

init turns one values file into every file that must agree on the provider’s identity: the provider configuration, both encryption configurations, the OpenBao policy and setup script, and for static pods the manifest. It never contacts OpenBao or changes a host. Run it on a workstation for a fresh, disposable evaluation cluster.

Write the values file

Save this example as values.yaml and replace its addresses and identity values. For native OAuth, start from deploy/config/init-values-oauth2.yaml instead. Do not put a JWT, client secret, or OpenBao token in the values file.

# Preview fresh-install values. Replace the example addresses and identities.
# Generate once with --new-key; reuse generated/config.yaml on other nodes.
configVersion: v1alpha1
openbao:
  address: https://bao.example.internal:8200
  tlsServerName: bao.example.internal
  instanceId: bao-prod-a                 # Stable identity, not a hostname.
auth:
  jwt:
    source: file
    mountPath: auth/k8s-workload-a-jwt
    role: openbao-kms-control-plane
    # The host JWT agent must renew without the protected Kubernetes API.
    expectedIssuer: https://issuer.example.internal
    expectedAudience: [bao-kms-provider]
    expectedSubject: system:openbao-kms:workload-a
transit:
  mountPath: transit
  keyName: k8s-workload-a-etcd
  keyIdScope:
    providerName: openbao-kms-workload-a
    clusterId: workload-a
    transitMountId: transit-prod-primary
    # Omit keyLineageId only when --new-key creates it for a new Transit key.

Choose each value as follows. Identity-bearing values are part of every key_id and must stay the same on every node for the life of the key.

Do not derive identity values from mutable topology such as URLs, node names, or mount accessors. For the reasoning, see Reference: Key ID and AAD . For every flag and the checks init applies to the values, see Reference: CLI .

Read the static-pod socket GID

Skip this section for systemd; the package creates the socket group.

A static pod needs the numeric ID of the host group that the API server uses to reach the provider socket. On each control-plane node, create the group if it does not exist and print its GID:

getent group openbao-kms-socket >/dev/null || sudo groupadd --system openbao-kms-socket
getent group openbao-kms-socket | cut -d: -f3

Use the same GID on every node where possible. If a node differs, generate its files separately as shown in Reuse the identity on other nodes .

Generate the files

Generate files for a new Transit key:

bao-kms-provider init --values values.yaml --out generated --new-key

For a static pod, add the verified image reference from image-ref.txt and the socket GID:

bao-kms-provider init --values values.yaml --out generated --new-key \
  --model static-pod --image "$(cat image-ref.txt)" --socket-gid <gid>

Run init with the binary for your workstation. On macOS, download and verify bao-kms-provider_<version>_darwin_<arch> as described in Download the release . On Windows, use the Linux binary inside WSL2.

init prints the identity fingerprint and the new lineage ID. It rejects incompatible values before writing anything and refuses to write into an output directory that contains files.

Review and record the output

Record the identity fingerprint and lineage ID in configuration management. installation.json describes the generated inputs. It contains no credentials and does not report installation or activation success.

Reuse the identity on other nodes

The same generated/ directory serves every node that shares its host paths and socket GID. For a node that differs, generate from the resolved configuration and omit --new-key:

bao-kms-provider init --values generated/config.yaml --out generated-node-2

For static pods, pass the same --model and --image, and that node’s --socket-gid. Credential and state paths can also differ by node. Every node must print the same identity fingerprint.

Never generate a new lineage ID for another node using the same Transit key. --new-key rejects an input that already contains a lineage ID. For an existing key, provide its recorded lineage ID; do not invent a replacement.

Continue with Prepare OpenBao .