.. This work is licensed under a Creative Commons Attribution 4.0 International .. License. .. http://creativecommons.org/licenses/by/4.0 .. Copyright 2020 Orange. All rights reserved. .. _developer-guide-label: Current given templating functions ================================== In order to have a consistent deployments of ONAP components, several templating functions are proposed in `kubernets/common/common/templates` folder. This file list them and gives examples for the most used. All these templating functions have a description in their own file, here we only give an overview. * conditional functions +----------------------------------------------------+-----------------------+ | Function | File | +----------------------------------------------------+-----------------------+ | `common.needPV` | `_storage.tpl` | +----------------------------------------------------+-----------------------+ | `common.onServiceMesh` | `_serviceMesh.tpl` | +----------------------------------------------------+-----------------------+ | `common.common.needTLS` | `_service.tpl` | +----------------------------------------------------+-----------------------+ * template generation functions +----------------------------------------------------+-----------------------+ | Function | File | +----------------------------------------------------+-----------------------+ | `common.masterPassword` | `_createPassword.tpl` | +----------------------------------------------------+-----------------------+ | `common.createPassword` | `_createPassword.tpl` | +----------------------------------------------------+-----------------------+ | `common.secret.genName` | `_secret.yaml` | +----------------------------------------------------+-----------------------+ | `common.secret.getSecretName` | `_secret.yaml` | +----------------------------------------------------+-----------------------+ | `common.secret.envFromSecret` | `_secret.yaml` | +----------------------------------------------------+-----------------------+ | `common.secret` | `_secret.yaml` | +----------------------------------------------------+-----------------------+ | `ingress.config.port` | `_ingress.tpl` | +----------------------------------------------------+-----------------------+ | `ingress.config.annotations.ssl` | `_ingress.tpl` | +----------------------------------------------------+-----------------------+ | `ingress.config.annotations` | `_ingress.tpl` | +----------------------------------------------------+-----------------------+ | `common.ingress` | `_ingress.tpl` | +----------------------------------------------------+-----------------------+ | `common.labels` | `_labels.tpl` | +----------------------------------------------------+-----------------------+ | `common.matchLabels` | `_labels.tpl` | +----------------------------------------------------+-----------------------+ | `common.resourceMetadata` | `_labels.tpl` | +----------------------------------------------------+-----------------------+ | `common.templateMetadata` | `_labels.tpl` | +----------------------------------------------------+-----------------------+ | `common.selectors` | `_labels.tpl` | +----------------------------------------------------+-----------------------+ | `common.name` | `_name.tpl` | +----------------------------------------------------+-----------------------+ | `common.fullname` | `_name.tpl` | +----------------------------------------------------+-----------------------+ | `common.fullnameExplicit` | `_name.tpl` | +----------------------------------------------------+-----------------------+ | `common.release` | `_name.tpl` | +----------------------------------------------------+-----------------------+ | `common.chart` | `_name.tpl` | +----------------------------------------------------+-----------------------+ | `common.namespace` | `_namespace.tpl` | +----------------------------------------------------+-----------------------+ | `common.repository` | `_repository.tpl` | +----------------------------------------------------+-----------------------+ | `common.flavor` | `_resources.tpl` | +----------------------------------------------------+-----------------------+ | `common.resources` | `_resources.tpl` | +----------------------------------------------------+-----------------------+ | `common.storageClass` | `_storage.tpl` | +----------------------------------------------------+-----------------------+ | `common.replicaPV` | `_storage.tpl` | +----------------------------------------------------+-----------------------+ | `common.servicename` | `_service.tpl` | +----------------------------------------------------+-----------------------+ | `common.serviceMetadata` | `_service.tpl` | +----------------------------------------------------+-----------------------+ | `common.servicePorts` | `_service.tpl` | +----------------------------------------------------+-----------------------+ | `common.genericService` | `_service.tpl` | +----------------------------------------------------+-----------------------+ | `common.service` | `_service.tpl` | +----------------------------------------------------+-----------------------+ | `common.headlessService` | `_service.tpl` | +----------------------------------------------------+-----------------------+ | `common.mariadb.secret.rootPassUID` | `_mariadb.tpl` | +----------------------------------------------------+-----------------------+ | `common.mariadb.secret.rootPassSecretName` | `_mariadb.tpl` | +----------------------------------------------------+-----------------------+ | `common.mariadb.secret.userCredentialsUID` | `_mariadb.tpl` | +----------------------------------------------------+-----------------------+ | `common.mariadb.secret.userCredentialsSecretName` | `_mariadb.tpl` | +----------------------------------------------------+-----------------------+ | `common.mariadbService` | `_mariadb.tpl` | +----------------------------------------------------+-----------------------+ | `common.mariadbPort` | `_mariadb.tpl` | +----------------------------------------------------+-----------------------+ | `common.mariadbSecret` | `_mariadb.tpl` | +----------------------------------------------------+-----------------------+ | `common.mariadbSecretParam` | `_mariadb.tpl` | +----------------------------------------------------+-----------------------+ | `common.postgres.secret.rootPassUID` | `_postgres.tpl` | +----------------------------------------------------+-----------------------+ | `common.postgres.secret.rootPassSecretName` | `_postgres.tpl` | +----------------------------------------------------+-----------------------+ | `common.postgres.secret.userCredentialsUID` | `_postgres.tpl` | +----------------------------------------------------+-----------------------+ | `common.postgres.secret.userCredentialsSecretName` | `_postgres.tpl` | +----------------------------------------------------+-----------------------+ | `common.postgres.secret.primaryPasswordUID` | `_postgres.tpl` | +----------------------------------------------------+-----------------------+ | `common.postgres.secret.primaryPasswordSecretName` | `_postgres.tpl` | +----------------------------------------------------+-----------------------+ | `common.tplValue` | `_tplValue.tpl` | +----------------------------------------------------+-----------------------+ Passwords --------- These functions are defined in `kubernetes/common/common/templates/_createPassword.tpl`. * `common.masterPassword`: Resolve the master password to be used to derive other passwords. * `common.createPassword`: Generate a new password based on masterPassword. Secrets ------- These functions are defined in `kubernetes/common/common/templates/_secret.yaml`. * `common.secret.genName`: Generate a secret name based on provided name or UID. * `common.secret.getSecretName`: Get the real secret name by UID or name, based on the configuration provided by user. * `common.secret.envFromSecret`: Convenience template which can be used to easily set the value of environment variable to the value of a key in a secret. * `common.secret`: Define secrets to be used by chart. The most widely use templates is the last (`common.secret`). It should be the only (except license part) line of your secret file: .. code-block:: yaml {{ include "common.secret" . }} In order to have the right values set, you need to create the right configuration in `values.yaml` (example taken from mariadb configuration): .. code-block:: yaml secrets: - uid: 'db-root-password' type: password externalSecret: '{{ tpl (default "" .Values.config.db.rootPasswordExternalSecret) . }}' password: '{{ .Values.config.dbRootPassword }}' - uid: 'db-user-creds' type: basicAuth externalSecret: '{{ tpl (default "" .Values.config.db.userCredentialsExternalSecret) . }}' login: '{{ .Values.config.db.userName }}' password: '{{ .Values.config.dbSdnctlPassword }}' Ingress ------- These functions are defined in `kubernetes/common/common/templates/_ingress.tpl`. * `ingress.config.port`: generate the port path on an Ingress resource. * `ingress.config.annotations.ssl`: generate the ssl annotations of an Ingress resource. * `ingress.config.annotations`: generate the annotations of an Ingress resource. * `common.ingress`: generate an Ingress resource (if needed). The most widely use templates is the last (`common.ingress`) . It should be the only (except license part) line of your ingress file: .. code-block:: yaml {{ include "common.ingress" . }} In order to have the right values set, you need to create the right configuration in `values.yaml` (example taken from clamp configuration): .. code-block:: yaml ingress: enabled: false service: - baseaddr: "clamp" name: "clamp" port: 443 config: ssl: "redirect" Labels ------ These functions are defined in `kubernetes/common/common/templates/_labels.tpl`. The goal of these functions is to always create the right labels for all the resource in a consistent way. * `common.labels`: generate the common labels for a resource * `common.matchLabels`: generate the labels to match (to be used in conjunction with `common.labels` or `common.resourceMetadata`) * `common.resourceMetadata`: generate the "top" metadatas for a resource (Deployment, StatefulSet, Service, ConfigMap, ...) * `common.templateMetadata`: generate the metadata put in the template part (for example `spec.template.metadata` for a Deployment) * `common.selectors`: generate the right selectors for Service / Deployment / StatefulSet, ... (to be used in conjunction with `common.labels` or `common.resourceMetadata`) Here's an example of use of these functions in a Deployment template (example taken on nbi): .. code-block:: yaml apiVersion: apps/v1 kind: Deployment metadata: {{- include "common.resourceMetadata" . | nindent 2 }} spec: selector: {{- include "common.selectors" . | nindent 4 }} replicas: {{ .Values.replicaCount }} template: metadata: {{- include "common.templateMetadata" . | nindent 6 }} spec: ... Name ---- These functions are defined in `kubernetes/common/common/templates/_name.tpl`. The goal of these functions is to always name the resource the same way. * `common.name`: Generate the name for a chart. * `common.fullname`: Create a default fully qualified application name. * `common.fullnameExplicit`: The same as common.full name but based on passed dictionary instead of trying to figure out chart name on its own. * `common.release`: Retrieve the "original" release from the component release. * `common.chart`: Generate the chart name Here's an example of use of these functions in a Deployment template (example taken on mariadb-galera): .. code-block:: yaml apiVersion: apps/v1beta1 kind: StatefulSet ... spec: serviceName: {{ .Values.service.name }} replicas: {{ .Values.replicaCount }} template: ... spec: {{- if .Values.nodeSelector }} nodeSelector: {{ toYaml .Values.nodeSelector | indent 8 }} {{- end }} volumes: {{- if .Values.externalConfig }} - name: config configMap: name: {{ include "common.fullname" . }}-external-config {{- end}} ... containers: - name: {{ include "common.name" . }} image: {{ include "repositoryGenerator.repository" . }}/{{ .Values.image }} ... Namespace --------- These functions are defined in `kubernetes/common/common/templates/_namespace.tpl`. The goal of these functions is to always retrieve the namespace the same way. * `common.namespace`: Generate the namespace for a chart. Shouldn't be used directly but use `common.resourceMetadata` (which uses it). Repository ---------- These functions are defined in `kubernetes/common/common/templates/_repository.tpl`. The goal of these functions is to generate image name the same way. * `common.repository`: Resolve the name of the common image repository. * `common.repository.secret`: Resolve the image repository secret token. Resources --------- These functions are defined in `kubernetes/common/common/templates/_resources.tpl`. The goal of these functions is to generate resources for pods the same way. * `common.flavor`: Resolve the name of the common resource limit/request flavor. Shouldn't be used alone. * `common.resources`: Resolve the resource limit/request flavor using the desired flavor value. Storage ------- These functions are defined in `kubernetes/common/common/templates/_storage.tpl`. The goal of these functions is to generate storage part of Deployment / Statefulset and storage resource (PV, PVC, ...) in a consistent way. * `common.storageClass`: Expand the name of the storage class. * `common.needPV`: Calculate if we need a PV. If a storageClass is provided, then we don't need. * `common.replicaPV`: Generate N PV for a statefulset Pod --- These functions are defined in `kubernetes/common/common/templates/_pod.tpl`. * `common.containerPorts`: generate the port list for containers. See Service part to know how to declare the port list. Here's an example of use of these functions in a Deployment template (example taken on nbi): .. code-block:: yaml apiVersion: apps/v1 kind: Deployment ... spec: ... template: ... spec: containers: - name: {{ include "common.name" . }} ports: {{- include "common.containerPorts" . | nindent 8 } Service ------- These functions are defined in `kubernetes/common/common/templates/_service.tpl`. The goal of these functions is to generate services in a consistent way. * `common.servicename`: Expand the service name for a chart. * `common.serviceMetadata`: Define the metadata of Service. Shouldn't be used directly but used through `common.service` or `common.headlessService`. * `common.servicePorts`: Define the ports of Service. Shouldn't be used directly but used through `common.service` or `common.headlessService`. * `common.genericService`: Template for creating any Service. Shouldn't be used directly but used through `common.service` or `common.headlessService`. May be used if you want to create a Service with some specificities (on the ports for example). * `common.needTLS`: Calculate if we need to use TLS ports on services * `common.service`: Create service template. * `common.headlessService`: Create headless service template The most widely used templates are the two last (`common.service` and `common.headlessService`). It should use with only one (except license part) line of your service (or service-headless) file: .. code-block:: yaml {{ include "common.service" . }} In order to have the right values set, you need to create the right configuration in `values.yaml` (example taken from nbi configuration + other part): .. code-block:: yaml service: type: NodePort name: nbi annotations: my: super-annotation ports: - name: api port: 8443 plain_port: 8080 port_protocol: http nodePort: 74 - name: tcp-raw port: 8459 nodePort: 89 would generate: .. code-block:: yaml apiVersion: v1 kind: Service metadata: annotations: my: super-annotation name: nbi namespace: default labels: app.kubernetes.io/name: nbi helm.sh/chart: nbi-6.0.0 app.kubernetes.io/instance: release app.kubernetes.io/managed-by: Tiller spec: ports: - port: 8443 targetPort: api name: https-api nodePort: 30274 - port: 8459 targetPort: tcp-raw name: tcp-raw nodePort: 30289 type: NodePort selector: app.kubernetes.io/name: nbi app.kubernetes.io/instance: release `plain_port` is used only if we mandate to use http (see ServiceMesh part). Today a port can be http or https but not both. headless configuration is equivalent (example taken from cassandra): .. code-block:: yaml service: name: cassandra headless: suffix: "" annotations: service.alpha.kubernetes.io/tolerate-unready-endpoints: "true" publishNotReadyAddresses: true headlessPorts: - name: tcp-intra port: 7000 - name: tls port: 7001 - name: tcp-jmx port: 7199 - name: tcp-cql port: 9042 - name: tcp-thrift port: 9160 - name: tcp-agent port: 61621 ServiceMesh ----------- These functions are defined in `kubernetes/common/common/templates/_serviceMesh.tpl`. The goal of these functions is to handle onboarding of ONAP on service mesh. * `common.onServiceMesh`: Calculate if we if we are on service mesh MariaDB ------- These functions are defined in `kubernetes/common/common/templates/_mariadb.tpl`. The goal of these functions is to simplify use of mariadb and its different values. * `common.mariadb.secret.rootPassUID`: UID of mariadb root password * `common.mariadb.secret.rootPassSecretName`: Name of mariadb root password secret * `common.mariadb.secret.userCredentialsUID`: UID of mariadb user credentials * `common.mariadb.secret.userCredentialsSecretName`: Name of mariadb user credentials secret * `common.mariadbService`: Choose the name of the mariadb service to use * `common.mariadbPort`: Choose the value of mariadb port to use * `common.mariadbSecret`: Choose the value of secret to retrieve user value * `common.mariadbSecretParam`: Choose the value of secret param to retrieve user value PostgreSQL ---------- These functions are defined in `kubernetes/common/common/templates/_postgres.tpl`. The goal of these functions is to simplify use of postgres and its different values. * `common.postgres.secret.rootPassUID`: UID of postgres root password * `common.postgres.secret.rootPassSecretName`: Name of postgres root password secret * `common.postgres.secret.userCredentialsUID`: UID of postgres user credentials * `common.postgres.secret.userCredentialsSecretName`: Name of postgres user credentials secret * `common.postgres.secret.primaryPasswordUID`: UID of postgres primary password * `common.postgres.secret.primaryPasswordSecretName`: Name of postgres primary credentials secret Utilities --------- These functions are defined in `kubernetes/common/common/templates/_tplValue.tpl`. The goal of these functions is provide utility function, usually used in other templating functions. * `common.tplValue`: Renders a value that contains template.