Skip to content

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 Ready connection whose OpenBao policy allows sys/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:

spec:
  connectionRef:
    name: openbao
  path: database
  type: database

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:

examples/secrets/databaserole.yaml
# 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:

examples/secrets/databasestaticrole.yaml
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