github.com/1aal/kubeblocks@v0.0.0-20231107070852-e1c03e598921/deploy/kafka/charts/common/README.md (about) 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® 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® 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 © 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.