Charts

attention

This page has not yet been updated for Helm 4. Some of the content might be inaccurate or not applicable to Helm 4. For more information about the Helm 4 new features, improvements, and breaking changes, see Helm 4 Overview.

Helm utilise un format d'empaquetage appelé charts. Un chart est une collection de fichiers décrivant un ensemble cohérent de ressources Kubernetes. Un chart peut servir à déployer quelque chose de simple, comme un pod memcached, ou quelque chose de complexe, comme une pile applicative web complète avec serveurs HTTP, bases de données, caches, etc.

Les charts sont créés sous forme de fichiers organisés dans une arborescence de répertoires particulière. Ils peuvent être empaquetés dans des archives versionnées pour être déployés.

Si vous souhaitez télécharger et examiner les fichiers d'un chart publié sans l'installer, vous pouvez le faire avec helm pull chartrepo/chartname.

Ce document explique le format des charts et fournit des conseils de base pour créer des charts avec Helm.

Structure des fichiers d'un chart

Un chart est organisé comme une collection de fichiers dans un répertoire. Le nom du répertoire est le nom du chart (sans information de version). Ainsi, un chart décrivant WordPress serait stocké dans un répertoire wordpress/.

À l'intérieur de ce répertoire, Helm s'attend à une structure correspondant à ceci :

wordpress/
  Chart.yaml          # A YAML file containing information about the chart
  LICENSE             # OPTIONAL: A plain text file containing the license for the chart
  README.md           # OPTIONAL: A human-readable README file
  values.yaml         # The default configuration values for this chart
  values.schema.json  # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file
  charts/             # A directory containing any charts upon which this chart depends.
  crds/               # Custom Resource Definitions
  templates/          # A directory of templates that, when combined with values,
                      # will generate valid Kubernetes manifest files.
  templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes

Helm réserve l'utilisation des répertoires charts/, crds/ et templates/, ainsi que des noms de fichiers listés ci-dessus. Les autres fichiers sont laissés tels quels.

Le fichier Chart.yaml

Le fichier Chart.yaml est obligatoire pour un chart. Il contient les champs suivants :

apiVersion: The chart API version (required)
name: The name of the chart (required)
version: The version of the chart (required)
kubeVersion: A SemVer range of compatible Kubernetes versions (optional)
description: A single-sentence description of this project (optional)
type: The type of the chart (optional)
keywords:
  - A list of keywords about this project (optional)
home: The URL of this projects home page (optional)
sources:
  - A list of URLs to source code for this project (optional)
dependencies: # A list of the chart requirements (optional)
  - name: The name of the chart (nginx)
    version: The version of the chart ("1.2.3")
    repository: (optional) The repository URL ("https://example.com/charts") or alias ("@repo-name")
    condition: (optional) A yaml path that resolves to a boolean, used for enabling/disabling charts (e.g. subchart1.enabled )
    tags: # (optional)
      - Tags can be used to group charts for enabling/disabling together
    import-values: # (optional)
      - ImportValues holds the mapping of source values to parent key to be imported. Each item can be a string or pair of child/parent sublist items.
    alias: (optional) Alias to be used for the chart. Useful when you have to add the same chart multiple times
maintainers: # (optional)
  - name: The maintainers name (required for each maintainer)
    email: The maintainers email (optional for each maintainer)
    url: A URL for the maintainer (optional for each maintainer)
icon: A URL to an SVG or PNG image to be used as an icon (optional).
appVersion: The version of the app that this contains (optional). Needn't be SemVer. Quotes recommended.
deprecated: Whether this chart is deprecated (optional, boolean)
annotations:
  example: A list of annotations keyed by name (optional).

Depuis la v3.3.2, les champs supplémentaires ne sont plus autorisés. L'approche recommandée est d'ajouter des métadonnées personnalisées dans annotations.

Charts et gestion des versions

Chaque chart doit avoir un numéro de version. Une version doit suivre le standard SemVer 2, mais ce n'est pas strictement imposé. Contrairement à Helm Classic, Helm v2 et les versions ultérieures utilisent les numéros de version comme marqueurs de release. Les paquets dans les dépôts sont identifiés par leur nom et leur version.

Par exemple, un chart nginx dont le champ version vaut version: 1.2.3 sera nommé :

nginx-1.2.3.tgz

Des noms SemVer 2 plus complexes sont également pris en charge, comme version: 1.2.3-alpha.1+ef365. Cependant, les noms non-SemVer sont explicitement interdits par le système. Sont toutefois acceptés les formats de version x ou x.y. Par exemple, s'il y a un v initial ou une version listée sans les 3 parties (par ex. v1.2), Helm tentera de la convertir en une version sémantique valide (par ex. v1.2.0).

Remarque : alors que Helm Classic et Deployment Manager étaient très orientés GitHub en ce qui concerne les charts, Helm v2 et les versions ultérieures ne dépendent pas de GitHub, ni même de Git. Par conséquent, les SHA Git ne sont pas du tout utilisés pour la gestion des versions.

