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 Rendern 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 Helm-Diagramme mit Kustomize rendern:

• Private und OCI-basierte Helm-Registries werden nicht unterstützt. Mit der Helm API werden sowohl private als auch OCI-basierte Registries unterstützt.
• Helm-Werte können in der Source of Truth verwaltet werden. Mit der Helm API werden Werte als Teil der RootSync- oder RepoSync API verwaltet.
• Das Rendern mehrerer Helm-Diagramme in einem RootSync- oder RepoSync-Objekt wird unterstützt. Mit der Helm API können Sie nur ein Helm-Diagramm in einem RootSync- oder RepoSync-Objekt 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.

Hinweis: Config Sync unterstützt keine Remotebasisdaten aus privaten „Source of Truth“-Quellen. Sie können Remotebasisdateine während des Renderings aus öffentlichen "Sources of Truth" abrufen, wenn Sie spec.override.enableShellInRendering auf true festlegen. Dies wird jedoch aufgrund von Sicherheitsrisiken nicht empfohlen.

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

configMapGenerator:
- name: my-configmap
  namespace: my-namespace
  files:
    - ../external-data.txt

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: [e-mail]
- 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 Sie Helm-Diagramme über Kustomize rendern. Unter Gebündelte Helm- und Kustomize-Versionen finden Sie die Kustomize- und Helm-Versionen, die mit der entsprechenden Version von Config Sync gebündelt sind.

Wichtiger Begriff Helm ist ein Paketmanager für Kubernetes, mit dem Sie Anwendungen definieren, installieren und upgraden können. Config Sync kann Helm-Diagramme mithilfe der Helm API direkt aus Artifact Registry synchronisieren oder Helm-Diagramme rendern, die in Kustomize-Konfigurationen angegeben sind.

Helm-Diagrammfelder

Sie können Ihren kustomization.yaml-Dateien die folgenden Helm-Diagrammfelder hinzufügen, um das Rendern 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:
  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

• Config Sync mit Kustomize und Helm verwenden
• Config Sync in mehreren Umgebungen mit automatisiertem Rendering verwenden