Skip to content

Connect to OpenBao

This guide points the installed operator at an OpenBao server you run: you declare the server, give the operator an OpenBao identity, create a connection and check that it logs in. Every field is described in the connections reference.

Before you begin

  • The operator is installed (Install).
  • OpenBao is initialised, unsealed and reachable from the operator pods, normally over HTTPS.
  • You have the PEM CA bundle that signed the OpenBao server certificate, unless a public CA signed it.
  • A bao CLI is logged in to OpenBao with the rights to enable an auth method, write a policy and create a role.

Choose the connection kind and the login

you want kind who creates it it logs in as
each team configures its own part of OpenBao OpenBaoConnection in the team's namespace the platform team a ServiceAccount of that namespace, or the AppRole or token configured for that connection
the platform team configures OpenBao for everyone ClusterOpenBaoConnection the platform team the operator's own ServiceAccount (injected identity), a named ServiceAccount, an AppRole or a token

Both kinds support four login methods. For workloads in Kubernetes, prefer a short-lived ServiceAccount token when the OpenBao deployment can validate it. The right method depends on network reachability and which system owns credential rotation.

Login When to use it Credential location Required OpenBao setup Production guidance
kubernetes OpenBao can call the cluster's TokenReview API Short-lived TokenRequest token; no stored login Secret Kubernetes auth mount, reviewer access and a role bound to the ServiceAccount, namespace and audience A practical default for in-cluster identity; restrict the role and use a dedicated audience
jwt OpenBao can verify the cluster's issuer and signing keys without TokenReview Short-lived TokenRequest token; no stored login Secret JWT auth mount with trusted discovery/JWKS or public keys, plus issuer, audience and subject bindings Useful across clusters; ensure signing-key rotation and issuer reachability are handled
appRole Kubernetes identity is unavailable or an existing credential-delivery system manages AppRole Role ID and Secret ID in Kubernetes Secrets AppRole mount and a least-privilege role Arrange Secret ID rotation before expiry; avoid copying an unbounded credential between teams
token An external system already supplies and rotates a scoped OpenBao token Kubernetes Secret; a cluster connection can instead read a token file in the operator pod An appropriately scoped token, normally periodic for an ongoing connection Use a managed token lifecycle and narrow policy; never use the root token for the operator

For namespaced connections, every referenced Secret and ServiceAccount belongs to the connection's Kubernetes namespace. A cluster connection can use the operator's projected identity; a tenant connection cannot. The connection reference lists the fields for both kinds.

Install: tenancy models helps you choose between per-team and shared connections.

1. Declare the server

The platform team declares each OpenBao server once. Store the CA bundle in a ConfigMap (or a Secret) that tenants cannot write:

kubectl -n openbao create configmap openbao-ca --from-file=ca.crt=ca.crt

Then create the OpenBaoServer. allowedNamespaces selects the namespaces whose OpenBaoConnections may use it, and allowedAudiences lists the token audiences they may request:

examples/core/openbaoserver.yaml
# The platform team declares the OpenBao server once. Tenants in namespaces labelled
# openbaoconfig.io/tenant=true may connect to it with OpenBaoConnections that request the openbao token audience;
# the Kubernetes API server's own audiences are always refused.
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoServer
metadata:
  name: openbao
spec:
  address: https://openbao.openbao.svc:8200
  caBundle:
    configMapRef:
      namespace: openbao
      name: openbao-ca
  allowedNamespaces:
    matchLabels:
      openbaoconfig.io/tenant: "true"
  allowedAudiences:
    - openbao
  rateLimit:
    qps: 50
    burst: 100
  requestTimeout: 30s
kubectl apply -f examples/core/openbaoserver.yaml
kubectl wait openbaoserver/openbao --for=condition=Ready --timeout=2m
Expected output
openbaoserver.core.openbaoconfig.io/openbao created
openbaoserver.core.openbaoconfig.io/openbao condition met

Ready=True means the server answered sys/health over TLS and is unsealed. The VERSION column of kubectl get openbaoserver shows the OpenBao version.

No plain HTTP

An http:// address is refused unless the server sets allowInsecureHTTP: true. That is for a local dev server only, as in the quickstart: every token and secret input then crosses the network in clear text. Hardening shows how to forbid it in production.

2. Give the operator an identity in OpenBao

Write a policy that allows only what the connection will manage (OpenBao policy for the operator has templates per kind), then create the login for it. The commands below follow the tenant example of step 3: team team-a works in the OpenBao namespace tenants/team-a and logs in there.

These commands assume the OpenBao namespace tenants/team-a already exists. Create it as a platform administrator before proceeding if needed. Prepare the Kubernetes namespace now, so AppRole and token Secrets can be created before the connection:

kubectl create namespace team-a --dry-run=client -o yaml | kubectl apply -f -

For a minimal connection check, save this as team-a-config.hcl. It allows the connection to inspect and renew its own token and manage one application policy, team-a-app:

path "auth/token/lookup-self" {
  capabilities = ["read"]
}
path "auth/token/renew-self" {
  capabilities = ["update"]
}
path "sys/policies/acl/team-a-app" {
  capabilities = ["create", "read", "update", "delete"]
}

team-a-config is the login policy you bootstrap below; team-a-app is a different policy the operator may manage through that login. The example grants no rights to rewrite its own login policy. Extend it deliberately for the resource kinds and paths you intend to manage, using the operator policy templates.

bao auth enable -namespace=tenants/team-a kubernetes
bao write -namespace=tenants/team-a auth/kubernetes/config \
  kubernetes_host=https://kubernetes.default.svc:443
bao policy write -namespace=tenants/team-a team-a-config team-a-config.hcl
bao write -namespace=tenants/team-a auth/kubernetes/role/team-a-configurer \
  bound_service_account_names=openbao-configurer \
  bound_service_account_namespaces=team-a \
  audience=openbao \
  token_policies=team-a-config \
  token_ttl=1h token_max_ttl=4h

OpenBao reviews the token with its own ServiceAccount when it runs in the same cluster; bind that ServiceAccount to the system:auth-delegator ClusterRole. When OpenBao runs elsewhere, also pass kubernetes_ca_cert=@ca.crt and a token_reviewer_jwt of a ServiceAccount that may create TokenReviews.

OpenBao fetches the cluster's discovery document and signing keys without credentials, and by default the API server serves them only to authenticated callers. Allow anonymous reads; the binding exposes only the issuer metadata and the public keys:

kubectl create clusterrolebinding oidc-reviewer \
  --clusterrole=system:service-account-issuer-discovery --group=system:unauthenticated
bao auth enable -namespace=tenants/team-a -path=jwt-k8s jwt
bao write -namespace=tenants/team-a auth/jwt-k8s/config \
  oidc_discovery_url=https://kubernetes.default.svc.cluster.local \
  oidc_discovery_ca_pem=@ca.crt \
  bound_issuer=https://kubernetes.default.svc.cluster.local
bao policy write -namespace=tenants/team-a team-a-config team-a-config.hcl
bao write -namespace=tenants/team-a auth/jwt-k8s/role/team-a-configurer \
  role_type=jwt \
  user_claim=sub \
  bound_audiences=openbao \
  bound_subject=system:serviceaccount:team-a:openbao-configurer \
  token_policies=team-a-config \
  token_ttl=1h token_max_ttl=4h

kubectl get --raw /.well-known/openid-configuration shows the cluster's issuer. If OpenBao cannot reach discovery, configure a reachable JWKS endpoint with jwks_url, or maintain PEM-formatted public keys in jwt_validation_pubkeys. The JSON returned by kubectl get --raw /openid/v1/jwks is a JWKS document, not a PEM public key; do not pass it directly to jwt_validation_pubkeys.

