KV secrets¶
This guide creates a KV version 2 secrets engine and fills it from Kubernetes: secrets copied from Kubernetes Secrets, and values the operator generates.
The operator writes into OpenBao; it does not copy secrets out of OpenBao into Kubernetes
(ADR 0007). Workloads read OpenBao directly, or through a tool such
as the External Secrets Operator. Only values the operator generates can also be written to a
Kubernetes Secret (writeSecretRef).
Before you begin¶
A Ready connection whose OpenBao policy allows sys/mounts (read), sys/mounts/<mount> and
sys/mounts/<mount>/tune to manage the engine, and <mount>/data/* (create, read,
update), <mount>/metadata/* (read) and <mount>/destroy/* (update) for destructive history cleanup, and <mount>/config
(read, update) for the engine configuration
(OpenBao policy for the operator).
1. Enable the engine¶
Every resource on this page uses the KV v2 mount secret, connection openbao and Kubernetes
namespace openbao-config. Save this as kv-mount.yaml; it creates that mount or adopts the
existing KV v2 mount on a dev server:
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: SecretsMount
metadata:
name: guide-secret
namespace: openbao-config
spec:
connectionRef:
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Orphan
path: secret
type: kv
options:
version: "2"
kubectl apply -f kv-mount.yaml
kubectl -n openbao-config wait secretsmount/guide-secret --for=condition=Ready --timeout=2m
If another operator resource already owns secret, reuse that resource instead of creating a
second owner. For a different mount, change path here and every mountPath below together.
Every mount field, including lease TTLs and audit settings:
examples/sys/secretsmount.yaml
# Enables a KV version 2 secrets engine at team-a/kv, plus a Nomad engine (external plugin) at nomad. With
# deletionPolicy Orphan the mount and its data stay in OpenBao when the resource is deleted.
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: SecretsMount
metadata:
name: obco-kv
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Orphan
driftDetection: Enabled
driftInterval: 1h
managementPolicy: Manage
path: team-a/kv
type: kv
description: Key-value secrets of team a
local: false
sealWrap: false
externalEntropyAccess: false
forceNoCache: false
pluginVersion: ""
options:
version: "2"
defaultLeaseTTL: 768h
maxLeaseTTL: 768h
listingVisibility: hidden
auditNonHMACRequestKeys:
- path
auditNonHMACResponseKeys:
- version
passthroughRequestHeaders:
- X-Request-Id
allowedResponseHeaders:
- X-Request-Id
---
apiVersion: sys.openbaoconfig.io/v1alpha1
kind: SecretsMount
metadata:
name: obco-nomad
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Orphan
driftDetection: Enabled
driftInterval: 1h
managementPolicy: Manage
path: nomad
type: nomad
pluginRef:
name: obco-nomad-secrets-plugin
description: Nomad tokens through the external plugin registered by the Plugin obco-nomad-secrets-plugin
A KVConfig sets the engine's version limits:
# Keeps ten versions of every secret on the secret mount and deletes versions older than 32 days.
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: KVConfig
metadata:
name: obco-secret-config
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Orphan
driftDetection: Enabled
mountPath: secret
maxVersions: 10
casRequired: false
metadataCASRequired: false
deleteVersionAfter: 768h
2. Write a secret from Kubernetes Secrets¶
A KVSecret writes the keys of one or more Kubernetes Secrets to one KV path. dataFrom copies
every key of a Secret; data maps single keys. The values are hashed into status.writeOnlyHash,
never stored in status, and a change of a referenced Secret writes a new version:
# Writes the KV version 2 secret secret/obco/app from two Kubernetes Secrets: every key of one, and one key of the
# other under a new name. The annotation allows deletionPolicy Delete to remove the secret data.
apiVersion: v1
kind: Secret
metadata:
name: obco-app-db
namespace: openbao-config
type: Opaque
stringData:
username: app
password: fake-db-password-not-real
---
apiVersion: v1
kind: Secret
metadata:
name: obco-app-api
namespace: openbao-config
type: Opaque
stringData:
token: fake-api-token-not-real
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: KVSecret
metadata:
name: obco-app
namespace: openbao-config
annotations:
openbaoconfig.io/allow-destructive-delete: "true"
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
mountPath: secret
path: obco/app
kvVersion: 2
dataFrom:
- secretRef:
name: obco-app-db
data:
api-token:
secretKeyRef:
name: obco-app-api
key: token
The KV data is removed with the resource only when deletionPolicy: Delete is set and the
resource carries openbaoconfig.io/allow-destructive-delete: "true", as in the example.
3. Generate a value¶
A RandomSecret generates a value once and stores it under one key of a KV secret. Change
refreshNonce to generate a new value. writeSecretRef also writes the value to a Kubernetes
Secret that the resource owns; passwordPolicyName generates it with an OpenBao password policy
instead of generator:
Save this minimal example as session-key.yaml:
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: RandomSecret
metadata:
name: obco-app-session-key
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: secret
path: obco/app-random
kvVersion: 2
key: session-key
generator:
length: 48
charset: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_
writeSecretRef:
name: obco-app-session-key
For password-policy generation, see the complete RandomSecret examples.
Their second resource requires the db-passwords policy from
passwordpolicy.yaml before it can become Ready.
4. Check that it worked¶
kubectl -n openbao-config wait kvsecret/obco-app randomsecret/obco-app-session-key \
--for=condition=Ready --timeout=2m
bao kv metadata get secret/obco/app
The metadata shows the current version. bao kv get secret/obco/app shows the data.
Troubleshooting¶
| symptom | check |
|---|---|
KVSecret or RandomSecret reports ReferenceNotReady |
the mount does not exist yet, or a referenced Secret or key is missing |
the resource reports PermissionDenied |
the connection's policy lacks <mount>/data/* |
deleting the resource reports DeleteGuarded |
the annotation openbaoconfig.io/allow-destructive-delete: "true" is missing |
RandomSecret reports SecretNotOwned |
a Secret named in writeSecretRef already exists and was not created by this resource |
Related¶
- API reference: SecretsMount, KVConfig, KVSecret, RandomSecret.
- Access model: give workloads and people access to KV paths.
- Quickstart on kind: a
RandomSecretread back by a workload.