tutorials/ApacheCNF/templates/cba/Templates/k8s-configs/deployment-config/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: 0.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.com/) for deployment and management of Helm Charts in clusters. This Helm chart has been tested on top of [Bitnami Kubernetes Production Runtime](https://kubeprod.io/) (BKPR). Deploy BKPR to get automated TLS certificates, logging and monitoring for your applications.
  32
  33 ## Prerequisites
  34
  35 - Kubernetes 1.12+
  36 - Helm 2.12+ or Helm 3.0-beta3+
  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.node.soft`       | Return a soft nodeAffinity definition                           | `dict "key" "FOO" "values" (list "BAR" "BAZ")`                   |
  47 | `common.affinities.node.hard`       | Return a hard nodeAffinity definition                           | `dict "key" "FOO" "values" (list "BAR" "BAZ")`                   |
  48 | `common.affinities.pod.soft`        | Return a soft podAffinity/podAntiAffinity definition            | `dict "component" "FOO" "context" $`                             |
  49 | `common.affinities.pod.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.deployment.apiVersion`    | Return the appropriate apiVersion for deployment.               | `.` Chart context          |
  56 | `common.capabilities.statefulset.apiVersion`   | Return the appropriate apiVersion for statefulset.              | `.` Chart context          |
  57 | `common.capabilities.ingress.apiVersion`       | Return the appropriate apiVersion for ingress.                  | `.` Chart context          |
  58
  59 ### Errors
  60
  61 | Helper identifier                        | Description                                                                                                                                                            | Expected Input                                                                      |
  62 |------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
  63 | `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" $` |
  64
  65 ### Images
  66
  67 | Helper identifier              | Description                                                     | Expected Input                                                                                              |
  68 |--------------------------------|-----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
  69 | `common.images.image`          | Return the proper and full image name                           | `dict "imageRoot" .Values.path.to.the.image "global" $`, see [ImageRoot](#imageroot) for the structure.     |
  70 | `common.images.pullSecrets`    | Return the proper Docker Image Registry Secret Names            | `dict "images" (list .Values.path.to.the.image1, .Values.path.to.the.image2) "global" .Values.global`       |
  71
  72 ### Labels
  73
  74 | Helper identifier              | Description                                                     | Expected Input              |
  75 |--------------------------------|-----------------------------------------------------------------|-----------------------------|
  76 | `common.labels.standard`       | Return Kubernetes standard labels                               | `.` Chart context           |
  77 | `common.labels.matchLabels`    | Return the proper Docker Image Registry Secret Names            | `.` Chart context           |
  78
  79 ### Names
  80
  81 | Helper identifier              | Description                                                     | Expected Inpput             |
  82 |--------------------------------|-----------------------------------------------------------------|-----------------------------|
  83 | `common.names.name`            | Expand the name of the chart or use `.Values.nameOverride`      | `.` Chart context           |
  84 | `common.names.fullname`        | Create a default fully qualified app name.                      | `.` Chart context           |
  85 | `common.names.chart`           | Chart name plus version                                         | `.` Chart context           |
  86
  87 ### Secrets
  88
  89 | Helper identifier              | Description                                                     | Expected Input                                                                                                                                                 |
  90 |--------------------------------|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
  91 | `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. |
  92 | `common.secrets.key`           | Generate secret key.                                            | `dict "existingSecret" .Values.path.to.the.existingSecret "key" "keyName"` see [ExistingSecret](#existingsecret) for the structure.                            |
  93
  94 ### Storage
  95
  96 | Helper identifier              | Description                                                     | Expected Input                                                                                                      |
  97 |--------------------------------|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
  98 | `common.affinities.node.soft`    | Return a soft nodeAffinity definition                           | `dict "persistence" .Values.path.to.the.persistence "global" $`, see [Persistence](#persistence) for the structure. |
  99
 100 ### TplValues
 101
 102 | Helper identifier              | Description                                                     | Expected Input                                                                                                                                           |
 103 |--------------------------------|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
 104 | `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 frecuently is the chart context `$` or `.` |
 105
 106 ### Utils
 107
 108 | Helper identifier              | Description                                                     | Expected Input                                                         |
 109 |--------------------------------|-----------------------------------------------------------------|------------------------------------------------------------------------|
 110 | `common.utils.fieldToEnvVar`   | Build environment variable name given a field.                  | `dict "field" "my-password"`                                           |
 111 | `common.utils.secret.getvalue` | Print instructions to get a secret value.                       | `dict "secret" "secret-name" "field" "secret-value-field" "context" $` |
 112 | `common.utils.getValueFromKey` | Gets a value from `.Values` object given its key path           | `dict "key" "path.to.key" "context" $`                                 |
 113
 114 ### Validations
 115
 116 | Helper identifier                                | Description                                                                                                            | Expected Input                                                                                                                                                                                                                           |
 117 |--------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 118 | `common.validations.values.single.empty`         | Validate a value must not be empty.                                                                                    | `dict "valueKey" "path.to.value" "secret" "secret.name" "field" "my-password" "context" $` secret and field are optional. In case they are given, the helper will generate a how to get instruction. See [ValidateValue](#validatevalue) |
 119 | `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)                                                                                                                      |
 120 | `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 postgresql chart and the helper.                                                   |
 121 | `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.                                                |
 122
 123 ### Warnings
 124
 125 | Helper identifier              | Description                                                     | Expected Input                                                   |
 126 |--------------------------------|-----------------------------------------------------------------|------------------------------------------------------------------|
 127 | `common.warnings.rollingTag`   | Warning about using rolling tag.                                | `ImageRoot` see [ImageRoot](#imageroot) for the structure.       |
 128
 129 ## Special input schemas
 130
 131 ### ImageRoot
 132
 133 ```yaml
 134 registry:
 135   type: string
 136   description: Docker registry where the image is located
 137   example: docker.io
 138
 139 repository:
 140   type: string
 141   description: Repository and image name
 142   example: bitnami/nginx
 143
 144 tag:
 145   type: string
 146   description: image tag
 147   example: 1.16.1-debian-10-r63
 148
 149 pullPolicy:
 150   type: string
 151   description: Specify a imagePullPolicy. Defaults to 'Always' if image tag is 'latest', else set to 'IfNotPresent'
 152
 153 pullSecrets:
 154   type: array
 155   items:
 156     type: string
 157   description: Optionally specify an array of imagePullSecrets.
 158
 159 debug:
 160   type: boolean
 161   description: Set to true if you would like to see extra information on logs
 162   example: false
 163
 164 ## An instance would be:
 165 # registry: docker.io
 166 # repository: bitnami/nginx
 167 # tag: 1.16.1-debian-10-r63
 168 # pullPolicy: IfNotPresent
 169 # debug: false
 170 ```
 171
 172 ### Persistence
 173
 174 ```yaml
 175 enabled:
 176   type: boolean
 177   description: Whether enable persistence.
 178   example: true
 179
 180 storageClass:
 181   type: string
 182   description: Ghost data Persistent Volume Storage Class, If set to "-", storageClassName: "" which disables dynamic provisioning.
 183   example: "-"
 184
 185 accessMode:
 186   type: string
 187   description: Access mode for the Persistent Volume Storage.
 188   example: ReadWriteOnce
 189
 190 size:
 191   type: string
 192   description: Size the Persistent Volume Storage.
 193   example: 8Gi
 194
 195 path:
 196   type: string
 197   description: Path to be persisted.
 198   example: /bitnami
 199
 200 ## An instance would be:
 201 # enabled: true
 202 # storageClass: "-"
 203 # accessMode: ReadWriteOnce
 204 # size: 8Gi
 205 # path: /bitnami
 206 ```
 207
 208 ### ExistingSecret
 209
 210 ```yaml
 211 name:
 212   type: string
 213   description: Name of the existing secret.
 214   example: mySecret
 215 keyMapping:
 216   description: Mapping between the expected key name and the name of the key in the existing secret.
 217   type: object
 218
 219 ## An instance would be:
 220 # name: mySecret
 221 # keyMapping:
 222 #   password: myPasswordKey
 223 ```
 224
 225 #### Example of use
 226
 227 When we store sensitive data for a deployment in a secret, some times we want to give to users the possiblity of using theirs existing secrets.
 228
 229 ```yaml
 230 # templates/secret.yaml
 231 ---
 232 apiVersion: v1
 233 kind: Secret
 234 metadata:
 235   name: {{ include "common.names.fullname" . }}
 236   labels:
 237     app: {{ include "common.names.fullname" . }}
 238 type: Opaque
 239 data:
 240   password: {{ .Values.password | b64enc | quote }}
 241
 242 # templates/dpl.yaml
 243 ---
 244 ...
 245       env:
 246         - name: PASSWORD
 247           valueFrom:
 248             secretKeyRef:
 249               name: {{ include "common.secrets.name" (dict "existingSecret" .Values.existingSecret "context" $) }}
 250               key: {{ include "common.secrets.key" (dict "existingSecret" .Values.existingSecret "key" "password") }}
 251 ...
 252
 253 # values.yaml
 254 ---
 255 name: mySecret
 256 keyMapping:
 257   password: myPasswordKey
 258 ```
 259
 260 ### ValidateValue
 261
 262 #### NOTES.txt
 263
 264 ```console
 265 {{- $validateValueConf00 := (dict "valueKey" "path.to.value00" "secret" "secretName" "field" "password-00") -}}
 266 {{- $validateValueConf01 := (dict "valueKey" "path.to.value01" "secret" "secretName" "field" "password-01") -}}
 267
 268 {{ include "common.validations.values.multiple.empty" (dict "required" (list $validateValueConf00 $validateValueConf01) "context" $) }}
 269 ```
 270
 271 If we force those values to be empty we will see some alerts
 272
 273 ```console
 274 $ helm install test mychart --set path.to.value00="",path.to.value01=""
 275     'path.to.value00' must not be empty, please add '--set path.to.value00=$PASSWORD_00' to the command. To get the current value:
 276
 277         export PASSWORD_00=$(kubectl get secret --namespace default secretName -o jsonpath="{.data.password-00}" | base64 --decode)
 278
 279     'path.to.value01' must not be empty, please add '--set path.to.value01=$PASSWORD_01' to the command. To get the current value:
 280
 281         export PASSWORD_01=$(kubectl get secret --namespace default secretName -o jsonpath="{.data.password-01}" | base64 --decode)
 282 ```
 283
 284 ## Notable changes
 285
 286 N/A