Kustomize で Kubernetes を構成する

Kustomize は、元のファイルを変更せずに、テンプレート化されていない YAML ファイルをカスタマイズできる Kubernetes 構成変換ツールです。Kustomize では、他の表現から ConfigMap や Secret などのリソースを生成することもできます。Kustomize は Kubernetes API 用に作成されているため、Kubernetes スタイルのオブジェクトを認識して変更できます。

Config Sync で Helm チャートを使用する場合、Kustomize で Helm をレンダリングする方法と Helm API を使用する方法の 2 つがサポートされています。このページでは、Kustomize を介して Helm チャートをレンダリングするための要件について詳しく説明します。Helm API の使用の詳細については、Artifact Registry から Helm チャートを同期するをご覧ください。

Kustomize を使用して Helm チャートをレンダリングする場合は、次の点が異なります。

  • 限定公開 Helm レジストリと OCI ベース Helm レジストリはサポートされません。Helm API では、限定公開レジストリと OCI ベース レジストリが両方ともサポートされます。
  • Helm の値は信頼できる情報源で管理できます。Helm API を使用する場合、値は RootSync API または RepoSync API の一環として管理されます。
  • RootSync オブジェクトまたは RepoSync オブジェクトで複数の Helm チャートをレンダリングできます。Helm API を使用する場合は、RootSync オブジェクトまたは RepoSync オブジェクトでレンダリングできる Helm チャートは 1 つだけです。

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 構成のアーキテクチャの例

このディレクトリには、同じベースを参照する 4 つのオーバーレイ（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 ジェネレータによる、4 つのオーバーレイへの参照が含まれています。

# ./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 チャートのフィールド

Kustomize による Helm チャートのレンダリングをサポートするには、次の Helm チャート フィールドを kustomization.yaml ファイルに追加します。

フィールド 説明
helmGlobals すべての Helm チャートに適用されるパラメータ
helmGlobals.chartHome 文字列で記述します。Kustomization に含める各チャートのサブディレクトリを含むディレクトリのパス（Kustomization のルートからの相対パス）。このフィールドのデフォルト値は charts です。
helmGlobals.configHome 文字列で記述します。Kustomize が HELM_CONFIG_HOME 環境変数で Helm に渡す値を定義します。Kustomize では、このディレクトリの読み取りや書き込みは試行されません。省略した場合は TMP_DIR/helm が使用されます。ここで、TMP_DIR は Kustomize for Helm によって作成される一時ディレクトリです。
helmCharts Helm チャート パラメータの配列
helmCharts.name 文字列で記述します。チャートの名前。この欄は必須です。
helmCharts.version 文字列で記述します。チャートのバージョン
helmCharts.repo 文字列で記述します。チャートの検索に使用される URL
helmCharts.releaseName 文字列で記述します。チャート テンプレート出力の RELEASE_NAME を置き換えます。
helmCharts.namespace 文字列で記述します。リリースのターゲット名前空間を設定します（テンプレート内の Release.Namespace）
helmCharts.valuesInline チャートに付随するデフォルト値の代わりに使用する値
helmCharts.valuesFile 文字列で記述します。ValuesFile は、チャートのデフォルト値の代わりに使用する値ファイルへのローカルパスまたはリモート URL です。デフォルト値は CHART_HOME/NAME/values.yaml にあります。
helmCharts.valuesMerge merge、override、(default) または replace を指定します。ValuesMerge には、Values に関する ValuesInline の処理方法を指定します。
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 など）から pull して、ローカルで変更を行い、信頼できる情報源の変更をリポジトリに push できます。

次の図にディレクトリ構造を示します。

├── 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 では、チャートがリモートかローカルかに関係なく、1 つの 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
...

次のステップ