OpenBao self-initialisation¶
OpenBao can initialise itself at first boot from initialize blocks in its configuration. With
examples/self-init/openbao.hcl the server:
- enables the
kubernetesauth method and points it at the in-cluster API server; - writes the policy
openbao-config-operator(a platform operator in the root namespace; trim it with OpenBao policy for the operator); - creates the role
auth/kubernetes/role/openbao-config-operator, bound to the ServiceAccountopenbao-config-operatorin the namespaceopenbao-config-operator, with audienceopenbao-config-operator; - revokes the root token it used. No root token is ever printed or stored.
The operator then logs in as itself, so nobody has to create a token for it.
Use it¶
- Add the file to the OpenBao server as an extra
-config(for the OpenBao Helm chart, as an extra config file next toserver.hcl). Self-init needs an auto-unseal seal; it does not work with Shamir. - Bind the OpenBao server's ServiceAccount to the
system:auth-delegatorClusterRole, so the kubernetes auth method can review tokens. - Install the operator in the namespace
openbao-config-operatorwith release nameopenbao-config-operator(the ServiceAccount name the role expects). The chart mounts a projected token for the audienceopenbao-config-operatorby default:
helm install openbao-config-operator oci://ghcr.io/alexandrust88/charts/openbao-config-operator \
--version 0.5.0 \
--namespace openbao-config-operator --create-namespace
- Create a
ClusterOpenBaoConnectionwithauth.kubernetes.role: openbao-config-operatorandinjectedIdentity: {}; its defaulttokenPathis the chart's token,/var/run/secrets/openbao/token. See Connect to OpenBao.
Self-init runs only once, on empty storage. The example denies the operator access to change its
own policy, auth mount, auth configuration and login role. Use a separate bootstrap administrator
identity to update those objects; a Policy or AuthMount using this connection cannot manage them.
Existing installations need the updated policy applied separately: upgrading the operator or
changing the self-init file does not rerun initialisation. Before applying the updated policy,
set deletionPolicy: Orphan on any resources that manage these bootstrap objects and remove
those resources from Kubernetes and their GitOps source. Keep the OpenBao objects in place;
otherwise the new denials can leave reconciliation or deletion blocked.
After a policy or login-role update, check the ClusterOpenBaoConnection's Ready and authenticated status, then reconcile a harmless configuration resource using that connection. Keep the bootstrap administrator available until both checks succeed. If login fails, repair the bootstrap objects with that administrator; restarting the operator does not repair OpenBao configuration.
These denials prevent accidental self-lockout. They do not make broad policy-authoring rights a safe tenant boundary: the operator can still author other powerful policies. Use separate, restricted identities for tenant connections.
Verify¶
examples/self-init/verify.sh boots OpenBao 2.7.2 in a
container with the example, raft storage, a static seal and fake ServiceAccount files, then
checks through a test-only userpass login that the auth method, the policy and the role exist and
that the root token was revoked. It needs Docker, the bao CLI and jq:
You should see verify: self-init created kubernetes auth, the operator policy and role, and
revoked the root token.