--- /dev/null
+.. 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.repository.secret` | `_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 "common.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-5.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.
Code Review / oom.git / blobdiff