bao auth enable -namespace=tenants/team-a approle
bao policy write -namespace=tenants/team-a team-a-config team-a-config.hcl
bao write -namespace=tenants/team-a auth/approle/role/team-a-configurer \
  token_policies=team-a-config token_ttl=1h token_max_ttl=4h secret_id_ttl=720h
role_id=$(bao read -namespace=tenants/team-a -field=role_id auth/approle/role/team-a-configurer/role-id)
secret_id=$(bao write -namespace=tenants/team-a -f -field=secret_id auth/approle/role/team-a-configurer/secret-id)
kubectl create secret generic openbao-approle -n team-a \
  --from-literal=role_id="$role_id" --from-literal=secret_id="$secret_id"

Write a new secret ID into the Secret before secret_id_ttl ends. The connection reads it at the next login, without a restart.

bao policy write -namespace=tenants/team-a team-a-config team-a-config.hcl
bao token create -namespace=tenants/team-a -orphan -period=24h -policy=team-a-config -field=token \
  | kubectl create secret generic openbao-token -n team-a --from-file=token=/dev/stdin

Use a periodic token: the operator renews a renewable token after a third of its TTL, and cannot renew any other.

If the connection works in the root namespace, leave out every -namespace flag.

3. Create the connection

The platform team creates the namespace, its ServiceAccount and the connection. The namespace needs the label that the server's allowedNamespaces selects:

kubectl create namespace team-a --dry-run=client -o yaml | kubectl apply -f -
kubectl label namespace team-a openbaoconfig.io/tenant=true
kubectl -n team-a create serviceaccount openbao-configurer
examples/core/openbaoconnection.yaml
# A tenant connection logs in as a ServiceAccount of its own namespace with a TokenRequest token for the
# OpenBao audience. The OpenBaoServer must select this namespace and allow the audience. Injected identity and file
# sources exist only on ClusterOpenBaoConnection.
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoConnection
metadata:
  name: openbao
  namespace: team-a
spec:
  serverRef:
    name: openbao
  namespace: tenants/team-a
  auth:
    kubernetes:
      role: team-a-configurer
      serviceAccountRef:
        name: openbao-configurer
      audiences:
        - openbao

For another login method, replace auth with one of these blocks; every Secret and ServiceAccount is in the connection's namespace:

auth:
  jwt:
    mountPath: jwt-k8s
    role: team-a-configurer
    serviceAccountRef:
      name: openbao-configurer
    audiences:
      - openbao
auth:
  appRole:
    roleIDSecretRef:
      name: openbao-approle
      key: role_id
    secretIDSecretRef:
      name: openbao-approle
      key: secret_id
auth:
  token:
    secretRef:
      name: openbao-token
      key: token

A ClusterOpenBaoConnection is usable from every namespace its allowedNamespaces selects. With Kubernetes or JWT auth and no serviceAccountRef, it logs in as the operator itself (see Log in as the operator):

examples/core/clusteropenbaoconnection-injectedidentity.yaml
# The operator logs in as itself with the token of the projected volume the chart mounts by default
# (injectedIdentity.projectedToken). The OpenBao role must bind the operator's ServiceAccount and the audience
# set in injectedIdentity.projectedToken.audience (default openbao-config-operator).
apiVersion: core.openbaoconfig.io/v1alpha1
kind: ClusterOpenBaoConnection
metadata:
  name: platform
spec:
  serverRef:
    name: openbao
  auth:
    kubernetes:
      role: openbao-config-operator
      injectedIdentity:
        tokenPath: /var/run/secrets/openbao/token
  allowedNamespaces:
    matchLabels:
      openbaoconfig.io/platform: "true"
---
apiVersion: core.openbaoconfig.io/v1alpha1
kind: ClusterOpenBaoConnection
metadata:
  name: platform-jwt
spec:
  serverRef:
    name: openbao
  auth:
    jwt:
      mountPath: jwt-k8s
      role: openbao-config-operator
      injectedIdentity:
        tokenPath: /var/run/secrets/openbao/token
  allowedNamespaces:
    matchLabels:
      openbaoconfig.io/platform: "true"

To read a token from a file in the operator pod, such as an agent sidecar's sink, use auth.token.filesystem:

examples/core/clusteropenbaoconnection-filesystem.yaml
# The token is read from a file in the operator pod at every login, such as the token sink of an agent sidecar
# that keeps it renewed (for example one injected through the chart's podAnnotations).
apiVersion: core.openbaoconfig.io/v1alpha1
kind: ClusterOpenBaoConnection
metadata:
  name: platform-agent
spec:
  serverRef:
    name: openbao
  auth:
    token:
      filesystem:
        path: /vault/secrets/token
  allowedNamespaces:
    matchLabels:
      openbaoconfig.io/platform: "true"

Apply the connection:

kubectl apply -f examples/core/openbaoconnection.yaml

Log in as the operator

A ClusterOpenBaoConnection with kubernetes or jwt auth and no serviceAccountRef presents the operator's own ServiceAccount token. The chart mounts a projected token for the audience openbao-config-operator at /var/run/secrets/openbao/token, which is the default tokenPath. Create the OpenBao role for the chart's ServiceAccount and namespace, with that audience:

bao write auth/kubernetes/role/openbao-config-operator \
  bound_service_account_names=openbao-config-operator \
  bound_service_account_namespaces=openbao-config-operator \
  audience=openbao-config-operator \
  token_policies=openbao-config-operator \
  token_ttl=1h token_max_ttl=4h

The ServiceAccount name is the chart's full name: the release name openbao-config-operator unless you set fullnameOverride or serviceAccount.name. OpenBao self-init creates this role at OpenBao's first boot, without a root token.

4. Test the connection

kubectl -n team-a wait openbaoconnection/openbao --for=condition=Ready --timeout=2m
kubectl -n team-a get openbaoconnection openbao
Expected output
openbaoconnection.core.openbaoconfig.io/openbao condition met

The get shows Ready True, the server and its OpenBao version. Ready=True with the reason Available means the server admits the connection, the login worked and auth/token/lookup-self succeeded. The operator checks again every minute, and when the server or the namespace labels change.

Check what the identity may do before you create resources. Log in as the identity, then ask OpenBao about the application-policy path granted by team-a-config.hcl:

bao token capabilities -namespace=tenants/team-a sys/policies/acl/team-a-app

Expect create, read, update and delete for team-a-app. Run this check with the connection's login identity, not the platform administrator's token. A resource that hits a missing capability reports PermissionDenied.

Troubleshooting

symptom check
server Ready=False, reason Unreachable the address, DNS, the chart's NetworkPolicy egress to OpenBao (networkPolicy.openbao), and x509 errors in the message: the CA bundle
server Ready=False, reason ReferenceNotReady the CA bundle ConfigMap or Secret and its key (default ca.crt) exist in the namespace you named
server Ready=False, reason Sealed unseal OpenBao; resources wait meanwhile
connection reason ConnectionDenied the server's allowedNamespaces against kubectl get namespace team-a --show-labels, and allowedAudiences against the connection's audiences
connection reason CredentialsNotFound the names, keys and namespaces of the Secrets in spec.auth; for a token file, the volume mount
connection reason AuthenticationFailed kubectl -n team-a describe openbaoconnection openbao shows the OpenBao error: the role name, its bound ServiceAccount, namespace and audience, the system:auth-delegator binding, and authNamespace
connection reason ReferenceNotReady the connection's OpenBao namespace exists: bao namespace list in its parent

Status and events has every reason.

Configure your first object

With the server and connection Ready, create a Policy and verify its OpenBao path. Continue with Kubernetes authentication for workload access, or import existing configuration if the server is already managed.