1 .. This work is licensed under a Creative Commons Attribution 4.0 International
3 .. http://creativecommons.org/licenses/by/4.0
4 .. Copyright 2020 Orange. All rights reserved.
6 .. _developer-guide-label:
9 Current given templating functions
10 ==================================
13 In order to have a consistent deployments of ONAP components, several templating
14 functions are proposed in `kubernets/common/common/templates` folder.
15 This file list them and gives examples for the most used.
16 All these templating functions have a description in their own file, here we
17 only give an overview.
19 * conditional functions
21 +----------------------------------------------------+-----------------------+
23 +----------------------------------------------------+-----------------------+
24 | `common.needPV` | `_storage.tpl` |
25 +----------------------------------------------------+-----------------------+
26 | `common.onServiceMesh` | `_serviceMesh.tpl` |
27 +----------------------------------------------------+-----------------------+
28 | `common.common.needTLS` | `_service.tpl` |
29 +----------------------------------------------------+-----------------------+
31 * template generation functions
33 +----------------------------------------------------+-----------------------+
35 +----------------------------------------------------+-----------------------+
36 | `common.masterPassword` | `_createPassword.tpl` |
37 +----------------------------------------------------+-----------------------+
38 | `common.createPassword` | `_createPassword.tpl` |
39 +----------------------------------------------------+-----------------------+
40 | `common.secret.genName` | `_secret.yaml` |
41 +----------------------------------------------------+-----------------------+
42 | `common.secret.getSecretName` | `_secret.yaml` |
43 +----------------------------------------------------+-----------------------+
44 | `common.secret.envFromSecret` | `_secret.yaml` |
45 +----------------------------------------------------+-----------------------+
46 | `common.secret` | `_secret.yaml` |
47 +----------------------------------------------------+-----------------------+
48 | `ingress.config.port` | `_ingress.tpl` |
49 +----------------------------------------------------+-----------------------+
50 | `ingress.config.annotations.ssl` | `_ingress.tpl` |
51 +----------------------------------------------------+-----------------------+
52 | `ingress.config.annotations` | `_ingress.tpl` |
53 +----------------------------------------------------+-----------------------+
54 | `common.ingress` | `_ingress.tpl` |
55 +----------------------------------------------------+-----------------------+
56 | `common.labels` | `_labels.tpl` |
57 +----------------------------------------------------+-----------------------+
58 | `common.matchLabels` | `_labels.tpl` |
59 +----------------------------------------------------+-----------------------+
60 | `common.resourceMetadata` | `_labels.tpl` |
61 +----------------------------------------------------+-----------------------+
62 | `common.templateMetadata` | `_labels.tpl` |
63 +----------------------------------------------------+-----------------------+
64 | `common.selectors` | `_labels.tpl` |
65 +----------------------------------------------------+-----------------------+
66 | `common.name` | `_name.tpl` |
67 +----------------------------------------------------+-----------------------+
68 | `common.fullname` | `_name.tpl` |
69 +----------------------------------------------------+-----------------------+
70 | `common.fullnameExplicit` | `_name.tpl` |
71 +----------------------------------------------------+-----------------------+
72 | `common.release` | `_name.tpl` |
73 +----------------------------------------------------+-----------------------+
74 | `common.chart` | `_name.tpl` |
75 +----------------------------------------------------+-----------------------+
76 | `common.namespace` | `_namespace.tpl` |
77 +----------------------------------------------------+-----------------------+
78 | `common.repository` | `_repository.tpl` |
79 +----------------------------------------------------+-----------------------+
80 | `common.flavor` | `_resources.tpl` |
81 +----------------------------------------------------+-----------------------+
82 | `common.resources` | `_resources.tpl` |
83 +----------------------------------------------------+-----------------------+
84 | `common.storageClass` | `_storage.tpl` |
85 +----------------------------------------------------+-----------------------+
86 | `common.replicaPV` | `_storage.tpl` |
87 +----------------------------------------------------+-----------------------+
88 | `common.servicename` | `_service.tpl` |
89 +----------------------------------------------------+-----------------------+
90 | `common.serviceMetadata` | `_service.tpl` |
91 +----------------------------------------------------+-----------------------+
92 | `common.servicePorts` | `_service.tpl` |
93 +----------------------------------------------------+-----------------------+
94 | `common.genericService` | `_service.tpl` |
95 +----------------------------------------------------+-----------------------+
96 | `common.service` | `_service.tpl` |
97 +----------------------------------------------------+-----------------------+
98 | `common.headlessService` | `_service.tpl` |
99 +----------------------------------------------------+-----------------------+
100 | `common.mariadb.secret.rootPassUID` | `_mariadb.tpl` |
101 +----------------------------------------------------+-----------------------+
102 | `common.mariadb.secret.rootPassSecretName` | `_mariadb.tpl` |
103 +----------------------------------------------------+-----------------------+
104 | `common.mariadb.secret.userCredentialsUID` | `_mariadb.tpl` |
105 +----------------------------------------------------+-----------------------+
106 | `common.mariadb.secret.userCredentialsSecretName` | `_mariadb.tpl` |
107 +----------------------------------------------------+-----------------------+
108 | `common.mariadbService` | `_mariadb.tpl` |
109 +----------------------------------------------------+-----------------------+
110 | `common.mariadbPort` | `_mariadb.tpl` |
111 +----------------------------------------------------+-----------------------+
112 | `common.mariadbSecret` | `_mariadb.tpl` |
113 +----------------------------------------------------+-----------------------+
114 | `common.mariadbSecretParam` | `_mariadb.tpl` |
115 +----------------------------------------------------+-----------------------+
116 | `common.postgres.secret.rootPassUID` | `_postgres.tpl` |
117 +----------------------------------------------------+-----------------------+
118 | `common.postgres.secret.rootPassSecretName` | `_postgres.tpl` |
119 +----------------------------------------------------+-----------------------+
120 | `common.postgres.secret.userCredentialsUID` | `_postgres.tpl` |
121 +----------------------------------------------------+-----------------------+
122 | `common.postgres.secret.userCredentialsSecretName` | `_postgres.tpl` |
123 +----------------------------------------------------+-----------------------+
124 | `common.postgres.secret.primaryPasswordUID` | `_postgres.tpl` |
125 +----------------------------------------------------+-----------------------+
126 | `common.postgres.secret.primaryPasswordSecretName` | `_postgres.tpl` |
127 +----------------------------------------------------+-----------------------+
128 | `common.tplValue` | `_tplValue.tpl` |
129 +----------------------------------------------------+-----------------------+
135 These functions are defined in
136 `kubernetes/common/common/templates/_createPassword.tpl`.
138 * `common.masterPassword`: Resolve the master password to be used to derive
140 * `common.createPassword`: Generate a new password based on masterPassword.
145 These functions are defined in
146 `kubernetes/common/common/templates/_secret.yaml`.
148 * `common.secret.genName`: Generate a secret name based on provided name or UID.
149 * `common.secret.getSecretName`: Get the real secret name by UID or name, based
150 on the configuration provided by user.
151 * `common.secret.envFromSecret`: Convenience template which can be used to
152 easily set the value of environment variable to the value of a key in a
154 * `common.secret`: Define secrets to be used by chart.
156 The most widely use templates is the last (`common.secret`).
157 It should be the only (except license part) line of your secret file:
161 {{ include "common.secret" . }}
163 In order to have the right values set, you need to create the right
164 configuration in `values.yaml` (example taken from mariadb configuration):
169 - uid: 'db-root-password'
171 externalSecret: '{{ tpl (default "" .Values.config.db.rootPasswordExternalSecret) . }}'
172 password: '{{ .Values.config.dbRootPassword }}'
173 - uid: 'db-user-creds'
175 externalSecret: '{{ tpl (default "" .Values.config.db.userCredentialsExternalSecret) . }}'
176 login: '{{ .Values.config.db.userName }}'
177 password: '{{ .Values.config.dbSdnctlPassword }}'
182 These functions are defined in
183 `kubernetes/common/common/templates/_ingress.tpl`.
185 * `ingress.config.port`: generate the port path on an Ingress resource.
186 * `ingress.config.annotations.ssl`: generate the ssl annotations of an Ingress
188 * `ingress.config.annotations`: generate the annotations of an Ingress resource.
189 * `common.ingress`: generate an Ingress resource (if needed).
191 The most widely use templates is the last (`common.ingress`) .
193 It should be the only (except license part) line of your ingress file:
197 {{ include "common.ingress" . }}
199 In order to have the right values set, you need to create the right
200 configuration in `values.yaml` (example taken from clamp configuration):
216 These functions are defined in `kubernetes/common/common/templates/_labels.tpl`.
218 The goal of these functions is to always create the right labels for all the
219 resource in a consistent way.
221 * `common.labels`: generate the common labels for a resource
222 * `common.matchLabels`: generate the labels to match (to be used in conjunction
223 with `common.labels` or `common.resourceMetadata`)
224 * `common.resourceMetadata`: generate the "top" metadatas for a resource
225 (Deployment, StatefulSet, Service, ConfigMap, ...)
226 * `common.templateMetadata`: generate the metadata put in the template part
227 (for example `spec.template.metadata` for a Deployment)
228 * `common.selectors`: generate the right selectors for Service / Deployment /
229 StatefulSet, ... (to be used in conjunction with `common.labels` or
230 `common.resourceMetadata`)
233 Here's an example of use of these functions in a Deployment template (example
240 metadata: {{- include "common.resourceMetadata" . | nindent 2 }}
242 selector: {{- include "common.selectors" . | nindent 4 }}
243 replicas: {{ .Values.replicaCount }}
245 metadata: {{- include "common.templateMetadata" . | nindent 6 }}
252 These functions are defined in `kubernetes/common/common/templates/_name.tpl`.
254 The goal of these functions is to always name the resource the same way.
256 * `common.name`: Generate the name for a chart.
257 * `common.fullname`: Create a default fully qualified application name.
258 * `common.fullnameExplicit`: The same as common.full name but based on passed
259 dictionary instead of trying to figure out chart name on its own.
260 * `common.release`: Retrieve the "original" release from the component release.
261 * `common.chart`: Generate the chart name
263 Here's an example of use of these functions in a Deployment template (example
264 taken on mariadb-galera):
268 apiVersion: apps/v1beta1
272 serviceName: {{ .Values.service.name }}
273 replicas: {{ .Values.replicaCount }}
277 {{- if .Values.nodeSelector }}
279 {{ toYaml .Values.nodeSelector | indent 8 }}
282 {{- if .Values.externalConfig }}
285 name: {{ include "common.fullname" . }}-external-config
289 - name: {{ include "common.name" . }}
290 image: {{ include "repositoryGenerator.repository" . }}/{{ .Values.image }}
296 These functions are defined in
297 `kubernetes/common/common/templates/_namespace.tpl`.
299 The goal of these functions is to always retrieve the namespace the same way.
301 * `common.namespace`: Generate the namespace for a chart. Shouldn't be used
302 directly but use `common.resourceMetadata` (which uses it).
308 These functions are defined in
309 `kubernetes/common/common/templates/_repository.tpl`.
311 The goal of these functions is to generate image name the same way.
313 * `common.repository`: Resolve the name of the common image repository.
314 * `common.repository.secret`: Resolve the image repository secret token.
320 These functions are defined in
321 `kubernetes/common/common/templates/_resources.tpl`.
323 The goal of these functions is to generate resources for pods the same way.
325 * `common.flavor`: Resolve the name of the common resource limit/request flavor.
326 Shouldn't be used alone.
327 * `common.resources`: Resolve the resource limit/request flavor using the
328 desired flavor value.
334 These functions are defined in
335 `kubernetes/common/common/templates/_storage.tpl`.
337 The goal of these functions is to generate storage part of Deployment /
338 Statefulset and storage resource (PV, PVC, ...) in a consistent way.
340 * `common.storageClass`: Expand the name of the storage class.
341 * `common.needPV`: Calculate if we need a PV. If a storageClass is provided,
343 * `common.replicaPV`: Generate N PV for a statefulset
349 These functions are defined in `kubernetes/common/common/templates/_pod.tpl`.
351 * `common.containerPorts`: generate the port list for containers. See Service
352 part to know how to declare the port list.
354 Here's an example of use of these functions in a Deployment template (example
368 - name: {{ include "common.name" . }}
369 ports: {{- include "common.containerPorts" . | nindent 8 }
375 These functions are defined in
376 `kubernetes/common/common/templates/_service.tpl`.
378 The goal of these functions is to generate services in a consistent way.
380 * `common.servicename`: Expand the service name for a chart.
381 * `common.serviceMetadata`: Define the metadata of Service. Shouldn't be used
382 directly but used through `common.service` or `common.headlessService`.
383 * `common.servicePorts`: Define the ports of Service. Shouldn't be used directly
384 but used through `common.service` or `common.headlessService`.
385 * `common.genericService`: Template for creating any Service. Shouldn't be used
386 directly but used through `common.service` or `common.headlessService`. May be
387 used if you want to create a Service with some specificities (on the ports for
389 * `common.needTLS`: Calculate if we need to use TLS ports on services
390 * `common.service`: Create service template.
391 * `common.headlessService`: Create headless service template
394 The most widely used templates are the two last (`common.service` and
395 `common.headlessService`).
396 It should use with only one (except license part) line of your service (or
397 service-headless) file:
401 {{ include "common.service" . }}
403 In order to have the right values set, you need to create the right
404 configuration in `values.yaml` (example taken from nbi configuration + other
437 app.kubernetes.io/name: nbi
438 helm.sh/chart: nbi-7.0.0
439 app.kubernetes.io/instance: release
440 app.kubernetes.io/managed-by: Tiller
453 app.kubernetes.io/name: nbi
454 app.kubernetes.io/instance: release
457 `plain_port` is used only if we mandate to use http (see ServiceMesh part).
458 Today a port can be http or https but not both.
459 headless configuration is equivalent (example taken from cassandra):
468 service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
469 publishNotReadyAddresses: true
488 These functions are defined in
489 `kubernetes/common/common/templates/_serviceMesh.tpl`.
491 The goal of these functions is to handle onboarding of ONAP on service mesh.
493 * `common.onServiceMesh`: Calculate if we if we are on service mesh
500 These functions are defined in
501 `kubernetes/common/common/templates/_mariadb.tpl`.
503 The goal of these functions is to simplify use of mariadb and its different
506 * `common.mariadb.secret.rootPassUID`: UID of mariadb root password
507 * `common.mariadb.secret.rootPassSecretName`: Name of mariadb root password
509 * `common.mariadb.secret.userCredentialsUID`: UID of mariadb user credentials
510 * `common.mariadb.secret.userCredentialsSecretName`: Name of mariadb user
512 * `common.mariadbService`: Choose the name of the mariadb service to use
513 * `common.mariadbPort`: Choose the value of mariadb port to use
514 * `common.mariadbSecret`: Choose the value of secret to retrieve user value
515 * `common.mariadbSecretParam`: Choose the value of secret param to retrieve user
521 These functions are defined in
522 `kubernetes/common/common/templates/_postgres.tpl`.
524 The goal of these functions is to simplify use of postgres and its different
527 * `common.postgres.secret.rootPassUID`: UID of postgres root password
528 * `common.postgres.secret.rootPassSecretName`: Name of postgres root password
530 * `common.postgres.secret.userCredentialsUID`: UID of postgres user credentials
531 * `common.postgres.secret.userCredentialsSecretName`: Name of postgres user
533 * `common.postgres.secret.primaryPasswordUID`: UID of postgres primary password
534 * `common.postgres.secret.primaryPasswordSecretName`: Name of postgres primary
541 These functions are defined in
542 `kubernetes/common/common/templates/_tplValue.tpl`.
544 The goal of these functions is provide utility function, usually used in other
545 templating functions.
547 * `common.tplValue`: Renders a value that contains template.