Skip to content

Quickstart on kind

In this tutorial you run OpenBao and the operator on a local kind cluster, then manage your first OpenBao objects from Kubernetes. At the end, a workload logs in to OpenBao and reads a password the operator generated, and you watch the operator undo a change made behind its back.

It takes about ten minutes.

Evaluation only

The OpenBao server in this tutorial runs in dev mode: it keeps everything in memory, listens on plain HTTP and uses the root token root. Everything is lost when its pod restarts. Use this setup to learn the operator, and never to hold real secrets. Install and Connect to OpenBao cover a real server.

Before you begin

You need:

  • Docker, or another container runtime that kind supports;
  • kind 0.25 or later, whose default node image runs Kubernetes 1.31 or later, as the chart requires;
  • kubectl;
  • Helm 3.8 or later;
  • git.

Clone the repository at the release you install. Every manifest this tutorial applies is in examples/quickstart/, and every command is in hack/docs/quickstart.sh:

git clone --branch v0.5.0 https://github.com/alexandrust88/openbao-config-operator.git
cd openbao-config-operator

Set the chart version and the names the commands use:

export VERSION=0.5.0
export KIND_CLUSTER=openbao-quickstart
export CHART_REF=oci://ghcr.io/alexandrust88/charts/openbao-config-operator

Run it in one go

hack/docs/quickstart.sh runs every step below and fails at the first one that does not reach its expected state. CI runs the same script on every change, so the steps on this page are tested:

VERSION=0.5.0 hack/docs/quickstart.sh

1. Create a kind cluster

kind create cluster --name "$KIND_CLUSTER" --wait 2m

kind creates a one-node cluster named openbao-quickstart and switches kubectl to the context kind-openbao-quickstart.

Confirm:

  • kubectl get nodes shows one node with the status Ready.

2. Start OpenBao

Apply examples/quickstart/openbao-dev.yaml: one OpenBao 2.7.2 pod in dev mode, a Service in front of it, and a binding that lets OpenBao check ServiceAccount tokens with the Kubernetes TokenReview API.

kubectl apply -f examples/quickstart/openbao-dev.yaml
kubectl -n openbao rollout status deployment/openbao --timeout=3m
Expected output
namespace/openbao created
serviceaccount/openbao created
clusterrolebinding.rbac.authorization.k8s.io/openbao-quickstart-auth-delegator created
deployment.apps/openbao created
service/openbao created
deployment "openbao" successfully rolled out

Dev mode starts OpenBao initialised and unsealed, so it is ready as soon as the pod is.

3. Let the operator log in to OpenBao

The operator logs in as a Kubernetes ServiceAccount, and the OpenBao policy of that login decides what it may change. This policy lets the operator manage ACL policies and Kubernetes auth roles whose names start with quickstart-, and the KV mount quickstart-kv:

examples/quickstart/operator-quickstart.hcl
path "sys/policies/acl/quickstart-*" {
  capabilities = ["create", "read", "update", "delete"]
}

path "sys/mounts" {
  capabilities = ["read"]
}

path "sys/mounts/quickstart-kv" {
  capabilities = ["create", "read", "update", "delete"]
}

path "sys/mounts/quickstart-kv/tune" {
  capabilities = ["create", "read", "update"]
}

path "auth/kubernetes/role/quickstart-*" {
  capabilities = ["create", "read", "update", "delete"]
}

path "quickstart-kv/data/*" {
  capabilities = ["create", "read", "update"]
}

path "quickstart-kv/metadata/*" {
  capabilities = ["read", "delete"]
}

Enable the Kubernetes auth method, upload the policy and create the role operator-quickstart. The role accepts only the ServiceAccount openbao-config of the namespace quickstart, with a token for the audience openbao:

kubectl -n openbao exec deploy/openbao -- bao auth enable kubernetes
kubectl -n openbao exec deploy/openbao -- bao write auth/kubernetes/config \
  kubernetes_host=https://kubernetes.default.svc:443
