Kubernetes mit Kustomize konfigurieren

Kustomize ist ein Kubernetes-Konfigurationstransformationstool, mit dem Sie nicht vorlagenbasierte YAML-Dateien anpassen und die ursprünglichen Dateien unverändert lassen können. Kustomize kann auch Ressourcen wie ConfigMaps und Secrets aus anderen Darstellungen generieren. Kustomize wurde für die Kubernetes API entwickelt, sodass es Kubernetes-ähnliche Objekte verstehen und ändern kann.

Wenn Sie Helm-Diagramme mit Config Sync verwenden möchten, gibt es zwei unterstützte Methoden: Helm über Kustomize rendern oder die Helm API verwenden. Auf dieser Seite werden die Anforderungen für das Rendering von Helm-Diagrammen über Kustomize beschrieben. Weitere Informationen zur Verwendung der Helm API finden Sie unter Helm-Diagramme aus Artifact Registry synchronisieren.

Die folgenden Unterschiede gelten, wenn Sie Kustomize zum Rendern von Helm-Diagrammen verwenden:

  • Private und OCI-basierte Helm-Registrys werden nicht unterstützt. Mit der Helm API werden sowohl private als auch OCI-basierte Registrys unterstützt.
  • Helm-Werte können in der "Source of Truth" verwaltet werden. Mit der Helm API werden Werte im Rahmen der RootSync- oder RepoSync API verwaltet.
  • Das Rendering mehrerer Helm-Diagramme in einem RootSync- oder RepoSync-Objekt wird unterstützt. Mit der Helm API können Sie in einem RootSync- oder RepoSync-Objekt nur ein Helm-Diagramm rendern.

Config Sync-Anforderungen für Kustomize

Achten Sie darauf, dass Ihre Config Sync-Umgebung die folgenden Anforderungen erfüllt, um Kustomize-Konfigurationen und Helm-Diagramme automatisch zu rendern:

  • Verwendet eine unstrukturierte "Source of Truth". Für hierarchische Quellen wird das automatische Rendering nicht unterstützt.
  • Zum Auslösen des Renderingprozesses muss Ihre Source of Truth eine Kustomization-Konfigurationsdatei (kustomization.yaml, kustomization.yml oder Kustomization) im Stammverzeichnis von Ihr Verzeichnis haben. Wenn das Stammverzeichnis keine Kustomization-Konfigurationsdatei hat, synchronisiert Config Sync die Konfigurationen unverändert, ohne dass ein Rendering erfolgt.
  • Fügen Sie Ihre Konfigurationen in die Datei kustomization.yaml ein. Wenn Sie diese Konfigurationsdateien nicht angeben, werden die Konfigurationen nicht mit dem Cluster synchronisiert.
  • Bei Versionen vor Config Sync 1.19.0 müssen alle Konfigurationen im Kustomization-Stammverzeichnis enthalten sein. Ab Version 1.19.0 unterstützt Config Sync Dateien außerhalb des Stammverzeichnisses.

Kustomize-Konfigurationen rendern

Das folgende Beispiel zeigt, wie Sie Ihre „Source of Truth“ so einrichten können, dass Kustomize-Konfigurationen mit automatischem Rendering verwendet werden.

Beispielarchitektur für Kustomize-Konfigurationen

Dieses Verzeichnis enthält vier Overlays (team-a, team-b, team-c und external-team), die auf dieselbe Basis verweisen, und eine Datei, die vom ConfigMap-Generator verwendet wird.

Das folgende Diagramm zeigt die Verzeichnisstruktur:

├── 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

Die folgende kustomization.yaml-Datei befindet sich im Stamm der Source of Truth und enthält Verweise auf die vier Overlays mit einem ConfigMap-Generator aus einer lokalen Datei:

# ./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.

Der folgende kustomize.yaml-Datei befindet sich im Verzeichnis team-a und ist das Overlay für 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: team-a-admin@mydomain.com
- target:
   kind: Namespace
   name: default
  patch: |-
    - op: replace
      path: /metadata/name
      value: team-a

Die folgende kustomization.yaml-Datei befindet sich im Verzeichnis base und ist die Kustomize-Basis:

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

Sie können sich ein Beispiel-Repository im Verzeichnis Namespace-spezifische Richtlinien konfigurieren auf GitHub ansehen.

Helm-Diagramme über Kustomize rendern

