kubernetes/common/common/documentation.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. Copyright 2020 Orange.  All rights reserved.
   5
   6 .. _developer-guide-label:
   7
   8
   9 Current given templating functions
  10 ==================================
  11
  12
  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.
  18
  19 * conditional functions
  20
  21   +----------------------------------------------------+-----------------------+
  22   | Function                                           | File                  |
  23   +----------------------------------------------------+-----------------------+
  24   | `common.needPV`                                    | `_storage.tpl`        |
  25   +----------------------------------------------------+-----------------------+
  26   | `common.onServiceMesh`                             | `_serviceMesh.tpl`    |
  27   +----------------------------------------------------+-----------------------+
  28   | `common.common.needTLS`                             | `_service.tpl`       |
  29   +----------------------------------------------------+-----------------------+
  30
  31 * template generation functions
  32
  33   +----------------------------------------------------+-----------------------+
  34   | Function                                           | File                  |
  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   +----------------------------------------------------+-----------------------+
 132
 133
 134 Passwords
 135 ---------
 136
 137 These functions are defined in
 138 `kubernetes/common/common/templates/_createPassword.tpl`.
 139
 140 * `common.masterPassword`: Resolve the master password to be used to derive
 141   other passwords.
 142 * `common.createPassword`: Generate a new password based on masterPassword.
 143
 144 Secrets
 145 -------
 146
 147 These functions are defined in
 148 `kubernetes/common/common/templates/_secret.yaml`.
 149
 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
 155   secret.
 156 * `common.secret`: Define secrets to be used by chart.
 157
 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:
 160
 161 .. code-block:: yaml
 162
 163   {{ include "common.secret" . }}
 164
 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):
 167
 168 .. code-block:: yaml
 169
 170   secrets:
 171   - uid: 'db-root-password'
 172     type: password
 173     externalSecret: '{{ tpl (default "" .Values.config.db.rootPasswordExternalSecret) . }}'
 174     password: '{{ .Values.config.dbRootPassword }}'
 175   - uid: 'db-user-creds'
 176     type: basicAuth
 177     externalSecret: '{{ tpl (default "" .Values.config.db.userCredentialsExternalSecret) . }}'
 178     login: '{{ .Values.config.db.userName }}'
 179     password: '{{ .Values.config.dbSdnctlPassword }}'
 180
 181 Ingress
 182 -------
 183
 184 These functions are defined in
 185 `kubernetes/common/common/templates/_ingress.tpl`.
 186
 187 * `ingress.config.port`: generate the port path on an Ingress resource.
 188 * `ingress.config.annotations.ssl`: generate the ssl annotations of an Ingress
 189   resource.
 190 * `ingress.config.annotations`: generate the annotations of an Ingress resource.
 191 * `common.ingress`: generate an Ingress resource (if needed).
 192
 193 The most widely use templates is the last (`common.ingress`) .
 194
 195 It should be the only (except license part) line of your ingress file:
 196
 197 .. code-block:: yaml
 198
 199   {{ include "common.ingress" . }}
 200
 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):
 203
 204 .. code-block:: yaml
 205
 206   ingress:
 207     enabled: false
 208     service:
 209       - baseaddr: "clamp"
 210         name: "clamp"
 211         port: 443
 212     config:
 213       ssl: "redirect"
 214
 215 Labels
 216 ------
 217
 218 These functions are defined in `kubernetes/common/common/templates/_labels.tpl`.
 219
 220 The goal of these functions is to always create the right labels for all the
 221 resource in a consistent way.
 222
 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`)
 233
 234
 235 Here's an example of use of these functions in a Deployment template (example
 236 taken on nbi):
 237
 238 .. code-block:: yaml
 239
 240   apiVersion: apps/v1
 241   kind: Deployment
 242   metadata: {{- include "common.resourceMetadata" . | nindent 2 }}
 243   spec:
 244     selector: {{- include "common.selectors" . | nindent 4 }}
 245     replicas: {{ .Values.replicaCount }}
 246     template:
 247       metadata: {{- include "common.templateMetadata" . | nindent 6 }}
 248       spec:
 249         ...
 250
 251 Name
 252 ----
 253
 254 These functions are defined in `kubernetes/common/common/templates/_name.tpl`.
 255
 256 The goal of these functions is to always name the resource the same way.
 257
 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
 264
 265 Here's an example of use of these functions in a Deployment template (example
 266 taken on mariadb-galera):
 267
 268 .. code-block:: yaml
 269
 270   apiVersion: apps/v1beta1
 271   kind: StatefulSet
 272   ...
 273   spec:
 274     serviceName: {{ .Values.service.name }}
 275     replicas: {{ .Values.replicaCount }}
 276     template:
 277       ...
 278       spec:
 279       {{- if .Values.nodeSelector }}
 280         nodeSelector:
 281   {{ toYaml .Values.nodeSelector | indent 8 }}
 282       {{- end }}
 283         volumes:
 284         {{- if .Values.externalConfig }}
 285           - name: config
 286             configMap:
 287               name: {{ include "common.fullname" . }}-external-config
 288         {{- end}}
 289         ...
 290         containers:
 291         - name: {{ include "common.name" . }}
 292           image: "{{ include "common.repository" . }}/{{ .Values.image }}"
 293         ...
 294
 295 Namespace
 296 ---------
 297
 298 These functions are defined in
 299 `kubernetes/common/common/templates/_namespace.tpl`.
 300
 301 The goal of these functions is to always retrieve the namespace the same way.
 302
 303 * `common.namespace`: Generate the namespace for a chart. Shouldn't be used
 304   directly but use `common.resourceMetadata` (which uses it).
 305
 306
 307 Repository
 308 ----------
 309
 310 These functions are defined in
 311 `kubernetes/common/common/templates/_repository.tpl`.
 312
 313 The goal of these functions is to generate image name the same way.
 314
 315 * `common.repository`: Resolve the name of the common image repository.
 316 * `common.repository.secret`: Resolve the image repository secret token.
 317
 318
 319 Resources
 320 ---------
 321
 322 These functions are defined in
 323 `kubernetes/common/common/templates/_resources.tpl`.
 324
 325 The goal of these functions is to generate resources for pods the same way.
 326
 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.
 331
 332
 333 Storage
 334 -------
 335
 336 These functions are defined in
 337 `kubernetes/common/common/templates/_storage.tpl`.
 338
 339 The goal of these functions is to generate storage part of Deployment /
 340 Statefulset and storage resource (PV, PVC, ...) in a consistent way.
 341
 342 * `common.storageClass`: Expand the name of the storage class.
 343 * `common.needPV`: Calculate if we need a PV. If a storageClass is provided,
 344   then we don't need.
 345 * `common.replicaPV`: Generate N PV for a statefulset
 346
 347
 348 Pod
 349 ---
 350
 351 These functions are defined in `kubernetes/common/common/templates/_pod.tpl`.
 352
 353 * `common.containerPorts`: generate the port list for containers. See Service
 354   part to know how to declare the port list.
 355
 356 Here's an example of use of these functions in a Deployment template (example
 357 taken on nbi):
 358
 359 .. code-block:: yaml
 360
 361   apiVersion: apps/v1
 362   kind: Deployment
 363   ...
 364   spec:
 365     ...
 366     template:
 367       ...
 368       spec:
 369         containers:
 370         - name:  {{ include "common.name" . }}
 371           ports: {{- include "common.containerPorts" . | nindent 8  }
 372
 373
 374 Service
 375 -------
 376
 377 These functions are defined in
 378 `kubernetes/common/common/templates/_service.tpl`.
 379
 380 The goal of these functions is to generate services in a consistent way.
 381
 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
 390   example).
 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
 394
 395
 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:
 400
 401 .. code-block:: yaml
 402
 403   {{ include "common.service" . }}
 404
 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
 407 part):
 408
 409 .. code-block:: yaml
 410
 411   service:
 412     type: NodePort
 413     name: nbi
 414     annotations:
 415       my: super-annotation
 416     ports:
 417       - name: api
 418         port: 8443
 419         plain_port: 8080
 420         port_protocol: http
 421         nodePort: 74
 422       - name: tcp-raw
 423         port: 8459
 424         nodePort: 89
 425
 426
 427 would generate:
 428
 429 .. code-block:: yaml
 430
 431   apiVersion: v1
 432   kind: Service
 433   metadata:
 434     annotations:
 435       my: super-annotation
 436     name: nbi
 437     namespace: default
 438     labels:
 439       app.kubernetes.io/name: nbi
 440       helm.sh/chart: nbi-5.0.0
 441       app.kubernetes.io/instance: release
 442       app.kubernetes.io/managed-by: Tiller
 443   spec:
 444     ports:
 445     - port: 8443
 446       targetPort: api
 447       name: https-api
 448       nodePort: 30274
 449     - port: 8459
 450       targetPort: tcp-raw
 451       name: tcp-raw
 452       nodePort: 30289
 453     type: NodePort
 454     selector:
 455       app.kubernetes.io/name: nbi
 456       app.kubernetes.io/instance: release
 457
 458
 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):
 462
 463 .. code-block:: yaml
 464
 465   service:
 466     name: cassandra
 467     headless:
 468       suffix: ""
 469       annotations:
 470         service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
 471       publishNotReadyAddresses: true
 472     headlessPorts:
 473     - name: tcp-intra
 474       port: 7000
 475     - name: tls
 476       port: 7001
 477     - name: tcp-jmx
 478       port: 7199
 479     - name: tcp-cql
 480       port: 9042
 481     - name: tcp-thrift
 482       port: 9160
 483     - name: tcp-agent
 484       port: 61621
 485
 486
 487 ServiceMesh
 488 -----------
 489
 490 These functions are defined in
 491 `kubernetes/common/common/templates/_serviceMesh.tpl`.
 492
 493 The goal of these functions is to handle onboarding of ONAP on service mesh.
 494
 495 * `common.onServiceMesh`: Calculate if we if we are on service mesh
 496
 497
 498
 499 MariaDB
 500 -------
 501
 502 These functions are defined in
 503 `kubernetes/common/common/templates/_mariadb.tpl`.
 504
 505 The goal of these functions is to simplify use of mariadb and its different
 506 values.
 507
 508 * `common.mariadb.secret.rootPassUID`: UID of mariadb root password
 509 * `common.mariadb.secret.rootPassSecretName`: Name of mariadb root password
 510   secret
 511 * `common.mariadb.secret.userCredentialsUID`: UID of mariadb user credentials
 512 * `common.mariadb.secret.userCredentialsSecretName`: Name of mariadb user
 513   credentials secret
 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
 518   value
 519
 520 PostgreSQL
 521 ----------
 522
 523 These functions are defined in
 524 `kubernetes/common/common/templates/_postgres.tpl`.
 525
 526 The goal of these functions is to simplify use of postgres and its different
 527 values.
 528
 529 * `common.postgres.secret.rootPassUID`: UID of postgres root password
 530 * `common.postgres.secret.rootPassSecretName`: Name of postgres root password
 531   secret
 532 * `common.postgres.secret.userCredentialsUID`: UID of postgres user credentials
 533 * `common.postgres.secret.userCredentialsSecretName`: Name of postgres user
 534   credentials secret
 535 * `common.postgres.secret.primaryPasswordUID`: UID of postgres primary password
 536 * `common.postgres.secret.primaryPasswordSecretName`: Name of postgres primary
 537   credentials secret
 538
 539
 540 Utilities
 541 ---------
 542
 543 These functions are defined in
 544 `kubernetes/common/common/templates/_tplValue.tpl`.
 545
 546 The goal of these functions is provide utility function, usually used in other
 547 templating functions.
 548
 549 * `common.tplValue`: Renders a value that contains template.