kubectl -n openbao exec -i deploy/openbao -- bao policy write operator-quickstart - \
  < examples/quickstart/operator-quickstart.hcl
kubectl -n openbao exec deploy/openbao -- bao write auth/kubernetes/role/operator-quickstart \
  bound_service_account_names=openbao-config \
  bound_service_account_namespaces=quickstart \
  audience=openbao \
  token_policies=operator-quickstart \
  token_ttl=1h token_max_ttl=4h
Expected output
Success! Enabled kubernetes auth method at: kubernetes/
Success! Data written to: auth/kubernetes/config
Success! Uploaded policy: operator-quickstart
Success! Data written to: auth/kubernetes/role/operator-quickstart

4. Install the operator

Install the chart from the OCI registry, with one replica, which is enough for a laptop:

helm upgrade --install openbao-config-operator "$CHART_REF" \
  --version "$VERSION" \
  --namespace openbao-config-operator --create-namespace \
  --set replicas=1 \
  --wait --timeout 5m

Helm waits until the manager pod is ready and prints STATUS: deployed.

Confirm:

  • kubectl -n openbao-config-operator get deployment openbao-config-operator shows 1/1 ready.

5. Connect the operator to OpenBao

Three objects connect the operator to OpenBao:

  • the namespace quickstart, with the label openbaoconfig.io/tenant: "true" and the ServiceAccounts openbao-config (the operator's identity) and app (a workload);
  • an OpenBaoServer, which says where OpenBao is and which namespaces may connect to it;
  • an OpenBaoConnection, which says how the operator logs in.
# The tenant namespace of the quickstart. The label lets the OpenBaoServer admit its connection. The operator
# logs in to OpenBao as the ServiceAccount openbao-config; app is the workload that logs in later.
apiVersion: v1
kind: Namespace
metadata:
  name: quickstart
  labels:
    openbaoconfig.io/tenant: "true"
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: openbao-config
  namespace: quickstart
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: app
  namespace: quickstart
# Evaluation only: the dev server of openbao-dev.yaml speaks plain HTTP, which allowInsecureHTTP permits.
# A real server uses an https:// address and a caBundle, as in examples/core/openbaoserver.yaml.
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoServer
metadata:
  name: quickstart
spec:
  address: http://openbao.openbao.svc:8200
  allowInsecureHTTP: true
  allowedNamespaces:
    matchLabels:
      openbaoconfig.io/tenant: "true"
  allowedAudiences:
    - openbao
# Logs in to the kubernetes auth method of OpenBao as the ServiceAccount openbao-config, with a short-lived token
# for the openbao audience. The OpenBao role operator-quickstart limits what the connection may configure.
apiVersion: core.openbaoconfig.io/v1alpha1
kind: OpenBaoConnection
metadata:
  name: openbao
  namespace: quickstart
spec:
  serverRef:
    name: quickstart
  auth:
    kubernetes:
      role: operator-quickstart
      serviceAccountRef:
        name: openbao-config
      audiences:
        - openbao

Apply them and wait until both report Ready:

kubectl apply -f examples/quickstart/namespace.yaml \
  -f examples/quickstart/openbaoserver.yaml \
  -f examples/quickstart/openbaoconnection.yaml
kubectl wait openbaoserver/quickstart --for=condition=Ready --timeout=2m
kubectl -n quickstart wait openbaoconnection/openbao --for=condition=Ready --timeout=2m
Expected output
namespace/quickstart created
serviceaccount/openbao-config created
serviceaccount/app created
openbaoserver.core.openbaoconfig.io/quickstart created
openbaoconnection.core.openbaoconfig.io/openbao created
openbaoserver.core.openbaoconfig.io/quickstart condition met
openbaoconnection.core.openbaoconfig.io/openbao condition met

The server is Ready when OpenBao answers its health check unsealed. The connection is Ready when the operator has logged in as openbao-config.

6. Create your first resources

Four resources describe what you want in OpenBao:

  • a Policy that may read one secret;
  • a SecretsMount: a KV version 2 secrets engine at quickstart-kv;
  • a KubernetesAuthRole that lets the ServiceAccount app log in and get that policy;
  • a RandomSecret that generates a password into quickstart-kv/app and copies it to a Kubernetes Secret.
# The ACL policy that the application's tokens get. driftInterval is short so the quickstart can show the
# operator repairing a change made in OpenBao; the default for policies is 15 minutes.
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: Policy
metadata:
  name: quickstart-app-read
  namespace: quickstart
spec:
  connectionRef:
    name: openbao
  deletionPolicy: Delete
  driftInterval: 30s
  policy: |
    path "quickstart-kv/data/app" {
      capabilities = ["read"]
    }
# A KV version 2 secrets engine at quickstart-kv (the path defaults to metadata.name).
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: SecretsMount
metadata:
  name: quickstart-kv
  namespace: quickstart
spec:
  connectionRef:
    name: openbao
  type: kv
  options:
    version: "2"
  description: Quickstart key-value secrets
# Lets the ServiceAccount app of the quickstart namespace log in with a token for the openbao audience. Its tokens
# get the OpenBao policy of the Policy resource quickstart-app-read.
apiVersion: auth.openbaoconfig.io/v1alpha1
kind: KubernetesAuthRole
metadata:
  name: quickstart-app
  namespace: quickstart
spec:
  connectionRef:
    name: openbao
  deletionPolicy: Delete
  boundServiceAccountNames:
    - app
  boundServiceAccountNamespaces:
    - quickstart
  audience: openbao
  tokenTTL: 15m
  policyRefs:
    - name: quickstart-app-read
# Generates a 32-character password once, stores it under the key password of quickstart-kv/app and also in the
# Kubernetes Secret quickstart-app-password.
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: RandomSecret
metadata:
  name: quickstart-app-password
  namespace: quickstart
spec:
  connectionRef:
    name: openbao
  mountPath: quickstart-kv
  path: app
  key: password
  generator:
    length: 32
  writeSecretRef:
    name: quickstart-app-password

Notice that the role does not repeat the policy name: policyRefs names the Policy resource, and the role waits until that policy is in OpenBao.

Apply them and wait until each one is Ready:

kubectl apply -f examples/quickstart/policy.yaml \
  -f examples/quickstart/secretsmount.yaml \
  -f examples/quickstart/kubernetesauthrole.yaml \
  -f examples/quickstart/randomsecret.yaml
kubectl -n quickstart wait --for=condition=Ready --timeout=3m \
  policy.sys.openbaoconfig.io/quickstart-app-read \
  secretsmount.sys.openbaoconfig.io/quickstart-kv \
  kubernetesauthrole.auth.openbaoconfig.io/quickstart-app \
  randomsecret.secrets.openbaoconfig.io/quickstart-app-password
Expected output
policy.sys.openbaoconfig.io/quickstart-app-read created
secretsmount.sys.openbaoconfig.io/quickstart-kv created
kubernetesauthrole.auth.openbaoconfig.io/quickstart-app created
randomsecret.secrets.openbaoconfig.io/quickstart-app-password created
policy.sys.openbaoconfig.io/quickstart-app-read condition met
secretsmount.sys.openbaoconfig.io/quickstart-kv condition met
kubernetesauthrole.auth.openbaoconfig.io/quickstart-app condition met
randomsecret.secrets.openbaoconfig.io/quickstart-app-password condition met

Every kind of the operator belongs to the openbao category, so one command lists them all with their Ready and Synced columns:

kubectl -n quickstart get openbao

Confirm:

  • Every resource in the list shows Ready True.

7. Check the result in OpenBao

Ask OpenBao directly. Read the policy, the type of the new mount and the policies of the new role:

kubectl -n openbao exec deploy/openbao -- bao policy read quickstart-app-read
kubectl -n openbao exec deploy/openbao -- bao read -field=type sys/mounts/quickstart-kv
kubectl -n openbao exec deploy/openbao -- bao read -field=token_policies auth/kubernetes/role/quickstart-app
Expected output
path "quickstart-kv/data/app" {
  capabilities = ["read"]
}
kv
[quickstart-app-read]

8. Log in as the application

Now act as the workload. Request a token for the ServiceAccount app, log in to OpenBao with it, and read the generated password with the OpenBao token you get back:

APP_JWT=$(kubectl -n quickstart create token app --audience openbao)
APP_TOKEN=$(kubectl -n openbao exec deploy/openbao -- \
  bao write -field=token auth/kubernetes/login role=quickstart-app jwt="$APP_JWT")
kubectl -n openbao exec deploy/openbao -- \
  env BAO_TOKEN="$APP_TOKEN" bao kv get -field=password quickstart-kv/app

OpenBao prints a random 32-character password. Read the copy in the Kubernetes Secret:

kubectl -n quickstart get secret quickstart-app-password -o jsonpath='{.data.password}' | base64 -d

You should see the same password. The application's token can read quickstart-kv/app and nothing else, because its only policy besides default is quickstart-app-read.

9. Watch the operator repair drift

Change the policy in OpenBao behind the operator's back, so that it grants every secret in the mount:

kubectl -n openbao exec -i deploy/openbao -- bao policy write quickstart-app-read - <<'EOF'
path "quickstart-kv/data/*" {
  capabilities = ["read"]
}
EOF
Expected output
Success! Uploaded policy: quickstart-app-read

The Policy resource checks OpenBao every 30 seconds (driftInterval: 30s), with up to 20% jitter. Wait about a minute, then read the policy again and list the events of the resource:

kubectl -n openbao exec deploy/openbao -- bao policy read quickstart-app-read
kubectl -n quickstart get events --field-selector involvedObject.name=quickstart-app-read,reason=Updated

The policy grants only quickstart-kv/data/app again, and an Updated event records the rewrite.

10. Clean up

Delete the kind cluster. OpenBao, the operator and everything they hold go with it:

kind delete cluster --name "$KIND_CLUSTER"

What you built

  • An OpenBao server and the operator on one kind cluster.
  • An OpenBaoServer that admits only labelled namespaces, and an OpenBaoConnection that logs in with a short-lived ServiceAccount token instead of a stored credential.
  • A policy, a KV version 2 mount, a Kubernetes auth role and a generated password, all declared in Kubernetes and checked against OpenBao.
  • Proof that a workload can log in and read its secret, and that the operator restores what someone changes in OpenBao by hand.

Troubleshooting

symptom check
kind create cluster fails because the cluster exists reuse it (kubectl config use-context kind-openbao-quickstart) or delete it with step 10
helm upgrade --install cannot find the chart VERSION is a released chart version without the v prefix: helm show chart oci://ghcr.io/alexandrust88/charts/openbao-config-operator --version "$VERSION"
openbaoserver/quickstart does not become Ready kubectl get openbaoserver quickstart -o yaml shows the reason; kubectl -n openbao get pods shows whether OpenBao runs
the connection reports ConnectionDenied the namespace label: kubectl get namespace quickstart --show-labels must list openbaoconfig.io/tenant=true
the connection reports AuthenticationFailed kubectl -n quickstart describe openbaoconnection openbao shows the OpenBao error; repeat step 3, and check that the ClusterRoleBinding openbao-quickstart-auth-delegator exists
a resource reports PermissionDenied the operator's policy allows only names that start with quickstart- and the mount quickstart-kv: compare the resource with examples/quickstart/operator-quickstart.hcl
everything was Ready, and now the connection fails the OpenBao pod restarted and dev mode lost its data: repeat step 3; the operator then recreates every object at its next check, and the RandomSecret generates a new password

Troubleshooting lists every condition reason.

Next steps

  • Install on a real cluster


    Verify the release, choose the scope and tenancy model, and install the chart.

  • Connect to your OpenBao


    A TLS server, a CA bundle and the login method that fits your platform.

  • Kubernetes auth


    Manage the auth method, its configuration and roles for your workloads.

  • Concepts


    Servers, connections, the tenant boundary and how the engine reconciles.