Создание пакетов для Kubernetes с Helm: структура чарта и шаблонизация

1. Файлы, необходимые для генерации манифестов Kubernetes-ресурсов. К ним относятся шаблоны из директории templates и файлы со значениями (значения по умолчанию хранятся в values.yaml). Также к данной группе относятся файл requirements.yaml и директория charts — всё это используется для организации вложенных чартов.
2. Сопроводительные файлы, содержащие информацию, которая может быть полезна при поиске чартов, знакомстве с ними и их использовании. Большая часть файлов этой группы является необязательной.

• Chart.yaml — файл с информацией о чарте;
• LICENSE — необязательный текстовый файл с лицензией чарта;
• README.md — необязательный файл с документацией;
• requirements.yaml — необязательный файл со списком чартов-зависимостей;
• values.yaml — файл со значениями по умолчанию для шаблонов;
• charts/ — необязательная директория со вложенными чартами;
• templates/ — директория с шаблонами манифестов Kubernetes-ресурсов;
• templates/NOTES.txt — необязательный текстовый файл с примечанием, которое выводится пользователю при инсталяции и обновлении.

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: {{ template "fullname" . }}
  labels:
    app: {{ template "fullname" . }}
    chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
    release: "{{ .Release.Name }}"
    heritage: "{{ .Release.Service }}"
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    metadata:
      labels:
        app: {{ template "fullname" . }}
        chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
        release: "{{ .Release.Name }}"
    spec:
      {{- if .Values.image.pullSecrets }}
      imagePullSecrets:
      {{- range .Values.image.pullSecrets }}
        - name: {{ . }}
      {{- end}}
      {{- end }}
      containers:
      - name: {{ template "fullname" . }}
        image: "{{ .Values.image.registry }}/{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        imagePullPolicy: {{ .Values.image.pullPolicy | quote }}
        env:
        - name: ALLOW_EMPTY_PASSWORD
        {{- if .Values.allowEmptyPassword }}
          value: "yes"
        {{- else }}
          value: "no"
        {{- end }}
        - name: MARIADB_HOST
        {{- if .Values.mariadb.enabled }}
          value: {{ template "mariadb.fullname" . }}
        {{- else }}
          value: {{ .Values.externalDatabase.host | quote }}
        {{- end }}
        - name: MARIADB_PORT_NUMBER
        {{- if .Values.mariadb.enabled }}
          value: "3306"
        {{- else }}
          value: {{ .Values.externalDatabase.port | quote }}
        {{- end }}
        - name: WORDPRESS_DATABASE_NAME
        {{- if .Values.mariadb.enabled }}
          value: {{ .Values.mariadb.db.name | quote }}
        {{- else }}
          value: {{ .Values.externalDatabase.database | quote }}
        {{- end }}
        - name: WORDPRESS_DATABASE_USER
        {{- if .Values.mariadb.enabled }}
          value: {{ .Values.mariadb.db.user | quote }}
        {{- else }}
          value: {{ .Values.externalDatabase.user | quote }}
        {{- end }}
        - name: WORDPRESS_DATABASE_PASSWORD
          valueFrom:
            secretKeyRef:
            {{- if .Values.mariadb.enabled }}
              name: {{ template "mariadb.fullname" . }}
              key: mariadb-password
            {{- else }}
              name: {{ printf "%s-%s" .Release.Name "externaldb" }}
              key: db-password
            {{- end }}
        - name: WORDPRESS_USERNAME
          value: {{ .Values.wordpressUsername | quote }}
        - name: WORDPRESS_PASSWORD
          valueFrom:
            secretKeyRef:
              name: {{ template "fullname" . }}
              key: wordpress-password
        - name: WORDPRESS_EMAIL
          value: {{ .Values.wordpressEmail | quote }}
        - name: WORDPRESS_FIRST_NAME
          value: {{ .Values.wordpressFirstName | quote }}
        - name: WORDPRESS_LAST_NAME
          value: {{ .Values.wordpressLastName | quote }}
        - name: WORDPRESS_BLOG_NAME
          value: {{ .Values.wordpressBlogName | quote }}
        - name: WORDPRESS_TABLE_PREFIX
          value: {{ .Values.wordpressTablePrefix | quote }}
        - name: SMTP_HOST
          value: {{ .Values.smtpHost | quote }}
        - name: SMTP_PORT
          value: {{ .Values.smtpPort | quote }}
        - name: SMTP_USER
          value: {{ .Values.smtpUser | quote }}
        - name: SMTP_PASSWORD
          valueFrom:
            secretKeyRef:
              name: {{ template "fullname" . }}
              key: smtp-password
        - name: SMTP_USERNAME
          value: {{ .Values.smtpUsername | quote }}
        - name: SMTP_PROTOCOL
          value: {{ .Values.smtpProtocol | quote }}
        ports:
        - name: http
          containerPort: 80
        - name: https
          containerPort: 443
        livenessProbe:
          httpGet:
            path: /wp-login.php
          {{- if not .Values.healthcheckHttps }}
            port: http
          {{- else }}
            port: https
            scheme: HTTPS
          {{- end }}
{{ toYaml .Values.livenessProbe | indent 10 }}
        readinessProbe:
          httpGet:
            path: /wp-login.php
          {{- if not .Values.healthcheckHttps }}
            port: http
          {{- else }}
            port: https
            scheme: HTTPS
          {{- end }}
{{ toYaml .Values.readinessProbe | indent 10 }}
        volumeMounts:
        - mountPath: /bitnami/apache
          name: wordpress-data
          subPath: apache
        - mountPath: /bitnami/wordpress
          name: wordpress-data
          subPath: wordpress
        - mountPath: /bitnami/php
          name: wordpress-data
          subPath: php
        resources:
{{ toYaml .Values.resources | indent 10 }}
      volumes:
      - name: wordpress-data
      {{- if .Values.persistence.enabled }}
        persistentVolumeClaim:
          claimName: {{ .Values.persistence.existingClaim | default (include "fullname" .) }}
      {{- else }}
        emptyDir: {}
      {{ end }}
    {{- if .Values.nodeSelector }}
      nodeSelector:
{{ toYaml .Values.nodeSelector | indent 8 }}
      {{- end -}}
    {{- with .Values.affinity }}
      affinity:
{{ toYaml . | indent 8 }}
    {{- end }}
    {{- with .Values.tolerations }}
      tolerations:
{{ toYaml . | indent 8 }}
    {{- end }}

