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:
1. Create a kind cluster¶
kind creates a one-node cluster named openbao-quickstart and switches kubectl to the context
kind-openbao-quickstart.
Confirm:
-
kubectl get nodesshows one node with the statusReady.
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
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:
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
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-operatorshows1/1ready.
5. Connect the operator to OpenBao¶
Three objects connect the operator to OpenBao:
- the namespace
quickstart, with the labelopenbaoconfig.io/tenant: "true"and the ServiceAccountsopenbao-config(the operator's identity) andapp(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
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
Policythat may read one secret; - a
SecretsMount: a KV version 2 secrets engine atquickstart-kv; - a
KubernetesAuthRolethat lets the ServiceAccountapplog in and get that policy; - a
RandomSecretthat generates a password intoquickstart-kv/appand 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
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:
Confirm:
- Every resource in the list shows
ReadyTrue.
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
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:
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
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:
What you built¶
- An OpenBao server and the operator on one kind cluster.
- An
OpenBaoServerthat admits only labelled namespaces, and anOpenBaoConnectionthat 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¶
-
Verify the release, choose the scope and tenancy model, and install the chart.
-
A TLS server, a CA bundle and the login method that fits your platform.
-
Manage the auth method, its configuration and roles for your workloads.
-
Servers, connections, the tenant boundary and how the engine reconciles.