Le champ version dans le fichier Chart.yaml est utilisé par de nombreux outils Helm, y compris la CLI. Lors de la génération d'un paquet, la commande helm package utilisera la version trouvée dans le Chart.yaml comme élément du nom du paquet. Le système suppose que le numéro de version dans le nom du paquet de chart correspond au numéro de version dans le Chart.yaml. Le non-respect de cette hypothèse provoquera une erreur.

Le champ apiVersion

Le champ apiVersion doit être v2 pour les charts Helm nécessitant au moins Helm 3. Les charts prenant en charge les versions précédentes de Helm ont un apiVersion défini à v1 et restent installables par Helm 3.

Changements de v1 à v2 :

• Un champ dependencies définissant les dépendances du chart, qui étaient situées dans un fichier séparé requirements.yaml pour les charts v1 (voir Dépendances des charts).
• Le champ type, distinguant les charts d'application et les charts de type library (voir Types de charts).

Le champ appVersion

Notez que le champ appVersion n'est pas lié au champ version. C'est un moyen de spécifier la version de l'application. Par exemple, le chart drupal peut avoir un appVersion: "8.2.1", indiquant que la version de Drupal incluse dans le chart (par défaut) est 8.2.1. Ce champ est informatif et n'a aucun impact sur les calculs de version du chart. Il est fortement recommandé d'entourer la version de guillemets. Cela force l'analyseur YAML à traiter le numéro de version comme une chaîne. Ne pas utiliser de guillemets peut entraîner des problèmes d'analyse dans certains cas. Par exemple, YAML interprète 1.0 comme une valeur à virgule flottante, et un SHA de commit git comme 1234e10 comme une notation scientifique.

Depuis Helm v3.5.0, helm create entoure de guillemets la valeur par défaut de appVersion.

Le champ kubeVersion

Le champ optionnel kubeVersion peut définir des contraintes semver sur les versions de Kubernetes prises en charge. Helm validera les contraintes de version lors de l'installation du chart et échouera si le cluster exécute une version de Kubernetes non prise en charge.

Les contraintes de version peuvent comprendre des comparaisons AND séparées par des espaces comme :

>= 1.13.0 < 1.15.0

qui peuvent elles-mêmes être combinées avec l'opérateur OR || comme dans l'exemple suivant :

>= 1.13.0 < 1.14.0 || >= 1.14.1 < 1.15.0

Dans cet exemple, la version 1.14.0 est exclue, ce qui peut être utile si l'on sait qu'un bug de certaines versions empêche le chart de fonctionner correctement.

En plus des contraintes de version utilisant les opérateurs = != > < >= <=, les notations raccourcies suivantes sont prises en charge :

• plages avec tiret pour les intervalles fermés, où 1.1 - 2.3.4 équivaut à >= 1.1 <= 2.3.4.
• jokers x, X et *, où 1.2.x équivaut à >= 1.2.0 < 1.3.0.
• plages tilde (changements de version patch autorisés), où ~1.2.3 équivaut à >= 1.2.3 < 1.3.0.
• plages caret (changements de version mineure autorisés), où ^1.2.3 équivaut à >= 1.2.3 < 2.0.0.

Pour une explication détaillée des contraintes semver prises en charge, consultez Masterminds/semver.

Déprécier des charts

Lors de la gestion de charts dans un dépôt de charts, il est parfois nécessaire de déprécier un chart. Le champ optionnel deprecated dans Chart.yaml peut être utilisé pour marquer un chart comme déprécié. Si la dernière version d'un chart dans le dépôt est marquée comme dépréciée, alors le chart dans son ensemble est considéré comme déprécié. Le nom du chart peut être réutilisé ultérieurement en publiant une nouvelle version qui n'est pas marquée comme dépréciée. Le workflow pour déprécier des charts est :

1. Mettre à jour le Chart.yaml du chart pour le marquer comme déprécié, en incrémentant la version
2. Publier la nouvelle version du chart dans le dépôt de charts
3. Supprimer le chart du dépôt source (par ex. git)

Types de charts

Le champ type définit le type de chart. Il existe deux types : application et library. Application est le type par défaut et c'est le chart standard sur lequel on peut effectuer toutes les opérations. Le chart de type library fournit des utilitaires ou des fonctions pour les auteurs de charts. Un chart de type library diffère d'un chart d'application car il n'est pas installable et ne contient généralement pas d'objets ressources.

Remarque : un chart d'application peut être utilisé comme chart de type library. Cela s'active en définissant le type à library. Le chart sera alors rendu comme un chart de type library où tous les utilitaires et fonctions peuvent être exploités. Aucun objet ressource du chart n'est rendu.

LICENSE, README et NOTES d'un chart

Les charts peuvent également contenir des fichiers décrivant l'installation, la configuration, l'utilisation et la licence d'un chart.