In diesem Abschnitt wird erläutert, wie Helm-Diagramme über Kustomize gerendert werden. Gebündelte Helm- und Kustomize-Versionen listet die Kustomize- und Helm-Versionen auf, die mit der entsprechenden Version von Config Sync gebündelt sind.

Helm-Diagrammfelder

Sie können Ihren kustomization.yaml-Dateien die folgenden Helm-Diagrammfelder hinzufügen, um das Rendering von Helm-Diagrammen über Kustomize zu unterstützen:

Feld Beschreibung
helmGlobals Parameter, die auf alle Helm-Diagramme angewendet werden
helmGlobals.chartHome Akzeptiert einen String. Ein Dateipfad relativ zum Kustomization-Stammverzeichnis, zu einem Verzeichnis, das ein Unterverzeichnis für jedes Diagramm enthält, das in Kustomization aufgenommen werden soll. Der Standardwert dieses Felds ist charts.
helmGlobals.configHome Akzeptiert einen String. Definiert einen Wert, den Kustomize mit der Umgebungsvariable HELM_CONFIG_HOME an Helm übergibt. Kustomize versucht nicht, dieses Verzeichnis zu lesen oder darin zu schreiben. Wenn keine Angabe gemacht wird, wird TMP_DIR/helm verwendet, wobei TMP_DIR ein temporäres Verzeichnis ist, das von Kustomize für Helm erstellt wurde.
helmCharts Ein Array mit Helm-Diagrammparametern
helmCharts.name Akzeptiert einen String. Der Name des Diagramms. Dies ist ein Pflichtfeld.
helmCharts.version Akzeptiert einen String. Die Version des Diagramms
helmCharts.repo Akzeptiert einen String. URL, die zum Suchen des Diagramms verwendet wird
helmCharts.releaseName Akzeptiert einen String. Ersetzt RELEASE_NAME in der Ausgabe der Diagrammvorlage
helmCharts.namespace Akzeptiert einen String. Legt den Ziel-Namespace für einen Release fest (Release.Namespace in der Vorlage)
helmCharts.valuesInline Anstelle der Standardwerte des Diagramms zu verwendende Werte
helmCharts.valuesFile Akzeptiert einen String. „ValuesFile“ ist ein lokaler Dateipfad oder eine Remote-URL zu einer Wertedatei, die anstelle der Standardwerte verwendet werden soll, die im Diagramm enthalten waren. Die Standardwerte befinden sich in CHART_HOME/NAME/values.yaml.
helmCharts.valuesMerge Akzeptiert merge, override, (default) oder replace. „ValueMerge“ gibt an, wie „ValuesInline“ in Bezug auf Werte behandelt wird.
helmCharts.includeCRDs Akzeptiert true oder false. Gibt an, ob Helm auch CustomResourceDefinitions generieren soll. Der Standardwert ist false.

Remote-Helm-Diagramm rendern

Config Sync unterstützt das Rendering von Remote-Helm-Diagrammen in Clustern mit öffentlichem Internetzugriff.

Mit der folgenden kustomization.yaml-Datei wird ein Remote-cert-manager durch Festlegen der folgenden helmCharts-Felder gerendert:

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

Lokales Helm-Diagramm rendern

Config Sync unterstützt das Rendering lokaler Helm-Diagramme. Um eine benutzerdefinierte Version eines Helm-Diagramms zu verwenden, können Sie die veröffentlichte Version aus dem Helm-Diagramm (z. B. ArtifactHub) abrufen, Änderungen lokal vornehmen und dann per Push übertragen an Ihre "Source of Truth".

Das folgende Diagramm zeigt die Verzeichnisstruktur:

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

Mit der folgenden kustomization.yaml-Datei wird ein lokales cert-manager-Diagramm gerendert. Das Standardverzeichnis für Helm-Diagramme ist charts. Da dieses Diagramm in das Verzeichnis charts eingecheckt wird, müssen Sie nicht .helmCharts.repo oder .helmCharts.version angeben.

# ./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
...

Mehrere Helm-Diagramme rendern

Config Sync unterstützt das Rendering mehrerer Helm-Diagramme in einer kustomization.yaml-Datei, unabhängig davon, ob es sich um ein Remote- oder lokales Diagramm handelt.

Mit der folgenden kustomization.yaml-Datei wird ein lokales Helm-Diagramm (cert-manager) gerendert:

# ./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
...

Nächste Schritte