Database secrets¶
This guide connects OpenBao's database secrets engine to a database and declares roles that issue credentials: a dynamic role that creates a user per request, and a static role that rotates the password of an existing user.
For a runnable local environment with real login and revocation checks, start with Issue and revoke dynamic database credentials. This guide describes configuration for a database you already operate.
Before you begin¶
- A database that OpenBao can reach, and a user with the rights to create users (dynamic roles) or change passwords (static roles).
- A
Readyconnection whose OpenBao policy allowssys/mounts/<mount>to enable the engine, and<mount>/config/*,<mount>/roles/*,<mount>/static-roles/*and<mount>/rotate-root/*(OpenBao policy for the operator).
1. Enable the engine¶
Create a SecretsMount with type: database at the path the roles use, as in this fragment of a
spec:
examples/sys/secretsmount.yaml shows a complete
SecretsMount.
2. Connect the database¶
A DatabaseConnection configures one database. The root password comes from a Secret; OpenBao
never returns it, so the operator records a hash and writes it again when the Secret changes.
allowedRoles lists the roles that may use the connection. The file holds one connection per
plugin section (PostgreSQL, MySQL, Cassandra, InfluxDB, Valkey, and Redis through the valkey
section) and a Snowflake connection set through pluginConfig; the PostgreSQL one comes first:
examples/secrets/databaseconnection.yaml
# Connects the database secrets engine to PostgreSQL with root credentials and TLS material read from Secrets, and
# allows the roles that issue credentials from it.
apiVersion: v1
kind: Secret
metadata:
name: obco-db-root
namespace: openbao-config
type: Opaque
stringData:
password: fake-root-password-not-real
private-key: fake-private-key-not-real
---
apiVersion: v1
kind: Secret
metadata:
name: obco-db-tls
namespace: openbao-config
type: Opaque
stringData:
client.pem: fake-client-certificate-and-key-not-real
bundle.pem: fake-pem-bundle-not-real
issue.json: '{"certificate":"fake-not-real","private_key":"fake-not-real","issuing_ca":"fake-not-real"}'
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseConnection
metadata:
name: obco-postgres
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
mountPath: database
name: postgres
pluginName: postgresql-database-plugin
verifyConnection: true
allowedRoles:
- obco-app-ro
- obco-app-cert
- obco-app-static
rootRotationStatements:
- ALTER USER "{{name}}" WITH PASSWORD '{{password}}';
passwordPolicy: obco-db
passwordSecretRef:
name: obco-db-root
key: password
rotateRootOnCreate: true
postgresql:
connectionURL: postgresql://{{username}}:{{password}}@postgres.openbao-config.svc:5432/app?sslmode=require
username: openbao-root
maxOpenConnections: 8
maxIdleConnections: 4
maxConnectionLifetime: 5m
usernameTemplate: '{{ printf "v-%s-%s" (.RoleName | truncate 16) (random 8) }}'
disableEscaping: false
passwordAuthentication: scram-sha-256
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseConnection
metadata:
name: obco-mysql
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: database
pluginName: mysql-database-plugin
verifyConnection: false
allowedRoles:
- '*'
passwordSecretRef:
name: obco-db-root
key: password
mysql:
connectionURL: '{{username}}:{{password}}@tcp(mysql.openbao-config.svc:3306)/'
username: openbao-root
maxOpenConnections: 4
maxIdleConnections: 2
maxConnectionLifetime: 1m
usernameTemplate: '{{ .RoleName | truncate 10 }}-{{ random 6 }}'
tlsCA: |
-----BEGIN CERTIFICATE-----
ZmFrZS1jYS1ub3QtcmVhbA==
-----END CERTIFICATE-----
tlsCertificateKeySecretRef:
name: obco-db-tls
key: client.pem
tlsServerName: mysql.openbao-config.svc
tlsSkipVerify: false
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseConnection
metadata:
name: obco-cassandra
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: database
pluginName: cassandra-database-plugin
verifyConnection: false
allowedRoles:
- obco-cassandra
passwordSecretRef:
name: obco-db-root
key: password
cassandra:
hosts:
- cassandra-0.cassandra.openbao-config.svc
- cassandra-1.cassandra.openbao-config.svc
port: 9042
protocolVersion: 4
username: cassandra
tls: true
insecureTLS: false
tlsServerName: cassandra.openbao-config.svc
tlsMinVersion: tls12
pemBundleSecretRef:
name: obco-db-tls
key: bundle.pem
skipVerification: false
connectTimeout: 5s
socketKeepAlive: 30s
consistency: LOCAL_QUORUM
localDatacenter: dc1
usernameTemplate: '{{ .RoleName }}_{{ random 8 }}'
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseConnection
metadata:
name: obco-influxdb
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: database
pluginName: influxdb-database-plugin
verifyConnection: false
allowedRoles:
- obco-influx
passwordSecretRef:
name: obco-db-root
key: password
influxdb:
host: influxdb.openbao-config.svc
port: 8086
username: admin
tls: true
insecureTLS: false
tlsMinVersion: tls12
pemJSONSecretRef:
name: obco-db-tls
key: issue.json
connectTimeout: 5s
usernameTemplate: '{{ .RoleName }}_{{ random 8 }}'
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseConnection
metadata:
name: obco-valkey
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: database
pluginName: valkey-database-plugin
verifyConnection: false
allowedRoles:
- obco-cache
passwordSecretRef:
name: obco-db-root
key: password
valkey:
host: valkey.openbao-config.svc
port: 6379
username: default
tls: true
insecureTLS: false
caCert: |
-----BEGIN CERTIFICATE-----
ZmFrZS1jYS1ub3QtcmVhbA==
-----END CERTIFICATE-----
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseConnection
metadata:
name: obco-redis-url
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: database
pluginName: redis-database-plugin
verifyConnection: false
valkey:
connectionURL: rediss://redis.openbao-config.svc:6379
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseConnection
metadata:
name: obco-snowflake
namespace: openbao-config
spec:
connectionRef:
name: openbao
mountPath: database
pluginName: snowflake-database-plugin
pluginVersion: v0.13.0
verifyConnection: false
allowedRoles:
- obco-analytics
privateKeySecretRef:
name: obco-db-root
key: private-key
pluginConfig:
connection_url: '{{username}}@obco-account/analytics'
username: OPENBAO_ROOT
max_open_connections: "4"
With rotateRootOnCreate: true, OpenBao rotates the root password once, right after it creates the
connection, so only OpenBao knows it. The password in the Secret is then stale and is sent again
only if the connection is created again. verifyConnection (default true) makes OpenBao connect
to the database on every write, so a wrong URL or password fails the write.
Built-in and registered plugins¶
For the pinned OpenBao server, PostgreSQL, MySQL (also used by the MariaDB lab), Cassandra,
InfluxDB and Valkey use built-in plugins. Set DatabaseConnection.spec.pluginName to the
appropriate name and use its typed settings. No Plugin resource or pluginRef is needed.
The valkey settings also accept the Redis plugin alias, but the live profile tests Valkey,
not a Redis server.
A plugin that is not built in must be installed on OpenBao and registered separately. A
Plugin CR records the catalog name, executable and checksum; it does not download or
install a binary. DatabaseConnection.pluginName selects that registered name and
pluginConfig carries plugin-specific settings. See the
custom-plugin prerequisites. Elasticsearch is not a built-in
profile and has no live verification in this suite.
3. Create roles¶
A DatabaseRole creates a user per credential request and drops it when the lease ends. The file
also has a role that issues client certificates:
# A dynamic role that creates a read-only PostgreSQL user per request, valid for an hour, and drops it when the lease
# ends.
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseRole
metadata:
name: obco-app-ro
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
mountPath: database
name: obco-app-ro
dbName: postgres
credentialType: password
credentialConfig:
password_policy: obco-db
defaultTTL: 1h
maxTTL: 24h
creationStatements:
- CREATE ROLE "{{name}}" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';
- GRANT SELECT ON ALL TABLES IN SCHEMA public TO "{{name}}";
revocationStatements:
- REVOKE ALL ON ALL TABLES IN SCHEMA public FROM "{{name}}";
- DROP ROLE IF EXISTS "{{name}}";
rollbackStatements:
- DROP ROLE IF EXISTS "{{name}}";
renewStatements:
- ALTER ROLE "{{name}}" VALID UNTIL '{{expiration}}';
---
apiVersion: v1
kind: Secret
metadata:
name: obco-db-client-ca
namespace: openbao-config
type: Opaque
stringData:
key: fake-ca-private-key-not-real
---
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseRole
metadata:
name: obco-app-cert
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
mountPath: database
name: obco-app-cert
dbName: postgres
credentialType: client_certificate
credentialConfig:
ca_cert: fake-ca-certificate-not-real
common_name_template: "{{.DisplayName}}_{{.RoleName}}"
key_type: ec
key_bits: "256"
signature_bits: "256"
caPrivateKeySecretRef:
name: obco-db-client-ca
key: key
defaultTTL: 1h
maxTTL: 24h
creationStatements:
- CREATE ROLE "{{name}}" WITH LOGIN;
revocationStatements:
- DROP ROLE IF EXISTS "{{name}}";
A DatabaseStaticRole manages the password of a user that already exists and rotates it every
rotationPeriod:
apiVersion: secrets.openbaoconfig.io/v1alpha1
kind: DatabaseStaticRole
metadata:
name: obco-app-static
namespace: openbao-config
spec:
connectionRef:
kind: OpenBaoConnection
name: openbao
creationPolicy: CreateOrAdopt
deletionPolicy: Delete
driftDetection: Enabled
mountPath: database
name: obco-app-static
dbName: postgres
username: obco_app
rotationPeriod: 24h
rotationStatements:
- ALTER USER "{{name}}" WITH PASSWORD '{{password}}';
credentialType: password
credentialConfig:
password_policy: obco-db
The role names must be in the connection's allowedRoles.
4. Check that it worked¶
kubectl -n openbao-config get databaseconnections,databaseroles,databasestaticroles
bao read database/creds/obco-app-ro
bao read database/static-creds/obco-app-static
Every resource shows Ready True, and OpenBao returns a username and password for each role.
Troubleshooting¶
| symptom | check |
|---|---|
DatabaseConnection reports ReconcileError with a connection error |
OpenBao connects to the database, not the operator: OpenBao's network path, the URL, the root user and password |
DatabaseConnection reports ReferenceNotReady |
the password Secret and key exist in the resource's namespace |
bao read database/creds/<role> fails with is not an allowed role |
add the role to allowedRoles |
| the Secret's root password no longer works | expected after rotateRootOnCreate or a rotate-root: only OpenBao knows the password |
Related¶
- API reference: DatabaseConnection, DatabaseRole, DatabaseStaticRole, SecretsMount.
- ADR 0017: write-once fields for rotated root credentials.