Шаблонизация

Шаблоны: {{ }}

Значение контекста: .

Базовая структура Helm

• Поле .Values — для доступа к параметрам, которые определяются при инсталяции и обновлении релиза. К ним относятся значения опций --set, --set-string и --set-file, а также параметры файлов со значeниями, файл values.yaml и файлы, соответствующие значениям опций --values:
  
  

  containers:
  - name: main
    image: "{{ .Values.image }}:{{ .Values.imageTag }}"
    imagePullPolicy: {{ .Values.imagePullPolicy }}
  

• .Release — для использования данных релиза о выкате, инсталяции или обновлении, имени релиза, namespace и значений ещё нескольких полей, которые могут пригодиться при генерации манифестов:
  
  

  metadata:
    labels:
      heritage: "{{ .Release.Service }}"
      release: "{{ .Release.Name }}"
  subjects:
  - namespace: {{ .Release.Namespace }}
  

• .Chart — для доступа к информации о чарте. Поля соответствуют содержимому файла Chart.yaml:
  
  

  labels:
    chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
  

• Структура .Files — для работы с хранящимися в директории чарта файлами; со структурой и доступными методами можно ознакомиться по ссылке. Примеры:
  
  

  data:
    openssl.conf: |
  {{ .Files.Get "config/openssl.conf" | indent 4 }}
  

  
  

  data:
  {{ (.Files.Glob "files/docker-entrypoint-initdb.d/*").AsConfig | indent 2 }}
  

• .Capabilities — для доступа к информации о кластере, в котором выполняется выкат:
  
  

  {{- if .Capabilities.APIVersions.Has "apps/v1beta2" }}
  apiVersion: apps/v1beta2
  {{- else }}
  apiVersion: extensions/v1beta1
  {{- end }}
  

  
  

  {{- if semverCompare "^1.9-0" .Capabilities.KubeVersion.GitVersion }}
  apiVersion: apps/v1
  {{- else }}
  

Операторы

{{- if .Values.agent.image.tag }}
image: "{{ .Values.agent.image.repository }}:{{ .Values.agent.image.tag }}"
{{- else }}
image: "{{ .Values.agent.image.repository }}:v{{ .Chart.AppVersion }}"
{{- end }}

{{- range .Values.ports }}
- name: {{ .name }}
  port: {{ .containerPort }}
  targetPort: {{ .containerPort}}
{{- else }}
...
{{- end}}

