Issue and revoke dynamic database credentials¶
Use the operator to configure OpenBao's database engine, then authenticate a workload and use its temporary credentials against a real database. This tutorial starts with PostgreSQL. The same runner supports the engine recipes below.
The database is a secrets-engine target. OpenBao continues to store its own data in its three-node TLS Raft cluster. The database fixtures are disposable single-instance services, not production database installation examples.
Before you begin¶
Work at the root of this repository with Docker running. Install Go, Python 3, kubectl and OpenSSL. The Make targets obtain the repository's pinned kind, Helm and yq tools. The lab needs enough Docker memory for OpenBao, the operator and the selected database; Cassandra alone has a 2 GiB container memory limit. Run engine profiles one at a time on a small machine. No external database account or hosted-provider secret is needed.
1. Start a separate lab¶
export LAB_CONTEXT=kind-obco-database-tutorial
make lab-up
export KUBECONFIG="$PWD/.tmp/lab/${LAB_CONTEXT#kind-}/kubeconfig"
lab-up installs OpenBao and the operator and creates the lab connection. Keep this shell
for the following commands. The explicit kubeconfig keeps inspection commands on this lab.
2. Configure PostgreSQL and run the lifecycle¶
The runner installs the database fixture, creates random bootstrap credentials and a disposable CA, and applies the operator configuration from the database configuration chart. Its resources are:
| Resource | Responsibility |
|---|---|
SecretsMount |
Enable database at lab-db-postgresql |
DatabaseConnection |
Connect to PostgreSQL using a same-namespace password Secret reference |
DatabaseRole |
Create a reader identity per request, with a 5-minute default and 15-minute maximum lease |
AuthMount, KubernetesAuthConfig, KubernetesAuthRole |
Authenticate the db-root or db-alpha ServiceAccount with audience openbao |
Policy |
Permit issuance only from lab-db-postgresql/creds/reader and session self-revocation |
There are separate configurations in OpenBao's root namespace and lab-alpha. Their Kubernetes
custom resources live in obco-lab; spec.namespace: lab-alpha selects the child OpenBao
namespace. The root workload has a restricted policy: it does not receive a root token.
You should see a configuration-Ready message followed by one successful lifecycle summary for each namespace. A failed login, permission check or cleanup makes the command fail.
3. Inspect the configuration without exposing credentials¶
kubectl --context "$LAB_CONTEXT" -n obco-lab get \
secretsmounts,databaseconnections,databaseroles,kubernetesauthroles \
-l lab.openbaoconfig.io/profile=database
The Ready connection and role prove configuration convergence. The preceding runner goes further: it opens actual database sessions with the generated identities.
To inspect the PostgreSQL root-namespace configuration before applying it elsewhere:
The rendered YAML contains Secret references, not passwords. The sample values assume the lab's existing connection, database endpoint, credentials and OpenBao CA mount; rendering them does not install those prerequisites. Keep statements in the values file specific to your database privileges rather than granting blanket administrator rights to generated users.
4. Understand the assertions¶
For both root and lab-alpha, the runner:
- Exchanges a short-lived ServiceAccount token for a narrowly scoped OpenBao token.
- Refuses credential issuance in the other OpenBao namespace.
- Requests two independent credentials and checks distinct users and renewable leases.
- Reads the tenant's fixture data, rejects a write and rejects the other tenant's data.
- Renews the first lease and verifies that its credentials still work.
- Revokes that lease, requires a database authentication rejection on a new connection, and verifies that the second identity still works.
- Revokes the remaining lease and workload token and deletes temporary credential Secrets.
Lease renewal and revocation use the lab's administrative identity. The workload policy grants neither permission. These tests do not prove workload self-service lease administration or termination of already-open database sessions after revocation.
Bootstrap database accounts have the privileges needed to create and drop users; generated reader accounts have narrower grants. Temporary credentials are passed to probe Jobs through Kubernetes Secrets and can be read by principals with appropriate Kubernetes access. Probe logs contain only a fixed success marker, not database passwords or query output.
Choose an engine¶
Run the matching command after step 1. Each recipe explains its privilege model and TLS settings.
| Recipe | Command | Connection plugin |
|---|---|---|
| PostgreSQL | make lab-database DATABASE_PROFILE=postgresql |
postgresql-database-plugin |
| MySQL | make lab-database DATABASE_PROFILE=mysql |
mysql-database-plugin |
| MariaDB | make lab-database DATABASE_PROFILE=mariadb |
mysql-database-plugin |
| Cassandra | make lab-database DATABASE_PROFILE=cassandra |
cassandra-database-plugin |
| InfluxDB | make lab-database DATABASE_PROFILE=influxdb |
influxdb-database-plugin |
| Valkey | make lab-database DATABASE_PROFILE=valkey |
valkey-database-plugin |
All six profiles use plugins built into the pinned OpenBao server. Set DatabaseConnection.spec.pluginName;
there is no pluginRef field to set and no Plugin resource to register for those built-ins.
For other engines, review the custom-plugin prerequisites.
No external database binary is downloaded by this lab.
The Redis plugin alias is not a Redis-server test. Elasticsearch is not a built-in profile
and has no live coverage here.
Deliver the configuration with Argo CD¶
The separate public-Git regression runs the PostgreSQL configuration through real Argo CD Applications rather than applying the rendered database CRs directly:
It creates its own disposable kind cluster. The
AppProject permits the operator's database and
workload-auth resources only in obco-gitops. The
root Application and
child Application use the shared chart
with separate PostgreSQL values files. Argo CD reports ownership of those resources and must
be Synced and Healthy at the selected public Git commit before the SQL lifecycle runs.
OpenBao and the operator are delivered through the existing Helm-based app hierarchy.
The PostgreSQL server, bootstrap password and public CA are prepared as test infrastructure;
the Applications reconcile the OpenBao configuration, not the database server. Their values
reference the pre-existing gitops-openbao connection and database password Secret. AppProject
restrictions limit what the Applications may manage; they are not Kubernetes Secret-read RBAC.
The checked-in Applications default to main. For an unmerged commit already pushed to the
public repository, select that revision as described in the
Argo CD deployment guide. The workflow uses its tested commit.
There is no equivalent database-specific Flux regression yet, and pruning the CRs does not
remove the database: their deletionPolicy is Orphan.
Troubleshooting¶
| Failure | Check |
|---|---|
| Database Deployment is not ready | Pod events, image availability and Docker memory in obco-db-<provider> |
| Connection is not Ready | Database administrator Secret, service DNS, trusted CA and database privileges; OpenBao makes the connection |
| Issuance fails | The connection's allowedRoles, role statements and the workload's exact credentials path |
| Probe Job fails | The fixed test stage and Job status; a wrong error category is a failure, not accepted as a denial |
| Cleanup reports an error | The remaining lease may still be active; inspect/revoke it with an administrator before reusing the fixture |
| A long-lived local lab stops connecting over TLS | Database fixture certificates expire after two days; recreate the disposable lab |
Do not dump Secrets or enable shell tracing to diagnose an authentication problem.
Remove the lab¶
This removes the databases and OpenBao volumes as well as their Kubernetes resources. The
runner's finally block normally removes issued credentials and probe Jobs, but it deliberately
keeps configuration and database fixtures for inspection. Database CRs use deletionPolicy: Orphan;
deleting their manifests alone is not a full database teardown.
Coverage boundary¶
These profiles are wired into the integration lab workflow. Their addition is not evidence
that every engine has passed on the current commit: check each db-* job. Offline schema and
harness tests do not substitute for a live run.
| Behaviour | This dynamic-credential suite |
|---|---|
| Issuance, real login, scoped read and denied writes/cross-tenant access | Executed for root and one child namespace |
| Distinct identities, renewal, revoked new-login denial | Executed for root and one child namespace |
| Static-role scheduled rotation and root-password rotation | PostgreSQL-only lifecycle extension; other profiles do not exercise these |
| Natural lease expiry and existing-session termination | Not exercised |
| Database HA, backups and production administration | Outside this disposable lab |
Continue with the database configuration guide for static roles and the verification guide for CI scope.