.. 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.