Une LICENSE est un fichier texte brut contenant la licence du chart. Le chart peut contenir une licence car il peut avoir une logique de programmation dans les templates et ne serait donc pas uniquement de la configuration. Il peut également y avoir des licences séparées pour l'application installée par le chart, si nécessaire.

Un README pour un chart doit être formaté en Markdown (README.md), et devrait généralement contenir :

• Une description de l'application ou du service fourni par le chart
• Tout prérequis ou exigence pour exécuter le chart
• Des descriptions des options dans values.yaml et des valeurs par défaut
• Toute autre information pertinente pour l'installation ou la configuration du chart

Lorsque les hubs et autres interfaces utilisateur affichent les détails d'un chart, ces informations sont extraites du contenu du fichier README.md.

Le chart peut également contenir un court fichier texte templates/NOTES.txt qui s'affiche après l'installation et lorsqu'on consulte l'état d'une release. Ce fichier est évalué comme un template, et peut être utilisé pour afficher des notes d'utilisation, les prochaines étapes, ou toute autre information pertinente pour une release du chart. Par exemple, des instructions pourraient être fournies pour se connecter à une base de données ou accéder à une interface web. Comme ce fichier est affiché sur STDOUT lors de l'exécution de helm install ou helm status, il est recommandé de garder le contenu bref et de pointer vers le README pour plus de détails.

Dépendances des charts

Dans Helm, un chart peut dépendre d'un nombre quelconque d'autres charts. Ces dépendances peuvent être liées dynamiquement en utilisant le champ dependencies dans Chart.yaml ou placées dans le répertoire charts/ et gérées manuellement.

Gérer les dépendances avec le champ dependencies

Les charts requis par le chart actuel sont définis comme une liste dans le champ dependencies.

dependencies:
  - name: apache
    version: 1.2.3
    repository: https://example.com/charts
  - name: mysql
    version: 3.2.1
    repository: https://another.example.com/charts

• Le champ name est le nom du chart souhaité.
• Le champ version est la version du chart souhaitée.
• Le champ repository est l'URL complète du dépôt de charts. Notez que vous devez également utiliser helm repo add pour ajouter ce dépôt localement.
• Vous pouvez utiliser le nom du dépôt au lieu de l'URL

$ helm repo add fantastic-charts https://charts.helm.sh/incubator

dependencies:
  - name: awesomeness
    version: 1.0.0
    repository: "@fantastic-charts"

Une fois les dépendances définies, vous pouvez exécuter helm dependency update qui utilisera votre fichier de dépendances pour télécharger tous les charts spécifiés dans votre répertoire charts/.

$ helm dep up foochart
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "local" chart repository
...Successfully got an update from the "stable" chart repository
...Successfully got an update from the "example" chart repository
...Successfully got an update from the "another" chart repository
Update Complete. Happy Helming!
Saving 2 charts
Downloading apache from repo https://example.com/charts
Downloading mysql from repo https://another.example.com/charts

Lorsque helm dependency update récupère les charts, il les stocke sous forme d'archives de charts dans le répertoire charts/. Ainsi, pour l'exemple ci-dessus, on s'attendrait à voir les fichiers suivants dans le répertoire charts :

charts/
  apache-1.2.3.tgz
  mysql-3.2.1.tgz

Champ alias dans les dépendances

En plus des autres champs ci-dessus, chaque entrée de dépendance peut contenir le champ optionnel alias.

Ajouter un alias pour un chart de dépendance place ce chart dans les dépendances en utilisant l'alias comme nom de la nouvelle dépendance.

On peut utiliser alias lorsqu'on a besoin d'accéder à un chart avec un ou plusieurs autres noms.

# parentchart/Chart.yaml

dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    alias: new-subchart-1
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    alias: new-subchart-2
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0

Dans l'exemple ci-dessus, nous obtiendrons 3 dépendances au total pour parentchart :

subchart
new-subchart-1
new-subchart-2

La méthode manuelle pour accomplir cela serait de copier/coller le même chart dans le répertoire charts/ plusieurs fois avec des noms différents.

Champs tags et condition dans les dépendances

En plus des autres champs ci-dessus, chaque entrée de dépendance peut contenir les champs optionnels tags et condition.

Tous les charts sont chargés par défaut. Si les champs tags ou condition sont présents, ils seront évalués et utilisés pour contrôler le chargement des charts auxquels ils s'appliquent.

Condition - Le champ condition contient un ou plusieurs chemins YAML (délimités par des virgules). Si ce chemin existe dans les valeurs du chart parent racine et se résout en une valeur booléenne, le chart sera activé ou désactivé en fonction de cette valeur booléenne. Seul le premier chemin valide trouvé dans la liste est évalué et si aucun chemin n'existe, la condition n'a aucun effet.

Tags - Le champ tags est une liste YAML de labels à associer à ce chart. Dans les valeurs du chart parent racine, tous les charts avec des tags peuvent être activés ou désactivés en spécifiant le tag et une valeur booléenne.

# parentchart/Chart.yaml

dependencies:
  - name: subchart1
    repository: http://localhost:10191
    version: 0.1.0
    condition: subchart1.enabled,global.subchart1.enabled
    tags:
      - front-end
      - subchart1
  - name: subchart2
    repository: http://localhost:10191
    version: 0.1.0
    condition: subchart2.enabled,global.subchart2.enabled
    tags:
      - back-end
      - subchart2

# parentchart/values.yaml

subchart1:
  enabled: true
tags:
  front-end: false
  back-end: true

Dans l'exemple ci-dessus, tous les charts avec le tag front-end seraient désactivés, mais comme le chemin subchart1.enabled s'évalue à true dans les valeurs du parent, la condition prendra le dessus sur le tag front-end et subchart1 sera activé.

Puisque subchart2 a le tag back-end et que ce tag s'évalue à true, subchart2 sera activé. Notez également que bien que subchart2 ait une condition spécifiée, il n'y a pas de chemin et de valeur correspondants dans les valeurs du parent, donc cette condition n'a aucun effet.

Utiliser la CLI avec les tags et conditions

Le paramètre --set peut être utilisé comme d'habitude pour modifier les valeurs des tags et conditions.

helm install --set tags.front-end=true --set subchart2.enabled=false

Résolution des tags et conditions

• Les conditions (quand elles sont définies dans les valeurs) prennent toujours le dessus sur les tags. Le premier chemin de condition qui existe l'emporte et les suivants pour ce chart sont ignorés.
• Les tags sont évalués comme « si l'un des tags du chart est vrai, alors activer le chart ».
• Les valeurs des tags et conditions doivent être définies dans les valeurs du chart parent racine.
• La clé tags: dans les valeurs doit être une clé de premier niveau. Les valeurs globales et les tables tags: imbriquées ne sont actuellement pas prises en charge.

Importer les valeurs des charts enfants via les dépendances

Dans certains cas, il est souhaitable de permettre aux valeurs d'un chart enfant de se propager au chart parent et d'être partagées comme valeurs par défaut communes. Un avantage supplémentaire de l'utilisation du format exports est qu'il permettra aux outils futurs d'inspecter les valeurs configurables par l'utilisateur.

Les clés contenant les valeurs à importer peuvent être spécifiées dans les dependencies du chart parent dans le champ import-values en utilisant une liste YAML. Chaque élément de la liste est une clé qui est importée depuis le champ exports du chart enfant.

Pour importer des valeurs non contenues dans la clé exports, utilisez le format child-parent. Des exemples des deux formats sont décrits ci-dessous.

Utiliser le format exports

Si le fichier values.yaml d'un chart enfant contient un champ exports à la racine, son contenu peut être importé directement dans les valeurs du parent en spécifiant les clés à importer comme dans l'exemple ci-dessous :

# parent's Chart.yaml file

dependencies:
  - name: subchart
    repository: http://localhost:10191
    version: 0.1.0
    import-values:
      - data

# child's values.yaml file

exports:
  data:
    myint: 99

Puisque nous spécifions la clé data dans notre liste d'import, Helm cherche dans le champ exports du chart enfant la clé data et importe son contenu.

Les valeurs finales du parent contiendront notre champ exporté :

# parent's values

myint: 99

Notez que la clé parente data n'est pas contenue dans les valeurs finales du parent. Si vous avez besoin de spécifier la clé parente, utilisez le format « child-parent ».

Utiliser le format child-parent

Pour accéder aux valeurs qui ne sont pas contenues dans la clé exports des valeurs du chart enfant, vous devrez spécifier la clé source des valeurs à importer (child) et le chemin de destination dans les valeurs du chart parent (parent).

Le champ import-values de l'exemple ci-dessous indique à Helm de prendre toutes les valeurs trouvées au chemin child: et de les copier vers les valeurs du parent au chemin spécifié dans parent:

# parent's Chart.yaml file

dependencies:
  - name: subchart1
    repository: http://localhost:10191
    version: 0.1.0
    ...
    import-values:
      - child: default.data
        parent: myimports

Dans l'exemple ci-dessus, les valeurs trouvées à default.data dans les valeurs de subchart1 seront importées à la clé myimports dans les valeurs du chart parent comme détaillé ci-dessous :

# parent's values.yaml file

myimports:
  myint: 0
  mybool: false
  mystring: "helm rocks!"

# subchart1's values.yaml file

default:
  data:
    myint: 999
    mybool: true

Les valeurs résultantes du chart parent seraient :

# parent's final values

myimports:
  myint: 999
  mybool: true
  mystring: "helm rocks!"

Les valeurs finales du parent contiennent maintenant les champs myint et mybool importés de subchart1.

Gérer les dépendances manuellement via le répertoire charts/

Pour mieux maîtriser les dépendances, vous pouvez les déclarer explicitement en copiant les charts de dépendance dans le répertoire charts/.

Une dépendance doit être un répertoire de chart non compressé mais son nom ne peut pas commencer par _ ou .. De tels fichiers sont ignorés par le chargeur de chart.

Par exemple, si le chart WordPress dépend du chart Apache, le chart Apache (de la bonne version) est fourni dans le répertoire charts/ du chart WordPress :

wordpress:
  Chart.yaml
  # ...
  charts/
    apache/
      Chart.yaml
      # ...
    mysql/
      Chart.yaml
      # ...

L'exemple ci-dessus montre comment le chart WordPress exprime sa dépendance envers Apache et MySQL en incluant ces charts dans son répertoire charts/.

CONSEIL : Pour placer une dépendance dans votre répertoire charts/, utilisez la commande helm pull

Aspects opérationnels de l'utilisation des dépendances

Les sections ci-dessus expliquent comment spécifier les dépendances de charts, mais comment cela affecte-t-il l'installation de charts avec helm install et helm upgrade ?

Supposons qu'un chart nommé « A » crée les objets Kubernetes suivants :

• namespace « A-Namespace »
• statefulset « A-StatefulSet »
• service « A-Service »

De plus, A dépend du chart B qui crée les objets :

• namespace « B-Namespace »
• replicaset « B-ReplicaSet »
• service « B-Service »

Après l'installation/mise à niveau du chart A, une seule release Helm est créée/modifiée. La release créera/mettra à jour tous les objets Kubernetes ci-dessus dans l'ordre suivant :

• A-Namespace
• B-Namespace
• A-Service
• B-Service
• B-ReplicaSet
• A-StatefulSet

En effet, lorsque Helm installe/met à niveau des charts, les objets Kubernetes provenant des charts et de toutes leurs dépendances sont :

• agrégés en un seul ensemble ; puis
• triés par type, puis par nom ; et ensuite
• créés/mis à jour dans cet ordre.

Par conséquent, une seule release est créée avec tous les objets du chart et de ses dépendances.

L'ordre d'installation des types Kubernetes est donné par l'énumération InstallOrder dans kind_sorter.go (voir le fichier source Helm).

Templates et valeurs

Les templates de charts Helm sont écrits dans le langage de template Go, avec l'ajout d'une cinquantaine de fonctions de template supplémentaires de la bibliothèque Sprig et quelques autres fonctions spécialisées.

Tous les fichiers de template sont stockés dans le dossier templates/ d'un chart. Lorsque Helm effectue le rendu des charts, il soumet chaque fichier de ce répertoire au moteur de template.

Les valeurs pour les templates sont fournies de deux manières :

• Les développeurs de charts peuvent fournir un fichier appelé values.yaml dans un chart. Ce fichier peut contenir des valeurs par défaut.
• Les utilisateurs de charts peuvent fournir un fichier YAML contenant des valeurs. Celui-ci peut être fourni en ligne de commande avec helm install.

Lorsqu'un utilisateur fournit des valeurs personnalisées, ces valeurs surchargeront les valeurs du fichier values.yaml du chart.

Fichiers de template

Les fichiers de template suivent les conventions standard pour écrire des templates Go (voir la documentation du package Go text/template pour les détails). Un exemple de fichier de template pourrait ressembler à ceci :

apiVersion: v1
kind: ReplicationController
metadata:
  name: deis-database
  namespace: deis
  labels:
    app.kubernetes.io/managed-by: deis
spec:
  replicas: 1
  selector:
    app.kubernetes.io/name: deis-database
  template:
    metadata:
      labels:
        app.kubernetes.io/name: deis-database
    spec:
      serviceAccount: deis-database
      containers:
        - name: deis-database
          image: {{ .Values.imageRegistry }}/postgres:{{ .Values.dockerTag }}
          imagePullPolicy: {{ .Values.pullPolicy }}
          ports:
            - containerPort: 5432
          env:
            - name: DATABASE_STORAGE
              value: {{ default "minio" .Values.storage }}

L'exemple ci-dessus, inspiré de https://github.com/deis/charts, est un template pour un contrôleur de réplication Kubernetes. Il peut utiliser les quatre valeurs de template suivantes (généralement définies dans un fichier values.yaml) :

• imageRegistry : le registre source pour l'image Docker.
• dockerTag : le tag pour l'image Docker.
• pullPolicy : la politique de pull Kubernetes.
• storage : le backend de stockage, dont la valeur par défaut est "minio"

Toutes ces valeurs sont définies par l'auteur du template. Helm n'exige ni ne dicte de paramètres.

Pour voir de nombreux charts fonctionnels, consultez l'Artifact Hub de la CNCF.

Valeurs prédéfinies

Les valeurs fournies via un fichier values.yaml (ou via l'option --set) sont accessibles depuis l'objet .Values dans un template. Mais il existe d'autres éléments de données prédéfinis auxquels vous pouvez accéder dans vos templates.

Les valeurs suivantes sont prédéfinies, disponibles pour chaque template, et ne peuvent pas être surchargées. Comme pour toutes les valeurs, les noms sont sensibles à la casse.

• Release.Name : le nom de la release (pas du chart)
• Release.Namespace : le namespace dans lequel le chart a été déployé.
• Release.Service : le service qui a effectué la release.
• Release.IsUpgrade : vaut true si l'opération actuelle est une mise à niveau ou une restauration (rollback).
• Release.IsInstall : vaut true si l'opération actuelle est une installation.
• Chart : le contenu du Chart.yaml. Ainsi, la version du chart est accessible via Chart.Version et les mainteneurs sont dans Chart.Maintainers.
• Files : un objet de type map contenant tous les fichiers non spéciaux du chart. Cela ne vous donne pas accès aux templates, mais vous permet d'accéder aux fichiers additionnels présents (sauf s'ils sont exclus via .helmignore). Les fichiers sont accessibles via {{ index .Files "file.name" }} ou via la fonction {{.Files.Get name }}. Vous pouvez également accéder au contenu du fichier sous forme de []byte avec {{ .Files.GetBytes }}
• Capabilities : un objet de type map contenant des informations sur les versions de Kubernetes ({{ .Capabilities.KubeVersion }}) et les versions d'API Kubernetes prises en charge ({{ .Capabilities.APIVersions.Has "batch/v1" }})

Remarque : tout champ inconnu du Chart.yaml est ignoré. Il ne sera pas accessible dans l'objet Chart. Ainsi, Chart.yaml ne peut pas être utilisé pour passer des données structurées arbitraires dans le template. Le fichier de valeurs peut être utilisé à cette fin.

Fichiers de valeurs

En considérant le template de la section précédente, un fichier values.yaml fournissant les valeurs nécessaires ressemblerait à ceci :

imageRegistry: "quay.io/deis"
dockerTag: "latest"
pullPolicy: "Always"
storage: "s3"

Un fichier de valeurs est formaté en YAML. Un chart peut inclure un fichier values.yaml par défaut. La commande helm install permet à un utilisateur de surcharger les valeurs en fournissant des valeurs YAML supplémentaires :

$ helm install --generate-name --values=myvals.yaml wordpress

Lorsque les valeurs sont passées de cette manière, elles seront fusionnées avec le fichier de valeurs par défaut. Par exemple, considérons un fichier myvals.yaml qui ressemble à ceci :

storage: "gcs"

Lorsque ceci est fusionné avec le values.yaml du chart, le contenu généré résultant sera :

imageRegistry: "quay.io/deis"
dockerTag: "latest"
pullPolicy: "Always"
storage: "gcs"

Notez que seul le dernier champ a été surchargé.

Remarque : le fichier de valeurs par défaut inclus dans un chart doit être nommé values.yaml. Mais les fichiers spécifiés en ligne de commande peuvent avoir n'importe quel nom.

Remarque : si l'option --set est utilisée avec helm install ou helm upgrade, ces valeurs sont simplement converties en YAML côté client.

Remarque : si des entrées obligatoires existent dans le fichier de valeurs, elles peuvent être déclarées comme requises dans le template du chart en utilisant la fonction « required ».

Toutes ces valeurs sont ensuite accessibles dans les templates via l'objet .Values :

apiVersion: v1
kind: ReplicationController
metadata:
  name: deis-database
  namespace: deis
  labels:
    app.kubernetes.io/managed-by: deis
spec:
  replicas: 1
  selector:
    app.kubernetes.io/name: deis-database
  template:
    metadata:
      labels:
        app.kubernetes.io/name: deis-database
    spec:
      serviceAccount: deis-database
      containers:
        - name: deis-database
          image: {{ .Values.imageRegistry }}/postgres:{{ .Values.dockerTag }}
          imagePullPolicy: {{ .Values.pullPolicy }}
          ports:
            - containerPort: 5432
          env:
            - name: DATABASE_STORAGE
              value: {{ default "minio" .Values.storage }}

Portée, dépendances et valeurs

Les fichiers de valeurs peuvent déclarer des valeurs pour le chart racine, ainsi que pour tous les charts inclus dans le répertoire charts/ de ce chart. Ou, formulé différemment, un fichier de valeurs peut fournir des valeurs au chart ainsi qu'à toutes ses dépendances. Par exemple, le chart WordPress de démonstration ci-dessus a mysql et apache comme dépendances. Le fichier de valeurs pourrait fournir des valeurs à tous ces composants :

title: "My WordPress Site" # Sent to the WordPress template

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

Les charts de niveau supérieur ont accès à toutes les variables définies en dessous. Ainsi, le chart WordPress peut accéder au mot de passe MySQL via .Values.mysql.password. Mais les charts de niveau inférieur ne peuvent pas accéder aux éléments des charts parents, donc MySQL ne pourra pas accéder à la propriété title. De même, il ne peut pas accéder à apache.port.

Les valeurs sont rangées par espace de noms, mais les préfixes d'espace de noms sont supprimés. Ainsi, le chart WordPress peut accéder au champ du mot de passe MySQL via .Values.mysql.password. Mais pour le chart MySQL, la portée des valeurs a été réduite et le préfixe d'espace de noms supprimé, donc il verra le champ password simplement comme .Values.password.

Valeurs globales

Depuis la version 2.0.0-Alpha.2, Helm prend en charge des valeurs « globales » spéciales. Considérons cette version modifiée de l'exemple précédent :

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  port: 8080 # Passed to Apache

Ceci ajoute une section global avec la valeur app: MyWordPress. Cette valeur est disponible pour tous les charts via .Values.global.app.

Par exemple, les templates mysql peuvent accéder à app via {{ .Values.global.app }}, tout comme le chart apache. Concrètement, le fichier de valeurs ci-dessus est régénéré comme ceci :

title: "My WordPress Site" # Sent to the WordPress template

global:
  app: MyWordPress

mysql:
  global:
    app: MyWordPress
  max_connections: 100 # Sent to MySQL
  password: "secret"

apache:
  global:
    app: MyWordPress
  port: 8080 # Passed to Apache

Cela fournit un moyen de partager une variable de premier niveau avec tous les sous-charts, ce qui est utile par exemple pour définir des propriétés metadata telles que les labels.

Si un sous-chart déclare une variable globale, cette variable globale est transmise vers le bas (aux sous-charts du sous-chart), mais pas vers le haut au chart parent. Il n'y a aucun moyen pour un sous-chart d'influencer les valeurs du chart parent.

De plus, les variables globales des charts parents ont la priorité sur les variables globales des sous-charts.

Fichiers de schéma

Parfois, un mainteneur de chart peut vouloir définir une structure pour ses valeurs. Cela peut être fait en définissant un schéma dans le fichier values.schema.json. Un schéma est représenté sous forme de JSON Schema. Il pourrait ressembler à ceci :

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "properties": {
    "image": {
      "description": "Container Image",
      "properties": {
        "repo": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": {
      "description": "Service name",
      "type": "string"
    },
    "port": {
      "description": "Port",
      "minimum": 0,
      "type": "integer"
    },
    "protocol": {
      "type": "string"
    }
  },
  "required": [
    "protocol",
    "port"
  ],
  "title": "Values",
  "type": "object"
}

Ce schéma sera appliqué aux valeurs pour les valider. La validation se produit lorsque l'une des commandes suivantes est invoquée :

• helm install
• helm upgrade
• helm lint
• helm template

Un exemple de fichier values.yaml qui répond aux exigences de ce schéma pourrait ressembler à ceci :

name: frontend
protocol: https
port: 443

Notez que le schéma est appliqué à l'objet .Values final, et pas seulement au fichier values.yaml. Cela signifie que le fichier yaml suivant est valide, à condition que le chart soit installé avec l'option --set appropriée montrée ci-dessous.

name: frontend
protocol: https

helm install --set port=443

De plus, l'objet .Values final est vérifié par rapport aux schémas de tous les sous-charts. Cela signifie que les restrictions d'un sous-chart ne peuvent pas être contournées par un chart parent. Cela fonctionne également dans l'autre sens : si un sous-chart a une exigence qui n'est pas satisfaite dans le fichier values.yaml du sous-chart, le chart parent doit satisfaire ces restrictions pour être valide.

La validation de schéma peut être désactivée avec l'option montrée ci-dessous. C'est particulièrement utile dans les environnements isolés lorsque le fichier JSON Schema d'un chart contient des références distantes.

helm install --skip-schema-validation

Références

En ce qui concerne l'écriture de templates, valeurs et fichiers de schéma, il existe plusieurs références standard qui vous aideront.

• Templates Go
• Fonctions de template supplémentaires
• Le format YAML
• JSON Schema

Custom Resource Definitions (CRD)

Kubernetes fournit un mécanisme pour déclarer de nouveaux types d'objets Kubernetes. En utilisant les CustomResourceDefinitions (CRD), les développeurs Kubernetes peuvent déclarer des types de ressources personnalisées.

Dans Helm 3, les CRD sont traitées comme un type spécial d'objet. Elles sont installées avant le reste du chart et sont soumises à certaines limitations.

Les fichiers YAML CRD doivent être placés dans le répertoire crds/ à l'intérieur d'un chart. Plusieurs CRD (séparées par des marqueurs de début et de fin YAML) peuvent être placées dans le même fichier. Helm tentera de charger tous les fichiers du répertoire CRD dans Kubernetes.

Les fichiers CRD ne peuvent pas contenir de directives de template. Ils doivent être des documents YAML bruts.

Lorsque Helm installe un nouveau chart, il envoie les CRD, attend que le serveur d'API les rende disponibles, puis démarre le moteur de template, effectue le rendu du reste du chart, et l'envoie à Kubernetes. En raison de cet ordre, les informations CRD sont disponibles dans l'objet .Capabilities des templates Helm, et les templates Helm peuvent créer de nouvelles instances d'objets qui ont été déclarés dans les CRD.

Par exemple, si votre chart contient une CRD pour CronTab dans le répertoire crds/, vous pouvez créer des instances du type CronTab dans le répertoire templates/ :

crontabs/
  Chart.yaml
  crds/
    crontab.yaml
  templates/
    mycrontab.yaml

Le fichier crontab.yaml doit contenir la CRD sans directives de template :

kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.com
  versions:
    - name: v1
      served: true
      storage: true
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab

Ensuite, le template mycrontab.yaml peut créer un nouveau CronTab (en utilisant les templates comme d'habitude) :

apiVersion: stable.example.com
kind: CronTab
metadata:
  name: {{ .Values.name }}
spec:
   # ...

Helm s'assurera que le type CronTab a été installé et est disponible depuis le serveur API Kubernetes avant de procéder à l'installation des éléments dans templates/.

Limitations des CRD

Contrairement à la plupart des objets dans Kubernetes, les CRD sont installées à l'échelle du cluster. Pour cette raison, Helm adopte une approche très prudente dans la gestion des CRD. Les CRD sont soumises aux limitations suivantes :

• Les CRD ne sont jamais réinstallées. Si Helm détermine que les CRD dans le répertoire crds/ sont déjà présentes (quelle que soit la version), Helm ne tentera pas de les installer ou de les mettre à niveau.
• Les CRD ne sont jamais installées lors d'une mise à niveau ou d'une restauration. Helm créera uniquement les CRD lors des opérations d'installation.
• Les CRD ne sont jamais supprimées. La suppression d'une CRD supprime automatiquement tout le contenu de la CRD dans tous les namespaces du cluster. Par conséquent, Helm ne supprimera pas les CRD.

Les administrateurs qui souhaitent mettre à niveau ou supprimer des CRD sont encouragés à le faire manuellement et avec beaucoup de précaution.

Utiliser Helm pour gérer les charts

L'outil helm dispose de plusieurs commandes pour travailler avec les charts.

Il peut créer un nouveau chart pour vous :

$ helm create mychart
Created mychart/

Une fois que vous avez modifié un chart, helm peut l'empaqueter dans une archive de chart pour vous :

$ helm package mychart
Archived mychart-0.1.-.tgz

Vous pouvez également utiliser helm pour vous aider à trouver des problèmes de formatage ou d'information dans votre chart :

$ helm lint mychart
No issues found

Dépôts de charts

Un dépôt de charts est un serveur HTTP qui héberge un ou plusieurs charts empaquetés. Bien que helm puisse être utilisé pour gérer des répertoires de charts locaux, quand il s'agit de partager des charts, la solution à privilégier est un dépôt de charts.

Tout serveur HTTP capable de servir des fichiers YAML et tar et de répondre aux requêtes GET peut être utilisé comme serveur de dépôt. L'équipe Helm a testé certains serveurs, notamment Google Cloud Storage avec le mode site web activé, et S3 avec le mode site web activé.

Un dépôt est caractérisé principalement par la présence d'un fichier spécial appelé index.yaml qui contient une liste de tous les paquets fournis par le dépôt, ainsi que des métadonnées permettant de récupérer et vérifier ces paquets.

Côté client, les dépôts sont gérés avec les commandes helm repo. Cependant, Helm ne fournit pas d'outils pour publier des charts sur des serveurs de dépôt distants. En effet, cela imposerait de lourdes exigences au serveur qui l'implémente et rendrait plus difficile la mise en place d'un dépôt.

Packs de démarrage de charts

La commande helm create accepte une option facultative --starter qui vous permet de spécifier un « chart de démarrage ». De plus, l'option --starter a un alias court -p.

Exemples d'utilisation :

helm create my-chart --starter starter-name
helm create my-chart -p starter-name
helm create my-chart -p /absolute/path/to/starter-name

Les charts de démarrage sont simplement des charts ordinaires, mais situés dans $XDG_DATA_HOME/helm/starters. En tant que développeur de chart, vous pouvez créer des charts spécifiquement conçus pour être utilisés comme charts de démarrage. Ces charts doivent être conçus avec les considérations suivantes en tête :

• Le Chart.yaml sera écrasé par le générateur.
• Les utilisateurs s'attendront à modifier le contenu d'un tel chart, donc la documentation devrait indiquer comment les utilisateurs peuvent le faire.
• Toutes les occurrences de <CHARTNAME> seront remplacées par le nom de chart spécifié afin que les charts de démarrage puissent être utilisés comme templates, sauf pour certains fichiers de variables. Par exemple, si vous utilisez des fichiers personnalisés dans le répertoire vars ou certains fichiers README.md, <CHARTNAME> ne sera PAS remplacé à l'intérieur de ceux-ci. De plus, la description du chart n'est pas héritée.

Actuellement, la seule façon d'ajouter un chart à $XDG_DATA_HOME/helm/starters est de le copier manuellement. Dans la documentation de votre chart, vous voudrez peut-être expliquer ce processus.