Helmあるから別にいいかーと避けていたkustomize、仕事で触れる機会があったのでごくごく簡単にまとめ。

※ Kustomizeの用途でよくあるbaseとoverlayを使った環境(dev/stg/prd)ごとのパラメタセットの切り替えは本エントリではまだ扱いません

基本
使ってみる
- kustomization.yamlの作成
- デプロイの確認と実行
Kustomizeによるマニフェストの書き換え
kustomizeコマンド
- インストール
- 使い方
環境

基本

かじった程度だけど、つかんだ感触としては以下の特徴。(個人の感想)

kustomizeの定義ファイルはkustomization.yaml
既存の静的なマニフェストファイルに対して、kustomization.yamlで定義した内容にしたがってパラメタを上書きする
- Helmなどはパラメタ化したい箇所を変数参照する書式にするが、kustomizeではその必要はない
Helmのようにパブリックなアプリケーションのリポジトリは多分なさそう
- 小・中規模向け、あるいはアプリ開発者が自分のソースリポジトリに含めるような形での提供
kubectlコマンドに内蔵してるので追加コマンド等のインストール不要ですぐに使える

という感じで、小規模なシステムやプロジェクトで、マニフェストファイルのパラメタ化を行いたいときは結構ハマると思う。
ポイントは元のマニフェストファイルを変更することなく特定の値をカスタムするという点で、雰囲気としては「既存のマニフェストファイルに対して値を変更するフィルタをかます」という動作が近いかも。(多分)

使ってみる

kustomization.yamlの作成

最低限必要な記述は、kustomization.yamlが処理する対象マニフェストファイルのパス。
ファイルのパスはkustomization.yamlがある場所からの相対パスで記述できる。

kustomization.yamlファイルのある場所にmanifestディレクトリを作り、その配下にsample-app.yamlファイルとsample-db.yamlファイルがある場合は以下のようになる。

resources:
- manifest/sample-app.yaml
- manifest/sample-db.yaml

また、ファイルシステム上にあるマニフェストファイルだけでなく、リポジトリ上にkustomization.yamlファイルがあればGitのリモートリポジトリの指定も可能。
その場合は以下のような書式。(リポジトリ上のファイル構成については本エントリでは扱わない)
詳細についてはresourcesのページと、そこからリンクされているhashicorp URL formatを参照。

resources:
- github.com/kubernetes-sigs/kustomize/examples/helloWorld?ref=v3.3.1

github.com

デプロイの確認と実行

クラスタへリソースをデプロイするにはapplyサブコマンドで-kオプションを使用する。実行するコマンド例は以下。

kubectl apply -k <kustomization.yamlのあるディレクトリパス>

クラスタへのリソースのデプロイでなく、Kustomizeによって変化する最終的なマニフェストの内容を確認するには、サブコマンドkustomizeを使用する。実行するコマンド例は以下。

kubectl kustomize <kustomization.yamlのあるディレクトリパス>

Kustomizeによるマニフェストの書き換え

全部を紹介はできないので、利用頻度が高そうで簡単なものを紹介

サンプルとして以下の何もしないwebサーバーをデプロイするだけのマニフェストを使用。

github.com

curl -LO https://raw.githubusercontent.com/zaki-lknr/k8s-samples/master/sample-web/httpd-loadbalancer-namespace/sample-http.yaml

ゲットしたら同じディレクトリにkustomization.yamlを作成する。

resources:
- sample-http.yaml

イメージのタグを変更

提供されているマニフェストに記載されているイメージのタグを変更したい場合。デフォルトではイメージの最新バージョンがタグとして使用されているが、1世代前のバージョンを使用したいなど。
元のマニフェストファイルを変更することなく、kustomization.yamlの記述で変更ができる。

サンプルではhttpdイメージのタグの指定がない(＝latest)ので、2.4を指定するように定義してみる。
その場合のkustomization.yamlの内容は以下。

resources:
- sample-http.yaml

images:
- name: httpd
  newTag: "2.4"

nameにはタグを上書きする対象を探すために、マニフェストで指定してあるイメージ(image)を指定する(nameでなく…サンプルはどちらもhttpdでわかりにくいけど)。
newTagに上書きしたいタグ名を指定する。注意点として文字列型で指定しなければならないため、タグ名が数字とドットのみのバージョン番号形式の場合はクォートも必要。

イメージのURL変更

ユースケースとしては、公開されているマニフェストファイルはDocker Hubにあるパブリックなイメージを使用するようになっているが、運用ではカスタムビルドしたものをプライベートにあるコンテナレジストリに配置して利用したい、みたいな場合。

サンプルでは単にhttpdと記述しておりDockerHubからpullしてくる動作になっているが、これを例としてQuay.ioのhttpdイメージをpullするよう変更してみる。
その場合のkustomization.yamlの内容は以下。

resources:
- sample-http.yaml

images:
- name: httpd
  newName: quay.io/fedora/httpd-24:2.4

イメージのURL変更も、タグと同様imagesフィールドを使用。nameで対象を指定し、書き換えるURLをnewNameに指定する。

ネームスペースの指定

マニフェストにはネームスペースを明記せず、kubectl applyで適用する際に-n <namespace name>で指定するパターンは多いと思うが、kustomization.yamlにデプロイするネームスペースを指定することができる。

またこの際、指定したネームスペースが存在しない場合はエラーになるが、ネームスペースを作成するマニフェストも含めている場合は、作成するネームスペースもデプロイするネームスペースも全てKustomizeで上書きできる。

resources:
- sample-http.yaml

namespace: myapps

各リソース定義のmetadata.namespaceおよび、kind: Namespaceのmetadata.nameのネームスペースが、namespaceフィールドに指定したネームスペース名に書き変わってデプロイされる。

レプリカ数の指定

Deploymentのマニフェストで指定されているPodのレプリカ数をkustomization.yamlで上書き設定できる。

resources:
- sample-http.yaml

replicas:
- name: sample-http
  count: 1

nameに対象のリソースを指定し、レプリカ数をcountで指定する。対象リソースはimageフィールドのコンテナイメージではなく、Deploymentなどのリソース名を指定する。
確認してないけどReplicaSetやStatefulSetにも使用可能。

kustomizeコマンド

kubectlコマンド内蔵のKustomizeでなく、単体のバイナリをインストールして実行もできる。kubectlのアップデートでKustomizeのバージョンも変更されるとCIなどで都合が悪い場合など、バージョンを固定したい場合に利用できる。

kubectl 組み込みは勝手にバージョンが上がるのでたまに大きな変更がある kustomize では困ることがありますね。CI みたいな壊れると業務が止まって困るところだと、任意のバージョンが使えるバイナリ版がいいなと思ってます。
— すぱぶら (Kazuki Suda) (@superbrothers) 2022年10月24日

なお、以前は「kubectl内蔵のkustomizeはバージョンが古い」という時期があったが、現在は最新バージョンが内蔵されるようになっているので、カジュアルに使いたいレベルであれば、kustomizeコマンドを別途入れなくても良い。

kustomize が改善されて、毎マイナーリリースでだいたいそのときの最新まで追従されるようになってます。
— すぱぶら (Kazuki Suda) (@superbrothers) 2022年10月24日

インストール

kustomizeコマンドのインストールはいくつか方法はあるが、素の環境であればバイナリインストールが一番簡単。

kubectl.docs.kubernetes.io

curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"  | bash

実行するとカレントディレクトリに実行ファイルが配置されるので、必要に応じて/usr/local/bin辺りに置く。

ちなみに現バージョンではドキュメントにもある通りARMアーキテクチャのOSだとこのスクリプトは正しく動作しないので、kustomizeのリリースページからバイナリを直接ダウンロードする。

This script doesn’t work for ARM architecture. If you want to install ARM binaries, please go to the release page to find the URL.

もしくはスクリプトをダウンロードして、archを判定しているロジックに

aarch64)
    arch=arm64
    ;;

を付け足しても動く。
(uname -mの結果がaarch64の場合の判定が無いため、デフォルトのamd64として動作している)

バージョンを指定してインストールする場合は、引数にインストールしたいバージョンを指定する。
間違いが無いのはインストールスクリプトを一度ダウンロードして実行すると良い。

./install_kustomize.sh 4.5.5

curlで取得したスクリプトを直接実行する場合は、プロセス置換を使って以下のように実行すればインストールできる。

[zaki@cloud-dev2 tmp]$ bash <(curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh") 4.5.5
{Version:kustomize/v4.5.5 GitCommit:daa3e5e2c2d3a4b8c94021a7384bfb06734bcd26 BuildDate:2022-05-20T20:25:40Z GoOs:linux GoArch:amd64}
kustomize installed to /home/zaki/local/tmp/kustomize

使い方

kustomizeコマンドはマニフェストの値を書き換えるフィルタ機能に限定している(クラスタへのリソース作成は具備していない)ため、標準出力へのリソース書き換え結果をkubectl apply -fへリダイレクトして使用する。

値の確認

kubectl kustomize <dir>に相当するのは以下。

kustomize build <dir>

リソースのデプロイ

kubectl apply -k <dir>に相当するのは以下。

kustomize build <dir> | apply -f -

その他

他にもkustomization.yamlのスケルトンを出力するkustomize createなどいくつかのサブコマンドがある。
詳細はヘルプ参照。