Getting started page and templates

docs/database.md

@@ -0,0 +1,3 @@
+# Database
+
+WIP

docs/dbinstances.md

@@ -0,0 +1,3 @@
+# DbInstance
+
+WIP

docs/dbuser.md

@@ -0,0 +1 @@
+# DbUser

docs/development/contribution.md

@@ -0,0 +1,5 @@
+# How to contribute
+
+## Workflow
+
+## How to become a maintainer

docs/development/helm-charts.md

@@ -25,4 +25,3 @@ yq -i '.appVersion = "${GIT_SHA}"' ./charts/db-operator/Chart.yaml
 ```
 
 After that, CRDs will be up-to-date with the operator repo and you can test your changes.
-##

docs/index.md

@@ -1,9 +1,159 @@
 # Getting Started
 
+DB Operator is a Kubernetes operator for managing **MySQL** and **PostgreSQL** databases through **CRDs**.
 
+This operator doesn't launch database servers, instead it should be connected to the running ones, that's why it doesn't nececeraly require that the database is running in Kubernetes, and can be used with any server that can be accessed from inside the cluster.
+
+After it is connected to a server, you can start managing databases and users through CRDs. When a user or a database is created, db-operator will add a `Secret` and a `ConfigMap` to the namespace where CR is deployed, they can be used by a pod to establish a connection with a database.
+
+### Example
+
+Let's imagine, you have an application that requires a connection to a Postgres DB, it receives credentials from the environment variable `POSTGRES_DATASOURCE`, and it needs to be in a following format: `postgresql://${USER}:${PASSWORD}@${HOSTNAME}:${PORT}/${DATABASE}?search_path=myapp`
+
+We will talk about how to install the operator and connect it to a server later, now let's focus on the main logic. We need to create a `Database` resource:
+```yaml
+apiVersion: kinda.rocks/v1beta1
+kind: Database
+metadata:
+  name: my-app
+  namespace: my-namespace
+spec:
+  backup:
+    enable: false
+  credentials:
+    templates:
+    # - This template will be used by the operator to add POSTGRES_DATASOURCE to the secret.
+    - name: POSTGRES_DATASOURCE
+      secret: true
+      template: '{{ .Protocol }}://{{ .Username }}:{{ .Password }}@{{ .Hostname }}:{{ .Port }}/{{ .Database }}?search_path=my-app'
+  deletionProtected: true
+  instance: some-postgres
+  postgres:
+    dropPublicSchema: true
+    schemas:
+    - my-app
+  secretName: my-app-db-creds
+```
+
+[Read more about templates here](templates.md)
+
+
+> (@allanger): This logic might be changed when the `Database` resource will be upgrade to the version `v1`
+After the reconciliation you should be able to find a `ConfigMap` and a `Secret` in the namespace `my-namespace`. They both will be called `my-app-db-creds`, and you can use them to connect your application to the database. No manual interactions are needed, everything is managed within a Kubernetes cluster.
 
 ## Install db-operator
 
