Skip to content

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:

examples/secrets/kvconfig.yaml
# 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
kubectl apply -f examples/secrets/kvconfig.yaml

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:

examples/secrets/kvsecret.yaml
# 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
kubectl apply -f examples/secrets/kvsecret.yaml

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
kubectl apply -f session-key.yaml

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