DbInstance

Currently, DbInstances are more or less a meta resource that connects the operator to a database server.

There are actually two types of databases: generic and gsql, and the gsql one is supposed to bootstrap an sql instance in GCP, but they are going to be deprecated soon, and hence I don't feel like writing docs for them. The only important thing about them is that you shouldn't use them

Here we only talk about the generic instances

How to configure a DbInstance

You need to have a PostgreSQL or a MySQL server running, and it has to be accessible by the operator. You also need a user with sufficient permissions, if it's fine in your environment, I would suggest to use an admin user.

Now let's get started:

apiVersion: kinda.rocks/v1beta1
kind: DbInstance
metadata:
  name: cloudnative-pg
spec:
  adminSecretRef:
    Name: cnpg17-admin-creds
    Namespace: databases
  # -- Legacy settings, please set it like this
  # -- it's going to be removed in the next api version
  backup:
    bucket: ""
  engine: postgres
  generic:
    hostFrom:
      key: host
      kind: ConfigMap
      name: cloudnative-pg-config
      namespace: databases
    portFrom:
      key: port
      kind: ConfigMap
      name: cloudnative-pg-config
      namespace: databases
  monitoring:
    enabled: false

Let's quickly go through the yaml

With .adminSecretRef you are pointing the operator to a secret, where the admin credentials are stored. They must be stored in a following format

kind: Secret
data:
  # -- user might be omitted, then the following values will be used
  # -- for PostgreSQL - postgres
  # -- for MySQL      - root
  user: < base64 encoded admin username >
  password: < base64 encoded admin password >

With .engine you let the operator know, if it should treat a server as a PostgreSQL or a MySQL one. Possible values are postgres and mysql

Then you need to configure a URL and a port that the operator should try to connect to, there are two options to do that, you can set them directly in the manifest:

spec:
  generic:
    host: ${HOST}
    port: ${PORT}

Or you can read them from a ConfigMap or a Secret:

spec:
  generic
    hostFrom:
      key: host
      kind: ConfigMap
      name: cloudnative-pg-config
      namespace: databases
    portFrom:
      key: port
      kind: ConfigMap
      name: cloudnative-pg-config
      namespace: databases

Additional configurations

Extra Grants

To use the .extraGrants feature of Databases, you need to enabled it on the instance level. To do so, set the .spec.allowExtraGrants to true

Allowed Privileges

To use the .extraPrivileges feature of DbUsers, you also need to enabled the privileges on the instance level. Extra privileges is a list of roles that can be granteed to DbUsers. For example:

spec:
  generic:
    allowedPriveleges:
      - readOnlyAdmin
      - rds-iam

Then you will be able to assigned these roles to DbUsers. The roles are not managed by the operator, they must be already on a server when a user is created.

Instance Vars

It may happen that you need to share the same variable in the Database/DbUser templates. Let's say you have a RW and RO urls, and your application need two env variables to connect: one - for actibely writing, and another - only for reading.

The RW URL will be available anyway, but how to set a RO one.

Without the instance vars you could just create a template with a hardcoded string in it:

templates:
  - name: PG_READONLYHOST
    secret: false
    template: "my-read-only-postgres-url.test"

Or you can use the instance variables.

kind: DbInstance
spec:
  instanceVars:
    PG_READONLYHOST: my-read-only-postgres-url.test

And then later use it in a template like that:

templates:
  - name: PG_READONLYHOST
    secret: false
    template: '{{ .instanceVar "PG_READONLYHOST" }}'

If a value of a variable is changed on the instance, it will be also synced for each Database and User.