+We distribute DB Operator as a `helm` chart. You don't have to use it, but if you want to be able to get support, it's would be easier for us if you use the chart.
+
+The charts is released as s simple help repo as well as a an OCI artifact.
+
+To install the repo, run the following
+
+```sh
+$ helm repo add db-operator https://db-operator.github.io/charts
+$ helm search repo db-operator
+```
+
+OCI artifacts are available under `ghcr.io/db-operator/charts/`
+
+To install the chart, run the following:
+
+```sh
+$ helm install db-operator/db-operator
+# -- Or OCI
+$ helm install ghcr.io/db-operator/charts/db-operator:${CHART_VERSION}
+```
+
+More info about the db-operator chart can be found in the [README.md](https://github.com/db-operator/charts/tree/main/charts/db-operator)
+
 ## Create a DbInstance
 
+After the operator is installed, you need to connect it to a database. For this the `db-instances` chart can be used.
+
+Create a following `values.yaml` file:
+```yaml
+# -- values.yaml
+dbinstances:
+  instance1:
+    engine: postgres
+    monitoring:
+      enabled: false
+    secrets:
+      adminUser: admin # Root username
+      adminPassword: password # Root password
+    generic:
+      host: postgres.databases.svc.cluster.local # Host
+      port: 5432
+```
+
+And install a helm chart like this:
+
+```sh
+$ helm install db-operator/db-instances -f ./values.yaml
+```
+
+To check the DbInstance status, run:
+```sh
+kubectl get dbinstance instance1
+
+NAME              PHASE          STATUS
+instance1         Running        true
+```
+
+If `.status.Status` is `true`, it means that you can create Databases on this instance.
+
+You can read more about DbInstances [here](dbinstances.md)
+
 ## Create a Database
+
+After the instancei is ready, you can start managing databases with the operator. Databases are not packaged in any helm chart, because they are supposed to be parts of the end applications, like an `Ingress` or a `PVC`, - something that your pod will need to run. Let's create a database:
+
+```yaml
+# - db.yaml
+apiVersion: kinda.rocks/v1beta1
+kind: Database
+metadata:
+  name: database-1
+spec:
+  backup:
+    enable: false
+  deletionProtected: false
+  instance: instance1
+  secretName: database-1-creds
+```
+
+```sh
+$ kubectl apply -f db.yaml
+$ kubectl get db
+NAME         STATUS   PROTECTED   DBINSTANCE         OPERATORVERSION   AGE
+database-1   true     false       instance1          2.19.0            31s
+```
+
+When `.status.Status` is `true`, it means that you can use your database.
+
+You can read more about databases [here](database.md)
+
+## F.A.Q.
+
+### How to add ownerReferences to Secrets and ConfigMaps created by the operator?
+
+DB Operator is designed in a way, that an application should be able to connect to a database, even if the operator was accidentally removed with all the CRDs. That's why by default Secrets and ConfigMaps are just created in the cluster without owner references. But if you would like these resources to be cleaned up after a databases is removed, or you need to see connection between them in ArgoCD, you can set the `.spec.cleanup` to `true`
+
+If ArgoCD is used to manage Databases and the `cleanup` is set to `true`, please make sure that the `PrunePropagationPolicy` is not set to `foreground`, because db-operator is using secrets to understand which Database must be removed, and with the `foreground` policy the secret is removed before the Database, that makes it impossible for the operator to finish the reconciliation.
+
+### How to connect the operator to an existing Database?
+
+DB Operator is reading the secret using the `spec.secretName` entry. If this secret doesn't exist, operator will create it and read data out of it. But if a secret is found, it will try to get items that are required to connect to a database from there.
+
+There are the keys, they a secret must contain:
+
+```
+# for PosrgreSQL
+POSTGRES_DB: $DATABASE_NAME
+POSTGRES_PASSWORD: $PASSWORD
+POSTGRES_USER: $USERNAME
+# and for MySQL
+DB: $DATABASE_NAME
+PASSWORD: $PASSWORD
+USER: $USER
+```

docs/templates.md

@@ -0,0 +1,97 @@
+# Templates
+
+DB Operator is capable of producing custom templated entries in `Secrets` and `ConfigMaps` using the database data. This features is using **go templates** and can be used in a following way:
+
+```yaml
+---
+# in Databases
+kind: Database
+spec:
+  credentials:
+    templates:
+      - name: USER_AND_PASSWORD
+        template: "{{ .Username }}-{{ .Password }}"
+        secret: true
+---
+# or in DbUsers
+kind: DbUser
+spec:
+  credentials:
+    templates:
+      - name: USER_AND_PASSWORD
+        template: "{{ .Username }}-{{ .Password }}"
+        secret: true
+```
+
+## Available fields and functions
+
+These fields are available for templating:
+
+- **Protocol**: Depends on the db engine. Possible values are `mysql`/`postgresql`
+- **Hostname**: The same value as for db host in the connection configmap
+- **Port**: The same value as for db port in the connection configmap
+- **Database**: The same value as for db name in the creds secret
+- **Username**: The same value as for database user in the creds secret
+- **Password**: The same value as for password in the creds secret
+
+So to create a full connection string, you could use a template like that:
+
+```
+"{{ .Protocol }}://{{ .Username }}:{{ .Password }}@{{ .Hostname }}:{{ .Port }}/{{ .Database }}"
+```
+
+It's also possible to use one of these functions to get data directly from data sources available to the operator:
+
+- **Secret**: Query data from the Secret
+- **ConfigMap**: Query data from the ConfigMap
+- **Query**: Get data directly from the database
+
+When using `Secret` and `ConfigMap` you can query the previously created secret to template a new one, e.g.:
+
+```yaml
+spec:
+  credentials:
+    templates:
+      - name: TMPL_1
+        template: "test"
+        secret: false
+      - name: TMPL_2
+        template: "{{ .ConfigMap \"TMPL_1\"}}"
+        secret: true
+      - name: TMPL_3
+        template: "{{ .Secret \"TMPL_2\"}}"
+        secret: false
+```
+
+When using `Query` you need to make sure that you query returns only one value. For example:
+
+```yaml
+...
+    templates:
+      - name: POSTGRES_VERSION
+        secret: false
+        template: "{{ .Query \"SHOW server_version;\" }}"
+```
+
+For values that are shared between different databases on the same instance, it's possible to set instance variables. Once they are set on the instance, they can also be used in database/dbuser templates.
+
+
+```yaml
+kind: DbInstance
+spec:
+  instanceVars:
+    TEST_KEY: TEST_VALUE
+```
+
+These variables can be also accessed by the Database/DbUser templates
+
+```yaml
+...
+    templates:
+      - name: DB_INSTANCE_VAR
+        secret: false
+        template: "{{ .InstanceVar 'TEST_KEY' }}"
+...
+```
+
+Then the secret that is created by the operator should contain the following entry: `DB_INSTANCE_VAR: TEST_VALUE`. When the value is changed on the instance level, it should also trigger reconciliation of the databases and hence the values should also be updated in the target secrets.

mkdocs.yml

@@ -1,4 +1,24 @@
 site_name: DB Operator
 theme:
+  logo: assets/logo.png
+  favicon: assets/logo.png
   name: material
   language: en
+  features:
+    - navigation.tabs
+
+  palette:
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode