こんにちは、松浦です。
シナジーマーケティングでは Kubernetes のマニフェスト管理については kustomize を主に利用しています。今回は、 kustomize にまつわる内容を扱います。
kustomize には、 kustomize build 時にリソース定義の生成を行う generator (ConfigMapGenerator, SecretGenerator)や、変換処理などを行う transformer (コンテナイメージ名やタグを変える images やラベルを各リソースに付与する commonLabels など)が用意されています。デフォルトの状態でも十分に使い勝手の良いものですが、ときに generator や transformer の振る舞いに変更を加えたり、新たに処理を追加したいこともあるかもしれません。そのような場合にどういう手段が用意されているのかをまとめてみました。
前提
以下の内容は kustomize v3.0.3 をもとにしたものとなっています。今後のリリースにより変更が加えられる可能性があります。
どのような手段があるのか
はじめに、現状でどのような手段が用意されているのかを列挙しておきます。
- v1.0.9 より、 Generator Options, Transformer Configurations が導入されています。これにより、デフォルトで用意されている generator や transformer の振る舞いを部分的に変更することが可能になりました。
- v2.1.0 より、プラグインの仕組みが導入されました。これにより、generator や transformer を自作できるようになりました（ただし v3.0.3 段階ではまだアルファ版なので今後の仕様変更などに注意が必要です）。
基本的には、Generator Options や Transformer Configurations を使うことで対応できないかを検討し、要求を満たせない場合はプラグインを作成する、という形になります。
では、それぞれの詳細に触れていきましょう。
Generator Options
概要
kustomize には、リソースを生成する generator として ConfigMapGenerator と SecretGenerator が用意されています。この2つの generator の振る舞いを一部変更するオプションが v1.0.9 から提供されるようになりました。オプションの内容としては、以下のようになっています。
- 生成されるリソースの name に対してハッシュ値が付与されないようにする
- 生成されるリソースに対して label を付与する
- 生成されるリソースに対して annotation を付与する
デモ
では、実際に試してみて、挙動を確認しましょう。
ConfigMapGenerator で ConfigMap を生成する kustomization.yaml をまず準備します。
|
1 2 3 4 5 |
configMapGenerator: - name: sample-configmap literals: - abc=def - ghi=jkl |
この状態で kustomize build を実行すると、以下のような内容の ConfigMap が生成されます。
|
1 2 3 4 5 6 7 8 |
$ kustomize build apiVersion: v1 data: abc: def ghi: jkl kind: ConfigMap metadata: name: sample-configmap-f44h7fd6b9 |
では、Generator Options を付与してみましょう。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
configMapGenerator: - name: sample-configmap literals: - abc=def - ghi=jkl generatorOptions: disableNameSuffixHash: true labels: hoge: fuga annotations: foo: bar |
付与した状態で kustomize build を実行すると、以下のように、 name にハッシュ値が付与されず、 label, annotation が付与されていることが分かります。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
$ kustomize build apiVersion: v1 data: abc: def ghi: jkl kind: ConfigMap metadata: annotations: foo: bar labels: hoge: fuga name: sample-configmap |
Transformer Configurations
概要
kustomize は、前述の通りデフォルトでいくつかの transformer を提供しています。
v1.0.9 から、 transformer の適用範囲を（ある程度の）変更・追加ができるようになりました。使い方としては、以下のような YAML を記述し、
|
1 2 3 4 5 6 7 8 9 |
# 挙動を調整したい transformer を記述します commonLabels: # 例として、以下は特定の CRD の指定したフィールドに commonLabels に指定した label を追加する設定になっています # create: true の場合、指定したパスにフィールドがない場合には作成する動きをします - group: sample.techscore.com version: v1 kind: SampleCRD path: spec/template/metadata/labels create: true |
kustomization.yaml に設定を追加します。
|
1 2 |
configurations: - configuration.yaml |
ちなみに、 kustomize のデフォルトの設定は kustomize config save コマンドで取得できます。
デモ
では、挙動を確認してみましょう。
分かりやすさ重視で、（実用性はそれほどありませんが）namePrefix の振る舞いを変更してみます。
まずは、Deployment と Service を定義した resources.yaml を用意します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
apiVersion: apps/v1 kind: Deployment metadata: name: nginx spec: replicas: 1 template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx ports: - containerPort: 80 --- apiVersion: v1 kind: Service metadata: name: nginx spec: selector: app: nginx ports: - name: http protocol: TCP port: 80 targetPort: 80 |
次に、 namePrefix を設定した kustomization.yaml を用意します。
|
1 2 3 4 |
resources: - resources.yaml namePrefix: test- |
この状態で kustomize build を実行すると、以下のように、Deployment, Service ともに metadata.name に 'test-' のプレフィックスが付与されています。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
$ kustomize build apiVersion: v1 kind: Service metadata: name: test-nginx spec: ports: - name: http port: 80 protocol: TCP targetPort: 80 selector: app: nginx --- apiVersion: apps/v1 kind: Deployment metadata: name: test-nginx spec: replicas: 1 template: metadata: labels: app: nginx spec: containers: - image: nginx name: nginx ports: - containerPort: 80 |
では、 nameprefix.yaml という名前のファイルを用意し、namePrefix の挙動を変えてみましょう。
Deployment の PodSpec の name にもプレフィックスが付与されるようにしてみます。
|
1 2 3 |
namePrefix: - path: spec/template/spec/containers/name kind: Deployment |
作成した YAML を kustomization.yaml に設定します。
|
1 2 3 4 5 6 7 |
resources: - resources.yaml configurations: - nameprefix.yaml nameprefix: test- |
kustomize build で出力される YAML を見ると、Deployment の PodSpec の name にもプレフィックスが付与されていることが分かります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
$ kustomize build apiVersion: v1 kind: Service metadata: name: test-nginx spec: ports: - name: http port: 80 protocol: TCP targetPort: 80 selector: app: nginx --- apiVersion: apps/v1 kind: Deployment metadata: name: test-nginx spec: replicas: 1 template: metadata: labels: app: nginx spec: containers: - image: nginx name: test-nginx ports: - containerPort: 80 |
kustomize プラグイン
現状、 Exec plugin と Go plugin の 2種類のプラグインがあります。 Exec plugin は、引数を受け取れる、実行可能なファイルを用いたプラグインで、 Go plugin は、文字通り Golang で記述したプラグインです。
今回は Exec plugin をもとに（実用性は度外視した）簡単な generator のプラグインの作成を通じて詳細を見ていきます。
設定ファイル作成
まずはプラグインの設定ファイルを作成します。プラグインの配置場所に関わる設定があるので、まずここから定義するとスムーズに進められると思います。
ということで、 sampleGenerator.yaml という名前で、以下のようなファイルを作成します。
|
1 2 3 4 5 6 7 |
apiVersion: sample.techscore.com/v1 kind: SampleGenerator metadata: name: anything argsOneLiner: val1 val2 # 引数を改行区切りで記述したファイルも指定できる # argsFromFile: someArgs.txt |
apiVersion, kind はプラグインの配置場所や名前に関係してきますので、必須になります。Kubernetes リソースの定義形式に則っている都合上、metadata.name も必要になります（特に使っていないようなので何でも良いです）。
プラグインに渡す引数は、 argsOneLiner と argsFromFile で定義できます。 argsOneLiner は半角スペース区切りで引数を記述します。 argsFromFile は引数を改行区切りで記述したファイルを指定します。
プラグインの設定ファイルが作成できたら、kustomization.yaml にそのファイルを指定しておきます。
|
1 2 3 4 5 6 |
generators: - sampleGenerator.yaml # transformer プラグインを作成した場合は以下で設定する # transformers: # - someTransformer.yaml |
プラグインディレクトリ作成
次にプラグインを置く、以下のようなディレクトリを作成します。
|
1 |
${XDG_CONFIG_HOME}/kustomize/plugin/${apiVersion}/LOWERCASE(${kind}) |
XDG_CONFIG_HOME はデフォルトでは $HOME/.config になります。プラグインごとにディレクトリを作成していく形になります。
プラグイン作成
ディレクトリを作成したら、いよいよプラグインを作成してみましょう。
kustomize はプラグインを探すにあたって、まず、${XDG_CONFIG_HOME}/kustomize/plugin/${apiVersion}/LOWERCASE(${kind})/${kind} を見ます。実行可能なファイルがなかった場合、${kind}.so のファイルがないかを確認し、存在する場合は Go plugin としてロードします。いずれも存在しなかった場合にはプラグインのロードに失敗し、kustomize build 全体が失敗します。
ということで、定義ファイルの内容に従い、$HOME/.config/kustomize/plugin/sample.techscore.com/v1/samplegenerator/ 以下に SampleGenerator というファイル名のシェルスクリプトを作成します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
#!/bin/bash # 実行時は SampleGenerator ${プラグインの設定ファイルのパス} ${argsOneLiner} ${argsFromFile} という形で引数が渡されるので、1つ目の引数を飛ばす shift echo " kind: ConfigMap apiVersion: v1 metadata: name: sample-configmap data: key1: $1 key2: $2 " |
作成したら、忘れず実行権限を付与しておきます。
|
1 |
$ chmod +x SampleGenerator |
実行
プラグインは kustomize build 実行時にのみ使用されます。
現状、プラグインを含んでいる場合 --enable_alpha_plugins のフラグを付与する必要があります。
|
1 2 3 4 5 6 7 8 |
$ kustomize build --enable_alpha_plugins apiVersion: v1 data: key1: val1 key2: val2 kind: ConfigMap metadata: name: sample-configmap |
意図した通りに変数が展開された ConfigMap が出力されました。
終わりに
以上、kustomize で generator / transformer の振る舞いを変更する方法のまとめでした。
凝ったことをする必要に迫られない限り、上記にまとめた内容を使う機会はそれほどないと思いますが、こういうこともできるのだと知っておいて損はないかなと思います。
