透過 Kustomize 設定 Kubernetes

Kustomize 是 Kubernetes 設定轉換工具,可讓您自訂未套用範本的 YAML 檔案,且不會修改原始檔案。Kustomize 也可以從其他表示法產生資源,例如 ConfigMap 和 Secret。Kustomize 是為 Kubernetes API 而建構,因此可以瞭解及修改 Kubernetes 樣式的物件。

如要搭配使用 Helm 資訊圖表與 Config Sync,有兩種支援的方法:透過 Kustomize 算繪 Helm,或使用 Helm API。本頁詳細說明透過 Kustomize 轉譯 Helm 圖表的需求。如要進一步瞭解如何使用 Helm API,請參閱「從 Artifact Registry 同步處理 Helm chart」。

使用 Kustomize 轉譯 Helm 圖表時,適用下列差異:

  • 系統不支援私人和 OCI 型 Helm 登錄檔。Helm API 支援私有和 OCI 型登錄檔。
  • 您可以在真實資訊來源中管理 Helm 值。透過 Helm API,系統會將值視為 RootSync 或 RepoSync API 的一部分進行管理。
  • RootSync 或 RepoSync 物件支援算繪多個 Helm 圖表。透過 Helm API,您可以在 RootSync 或 RepoSync 物件中只算繪一個 Helm 資訊圖表。

Kustomize 的 Config Sync 需求

如要自動轉譯 Kustomize 設定和 Helm 圖表,請確認 Config Sync 環境符合下列需求:

  • 使用非結構化可靠資料來源。 系統不支援自動算繪階層式來源
  • 如要觸發算繪程序,單一事實來源的目錄根層級必須有 Kustomization 設定檔 (kustomization.yamlkustomization.ymlKustomization)。如果根目錄沒有 Kustomization 設定檔,Config Sync 會直接同步處理設定,不會進行任何算繪作業。
  • kustomization.yaml 檔案中加入設定。如果未加入這些設定檔,設定就不會同步至叢集。
  • 在 Config Sync 1.19.0 之前,所有設定都必須納入 Kustomization 根目錄。從 1.19.0 版開始,Config Sync 支援根目錄以外的檔案。

算繪 Kustomize 設定

以下範例說明如何設定單一事實來源,以便使用 Kustomize 設定自動算繪。

Kustomize 設定的架構範例

這個目錄包含四個疊加層 (team-ateam-bteam-cexternal-team),這些疊加層參照相同的基底,以及 ConfigMap 產生器使用的檔案。

下圖顯示目錄結構:

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

下列 kustomization.yaml 檔案位於可靠來源的根目錄中,並包含四個疊加層的參照,以及來自本機檔案的 ConfigMap 產生器:

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

下列 kustomize.yaml 位於 team-a 目錄中,是 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

下列 kustomization.yaml 位於 base 目錄中,是 Kustomize 基礎:

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

您可以在 GitHub 的「configuring namespace-specific policies」目錄中,探索範例存放區。

透過 Kustomize 轉譯 Helm 圖表

本節說明如何透過 Kustomize 算繪 Helm 資訊圖表。隨附的 Helm 和 Kustomize 版本:列出與對應 Config Sync 版本隨附的 Kustomize 和 Helm 版本。

Helm 資訊套件欄位

您可以在 kustomization.yaml 檔案中新增下列 Helm 資訊套件欄位,透過 Kustomize 支援算繪 Helm 資訊套件:

欄位 說明
helmGlobals 套用至所有 Helm 資訊套件的參數
helmGlobals.chartHome 接受字串。路徑 (相對於 Kustomization 根目錄),指向包含每個圖表子目錄的目錄,這些圖表會納入 Kustomization。這個欄位的預設值為 charts
helmGlobals.configHome 接受字串。定義 Kustomize 應透過 HELM_CONFIG_HOME 環境變數傳遞給 Helm 的值。Kustomize 不會嘗試讀取或寫入這個目錄。如果省略,系統會使用 TMP_DIR/helm,其中 TMP_DIR 是 Kustomize 為 Helm 建立的暫時目錄。
helmCharts Helm 資訊套件參數的陣列
helmCharts.name 接受字串。圖表的名稱。這是必填欄位。
helmCharts.version 接受字串。圖表版本
helmCharts.repo 接受字串。用於尋找圖表的網址
helmCharts.releaseName 接受字串。取代圖表範本輸出中的 RELEASE_NAME
helmCharts.namespace 接受字串。設定版本的目標命名空間 (範本中的 .Release.Namespace)
helmCharts.valuesInline 要使用的值 (而非圖表隨附的預設值)
helmCharts.valuesFile 接受字串。ValuesFile 是本機路徑或遠端網址,指向要使用的值檔案,而非圖表隨附的預設值。預設值位於 CHART_HOME/NAME/values.yaml
helmCharts.valuesMerge 可接受 mergeoverride(default)replace。ValuesMerge 會指定如何處理 ValuesInline (相對於 Values)。
helmCharts.includeCRDs 接受 truefalse。指定 Helm 是否也應產生 CustomResourceDefinitions。預設值為 false

轉譯遠端 Helm 資訊套件

Config Sync 支援在可公開存取網際網路的叢集上,算繪遠端 Helm 範本。

下列 kustomization.yaml 會透過設定以下 helmCharts 欄位,算繪遠端 cert-manager

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

轉譯本機 Helm 資訊套件

Config Sync 支援算繪本機 Helm 範本。如要使用自訂版本的 Helm 圖表,可以從 Helm 圖表 (例如 ArtifactHub) 提取發布版本,在本機進行變更,然後將變更推送至真理來源。

下圖顯示目錄結構:

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

下列 kustomization.yaml 會算繪本機 cert-manager 圖表。Helm 圖表的預設目錄為 charts,由於這個圖表已簽入 charts 目錄,因此您不需要指定 .helmCharts.repo.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
...

轉譯多個 Helm 資訊套件

Config Sync 支援在一個 kustomization.yaml 檔案中算繪多個 Helm 資訊套件,無論資訊套件是遠端或本機都適用。

下列 kustomization.yaml 會轉譯本機 Helm 資訊套件 (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
...

後續步驟