|
1 | 1 | # Getting Started |
2 | 2 |
|
| 3 | +DB Operator is a Kubernetes operator for managing **MySQL** and **PostgreSQL** databases through **CRDs**. |
3 | 4 |
|
| 5 | +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. |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +### Example |
| 10 | + |
| 11 | +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` |
| 12 | + |
| 13 | +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: |
| 14 | +```yaml |
| 15 | +apiVersion: kinda.rocks/v1beta1 |
| 16 | +kind: Database |
| 17 | +metadata: |
| 18 | + name: my-app |
| 19 | + namespace: my-namespace |
| 20 | +spec: |
| 21 | + backup: |
| 22 | + enable: false |
| 23 | + credentials: |
| 24 | + templates: |
| 25 | + # - This template will be used by the operator to add POSTGRES_DATASOURCE to the secret. |
| 26 | + - name: POSTGRES_DATASOURCE |
| 27 | + secret: true |
| 28 | + template: '{{ .Protocol }}://{{ .Username }}:{{ .Password }}@{{ .Hostname }}:{{ .Port }}/{{ .Database }}?search_path=my-app' |
| 29 | + deletionProtected: true |
| 30 | + instance: some-postgres |
| 31 | + postgres: |
| 32 | + dropPublicSchema: true |
| 33 | + schemas: |
| 34 | + - my-app |
| 35 | + secretName: my-app-db-creds |
| 36 | +``` |
| 37 | +
|
| 38 | +[Read more about templates here](templates.md) |
| 39 | +
|
| 40 | +
|
| 41 | +> (@allanger): This logic might be changed when the `Database` resource will be upgrade to the version `v1` |
| 42 | +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. |
4 | 43 |
|
5 | 44 | ## Install db-operator |
6 | 45 |
|
| 46 | +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. |
| 47 | + |
| 48 | +The charts is released as s simple help repo as well as a an OCI artifact. |
| 49 | + |
| 50 | +To install the repo, run the following |
| 51 | + |
| 52 | +```sh |
| 53 | +$ helm repo add db-operator https://db-operator.github.io/charts |
| 54 | +$ helm search repo db-operator |
| 55 | +``` |
| 56 | + |
| 57 | +OCI artifacts are available under `ghcr.io/db-operator/charts/` |
| 58 | + |
| 59 | +To install the chart, run the following: |
| 60 | + |
| 61 | +```sh |
| 62 | +$ helm install db-operator/db-operator |
| 63 | +# -- Or OCI |
| 64 | +$ helm install ghcr.io/db-operator/charts/db-operator:${CHART_VERSION} |
| 65 | +``` |
| 66 | + |
| 67 | +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) |
| 68 | + |
7 | 69 | ## Create a DbInstance |
8 | 70 |
|
| 71 | +After the operator is installed, you need to connect it to a database. For this the `db-instances` chart can be used. |
| 72 | + |
| 73 | +Create a following `values.yaml` file: |
| 74 | +```yaml |
| 75 | +# -- values.yaml |
| 76 | +dbinstances: |
| 77 | + instance1: |
| 78 | + engine: postgres |
| 79 | + monitoring: |
| 80 | + enabled: false |
| 81 | + secrets: |
| 82 | + adminUser: admin # Root username |
| 83 | + adminPassword: password # Root password |
| 84 | + generic: |
| 85 | + host: postgres.databases.svc.cluster.local # Host |
| 86 | + port: 5432 |
| 87 | +``` |
| 88 | + |
| 89 | +And install a helm chart like this: |
| 90 | + |
| 91 | +```sh |
| 92 | +$ helm install db-operator/db-instances -f ./values.yaml |
| 93 | +``` |
| 94 | + |
| 95 | +To check the DbInstance status, run: |
| 96 | +```sh |
| 97 | +kubectl get dbinstance instance1 |
| 98 | +
|
| 99 | +NAME PHASE STATUS |
| 100 | +instance1 Running true |
| 101 | +``` |
| 102 | + |
| 103 | +If `.status.Status` is `true`, it means that you can create Databases on this instance. |
| 104 | + |
| 105 | +You can read more about DbInstances [here](dbinstances.md) |
| 106 | + |
9 | 107 | ## Create a Database |
| 108 | + |
| 109 | +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: |
| 110 | + |
| 111 | +```yaml |
| 112 | +# - db.yaml |
| 113 | +apiVersion: kinda.rocks/v1beta1 |
| 114 | +kind: Database |
| 115 | +metadata: |
| 116 | + name: database-1 |
| 117 | +spec: |
| 118 | + backup: |
| 119 | + enable: false |
| 120 | + deletionProtected: false |
| 121 | + instance: instance1 |
| 122 | + secretName: database-1-creds |
| 123 | +``` |
| 124 | + |
| 125 | +```sh |
| 126 | +$ kubectl apply -f db.yaml |
| 127 | +$ kubectl get db |
| 128 | +NAME STATUS PROTECTED DBINSTANCE OPERATORVERSION AGE |
| 129 | +database-1 true false instance1 2.19.0 31s |
| 130 | +``` |
| 131 | + |
| 132 | +When `.status.Status` is `true`, it means that you can use your database. |
| 133 | + |
| 134 | +You can read more about databases [here](database.md) |
| 135 | + |
| 136 | +## F.A.Q. |
| 137 | + |
| 138 | +### How to add ownerReferences to Secrets and ConfigMaps created by the operator? |
| 139 | + |
| 140 | +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` |
| 141 | + |
| 142 | +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. |
| 143 | + |
| 144 | +### How to connect the operator to an existing Database? |
| 145 | + |
| 146 | +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. |
| 147 | + |
| 148 | +There are the keys, they a secret must contain: |
| 149 | + |
| 150 | +``` |
| 151 | +# for PosrgreSQL |
| 152 | +POSTGRES_DB: $DATABASE_NAME |
| 153 | +POSTGRES_PASSWORD: $PASSWORD |
| 154 | +POSTGRES_USER: $USERNAME |
| 155 | +# and for MySQL |
| 156 | +DB: $DATABASE_NAME |
| 157 | +PASSWORD: $PASSWORD |
| 158 | +USER: $USER |
| 159 | +``` |
0 commit comments