|
1 | 1 | # db-operator |
2 | 2 |
|
3 | | -   |
| 3 | +   |
4 | 4 |
|
5 | | -The DB Operator creates databases and make them available in the cluster via Custom Resource. |
| 5 | +This operator lets you manage databases in a Kubernetes native way, even if they are not deployed to Kubernetes |
6 | 6 |
|
7 | | -## Source Code |
8 | | - |
9 | | -* <https://github.com/db-operator/db-operator> |
10 | | -* <https://github.com/db-operator/cloudish-sql> |
11 | | -* <https://github.com/db-operator/pgdump-gcs> |
12 | | -* <https://github.com/db-operator/mydump-gcs> |
| 7 | +**Homepage:** <https://github.com/db-operator> |
13 | 8 |
|
14 | 9 | ## Maintainers |
15 | 10 |
|
16 | 11 | | Name | Email | Url | |
17 | 12 | | ---- | ------ | --- | |
18 | | -| Nikolai Rodionov | <allanger@zohomail.com> | <https://badhouseplants.net> | |
19 | | - |
20 | | -## Requirements |
21 | | - |
22 | | -Kubernetes: `>= 1.30-prerelease` |
23 | | - |
24 | | -## Installing the Chart |
25 | | - |
26 | | -```console |
27 | | -$ helm repo add db-operator https://db-operator.github.io/charts |
28 | | -$ helm repo update |
29 | | -$ helm install db-operator/db-operator |
30 | | -``` |
31 | | - |
32 | | -If you want to manage `CRDs` yourself, you need to set `.Values.crds.install` to `false`. In that case they won't be a part of templated manifests. |
33 | | - |
34 | | -We don't support this way of `CRD` management officially though, so we can't promise to answer your questions if you choose to go this way. If you want to know more about it, keep reading, we'll talk about it later. |
35 | | - |
36 | | -## Upgarding the Chart |
37 | | - |
38 | | -If there are breaking changes, they should be described in this README's latest item and in helm-chart notes. So if you run `helm upgrade db-operator db-operator/db-operator --dry-run`, you will see if there are breaking changes there. |
39 | | - |
40 | | -## Uninstalling the Chart |
41 | | - |
42 | | -To uninstall the operator only, run |
43 | | - |
44 | | -```console |
45 | | -$ helm uninstall db-operator |
46 | | -``` |
47 | | - |
48 | | -If you have CRDs installed by the chart, you will also have to run something like: |
49 | | - |
50 | | -```console |
51 | | -# !!! This command will remove all kinda.rocks CRDs from the cluster, |
52 | | -# so please make sure that you really want to run it |
53 | | -$ for crd in $(kubectl get crds | awk '{print $1}' | grep 'kinda.rocks'); do kubectl delete crd "${crd}"; done |
54 | | -``` |
55 | | - |
56 | | -## Why are we packaging CRDs in templates? |
57 | | - |
58 | | -There are several reasons for that. The main one is that we are using webhooks and they require certificates to be created. If you have a look at the `CRDs` templates, you'll see something like that: |
59 | | - |
60 | | -```mustache |
61 | | - annotations: |
62 | | - controller-gen.kubebuilder.io/version: v0.12.1 |
63 | | - {{- if .Values.webhook.certificate.create }} |
64 | | - cert-manager.io/inject-ca-from: {{ .Release.Namespace }}/{{ .Values.webhook.certificate.name}} |
65 | | - {{ else }} |
66 | | - cert-manager.io/inject-ca-from-secret: {{ .Release.Namespace }}/{{ .Values.webhook.certificate.secretName}} |
67 | | - {{- end }} |
68 | | - {{- if .Values.crds.keep }} |
69 | | - helm.sh/resource-policy: keep |
70 | | - {{- end }} |
71 | | - {{- with .Values.crds.annotations }} |
72 | | - {{- toYaml . | nindent 4 }} |
73 | | - {{- end }} |
74 | | -``` |
75 | | - |
76 | | -So, as you can see they require some information about the release, so they can't be static. Since the webhook is an important part of what we're distributing, we don't want to have it disabled by default. |
77 | | - |
78 | | -Also, we do not have `CRs` in the package, so there is no chicken-egg problem here. You don't need to have `CRDs` installed to install the chart. Since `CRDs` are a part of the operator and you can't have one without another, having them packaged and distributed together makes more sense to us. |
| 13 | +| Nikolai Rodionov | <iam@allanger.xyz> | <https://badhouseplants.net> | |
79 | 14 |
|
80 | | -But it's still possible for users to manage `CRDs` on their own. You need to set `.Values.crds.install` to false and go to the [db-operator rgit repository](https://github.com/db-operator/db-operator). There, in the `config/crd/bases` directory, you'll find `CRD` manifests. But if you decided to go this way and you have problems with `CRDs`, you're most probably on your own, you still can open issues though. |
| 15 | +## Source Code |
81 | 16 |
|
82 | | -## Why do we need cert-manager? |
| 17 | +* <https://github.com/db-operator/db-operator> |
83 | 18 |
|
84 | | -At the moment, `db-operator` chart requires `cert-manager` to be present in the cluster. It's because webhook related resources are using it to create certificates. It should change one day, since we would like this chart to be self-sufficient, but currently that's what we've got. |
| 19 | +## Requirements |
85 | 20 |
|
86 | | -## What is `.Values.tests`? |
| 21 | +Kubernetes: `>= 1.32-prerelease` |
87 | 22 |
|
88 | | -We use helm tests feature for testing the chart in CI. Though we know that this feature should be used by users to test their intsallations, we do not think that it can be very helpful in this particular case. Test resources are creating a powerful `ClusterRoles`, so **please make sure you don't have them enabled**, unless you really know what you're doing and why. |
| 23 | +## Values |
89 | 24 |
|
90 | | -## Chart Values |
91 | 25 | | Key | Type | Default | Description | |
92 | 26 | |-----|------|---------|-------------| |
93 | 27 | | nameOverride | string | `""` | | |
94 | 28 | | image.repository | string | `"ghcr.io/db-operator/db-operator"` | | |
95 | 29 | | image.pullPolicy | string | `"Always"` | | |
96 | | -| controller.logLevel | string | `"info"` | | |
97 | | -| controller.extraArgs | list | `[]` | | |
98 | | -| reconcileInterval | string | `"60"` | | |
99 | | -| watchNamespace | string | `""` | | |
100 | | -| checkForChanges | bool | `false` | ---------------------------------------------------------- | |
101 | | -| rbac.create | bool | `true` | | |
102 | | -| serviceAccount.create | bool | `true` | | |
103 | 30 | | crds.install | bool | `true` | | |
104 | 31 | | crds.keep | bool | `true` | | |
105 | 32 | | crds.annotations | object | `{}` | | |
106 | | -| webhook.extraArgs | list | `[]` | | |
| 33 | +| controller.logLevel | string | `"info"` | | |
| 34 | +| controller.extraArgs | list | `[]` | | |
| 35 | +| controller.rbac.create | bool | `true` | | |
| 36 | +| controller.rbac.serviceAccount.name | string | `""` | | |
| 37 | +| controller.rbac.serviceAccount.create | bool | `true` | | |
| 38 | +| controller.config.reconcileInterval | string | `"60"` | | |
| 39 | +| controller.config.watchNamespace | string | `""` | | |
| 40 | +| controller.config.checkForChanges | bool | `false` | | |
107 | 41 | | webhook.enabled | bool | `true` | | |
108 | 42 | | webhook.logLevel | string | `"info"` | | |
| 43 | +| webhook.extraArgs | list | `[]` | | |
109 | 44 | | webhook.podLabels | object | `{}` | | |
110 | | -| webhook.serviceAccount.create | bool | `true` | | |
| 45 | +| webhook.rbac.create | bool | `true` | | |
| 46 | +| webhook.rbac.serviceAccount.name | string | `""` | | |
| 47 | +| webhook.rbac.serviceAccount.create | bool | `true` | | |
111 | 48 | | webhook.names.mutating | string | `"db-operator-mutating-webhook-configuration"` | | |
112 | 49 | | webhook.names.validating | string | `"db-operator-validating-webhook-configuration"` | | |
113 | 50 | | webhook.certificate.create | bool | `true` | ------------------------------------------ | |
@@ -164,53 +101,3 @@ We use helm tests feature for testing the chart in CI. Though we know that this |
164 | 101 | | service.annotations | object | `{}` | | |
165 | 102 | | service.type | string | `"ClusterIP"` | | |
166 | 103 | | service.port | int | `8080` | | |
167 | | -## Dev Notes |
168 | | - |
169 | | -After changing default `Values`, please execute `make gen_docs` to update the `README.md` file. Readme file is generated by the `helm-docs` tool, so make sure not to edit it manually. |
170 | | - |
171 | | -## Upgrading |
172 | | - |
173 | | -If there is an breaking change, or something that might make the upgrade complicated, it should be described here |
174 | | - |
175 | | -<details> |
176 | | - <summary>To <code>v2.0.0</code></summary> |
177 | | -From `v2.0.0` onwards, the `v` prefix will not be automatically added to the image tag. If you are overriding the image tag through `.Values.image.tag` and are relying on this behaviour, please add the `v` prefix manually to the Helm value. Otherwise, no action is required from your side! |
178 | | -</details> |
179 | | - |
180 | | -<details> |
181 | | - <summary>To <code>v1.11.0</code></summary> |
182 | | -Additional selectors were added to the default templates in an attempt to follow the same labelling scheme everywhere, but since selectors are immutable, the upgrade will require removing of the db-operator deployment. |
183 | | - |
184 | | -```bash |
185 | | -$ kubectl get deploy |
186 | | -NAME READY UP-TO-DATE AVAILABLE AGE |
187 | | -db-operator 1/1 1 1 22s |
188 | | -$ kubectl delete deploy db-operator |
189 | | -deployment.apps "db-operator" deleted |
190 | | -$ helm upgrade db-operator db-operator/db-operator --version 1.11.0 |
191 | | -``` |
192 | | - |
193 | | -</details> |
194 | | - |
195 | | -<details> |
196 | | - <summary>To <code>v1.10.0</code></summary> |
197 | | - |
198 | | -CRDs are moved to the `templates` folder, so now they are part of the release. It means that after the upgrade, you will get errors about resource ownerships. Thow errors will contain messages about missing `labels` and `annotations`, and the easiest way to fix it, will be just to add the `metadata` that helm can't find. So you can follow those messages one by one and when all the `CRDs` are patched, you'll be able to install the release. |
199 | | - |
200 | | -For example: |
201 | | - |
202 | | -```BASH |
203 | | -$ helm upgrade my-release . |
204 | | -Error: UPGRADE FAILED: rendered manifests contain a resource that already exists. Unable to continue with update: CustomResourceDefinition "databases.kinda.rocks" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "my-release"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "default" |
205 | | -``` |
206 | | - |
207 | | -So you should add following metadata: |
208 | | -```YAML |
209 | | -metadata: |
210 | | - labels: |
211 | | - "app.kubernetes.io/managed-by": Helm |
212 | | - annotations: |
213 | | - "meta.helm.sh/release-name": my-release |
214 | | - "meta.helm.sh/release-namespace": default |
215 | | -``` |
216 | | -</details> |
0 commit comments