Reference: Database CRD¶
A Database resource requests a PostgreSQL database on a shared database
server. When you create it, the db-operator creates the database and a primary
user with full access to it. The operator then writes the credentials to a
Secret and the connection details to a ConfigMap in your namespace.
- API version:
kinda.rocks/v1beta1 - Kind:
Database(short namedb) - Scope: Namespaced
This page documents db-operator 2.45.1.
Example¶
The following manifest creates a database on the shared instance, protects it
from deletion, creates two extra schemas and adds a JDBC connection string to
the generated Secret.
apiVersion: kinda.rocks/v1beta1
kind: Database
metadata:
name: my-application-db
namespace: my-app
spec:
instance: prod1-dc4-dbaas01.netic-platform.shared.k8s.netic.dk
secretName: my-app-db-credentials
deletionProtected: true
postgres:
schemas:
- orders
- billing
credentials:
templates:
- name: CONNECTION_STRING
secret: true
template: "{{ .Protocol }}://{{ .Username }}:{{ .Password }}@{{ .Hostname }}:{{ .Port }}/{{ .Database }}"
- name: JDBC_URL
secret: true
template: "jdbc:{{ .Protocol }}://{{ .Hostname }}:{{ .Port }}/{{ .Database }}?user={{ .Username }}&password={{ .Password }}"
metadata:
extraLabels:
app.kubernetes.io/part-of: my-application
Specification (spec)¶
| Field | Type | Description |
|---|---|---|
instance |
string |
Required. Name of the cluster-scoped DbInstance that hosts the database. The field is immutable. See The DbInstance Resource. |
secretName |
string |
Required. Name of the Secret that the operator creates to store the generated credentials. The operator also creates a ConfigMap with the same name. If a Secret with this name already exists, the operator uses the credentials in it. See Generated Secret and ConfigMap. |
deletionProtected |
boolean |
Required. When true, the operator keeps the database and its primary user on the server when you delete the Database resource. We recommend true for all databases that hold data you want to keep. |
cleanup |
boolean |
Optional. When true, the Database becomes the owner of the Secret and ConfigMap it creates, so Kubernetes garbage collection deletes them together with the Database. Defaults to false, which keeps them after the Database is deleted. If you set cleanup: true and manage the resource with Argo CD, do not use the foreground prune propagation policy. |
credentials |
object |
Optional. Extra entries and metadata for the generated Secret and ConfigMap. See spec.credentials. |
postgres |
object |
Optional. Settings that apply only to PostgreSQL databases. See spec.postgres. |
existingUser |
string |
Optional. Name of an existing database user to use as the primary user. The operator grants and revokes permissions for this user but does not create or delete it. The operator does not know the user's password, so the POSTGRES_PASSWORD key in the Secret is empty. |
extraGrants |
[]object |
Optional. Grants other existing database users access to this database. The referenced DbInstance must allow extra grants. See spec.extraGrants. |
backup |
object |
Optional. Scheduled database dumps run as a CronJob. Do not set this on Contain Platform. See spec.backup and Platform Notes. |
spec.credentials¶
| Field | Type | Description |
|---|---|---|
templates |
[]object |
Optional. Additional entries that the operator renders and writes to the generated Secret or ConfigMap. When you leave this field empty, the operator adds one default entry named CONNECTION_STRING. When you set it, the default entry is not added, so include CONNECTION_STRING yourself if your application uses it. See spec.credentials.templates[]. |
metadata |
object |
Optional. Labels and annotations to add to the generated Secret. See spec.credentials.metadata. |
spec.credentials.templates[]¶
| Field | Type | Description |
|---|---|---|
name |
string |
Required. Data key that the operator writes. You cannot use the keys that the operator manages itself, such as POSTGRES_DB, POSTGRES_USER and POSTGRES_PASSWORD. |
secret |
boolean |
Required. When true, the operator writes the entry to the Secret. When false, it writes the entry to the ConfigMap. Use true for any value that contains a password. |
template |
string |
Required. A Go template. The operator evaluates it with the fields and functions listed below. |
The following fields are available in a template:
| Field | Value |
|---|---|
{{ .Protocol }} |
postgresql for PostgreSQL databases. |
{{ .Hostname }} |
Database server host, the same value as DB_CONN in the ConfigMap. |
{{ .Port }} |
Database server port, the same value as DB_PORT in the ConfigMap. |
{{ .Database }} |
Database name, the same value as POSTGRES_DB in the Secret. |
{{ .Username }} |
User name, the same value as POSTGRES_USER in the Secret. |
{{ .Password }} |
Password, the same value as POSTGRES_PASSWORD in the Secret. |
The following functions are available in a template. Wrap the argument in double quotes.
| Function | Description |
|---|---|
{{ .Secret "KEY" }} |
Reads a key from the generated Secret, including other templated entries. |
{{ .ConfigMap "KEY" }} |
Reads a key from the generated ConfigMap, including other templated entries. |
{{ .Query "SQL" }} |
Runs a SQL query against the database. The query must return exactly one value. |
{{ .InstanceVar "KEY" }} |
Reads a variable that the DbInstance defines. |
The operator rejects templates that use any other field or function.
spec.credentials.metadata¶
| Field | Type | Description |
|---|---|---|
extraLabels |
map[string]string |
Optional. Labels to merge into the generated Secret. A key in this map replaces an existing label with the same key. |
extraAnnotations |
map[string]string |
Optional. Annotations to merge into the generated Secret. A key in this map replaces an existing annotation with the same key. |
spec.postgres¶
| Field | Type | Description |
|---|---|---|
schemas |
[]string |
Optional. Schemas to create. The primary user receives full access to each schema. Names must match ^[a-zA-Z_][a-zA-Z0-9_-]*$. The operator does not drop schemas with CASCADE, so removing a schema from this list fails while objects in the schema exist. |
dropPublicSchema |
boolean |
Optional. When true, the operator removes the public schema after it creates the database. Changing this to true later fails while objects in public exist. |
extensions |
[]string |
Optional. PostgreSQL extensions to create in the database with CREATE EXTENSION IF NOT EXISTS. Names must match ^[a-zA-Z_][a-zA-Z0-9_-]*$. |
template |
string |
Optional. Name of a PostgreSQL template database on the server to create this database from. This refers to a database on the server, not to a Database resource, and the operator does not check that it exists. The field is immutable. |
spec.extraGrants[]¶
| Field | Type | Description |
|---|---|---|
user |
string |
Required. Name of an existing database user to grant access to. |
accessType |
string |
Required. Access level. Allowed values are readOnly (SELECT) and readWrite (SELECT, INSERT, UPDATE, DELETE). |
To revoke or change a grant, remove or edit its entry. The operator applies the change on the next reconciliation.
spec.backup¶
| Field | Type | Description |
|---|---|---|
enable |
boolean |
Required when backup is set. When true, the operator creates a CronJob that dumps the database. |
cron |
string |
Required when backup is set. Schedule for the CronJob, in cron format. |
envFromSecret |
string |
Optional. Name of a Secret whose data the operator exposes to the backup container as environment variables. |
Deprecated Fields¶
secretsTemplates(map[string]string) is deprecated. Usecredentials.templatesinstead. You cannot set both fields on the sameDatabase.
Generated Secret and ConfigMap¶
For a PostgreSQL database, the operator creates the following resources, both
named after spec.secretName:
| Resource | Key | Content |
|---|---|---|
Secret |
POSTGRES_DB |
Database name. |
Secret |
POSTGRES_USER |
User name of the primary user. |
Secret |
POSTGRES_PASSWORD |
Password of the primary user. Empty when you set existingUser. |
Secret |
CONNECTION_STRING |
Connection URL in the form postgresql://<user>:<password>@<host>:<port>/<database>. Present by default, or when you define it in credentials.templates. |
ConfigMap |
DB_CONN |
Database server host. |
ConfigMap |
DB_PORT |
Database server port. |
ConfigMap |
SSL_MODE |
SSL mode for connections to the server. |
Entries from credentials.templates are added to the Secret or ConfigMap
according to their secret field.
Annotations¶
The operator reads the following annotations on a Database. Upstream marks
kinda.rocks/postgres-force-delete-db as experimental.
| Annotation | Description |
|---|---|
kinda.rocks/db-force-full-reconcile: "true" |
Forces a full reconciliation. The operator removes the annotation afterward. |
kinda.rocks/postgres-force-delete-db: "true" |
Deletes the PostgreSQL database even while it has open connections. |
Status (status)¶
| Field | Type | Description |
|---|---|---|
status |
boolean |
true after the database reconciles successfully. Shown in the STATUS column of kubectl get db. |
database |
string |
Name of the database on the server. |
user |
string |
Name of the primary user on the server. |
engine |
string |
Database engine, postgres on Contain Platform. |
extraGrants |
[]object |
Grants applied during the last successful reconciliation. |
operatorVersion |
string |
db-operator version that last completed reconciliation. |
monitorUserSecret |
string |
Name of the Secret for the monitoring user, if any. |
proxyStatus |
object |
Connection proxy state, with serviceName, sqlPort and status. When the proxy is ready, {{ .Hostname }} and {{ .Port }} resolve to the proxy service. |
To check the state of a database, run:
The DbInstance Resource¶
The DbInstance resource describes the database server that hosts your
databases. It is cluster-scoped, and we create and operate it for you. You do
not create a DbInstance. Instead, you reference it by name in
spec.instance. To list the instances available in your cluster, run
kubectl get dbin. Features that depend on instance configuration, such as
extraGrants and {{ .InstanceVar }} variables, are available only if the
instance enables them.
Platform Notes¶
- We provide one or more highly available database servers per cluster. Use
kubectl get dbinto find the name to set inspec.instance, for exampleprod1-dc4-dbaas01.netic-platform.shared.k8s.netic.dk. - We manage backup and recovery at the instance level. Full backups run
nightly at 22:00 and are archived for 6 months, and point-in-time recovery
covers the last 5 days. Leave
spec.backupunset. To restore a database, contact us. - If your namespace is provisioned with a
ProjectBootstrap, you can create databases through itsspec.databasesfield instead of writing aDatabasemanifest. See theProjectBootstrapreference.