{{ range .Values.tolerations -}}
- {{ toYaml . | indent 8 | trim }}
{{ end }}

{{- range $key, $value := .Values.credentials.secretContents }}
  {{ $key }}: {{ $value | b64enc | quote }}
{{- end }}

{{- with .config }}
  config:
  {{- with .region }}
    region: {{ . }}
  {{- end }}
  {{- with .s3ForcePathStyle }}
    s3ForcePathStyle: {{ . }}
  {{- end }}
  {{- with .s3Url }}
    s3Url: {{ . }}
  {{- end }}
  {{- with .kmsKeyId }}
    kmsKeyId: {{ . }}
  {{- end }}
{{- end }}

apiVersion: v1
kind: ServiceAccount
metadata:
  name: {{ template "kiam.serviceAccountName.agent" . }}
...
{{- define "kiam.serviceAccountName.agent" -}}
{{- if .Values.serviceAccounts.agent.create -}}
  {{ default (include "kiam.agent.fullname" .) .Values.serviceAccounts.agent.name }}
{{- else -}}
  {{ default "default" .Values.serviceAccounts.agent.name }}
{{- end -}}
{{- end -}}

• Объявленные partial'ы являются глобальными и могут использоваться во всех файлах директории templates.
• Основной чарт компилируется вместе с зависимыми чартами, поэтому при существовании двух одноимённых partial'ов будет использоваться последний загруженный. При именовании partial'а принято добавлять имя чарта для избежания подобных конфликтов: define "chart_name.partial_name".

Переменные: $

{{ $provider := .Values.configuration.backupStorageProvider.name }}
...
{{ if eq $provider "azure" }}
envFrom:
- secretRef:
    name: {{ template "ark.secretName" . }}
{{ end }}

context: {{ . }}
dollar: {{ $ }}
with: 
{{- with .Chart }}
  context: {{ . }}
  dollar: {{ $ }}
{{- end }}

template:
{{- template "flant" .Chart -}}

{{ define "flant" }}
  context: {{ . }}
  dollar: {{ $ }}
  with: 
  {{- with .Name }}
    context: {{ . }}
    dollar: {{ $ }}
  {{- end }}
{{- end -}}

context: #Базовая структура helm
dollar: #Базовая структура helm
with:
  context: #.Chart
  dollar: #Базовая структура helm

template:
  context: #.Chart
  dollar: #.Chart
  with:
    context: habr
    dollar: #.Chart

{{- if .Values.ingress.enabled -}}
{{- range .Values.ingress.hosts }}
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: {{ template "nats.fullname" $ }}-monitoring
  labels:
    app: "{{ template "nats.name" $ }}"
    chart: "{{ template "nats.chart" $ }}"
    release: {{ $.Release.Name | quote }}
    heritage: {{ $.Release.Service | quote }}
  annotations:
    {{- if .tls }}
    ingress.kubernetes.io/secure-backends: "true"
    {{- end }}
    {{- range $key, $value := .annotations }}
    {{ $key }}: {{ $value | quote }}
    {{- end }}
spec:
  rules:
    - host: {{ .name }}
      http:
        paths:
        - path: {{ default "/" .path }}
          backend:
            serviceName: {{ template "nats.fullname" $ }}-monitoring
            servicePort: monitoring
{{- if .tls }}
  tls:
  - hosts:
    - {{ .name }}
    secretName: {{ .tlsSecret }}
{{- end }}
---
{{- end }}
{{- end }}

Отступы

• {{- variable }} обрезает предшествующие пробелы;
• {{ variable -}} обрезает последующие пробелы;
• {{- variable -}} — оба варианта.

habr
{{- " flant " -}}
helm

Встроенные функции

definitions.json: |
    {
      "users": [
        {
          "name": "{{ index .Values "rabbitmq-ha" "rabbitmqUsername" }}",
          "password": "{{ index .Values "rabbitmq-ha" "rabbitmqPassword" }}",
          "tags": "administrator"
        }
      ]
    }

httpGet:
{{- if (index .Values "pushgateway" "extraArgs" "web.route-prefix") }}
  path: /{{ index .Values "pushgateway" "extraArgs" "web.route-prefix" }}/#/status
{{- end }}

{{ if and (index .Values field) (eq (len .Values.field) 10) }}
...
{{ end }}

