Skip to content

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 name db)
  • 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. Use credentials.templates instead. You cannot set both fields on the same Database.

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:

kubectl get db my-application-db -n my-app

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 dbin to find the name to set in spec.instance, for example prod1-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.backup unset. To restore a database, contact us.
  • If your namespace is provisioned with a ProjectBootstrap, you can create databases through its spec.databases field instead of writing a Database manifest. See the ProjectBootstrap reference.

Further Reading