Add docs about dbinstances

docs/database.md

@@ -227,20 +227,36 @@ USER: << base64 encoded user name (generated by db operator) >>
 
 Then DB Operator will connect to an existing database and set up a user for it.
 
-## Experimantal features
-
-Experimantal features are added via annotations, the following features are available for `Databases`
+## Experimental features
 
+Experimental features are added via annotations, the following features are available for `Databases`
 
+---
 This annotation should be used, when a DbUser is not allowed to log in with password, should be used on the RDS instances, when the SSO is used for authentication.
 
 For more info see this issue: https://github.com/db-operator/db-operator/issues/125
 ```yaml
 kinda.rocks/rds-iam-impersonate: "true"
 ```
-
-Delete a postgres database with present connectins, might be useful when pgbouncer is used
+---
+Delete a postgres database with present connections, might be useful when pgbouncer is used
 
 ```yaml
 kinda.rocks/postgres-force-delete-db: "true"
 ```
+
+## Reconciliation logic
+
+By default db-operator checks if a database needs to be reconcilied.
+
+First, use can force a full reconciliation by setting a following annotation:
+
+```yaml
+kinda.rocks/db-force-full-reconcile: "true"
+```
+
+If it's set, operator will remove it and run the full reconciliation.
+
+Then it checks if it's running in a mode, where it should not check changes and each resource should be fully reconcilied on each loop. Actually, by default it doesn't check and always reconciles databases, but to enable this mode, you need to run the operator with the `--check-for-changes` argument. It might be useful when you have a lot of databases, and updating each one of them might take a very long time.
+
+If you do check for changes, the operator will first check the status of a database and a secret that is used for creating a user. If the status is `false`, or the secret was changed, it will also trigger reconciliation.

docs/dbinstance.md

@@ -1,3 +1,138 @@
 # DbInstance
 
-WIP
+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:
+```yaml
+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
+
+```yaml
+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:
+
+```yaml
+spec:
+  generic:
+    host: ${HOST}
+    port: ${PORT}
+```
+
+Or you can read them from a ConfigMap or a Secret:
+
+```yaml
+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:
+
+```yaml
+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](templates.md). 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:
+
+```yaml
+templates:
+  - name: PG_READONLYHOST
+    secret: false
+    template: "my-read-only-postgres-url.test"
+```
+
+Or you can use the instance variables.
+
+```yaml
+kind: DbInstance
+spec:
+  instanceVars:
+    PG_READONLYHOST: my-read-only-postgres-url.test
+```
+
+And then later use it in a template like that:
+```yaml
+templates:
+  - name: PG_READONLYHOST
+    secret: false
+    template: '{{ .instanceVar "PG_READONLYHOST" }}'
+```
+
+If a value of the variable is changed on the instance, it will be also syned for each Database and User.

docs/index.md

@@ -157,3 +157,7 @@ DB: $DATABASE_NAME
 PASSWORD: $PASSWORD
 USER: $USER
 ```
+
+### How to rotate passwords?
+
+To rotate a db password with a help of DB Operator, it's enough to remove/update the secret that is used by a database.

mkdocs.yml

@@ -4,8 +4,6 @@ theme:
   favicon: assets/logo.png
   name: material
   language: en
-  features:
-    - navigation.tabs
 
   palette: