Configurer Kubernetes avec Kustomize

Kustomize est un outil de transformation de configuration Kubernetes qui vous permet de personnaliser les fichiers YAML non modélisés, en laissant les fichiers d'origine intacts. Kustomize peut également générer des ressources telles que des ConfigMaps et des Secrets à partir d'autres représentations. Kustomize est conçu pour l'API Kubernetes, afin de pouvoir comprendre et modifier les objets de style Kubernetes.

Si vous souhaitez utiliser des charts Helm avec Config Sync, vous disposez de deux méthodes : le rendu de Helm via Kustomize ou l'utilisation de l'API Helm. Cette page détaille les conditions requises pour le rendu des graphiques Helm via Kustomize. Pour en savoir plus sur l'utilisation de l'API Helm, consultez la page Synchroniser des charts Helm à partir d'Artifact Registry.

Les différences suivantes s'appliquent lors de l'utilisation de Kustomize pour le rendu des charts Helm :

  • Les registres Helm privés et basés sur OCI ne sont pas acceptés. Avec l'API Helm, les registres privés et basés sur l'OCI sont tous deux compatibles.
  • Les valeurs Helm peuvent être gérées dans la source de vérité. Avec l'API Helm, les valeurs sont gérées dans le cadre de l'API RootSync ou RepoSync.
  • Le rendu de plusieurs graphiques Helm dans un objet RootSync ou RepoSync est possible. Avec l'API Helm, vous ne pouvez afficher qu'un seul graphique Helm dans un objet RootSync ou RepoSync.

Exigences concernant Config Sync pour Kustomize

Pour afficher automatiquement les configurations Kustomize et les charts Helm, assurez-vous que votre environnement Config Sync répond aux exigences suivantes :

  • Utilise une source de vérité non structurée. L'affichage automatique n'est pas compatible avec les dépôts hiérarchiques.
  • Pour déclencher le processus de rendu, votre source de vérité doit comporter un fichier de configuration Kustomize (kustomization.yaml, kustomization.yml ou Kustomization) à la racine de votre répertoire. Si le répertoire racine ne possède pas de fichier de configuration Kustomization, Config Sync synchronise les configurations telles quelles sans aucun rendu.
  • Incluez vos configurations dans le fichier kustomization.yaml. Si vous n'incluez pas ces fichiers de configuration, les configurations ne sont pas synchronisées avec le cluster.
  • Avant Config Sync 1.19.0, toutes les configurations doivent être incluses dans le répertoire racine de Kustomization. À partir de la version 1.19.0, Config Sync accepte les fichiers en dehors du répertoire racine.

Rendre les configurations Kustomize

L'exemple suivant montre comment configurer votre source de vérité pour utiliser les configurations Kustomize avec le rendu automatique.

Exemple d'architecture pour les configurations Kustomize

Ce répertoire comprend quatre superpositions (team-a, team-b, team-c et external-team) qui référencent la même base, ainsi qu'un fichier utilisé par le générateur ConfigMap.

Le schéma suivant montre la structure des répertoires :

├── example
│   ├── base
│   │   ├── kustomization.yaml
│   │   ├── namespace.yaml
│   │   ├── networkpolicy.yaml
│   │   ├── rolebinding.yaml
│   │   └── role.yaml
│   ├── kustomization.yaml
│   ├── README.md
│   ├── team-a
│   │   └── kustomization.yaml
│   ├── team-b
│   │   └── kustomization.yaml
│   └── team-c
│       └── kustomization.yaml
├── external-team
│   └── kustomization.yaml
└── external-data.txt

Le fichier kustomization.yaml suivant se trouve à la racine de la source fiable et contient des références aux quatre superpositions avec un générateur ConfigMap à partir d'un fichier local:

# ./example/kustomization.yaml
resources:
- team-a
- team-b
- team-c
- ../external-team # Starting from 1.19.0, Config Sync allows external resources located outside of the Kustomization root directory.

configMapGenerator:
- name: my-configmap
  namespace: my-namespace
  files:
    - ../external-data.txt # Starting from 1.19.0, Config Sync allows external files located outside of the Kustomization root directory.

Le fichier kustomize.yaml suivant se trouve dans le répertoire team-a et est la superposition de team-a :

# ./example/team-a/kustomization.yaml
namespace: team-a

resources:
- ../base

patches:
- target:
   kind: RoleBinding
   name: team-admin-rolebinding
  patch: |-
    - op: replace
      path: /subjects/0/name
      value: [email protected]
- target:
   kind: Namespace
   name: default
  patch: |-
    - op: replace
      path: /metadata/name
      value: team-a

Le fichier kustomization.yaml suivant se trouve dans le répertoire base et est la base Kustomize :

# ./example/base/kustomization.yaml
resources:
- namespace.yaml
- rolebinding.yaml
- role.yaml
- networkpolicy.yaml

Vous pouvez explorer un exemple de dépôt dans le répertoire Configurer des règles spécifiques à un espace de noms de GitHub.

Afficher des charts Helm via Kustomize

Cette section explique comment afficher des graphiques Helm via Kustomize. Les versions groupées de Helm et Kustomize listent les versions de Kustomize et Helm groupées avec la version correspondante de Config Sync.

Champs du chart Helm

Vous pouvez ajouter les champs de chart Helm suivants à vos fichiers kustomization.yaml pour permettre le rendu des charts Helm via Kustomize :

Champ Description
helmGlobals Paramètres appliqués à tous les charts Helm
helmGlobals.chartHome Accepte une chaîne. Un chemin d'accès, en rapport à la racine Kustomization, vers un répertoire contenant un sous-répertoire pour chaque chart à inclure dans Kustomization. La valeur par défaut de ce champ est charts.
helmGlobals.configHome Accepte une chaîne. Définit une valeur que Kustomize doit transmettre à Helm avec la variable d'environnement HELM_CONFIG_HOME. Kustomize ne tente pas de lire ou d'écrire ce répertoire. En cas d'omission, TMP_DIR/helm est utilisé, où TMP_DIR est un répertoire temporaire créé par Kustomize pour Helm.
helmCharts Un tableau de paramètres de chart Helm
helmCharts.name Accepte une chaîne. Le nom du chart. Ce champ est obligatoire.
helmCharts.version Accepte une chaîne. La version du chart
helmCharts.repo Accepte une chaîne. L'URL utilisée pour localiser le chart
helmCharts.releaseName Accepte une chaîne. Remplace RELEASE_NAME dans le résultat du modèle de chart
helmCharts.namespace Accepte une chaîne. Définit l'espace de noms cible pour une version (.Release.Namespace dans le modèle)
helmCharts.valuesInline Valeurs à utiliser à la place des valeurs par défaut qui accompagnent le chart
helmCharts.valuesFile Accepte une chaîne. ValuesFile est un chemin d'accès local ou une URL distante vers un fichier de valeurs à utiliser à la place des valeurs par défaut qui accompagnent le chart. Les valeurs par défaut sont dans CHART_HOME/NAME/values.yaml.
helmCharts.valuesMerge Accepte merge, override, (default), ou replace. ValuesMerge spécifie comment traiter ValuesInline par rapport à Values.
helmCharts.includeCRDs Accepte true ou false. Spécifie si Helm doit également générer CustomResourceDefinitions. La valeur par défaut est false.

Effectuer le rendu d'un chart Helm distant

Config Sync est compatible avec le rendu des charts Helm distants sur les clusters disposant d'un accès Internet public.

Le kustomization.yaml suivant effectue le rendu d'un cert-manager distant en définissant les champs helmCharts suivants :

# ./kustomization.yaml
...
helmCharts:
- name: cert-manager
  repo: https://charts.jetstack.io
  version: v1.5.3
  releaseName: my-cert-manager
  namespace: cert-manager
...

Effectuer le rendu d'un chart Helm local

Config Sync est compatible avec le rendu des charts Helm locaux. Pour utiliser une version personnalisée d'un chart Helm, vous pouvez extraire la version publiée depuis le chart Helm (par exemple, ArtifactHub), effectuer les modifications localement, puis transférer les modifications vers votre source fiable.

Le schéma suivant montre la structure des répertoires :

├── base
│   ├── charts
│   │   └── cert-manager
│   └── kustomization.yaml
├── overlays
│   └── stage
│       └── kustomization.yaml
└── base_value_overrides.yaml

Le kustomization.yaml suivant effectue le rendu d'un chart cert-manager local. Le répertoire par défaut des charts Helm est charts, et comme ce chart est vérifié dans le répertoire charts, vous n'avez pas besoin de spécifier .helmCharts.repo ou .helmCharts.version.

# ./overlays/stage/kustomization.yaml
...
# This field is optional if your Helm charts are located in the default 'charts' directory.
helmGlobals:
  # Starting from 1.19.0, Config Sync allows loading from an external directory outside of the Kustomization root.
  chartHome: ../../base/charts
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
  # Specify a local path or a remote URL to a values file instead of using the default values in CHART_HOME/NAME/values.yaml.
  valuesFile: ../../base_value_overrides.yaml
...

Effectuer le rendu de plusieurs charts Helm

Config Sync accepte le rendu de plusieurs charts Helm dans un fichier kustomization.yaml, que le chart soit distant ou local.

Le kustomization.yaml suivant effectue le rendu d'un chart Helm local (cert-manager) :

# ./kustomization.yaml
...
helmCharts:
- name: cert-manager
  releaseName: my-cert-manager
  namespace: cert-manager
- name: prometheus
  repo: https://prometheus-community.github.io/helm-charts
  version: 14.3.0
  releaseName: my-prometheus
  namespace: monitoring
...

Étapes suivantes