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.repository.secret` | `_repository.tpl` |
81 +----------------------------------------------------+-----------------------+
82 | `common.flavor` | `_resources.tpl` |
83 +----------------------------------------------------+-----------------------+
84 | `common.resources` | `_resources.tpl` |
85 +----------------------------------------------------+-----------------------+
86 | `common.storageClass` | `_storage.tpl` |
87 +----------------------------------------------------+-----------------------+
88 | `common.replicaPV` | `_storage.tpl` |
89 +----------------------------------------------------+-----------------------+
90 | `common.servicename` | `_service.tpl` |
91 +----------------------------------------------------+-----------------------+
92 | `common.serviceMetadata` | `_service.tpl` |
93 +----------------------------------------------------+-----------------------+
94 | `common.servicePorts` | `_service.tpl` |
95 +----------------------------------------------------+-----------------------+
96 | `common.genericService` | `_service.tpl` |
97 +----------------------------------------------------+-----------------------+
98 | `common.service` | `_service.tpl` |
99 +----------------------------------------------------+-----------------------+
100 | `common.headlessService` | `_service.tpl` |
101 +----------------------------------------------------+-----------------------+
102 | `common.mariadb.secret.rootPassUID` | `_mariadb.tpl` |
103 +----------------------------------------------------+-----------------------+
104 | `common.mariadb.secret.rootPassSecretName` | `_mariadb.tpl` |
105 +----------------------------------------------------+-----------------------+
106 | `common.mariadb.secret.userCredentialsUID` | `_mariadb.tpl` |
107 +----------------------------------------------------+-----------------------+
108 | `common.mariadb.secret.userCredentialsSecretName` | `_mariadb.tpl` |
109 +----------------------------------------------------+-----------------------+
110 | `common.mariadbService` | `_mariadb.tpl` |
111 +----------------------------------------------------+-----------------------+
112 | `common.mariadbPort` | `_mariadb.tpl` |
113 +----------------------------------------------------+-----------------------+
114 | `common.mariadbSecret` | `_mariadb.tpl` |
115 +----------------------------------------------------+-----------------------+
116 | `common.mariadbSecretParam` | `_mariadb.tpl` |
117 +----------------------------------------------------+-----------------------+
118 | `common.postgres.secret.rootPassUID` | `_postgres.tpl` |
119 +----------------------------------------------------+-----------------------+
120 | `common.postgres.secret.rootPassSecretName` | `_postgres.tpl` |
121 +----------------------------------------------------+-----------------------+
122 | `common.postgres.secret.userCredentialsUID` | `_postgres.tpl` |
123 +----------------------------------------------------+-----------------------+
124 | `common.postgres.secret.userCredentialsSecretName` | `_postgres.tpl` |
125 +----------------------------------------------------+-----------------------+
126 | `common.postgres.secret.primaryPasswordUID` | `_postgres.tpl` |
127 +----------------------------------------------------+-----------------------+
128 | `common.postgres.secret.primaryPasswordSecretName` | `_postgres.tpl` |
129 +----------------------------------------------------+-----------------------+
130 | `common.tplValue` | `_tplValue.tpl` |
131 +----------------------------------------------------+-----------------------+
137 These functions are defined in
138 `kubernetes/common/common/templates/_createPassword.tpl`.
140 * `common.masterPassword`: Resolve the master password to be used to derive
142 * `common.createPassword`: Generate a new password based on masterPassword.
147 These functions are defined in
148 `kubernetes/common/common/templates/_secret.yaml`.
150 * `common.secret.genName`: Generate a secret name based on provided name or UID.
151 * `common.secret.getSecretName`: Get the real secret name by UID or name, based
152 on the configuration provided by user.
153 * `common.secret.envFromSecret`: Convenience template which can be used to
154 easily set the value of environment variable to the value of a key in a
156 * `common.secret`: Define secrets to be used by chart.
158 The most widely use templates is the last (`common.secret`).
159 It should be the only (except license part) line of your secret file:
163 {{ include "common.secret" . }}
165 In order to have the right values set, you need to create the right
166 configuration in `values.yaml` (example taken from mariadb configuration):
171 - uid: 'db-root-password'
173 externalSecret: '{{ tpl (default "" .Values.config.db.rootPasswordExternalSecret) . }}'
174 password: '{{ .Values.config.dbRootPassword }}'
175 - uid: 'db-user-creds'
177 externalSecret: '{{ tpl (default "" .Values.config.db.userCredentialsExternalSecret) . }}'
178 login: '{{ .Values.config.db.userName }}'
179 password: '{{ .Values.config.dbSdnctlPassword }}'
184 These functions are defined in
185 `kubernetes/common/common/templates/_ingress.tpl`.
187 * `ingress.config.port`: generate the port path on an Ingress resource.
188 * `ingress.config.annotations.ssl`: generate the ssl annotations of an Ingress
190 * `ingress.config.annotations`: generate the annotations of an Ingress resource.
191 * `common.ingress`: generate an Ingress resource (if needed).
193 The most widely use templates is the last (`common.ingress`) .
195 It should be the only (except license part) line of your ingress file:
199 {{ include "common.ingress" . }}
201 In order to have the right values set, you need to create the right
202 configuration in `values.yaml` (example taken from clamp configuration):
218 These functions are defined in `kubernetes/common/common/templates/_labels.tpl`.
220 The goal of these functions is to always create the right labels for all the
221 resource in a consistent way.
223 * `common.labels`: generate the common labels for a resource
224 * `common.matchLabels`: generate the labels to match (to be used in conjunction
225 with `common.labels` or `common.resourceMetadata`)
226 * `common.resourceMetadata`: generate the "top" metadatas for a resource
227 (Deployment, StatefulSet, Service, ConfigMap, ...)
228 * `common.templateMetadata`: generate the metadata put in the template part
229 (for example `spec.template.metadata` for a Deployment)
230 * `common.selectors`: generate the right selectors for Service / Deployment /
231 StatefulSet, ... (to be used in conjunction with `common.labels` or
232 `common.resourceMetadata`)
235 Here's an example of use of these functions in a Deployment template (example
242 metadata: {{- include "common.resourceMetadata" . | nindent 2 }}
244 selector: {{- include "common.selectors" . | nindent 4 }}
245 replicas: {{ .Values.replicaCount }}
247 metadata: {{- include "common.templateMetadata" . | nindent 6 }}
254 These functions are defined in `kubernetes/common/common/templates/_name.tpl`.
256 The goal of these functions is to always name the resource the same way.
258 * `common.name`: Generate the name for a chart.
259 * `common.fullname`: Create a default fully qualified application name.
260 * `common.fullnameExplicit`: The same as common.full name but based on passed
261 dictionary instead of trying to figure out chart name on its own.
262 * `common.release`: Retrieve the "original" release from the component release.
263 * `common.chart`: Generate the chart name
265 Here's an example of use of these functions in a Deployment template (example
266 taken on mariadb-galera):
270 apiVersion: apps/v1beta1
274 serviceName: {{ .Values.service.name }}
275 replicas: {{ .Values.replicaCount }}
279 {{- if .Values.nodeSelector }}
281 {{ toYaml .Values.nodeSelector | indent 8 }}
284 {{- if .Values.externalConfig }}
287 name: {{ include "common.fullname" . }}-external-config
291 - name: {{ include "common.name" . }}
292 image: "{{ include "common.repository" . }}/{{ .Values.image }}"
298 These functions are defined in
299 `kubernetes/common/common/templates/_namespace.tpl`.
301 The goal of these functions is to always retrieve the namespace the same way.
303 * `common.namespace`: Generate the namespace for a chart. Shouldn't be used
304 directly but use `common.resourceMetadata` (which uses it).
310 These functions are defined in
311 `kubernetes/common/common/templates/_repository.tpl`.
313 The goal of these functions is to generate image name the same way.
315 * `common.repository`: Resolve the name of the common image repository.
316 * `common.repository.secret`: Resolve the image repository secret token.
322 These functions are defined in
323 `kubernetes/common/common/templates/_resources.tpl`.
325 The goal of these functions is to generate resources for pods the same way.
327 * `common.flavor`: Resolve the name of the common resource limit/request flavor.
328 Shouldn't be used alone.
329 * `common.resources`: Resolve the resource limit/request flavor using the
330 desired flavor value.
336 These functions are defined in
337 `kubernetes/common/common/templates/_storage.tpl`.
339 The goal of these functions is to generate storage part of Deployment /
340 Statefulset and storage resource (PV, PVC, ...) in a consistent way.
342 * `common.storageClass`: Expand the name of the storage class.
343 * `common.needPV`: Calculate if we need a PV. If a storageClass is provided,
345 * `common.replicaPV`: Generate N PV for a statefulset
351 These functions are defined in `kubernetes/common/common/templates/_pod.tpl`.
353 * `common.containerPorts`: generate the port list for containers. See Service
354 part to know how to declare the port list.
356 Here's an example of use of these functions in a Deployment template (example
370 - name: {{ include "common.name" . }}
371 ports: {{- include "common.containerPorts" . | nindent 8 }
377 These functions are defined in
378 `kubernetes/common/common/templates/_service.tpl`.
380 The goal of these functions is to generate services in a consistent way.
382 * `common.servicename`: Expand the service name for a chart.
383 * `common.serviceMetadata`: Define the metadata of Service. Shouldn't be used
384 directly but used through `common.service` or `common.headlessService`.
385 * `common.servicePorts`: Define the ports of Service. Shouldn't be used directly
386 but used through `common.service` or `common.headlessService`.
387 * `common.genericService`: Template for creating any Service. Shouldn't be used
388 directly but used through `common.service` or `common.headlessService`. May be
389 used if you want to create a Service with some specificities (on the ports for
391 * `common.needTLS`: Calculate if we need to use TLS ports on services
392 * `common.service`: Create service template.
393 * `common.headlessService`: Create headless service template
396 The most widely used templates are the two last (`common.service` and
397 `common.headlessService`).
398 It should use with only one (except license part) line of your service (or
399 service-headless) file:
403 {{ include "common.service" . }}
405 In order to have the right values set, you need to create the right
406 configuration in `values.yaml` (example taken from nbi configuration + other
439 app.kubernetes.io/name: nbi
440 helm.sh/chart: nbi-6.0.0
441 app.kubernetes.io/instance: release
442 app.kubernetes.io/managed-by: Tiller
455 app.kubernetes.io/name: nbi
456 app.kubernetes.io/instance: release
459 `plain_port` is used only if we mandate to use http (see ServiceMesh part).
460 Today a port can be http or https but not both.
461 headless configuration is equivalent (example taken from cassandra):
470 service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
471 publishNotReadyAddresses: true
490 These functions are defined in
491 `kubernetes/common/common/templates/_serviceMesh.tpl`.
493 The goal of these functions is to handle onboarding of ONAP on service mesh.
495 * `common.onServiceMesh`: Calculate if we if we are on service mesh
502 These functions are defined in
503 `kubernetes/common/common/templates/_mariadb.tpl`.
505 The goal of these functions is to simplify use of mariadb and its different
508 * `common.mariadb.secret.rootPassUID`: UID of mariadb root password
509 * `common.mariadb.secret.rootPassSecretName`: Name of mariadb root password
511 * `common.mariadb.secret.userCredentialsUID`: UID of mariadb user credentials
512 * `common.mariadb.secret.userCredentialsSecretName`: Name of mariadb user
514 * `common.mariadbService`: Choose the name of the mariadb service to use
515 * `common.mariadbPort`: Choose the value of mariadb port to use
516 * `common.mariadbSecret`: Choose the value of secret to retrieve user value
517 * `common.mariadbSecretParam`: Choose the value of secret param to retrieve user
523 These functions are defined in
524 `kubernetes/common/common/templates/_postgres.tpl`.
526 The goal of these functions is to simplify use of postgres and its different
529 * `common.postgres.secret.rootPassUID`: UID of postgres root password
530 * `common.postgres.secret.rootPassSecretName`: Name of postgres root password
532 * `common.postgres.secret.userCredentialsUID`: UID of postgres user credentials
533 * `common.postgres.secret.userCredentialsSecretName`: Name of postgres user
535 * `common.postgres.secret.primaryPasswordUID`: UID of postgres primary password
536 * `common.postgres.secret.primaryPasswordSecretName`: Name of postgres primary
543 These functions are defined in
544 `kubernetes/common/common/templates/_tplValue.tpl`.
546 The goal of these functions is provide utility function, usually used in other
547 templating functions.
549 * `common.tplValue`: Renders a value that contains template.