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.yaml
、kustomization.yml
或Kustomization
)。如果根目錄沒有 Kustomization 設定檔,Config Sync 會直接同步處理設定,不會進行任何算繪作業。 - 在
kustomization.yaml
檔案中加入設定。如果未加入這些設定檔,設定就不會同步至叢集。 - 在 Config Sync 1.19.0 之前,所有設定都必須納入 Kustomization 根目錄。從 1.19.0 版開始,Config Sync 支援根目錄以外的檔案。
算繪 Kustomize 設定
以下範例說明如何設定單一事實來源,以便使用 Kustomize 設定自動算繪。
Kustomize 設定的架構範例
這個目錄包含四個疊加層 (team-a
、team-b
、team-c
和 external-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
|
可接受 merge 、override 、(default) 或 replace 。ValuesMerge 會指定如何處理 ValuesInline (相對於 Values)。 |
helmCharts.includeCRDs
|
接受 true 或 false 。指定 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
...