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.flavor`                                    | `_resources.tpl`      |
  81   +----------------------------------------------------+-----------------------+
  82   | `common.resources`                                 | `_resources.tpl`      |
  83   +----------------------------------------------------+-----------------------+
  84   | `common.storageClass`                              | `_storage.tpl`        |
  85   +----------------------------------------------------+-----------------------+
  86   | `common.replicaPV`                                 | `_storage.tpl`        |
  87   +----------------------------------------------------+-----------------------+
  88   | `common.servicename`                               | `_service.tpl`        |
  89   +----------------------------------------------------+-----------------------+
  90   | `common.serviceMetadata`                           | `_service.tpl`        |
  91   +----------------------------------------------------+-----------------------+
  92   | `common.servicePorts`                              | `_service.tpl`        |
  93   +----------------------------------------------------+-----------------------+
  94   | `common.genericService`                            | `_service.tpl`        |
  95   +----------------------------------------------------+-----------------------+
  96   | `common.service`                                   | `_service.tpl`        |
  97   +----------------------------------------------------+-----------------------+
  98   | `common.headlessService`                           | `_service.tpl`        |
  99   +----------------------------------------------------+-----------------------+
 100   | `common.mariadb.secret.rootPassUID`                | `_mariadb.tpl`        |
 101   +----------------------------------------------------+-----------------------+
 102   | `common.mariadb.secret.rootPassSecretName`         | `_mariadb.tpl`        |
 103   +----------------------------------------------------+-----------------------+
 104   | `common.mariadb.secret.userCredentialsUID`         | `_mariadb.tpl`        |
 105   +----------------------------------------------------+-----------------------+
 106   | `common.mariadb.secret.userCredentialsSecretName`  | `_mariadb.tpl`        |
 107   +----------------------------------------------------+-----------------------+
 108   | `common.mariadbService`                            | `_mariadb.tpl`        |
 109   +----------------------------------------------------+-----------------------+
 110   | `common.mariadbPort`                               | `_mariadb.tpl`        |
 111   +----------------------------------------------------+-----------------------+
 112   | `common.mariadbSecret`                             | `_mariadb.tpl`        |
 113   +----------------------------------------------------+-----------------------+
 114   | `common.mariadbSecretParam`                        | `_mariadb.tpl`        |
 115   +----------------------------------------------------+-----------------------+
 116   | `common.postgres.secret.rootPassUID`               | `_postgres.tpl`       |
 117   +----------------------------------------------------+-----------------------+
 118   | `common.postgres.secret.rootPassSecretName`        | `_postgres.tpl`       |
 119   +----------------------------------------------------+-----------------------+
 120   | `common.postgres.secret.userCredentialsUID`        | `_postgres.tpl`       |
 121   +----------------------------------------------------+-----------------------+
 122   | `common.postgres.secret.userCredentialsSecretName` | `_postgres.tpl`       |
 123   +----------------------------------------------------+-----------------------+
 124   | `common.postgres.secret.primaryPasswordUID`        | `_postgres.tpl`       |
 125   +----------------------------------------------------+-----------------------+
 126   | `common.postgres.secret.primaryPasswordSecretName` | `_postgres.tpl`       |
 127   +----------------------------------------------------+-----------------------+
 128   | `common.tplValue`                                  | `_tplValue.tpl`       |
 129   +----------------------------------------------------+-----------------------+
 130
 131
 132 Passwords
 133 ---------
 134
 135 These functions are defined in
 136 `kubernetes/common/common/templates/_createPassword.tpl`.
 137
 138 * `common.masterPassword`: Resolve the master password to be used to derive
 139   other passwords.
 140 * `common.createPassword`: Generate a new password based on masterPassword.
 141
 142 Secrets
 143 -------
 144
 145 These functions are defined in
 146 `kubernetes/common/common/templates/_secret.yaml`.
 147
 148 * `common.secret.genName`: Generate a secret name based on provided name or UID.
 149 * `common.secret.getSecretName`: Get the real secret name by UID or name, based
 150   on the configuration provided by user.
 151 * `common.secret.envFromSecret`: Convenience template which can be used to
 152   easily set the value of environment variable to the value of a key in a
 153   secret.
 154 * `common.secret`: Define secrets to be used by chart.
 155
 156 The most widely use templates is the last (`common.secret`).
 157 It should be the only (except license part) line of your secret file:
 158
 159 .. code-block:: yaml
 160
 161   {{ include "common.secret" . }}
 162
 163 In order to have the right values set, you need to create the right
 164 configuration in `values.yaml` (example taken from mariadb configuration):
 165
 166 .. code-block:: yaml
 167
 168   secrets:
 169   - uid: 'db-root-password'
 170     type: password
 171     externalSecret: '{{ tpl (default "" .Values.config.db.rootPasswordExternalSecret) . }}'
 172     password: '{{ .Values.config.dbRootPassword }}'
 173   - uid: 'db-user-creds'
 174     type: basicAuth
 175     externalSecret: '{{ tpl (default "" .Values.config.db.userCredentialsExternalSecret) . }}'
 176     login: '{{ .Values.config.db.userName }}'
 177     password: '{{ .Values.config.dbSdnctlPassword }}'
 178
 179 Ingress
 180 -------
 181
 182 These functions are defined in
 183 `kubernetes/common/common/templates/_ingress.tpl`.
 184
 185 * `ingress.config.port`: generate the port path on an Ingress resource.
 186 * `ingress.config.annotations.ssl`: generate the ssl annotations of an Ingress
 187   resource.
 188 * `ingress.config.annotations`: generate the annotations of an Ingress resource.
 189 * `common.ingress`: generate an Ingress resource (if needed).
 190
 191 The most widely use templates is the last (`common.ingress`) .
 192
 193 It should be the only (except license part) line of your ingress file:
 194
 195 .. code-block:: yaml
 196
 197   {{ include "common.ingress" . }}
 198
 199 In order to have the right values set, you need to create the right
 200 configuration in `values.yaml` (example taken from clamp configuration):
 201
 202 .. code-block:: yaml
 203
 204   ingress:
 205     enabled: false
 206     service:
 207       - baseaddr: "clamp"
 208         name: "clamp"
 209         port: 443
 210     config:
 211       ssl: "redirect"
 212
 213 Labels
 214 ------
 215
 216 These functions are defined in `kubernetes/common/common/templates/_labels.tpl`.
 217
 218 The goal of these functions is to always create the right labels for all the
 219 resource in a consistent way.
 220
 221 * `common.labels`: generate the common labels for a resource
 222 * `common.matchLabels`: generate the labels to match (to be used in conjunction
 223   with `common.labels` or `common.resourceMetadata`)
 224 * `common.resourceMetadata`: generate the "top" metadatas for a resource
 225   (Deployment, StatefulSet, Service, ConfigMap, ...)
 226 * `common.templateMetadata`: generate the metadata put in the template part
 227   (for example `spec.template.metadata` for a Deployment)
 228 * `common.selectors`: generate the right selectors for Service / Deployment /
 229   StatefulSet, ... (to be used in conjunction with `common.labels` or
 230   `common.resourceMetadata`)
 231
 232
 233 Here's an example of use of these functions in a Deployment template (example
 234 taken on nbi):
 235
 236 .. code-block:: yaml
 237
 238   apiVersion: apps/v1
 239   kind: Deployment
 240   metadata: {{- include "common.resourceMetadata" . | nindent 2 }}
 241   spec:
 242     selector: {{- include "common.selectors" . | nindent 4 }}
 243     replicas: {{ .Values.replicaCount }}
 244     template:
 245       metadata: {{- include "common.templateMetadata" . | nindent 6 }}
 246       spec:
 247         ...
 248
 249 Name
 250 ----
 251
 252 These functions are defined in `kubernetes/common/common/templates/_name.tpl`.
 253
 254 The goal of these functions is to always name the resource the same way.
 255
 256 * `common.name`: Generate the name for a chart.
 257 * `common.fullname`: Create a default fully qualified application name.
 258 * `common.fullnameExplicit`: The same as common.full name but based on passed
 259   dictionary instead of trying to figure out chart name on its own.
 260 * `common.release`: Retrieve the "original" release from the component release.
 261 * `common.chart`: Generate the chart name
 262
 263 Here's an example of use of these functions in a Deployment template (example
 264 taken on mariadb-galera):
 265
 266 .. code-block:: yaml
 267
 268   apiVersion: apps/v1beta1
 269   kind: StatefulSet
 270   ...
 271   spec:
 272     serviceName: {{ .Values.service.name }}
 273     replicas: {{ .Values.replicaCount }}
 274     template:
 275       ...
 276       spec:
 277       {{- if .Values.nodeSelector }}
 278         nodeSelector:
 279   {{ toYaml .Values.nodeSelector | indent 8 }}
 280       {{- end }}
 281         volumes:
 282         {{- if .Values.externalConfig }}
 283           - name: config
 284             configMap:
 285               name: {{ include "common.fullname" . }}-external-config
 286         {{- end}}
 287         ...
 288         containers:
 289         - name: {{ include "common.name" . }}
 290           image: {{ include "repositoryGenerator.repository" . }}/{{ .Values.image }}
 291         ...
 292
 293 Namespace
 294 ---------
 295
 296 These functions are defined in
 297 `kubernetes/common/common/templates/_namespace.tpl`.
 298
 299 The goal of these functions is to always retrieve the namespace the same way.
 300
 301 * `common.namespace`: Generate the namespace for a chart. Shouldn't be used
 302   directly but use `common.resourceMetadata` (which uses it).
 303
 304
 305 Repository
 306 ----------
 307
 308 These functions are defined in
 309 `kubernetes/common/common/templates/_repository.tpl`.
 310
 311 The goal of these functions is to generate image name the same way.
 312
 313 * `common.repository`: Resolve the name of the common image repository.
 314 * `common.repository.secret`: Resolve the image repository secret token.
 315
 316
 317 Resources
 318 ---------
 319
 320 These functions are defined in
 321 `kubernetes/common/common/templates/_resources.tpl`.
 322
 323 The goal of these functions is to generate resources for pods the same way.
 324
 325 * `common.flavor`: Resolve the name of the common resource limit/request flavor.
 326   Shouldn't be used alone.
 327 * `common.resources`: Resolve the resource limit/request flavor using the
 328   desired flavor value.
 329
 330
 331 Storage
 332 -------
 333
 334 These functions are defined in
 335 `kubernetes/common/common/templates/_storage.tpl`.
 336
 337 The goal of these functions is to generate storage part of Deployment /
 338 Statefulset and storage resource (PV, PVC, ...) in a consistent way.
 339
 340 * `common.storageClass`: Expand the name of the storage class.
 341 * `common.needPV`: Calculate if we need a PV. If a storageClass is provided,
 342   then we don't need.
 343 * `common.replicaPV`: Generate N PV for a statefulset
 344
 345
 346 Pod
 347 ---
 348
 349 These functions are defined in `kubernetes/common/common/templates/_pod.tpl`.
 350
 351 * `common.containerPorts`: generate the port list for containers. See Service
 352   part to know how to declare the port list.
 353
 354 Here's an example of use of these functions in a Deployment template (example
 355 taken on nbi):
 356
 357 .. code-block:: yaml
 358
 359   apiVersion: apps/v1
 360   kind: Deployment
 361   ...
 362   spec:
 363     ...
 364     template:
 365       ...
 366       spec:
 367         containers:
 368         - name:  {{ include "common.name" . }}
 369           ports: {{- include "common.containerPorts" . | nindent 8  }
 370
 371
 372 Service
 373 -------
 374
 375 These functions are defined in
 376 `kubernetes/common/common/templates/_service.tpl`.
 377
 378 The goal of these functions is to generate services in a consistent way.
 379
 380 * `common.servicename`: Expand the service name for a chart.
 381 * `common.serviceMetadata`: Define the metadata of Service. Shouldn't be used
 382   directly but used through `common.service` or `common.headlessService`.
 383 * `common.servicePorts`: Define the ports of Service. Shouldn't be used directly
 384   but used through `common.service` or `common.headlessService`.
 385 * `common.genericService`: Template for creating any Service. Shouldn't be used
 386   directly but used through `common.service` or `common.headlessService`. May be
 387   used if you want to create a Service with some specificities (on the ports for
 388   example).
 389 * `common.needTLS`: Calculate if we need to use TLS ports on services
 390 * `common.service`: Create service template.
 391 * `common.headlessService`: Create headless service template
 392
 393
 394 The most widely used templates are the two last (`common.service` and
 395 `common.headlessService`).
 396 It should use with only one (except license part) line of your service (or
 397 service-headless) file:
 398
 399 .. code-block:: yaml
 400
 401   {{ include "common.service" . }}
 402
 403 In order to have the right values set, you need to create the right
 404 configuration in `values.yaml` (example taken from nbi configuration + other
 405 part):
 406
 407 .. code-block:: yaml
 408
 409   service:
 410     type: NodePort
 411     name: nbi
 412     annotations:
 413       my: super-annotation
 414     ports:
 415       - name: api
 416         port: 8443
 417         plain_port: 8080
 418         port_protocol: http
 419         nodePort: 74
 420       - name: tcp-raw
 421         port: 8459
 422         nodePort: 89
 423
 424
 425 would generate:
 426
 427 .. code-block:: yaml
 428
 429   apiVersion: v1
 430   kind: Service
 431   metadata:
 432     annotations:
 433       my: super-annotation
 434     name: nbi
 435     namespace: default
 436     labels:
 437       app.kubernetes.io/name: nbi
 438       helm.sh/chart: nbi-7.0.0
 439       app.kubernetes.io/instance: release
 440       app.kubernetes.io/managed-by: Tiller
 441   spec:
 442     ports:
 443     - port: 8443
 444       targetPort: api
 445       name: https-api
 446       nodePort: 30274
 447     - port: 8459
 448       targetPort: tcp-raw
 449       name: tcp-raw
 450       nodePort: 30289
 451     type: NodePort
 452     selector:
 453       app.kubernetes.io/name: nbi
 454       app.kubernetes.io/instance: release
 455
 456
 457 `plain_port` is used only if we mandate to use http (see ServiceMesh part).
 458 Today a port can be http or https but not both.
 459 headless configuration is equivalent (example taken from cassandra):
 460
 461 .. code-block:: yaml
 462
 463   service:
 464     name: cassandra
 465     headless:
 466       suffix: ""
 467       annotations:
 468         service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
 469       publishNotReadyAddresses: true
 470     headlessPorts:
 471     - name: tcp-intra
 472       port: 7000
 473     - name: tls
 474       port: 7001
 475     - name: tcp-jmx
 476       port: 7199
 477     - name: tcp-cql
 478       port: 9042
 479     - name: tcp-thrift
 480       port: 9160
 481     - name: tcp-agent
 482       port: 61621
 483
 484
 485 ServiceMesh
 486 -----------
 487
 488 These functions are defined in
 489 `kubernetes/common/common/templates/_serviceMesh.tpl`.
 490
 491 The goal of these functions is to handle onboarding of ONAP on service mesh.
 492
 493 * `common.onServiceMesh`: Calculate if we if we are on service mesh
 494
 495
 496
 497 MariaDB
 498 -------
 499
 500 These functions are defined in
 501 `kubernetes/common/common/templates/_mariadb.tpl`.
 502
 503 The goal of these functions is to simplify use of mariadb and its different
 504 values.
 505
 506 * `common.mariadb.secret.rootPassUID`: UID of mariadb root password
 507 * `common.mariadb.secret.rootPassSecretName`: Name of mariadb root password
 508   secret
 509 * `common.mariadb.secret.userCredentialsUID`: UID of mariadb user credentials
 510 * `common.mariadb.secret.userCredentialsSecretName`: Name of mariadb user
 511   credentials secret
 512 * `common.mariadbService`: Choose the name of the mariadb service to use
 513 * `common.mariadbPort`: Choose the value of mariadb port to use
 514 * `common.mariadbSecret`: Choose the value of secret to retrieve user value
 515 * `common.mariadbSecretParam`: Choose the value of secret param to retrieve user
 516   value
 517
 518 PostgreSQL
 519 ----------
 520
 521 These functions are defined in
 522 `kubernetes/common/common/templates/_postgres.tpl`.
 523
 524 The goal of these functions is to simplify use of postgres and its different
 525 values.
 526
 527 * `common.postgres.secret.rootPassUID`: UID of postgres root password
 528 * `common.postgres.secret.rootPassSecretName`: Name of postgres root password
 529   secret
 530 * `common.postgres.secret.userCredentialsUID`: UID of postgres user credentials
 531 * `common.postgres.secret.userCredentialsSecretName`: Name of postgres user
 532   credentials secret
 533 * `common.postgres.secret.primaryPasswordUID`: UID of postgres primary password
 534 * `common.postgres.secret.primaryPasswordSecretName`: Name of postgres primary
 535   credentials secret
 536
 537
 538 Utilities
 539 ---------
 540
 541 These functions are defined in
 542 `kubernetes/common/common/templates/_tplValue.tpl`.
 543
 544 The goal of these functions is provide utility function, usually used in other
 545 templating functions.
 546
 547 * `common.tplValue`: Renders a value that contains template.