{{ if index . field }}
  {{ if eq (len .field) 10 }}
  ...
  {{ end }}
{{ end }}

data:
  openssl.conf: |
{{ .Files.Get "config/openssl.conf" | indent 4 }}

data:
  db-password: {{ .Values.externalDatabase.password | b64enc | quote }}

Дополнительные функции

metadata:
  labels:
{{ include "labels.standard" . | indent 4 }}

{{- define "labels.standard" -}}
app: {{ include "hlf-couchdb.name" . }}
heritage: {{ .Release.Service | quote }}
release: {{ .Release.Name | quote }}
chart: {{ include "hlf-couchdb.chart" . }}
{{- end -}}

sftp-user: {{ required "Please specify the SFTP user name at .Values.sftp.user" .Values.sftp.user | b64enc | quote }}
sftp-password: {{ required "Please specify the SFTP user password at .Values.sftp.password" .Values.sftp.password | b64enc | quote }}
{{- end }}
{{- if .Values.svn.enabled }}
svn-user: {{ required "Please specify the SVN user name at .Values.svn.user" .Values.svn.user | b64enc | quote }}
svn-password: {{ required "Please specify the SVN user password at .Values.svn.password" .Values.svn.password | b64enc | quote }}
{{- end }}
{{- if .Values.webdav.enabled }}
webdav-user: {{ required "Please specify the WebDAV user name at .Values.webdav.user" .Values.webdav.user | b64enc | quote }}
webdav-password: {{ required "Please specify the WebDAV user password at .Values.webdav.password" .Values.webdav.password | b64enc | quote }}
{{- end }}

containers:
{{- with .Values.keycloak.extraContainers }}
{{ tpl . $ | indent 2 }}
{{- end }}

keycloak:
  extraContainers: |
    - name: cloudsql-proxy
      image: gcr.io/cloudsql-docker/gce-proxy:1.11
      command:
        - /cloud_sql_proxy
      args:
        - -instances={{ .Values.cloudsql.project }}:{{ .Values.cloudsql.region }}:{{ .Values.cloudsql.instance }}=tcp:5432
        - -credential_file=/secrets/cloudsql/credentials.json
      volumeMounts:
        - name: cloudsql-creds
          mountPath: /secrets/cloudsql
          readOnly: true

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ template "mysqldump.fullname" . }}
  labels:
    app: {{ template "mysqldump.name" . }}
    chart: {{ template "mysqldump.chart" . }}
    release: "{{ .Release.Name }}"
    heritage: "{{ .Release.Service }}"
spec:
  backoffLimit: 1
  template:
{{ $file := .Files.Get "files/job.tpl" }}
{{ tpl $file . | indent 4 }}

spec:
  containers:
  - name: xtrabackup
    image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
    imagePullPolicy: {{ .Values.image.pullPolicy | quote }}
    command: ["/bin/bash", "/scripts/backup.sh"]
    envFrom:
    - configMapRef:
        name: "{{ template "mysqldump.fullname" . }}"
    - secretRef:
        name: "{{ template "mysqldump.fullname" . }}"
    volumeMounts:
    - name: backups
      mountPath: /backup
    - name: xtrabackup-script
      mountPath: /scripts
  restartPolicy: Never
  volumes:
  - name: backups
{{- if .Values.persistentVolumeClaim }}
    persistentVolumeClaim:
      claimName: {{ .Values.persistentVolumeClaim }}
{{- else -}}
{{- if .Values.persistence.enabled }}
    persistentVolumeClaim:
      claimName: {{ template "mysqldump.fullname" . }}
{{- else }}
    emptyDir: {}
{{- end }}
{{- end }}
  - name: xtrabackup-script
    configMap:
      name: {{ template "mysqldump.fullname" . }}-script

Заключение

• Руководство разработчика чартов;
• Лучшие практики;
• Документация Go-шаблонизатора;
• Документация библиотеки Sprig;
• Официальный репозиторий чартов (как база знаний и реализованных лучших практик).

P.S.

• «Практическое знакомство с пакетным менеджером для Kubernetes — Helm»;
• «Пакетный менеджер для Kubernetes — Helm: прошлое, настоящее, будущее»;
• «Практика с dapp. Часть 2. Деплой Docker-образов в Kubernetes с помощью Helm»;
• «Сборка и дeплой приложений в Kubernetes с помощью dapp и GitLab CI»;
• «Лучшие практики CI/CD с Kubernetes и GitLab» (обзор и видео доклада).