helm/infrastructure/subcharts/kong/charts/postgresql/charts/common/README.md

   1 # Bitnami Common Library Chart
   2
   3 A [Helm Library Chart](https://helm.sh/docs/topics/library_charts/#helm) for grouping common logic between bitnami charts.
   4
   5 ## TL;DR
   6
   7 ```yaml
   8 dependencies:
   9   - name: common
  10     version: 1.x.x
  11     repository: https://charts.bitnami.com/bitnami
  12 ```
  13
  14 ```bash
  15 $ helm dependency update
  16 ```
  17
  18 ```yaml
  19 apiVersion: v1
  20 kind: ConfigMap
  21 metadata:
  22   name: {{ include "common.names.fullname" . }}
  23 data:
  24   myvalue: "Hello World"
  25 ```
  26
  27 ## Introduction
  28
  29 This chart provides a common template helpers which can be used to develop new charts using [Helm](https://helm.sh) package manager.
  30
  31 Bitnami charts can be used with [Kubeapps](https://kubeapps.dev/) for deployment and management of Helm Charts in clusters.
  32
  33 ## Prerequisites
  34
  35 - Kubernetes 1.19+
  36 - Helm 3.2.0+
  37
  38 ## Parameters
  39
  40 The following table lists the helpers available in the library which are scoped in different sections.
  41
  42 ### Affinities
  43
  44 | Helper identifier             | Description                                          | Expected Input                                 |
  45 |-------------------------------|------------------------------------------------------|------------------------------------------------|
  46 | `common.affinities.nodes.soft` | Return a soft nodeAffinity definition                | `dict "key" "FOO" "values" (list "BAR" "BAZ")` |
  47 | `common.affinities.nodes.hard` | Return a hard nodeAffinity definition                | `dict "key" "FOO" "values" (list "BAR" "BAZ")` |
  48 | `common.affinities.pods.soft`  | Return a soft podAffinity/podAntiAffinity definition | `dict "component" "FOO" "context" $`           |
  49 | `common.affinities.pods.hard`  | Return a hard podAffinity/podAntiAffinity definition | `dict "component" "FOO" "context" $`           |
  50
  51 ### Capabilities
  52
  53 | Helper identifier                              | Description                                                                                    | Expected Input    |
  54 |------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------|
  55 | `common.capabilities.kubeVersion`              | Return the target Kubernetes version (using client default if .Values.kubeVersion is not set). | `.` Chart context |
  56 | `common.capabilities.cronjob.apiVersion`       | Return the appropriate apiVersion for cronjob.                                                 | `.` Chart context |
  57 | `common.capabilities.deployment.apiVersion`    | Return the appropriate apiVersion for deployment.                                              | `.` Chart context |
  58 | `common.capabilities.statefulset.apiVersion`   | Return the appropriate apiVersion for statefulset.                                             | `.` Chart context |
  59 | `common.capabilities.ingress.apiVersion`       | Return the appropriate apiVersion for ingress.                                                 | `.` Chart context |
  60 | `common.capabilities.rbac.apiVersion`          | Return the appropriate apiVersion for RBAC resources.                                          | `.` Chart context |
  61 | `common.capabilities.crd.apiVersion`           | Return the appropriate apiVersion for CRDs.                                                    | `.` Chart context |
  62 | `common.capabilities.policy.apiVersion`        | Return the appropriate apiVersion for podsecuritypolicy.                                       | `.` Chart context |
  63 | `common.capabilities.networkPolicy.apiVersion` | Return the appropriate apiVersion for networkpolicy.                                           | `.` Chart context |
  64 | `common.capabilities.apiService.apiVersion`    | Return the appropriate apiVersion for APIService.                                              | `.` Chart context |
  65 | `common.capabilities.hpa.apiVersion`           | Return the appropriate apiVersion for Horizontal Pod Autoscaler                                | `.` Chart context |
  66 | `common.capabilities.supportsHelmVersion`      | Returns true if the used Helm version is 3.3+                                                  | `.` Chart context |
  67
  68 ### Errors
  69
  70 | Helper identifier                       | Description                                                                                                                                                            | Expected Input                                                                      |
  71 |-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
  72 | `common.errors.upgrade.passwords.empty` | It will ensure required passwords are given when we are upgrading a chart. If `validationErrors` is not empty it will throw an error and will stop the upgrade action. | `dict "validationErrors" (list $validationError00 $validationError01)  "context" $` |
  73
  74 ### Images
  75
  76 | Helper identifier           | Description                                          | Expected Input                                                                                          |
  77 |-----------------------------|------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
  78 | `common.images.image`       | Return the proper and full image name                | `dict "imageRoot" .Values.path.to.the.image "global" $`, see [ImageRoot](#imageroot) for the structure. |
  79 | `common.images.pullSecrets` | Return the proper Docker Image Registry Secret Names (deprecated: use common.images.renderPullSecrets instead) | `dict "images" (list .Values.path.to.the.image1, .Values.path.to.the.image2) "global" .Values.global` |
  80 | `common.images.renderPullSecrets` | Return the proper Docker Image Registry Secret Names (evaluates values as templates) | `dict "images" (list .Values.path.to.the.image1, .Values.path.to.the.image2) "context" $` |
  81
  82 ### Ingress
  83
  84 | Helper identifier                         | Description                                                                                                       | Expected Input                                                                                                                                                                   |
  85 |-------------------------------------------|-------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
  86 | `common.ingress.backend`                  | Generate a proper Ingress backend entry depending on the API version                                              | `dict "serviceName" "foo" "servicePort" "bar"`, see the [Ingress deprecation notice](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/) for the syntax differences |
  87 | `common.ingress.supportsPathType`         | Prints "true" if the pathType field is supported                                                                  | `.` Chart context                                                                                                                                                                |
  88 | `common.ingress.supportsIngressClassname` | Prints "true" if the ingressClassname field is supported                                                          | `.` Chart context                                                                                                                                                                |
  89 | `common.ingress.certManagerRequest`       | Prints "true" if required cert-manager annotations for TLS signed certificates are set in the Ingress annotations | `dict "annotations" .Values.path.to.the.ingress.annotations`                                                                                                                     |
  90
  91 ### Labels
  92
  93 | Helper identifier           | Description                                                                 | Expected Input    |
  94 |-----------------------------|-----------------------------------------------------------------------------|-------------------|
  95 | `common.labels.standard`    | Return Kubernetes standard labels                                           | `.` Chart context |
  96 | `common.labels.matchLabels` | Labels to use on `deploy.spec.selector.matchLabels` and `svc.spec.selector` | `.` Chart context |
  97
  98 ### Names
  99
 100 | Helper identifier                 | Description                                                           | Expected Input    |
 101 |-----------------------------------|-----------------------------------------------------------------------|-------------------|
 102 | `common.names.name`               | Expand the name of the chart or use `.Values.nameOverride`            | `.` Chart context |
 103 | `common.names.fullname`           | Create a default fully qualified app name.                            | `.` Chart context |
 104 | `common.names.namespace`          | Allow the release namespace to be overridden                          | `.` Chart context |
 105 | `common.names.fullname.namespace` | Create a fully qualified app name adding the installation's namespace | `.` Chart context |
 106 | `common.names.chart`              | Chart name plus version                                               | `.` Chart context |
 107
 108 ### Secrets
 109
 110 | Helper identifier         | Description                                                  | Expected Input                                                                                                                                                                                                                  |
 111 |---------------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 112 | `common.secrets.name`     | Generate the name of the secret.                             | `dict "existingSecret" .Values.path.to.the.existingSecret "defaultNameSuffix" "mySuffix" "context" $` see [ExistingSecret](#existingsecret) for the structure.                                                                  |
 113 | `common.secrets.key`      | Generate secret key.                                         | `dict "existingSecret" .Values.path.to.the.existingSecret "key" "keyName"` see [ExistingSecret](#existingsecret) for the structure.                                                                                             |
 114 | `common.passwords.manage` | Generate secret password or retrieve one if already created. | `dict "secret" "secret-name" "key" "keyName" "providedValues" (list "path.to.password1" "path.to.password2") "length" 10 "strong" false "chartName" "chartName" "context" $`, length, strong and chartNAme fields are optional. |
 115 | `common.secrets.exists`   | Returns whether a previous generated secret already exists.  | `dict "secret" "secret-name" "context" $`                                                                                                                                                                                       |
 116
 117 ### Storage
 118
 119 | Helper identifier             | Description                           | Expected Input                                                                                                      |
 120 |-------------------------------|---------------------------------------|---------------------------------------------------------------------------------------------------------------------|
 121 | `common.storage.class` | Return  the proper Storage Class | `dict "persistence" .Values.path.to.the.persistence "global" $`, see [Persistence](#persistence) for the structure. |
 122
 123 ### TplValues
 124
 125 | Helper identifier         | Description                            | Expected Input                                                                                                                                           |
 126 |---------------------------|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
 127 | `common.tplvalues.render` | Renders a value that contains template | `dict "value" .Values.path.to.the.Value "context" $`, value is the value should rendered as template, context frequently is the chart context `$` or `.` |
 128
 129 ### Utils
 130
 131 | Helper identifier              | Description                                                                              | Expected Input                                                         |
 132 |--------------------------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
 133 | `common.utils.fieldToEnvVar`   | Build environment variable name given a field.                                           | `dict "field" "my-password"`                                           |
 134 | `common.utils.secret.getvalue` | Print instructions to get a secret value.                                                | `dict "secret" "secret-name" "field" "secret-value-field" "context" $` |
 135 | `common.utils.getValueFromKey` | Gets a value from `.Values` object given its key path                                    | `dict "key" "path.to.key" "context" $`                                 |
 136 | `common.utils.getKeyFromList`  | Returns first `.Values` key with a defined value or first of the list if all non-defined | `dict "keys" (list "path.to.key1" "path.to.key2") "context" $`         |
 137
 138 ### Validations
 139
 140 | Helper identifier                                | Description                                                                                                                   | Expected Input                                                                                                                                                                                                                                                           |
 141 |--------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 142 | `common.validations.values.single.empty`         | Validate a value must not be empty.                                                                                           | `dict "valueKey" "path.to.value" "secret" "secret.name" "field" "my-password" "subchart" "subchart" "context" $` secret, field and subchart are optional. In case they are given, the helper will generate a how to get instruction. See [ValidateValue](#validatevalue) |
 143 | `common.validations.values.multiple.empty`       | Validate a multiple values must not be empty. It returns a shared error for all the values.                                   | `dict "required" (list $validateValueConf00 $validateValueConf01) "context" $`. See [ValidateValue](#validatevalue)                                                                                                                                                      |
 144 | `common.validations.values.mariadb.passwords`    | This helper will ensure required password for MariaDB are not empty. It returns a shared error for all the values.            | `dict "secret" "mariadb-secret" "subchart" "true" "context" $` subchart field is optional and could be true or false it depends on where you will use mariadb chart and the helper.                                                                                      |
 145 | `common.validations.values.mysql.passwords`      | This helper will ensure required password for MySQL are not empty. It returns a shared error for all the values.              | `dict "secret" "mysql-secret" "subchart" "true" "context" $` subchart field is optional and could be true or false it depends on where you will use mysql chart and the helper.                                                                                      |
 146 | `common.validations.values.postgresql.passwords` | This helper will ensure required password for PostgreSQL are not empty. It returns a shared error for all the values.         | `dict "secret" "postgresql-secret" "subchart" "true" "context" $` subchart field is optional and could be true or false it depends on where you will use postgresql chart and the helper.                                                                                |
 147 | `common.validations.values.redis.passwords`      | This helper will ensure required password for Redis&reg; are not empty. It returns a shared error for all the values. | `dict "secret" "redis-secret" "subchart" "true" "context" $` subchart field is optional and could be true or false it depends on where you will use redis chart and the helper.                                                                                          |
 148 | `common.validations.values.cassandra.passwords`  | This helper will ensure required password for Cassandra are not empty. It returns a shared error for all the values.          | `dict "secret" "cassandra-secret" "subchart" "true" "context" $` subchart field is optional and could be true or false it depends on where you will use cassandra chart and the helper.                                                                                  |
 149 | `common.validations.values.mongodb.passwords`    | This helper will ensure required password for MongoDB&reg; are not empty. It returns a shared error for all the values.            | `dict "secret" "mongodb-secret" "subchart" "true" "context" $` subchart field is optional and could be true or false it depends on where you will use mongodb chart and the helper.                                                                                      |
 150
 151 ### Warnings
 152
 153 | Helper identifier            | Description                      | Expected Input                                             |
 154 |------------------------------|----------------------------------|------------------------------------------------------------|
 155 | `common.warnings.rollingTag` | Warning about using rolling tag. | `ImageRoot` see [ImageRoot](#imageroot) for the structure. |
 156
 157 ## Special input schemas
 158
 159 ### ImageRoot
 160
 161 ```yaml
 162 registry:
 163   type: string
 164   description: Docker registry where the image is located
 165   example: docker.io
 166
 167 repository:
 168   type: string
 169   description: Repository and image name
 170   example: bitnami/nginx
 171
 172 tag:
 173   type: string
 174   description: image tag
 175   example: 1.16.1-debian-10-r63
 176
 177 pullPolicy:
 178   type: string
 179   description: Specify a imagePullPolicy. Defaults to 'Always' if image tag is 'latest', else set to 'IfNotPresent'
 180
 181 pullSecrets:
 182   type: array
 183   items:
 184     type: string
 185   description: Optionally specify an array of imagePullSecrets (evaluated as templates).
 186
 187 debug:
 188   type: boolean
 189   description: Set to true if you would like to see extra information on logs
 190   example: false
 191
 192 ## An instance would be:
 193 # registry: docker.io
 194 # repository: bitnami/nginx
 195 # tag: 1.16.1-debian-10-r63
 196 # pullPolicy: IfNotPresent
 197 # debug: false
 198 ```
 199
 200 ### Persistence
 201
 202 ```yaml
 203 enabled:
 204   type: boolean
 205   description: Whether enable persistence.
 206   example: true
 207
 208 storageClass:
 209   type: string
 210   description: Ghost data Persistent Volume Storage Class, If set to "-", storageClassName: "" which disables dynamic provisioning.
 211   example: "-"
 212
 213 accessMode:
 214   type: string
 215   description: Access mode for the Persistent Volume Storage.
 216   example: ReadWriteOnce
 217
 218 size:
 219   type: string
 220   description: Size the Persistent Volume Storage.
 221   example: 8Gi
 222
 223 path:
 224   type: string
 225   description: Path to be persisted.
 226   example: /bitnami
 227
 228 ## An instance would be:
 229 # enabled: true
 230 # storageClass: "-"
 231 # accessMode: ReadWriteOnce
 232 # size: 8Gi
 233 # path: /bitnami
 234 ```
 235
 236 ### ExistingSecret
 237
 238 ```yaml
 239 name:
 240   type: string
 241   description: Name of the existing secret.
 242   example: mySecret
 243 keyMapping:
 244   description: Mapping between the expected key name and the name of the key in the existing secret.
 245   type: object
 246
 247 ## An instance would be:
 248 # name: mySecret
 249 # keyMapping:
 250 #   password: myPasswordKey
 251 ```
 252
 253 #### Example of use
 254
 255 When we store sensitive data for a deployment in a secret, some times we want to give to users the possibility of using theirs existing secrets.
 256
 257 ```yaml
 258 # templates/secret.yaml
 259 ---
 260 apiVersion: v1
 261 kind: Secret
 262 metadata:
 263   name: {{ include "common.names.fullname" . }}
 264   labels:
 265     app: {{ include "common.names.fullname" . }}
 266 type: Opaque
 267 data:
 268   password: {{ .Values.password | b64enc | quote }}
 269
 270 # templates/dpl.yaml
 271 ---
 272 ...
 273       env:
 274         - name: PASSWORD
 275           valueFrom:
 276             secretKeyRef:
 277               name: {{ include "common.secrets.name" (dict "existingSecret" .Values.existingSecret "context" $) }}
 278               key: {{ include "common.secrets.key" (dict "existingSecret" .Values.existingSecret "key" "password") }}
 279 ...
 280
 281 # values.yaml
 282 ---
 283 name: mySecret
 284 keyMapping:
 285   password: myPasswordKey
 286 ```
 287
 288 ### ValidateValue
 289
 290 #### NOTES.txt
 291
 292 ```console
 293 {{- $validateValueConf00 := (dict "valueKey" "path.to.value00" "secret" "secretName" "field" "password-00") -}}
 294 {{- $validateValueConf01 := (dict "valueKey" "path.to.value01" "secret" "secretName" "field" "password-01") -}}
 295
 296 {{ include "common.validations.values.multiple.empty" (dict "required" (list $validateValueConf00 $validateValueConf01) "context" $) }}
 297 ```
 298
 299 If we force those values to be empty we will see some alerts
 300
 301 ```console
 302 $ helm install test mychart --set path.to.value00="",path.to.value01=""
 303     'path.to.value00' must not be empty, please add '--set path.to.value00=$PASSWORD_00' to the command. To get the current value:
 304
 305         export PASSWORD_00=$(kubectl get secret --namespace default secretName -o jsonpath="{.data.password-00}" | base64 -d)
 306
 307     'path.to.value01' must not be empty, please add '--set path.to.value01=$PASSWORD_01' to the command. To get the current value:
 308
 309         export PASSWORD_01=$(kubectl get secret --namespace default secretName -o jsonpath="{.data.password-01}" | base64 -d)
 310 ```
 311
 312 ## Upgrading
 313
 314 ### To 1.0.0
 315
 316 [On November 13, 2020, Helm v2 support was formally finished](https://github.com/helm/charts#status-of-the-project), this major version is the result of the required changes applied to the Helm Chart to be able to incorporate the different features added in Helm v3 and to be consistent with the Helm project itself regarding the Helm v2 EOL.
 317
 318 **What changes were introduced in this major version?**
 319
 320 - Previous versions of this Helm Chart use `apiVersion: v1` (installable by both Helm 2 and 3), this Helm Chart was updated to `apiVersion: v2` (installable by Helm 3 only). [Here](https://helm.sh/docs/topics/charts/#the-apiversion-field) you can find more information about the `apiVersion` field.
 321 - Use `type: library`. [Here](https://v3.helm.sh/docs/faq/#library-chart-support) you can find more information.
 322 - The different fields present in the *Chart.yaml* file has been ordered alphabetically in a homogeneous way for all the Bitnami Helm Charts
 323
 324 **Considerations when upgrading to this version**
 325
 326 - If you want to upgrade to this version from a previous one installed with Helm v3, you shouldn't face any issues
 327 - If you want to upgrade to this version using Helm v2, this scenario is not supported as this version doesn't support Helm v2 anymore
 328 - If you installed the previous version with Helm v2 and wants to upgrade to this version with Helm v3, please refer to the [official Helm documentation](https://helm.sh/docs/topics/v2_v3_migration/#migration-use-cases) about migrating from Helm v2 to v3
 329
 330 **Useful links**
 331
 332 - https://docs.bitnami.com/tutorials/resolve-helm2-helm3-post-migration-issues/
 333 - https://helm.sh/docs/topics/v2_v3_migration/
 334 - https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/
 335
 336 ## License
 337
 338 Copyright &copy; 2022 Bitnami
 339
 340 Licensed under the Apache License, Version 2.0 (the "License");
 341 you may not use this file except in compliance with the License.
 342 You may obtain a copy of the License at
 343
 344     http://www.apache.org/licenses/LICENSE-2.0
 345
 346 Unless required by applicable law or agreed to in writing, software
 347 distributed under the License is distributed on an "AS IS" BASIS,
 348 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 349 See the License for the specific language governing permissions and
 350 limitations under the License.