ベースとオーバーレイで環境差を作る

目標

1つのベースからdev・prodの2つの環境を作り出し、そのオーバーレイをArgo CD Applicationのソースとして接続できるようになります。

なぜ重要なのか

環境ごとのYAMLをコピーして管理すると、必ず分かれます。分かれたあとは、どちらが正解か誰にもわからなくなり、「devでは動いたんですが」が始まります。オーバーレイは、共通部分を1回だけ書き、違いだけをファイルに残す構造なので、その分岐を構造的に防ぎます。このラボで特に注目してほしいのは、configMapGeneratorのハッシュ接尾辞です。設定の内容が変わるとConfigMapの名前が変わり、それを参照するPodテンプレートが変わって、ロールアウトがひとりでに起きます。ハッシュがないと、ConfigMapだけが更新されてPodは古い設定を持ったまま動き続ける、原因の特定が最も難しい種類の事故が起きます。最後に、Argo CDがHelmを扱う方式も押さえます。Argo CDはhelm installをせず、repo-serverでhelm templateによってレンダリングした結果をapplyします。そのため、クラスターでhelm listをしても何も見えず、ロールバックはHelmのリビジョンではなくgitのコミットで行います。

ステップ

ベースの指示書は/root/gitops/kustomize/base/kustomization.yamlです。/opt/lab/fixtures/gitops/seed/deployment.yamlとservice.yamlを/root/gitops/kustomize/base/にコピーし、同じディレクトリにkustomization.yamlを作ってください。apiVersion: kustomize.config.k8s.io/v1beta1、kind: Kustomizationで、resourcesに2つのファイル名を書きます。ベースのspec.replicasは2にします(ベースが1だと失敗扱いになります)。
kustomize build /root/gitops/kustomize/base > /root/gitops/kustomize/out/base.yamlで結果を保存してください。結果にkind: Deploymentとkind: Serviceがあり、kind: Kustomizationは入っていてはいけません。
ベースのkustomization.yamlにnamePrefix: labhub-を入れ、共通ラベルapp.kubernetes.io/part-of: labhub-platformを追加してください(labels:の下に- pairs:の形か、commonLabels:のどちらも認められます)。もう一度ビルドしてout/base.yamlを更新すると、Deploymentの名前がlabhub-webになり、Serviceのmetadata.labelsにもそのラベルが付いている必要があります。
/root/gitops/kustomize/overlays/dev/kustomization.yamlを作ってください。resourcesの最初の項目は../../base、namespaceはgitops-dev、nameSuffixは-devです。kustomize build /root/gitops/kustomize/overlays/dev > /root/gitops/kustomize/out/dev.yamlで保存してください。
devのオーバーレイに戦略的マージパッチのファイル(例: patch-deployment.yaml)を置いて、kustomization.yamlのpatchesにそのパスを書いてください。パッチは、Deploymentのspec.replicasを1に下げ、コンテナwebに環境変数LOG_LEVEL=debugを追加する必要があります。パッチファイルのmetadata.nameは、ベースに書かれた元の名前のwebです。ベースのreplicasは2のままである必要があります。もう一度ビルドしてout/dev.yamlを更新してください。
devのオーバーレイのkustomization.yamlに、configMapGeneratorで名前app-configのConfigMapを作ってください(例: literalsにLOG_FORMAT=json)。そしてステップ5のパッチで、コンテナwebがenvFromのconfigMapRef.name: app-configでそれを参照するようにしてください。もう一度ビルドすると、ConfigMapの名前の末尾に内容のハッシュが付き、Deploymentの参照名もそのハッシュ付きの名前に変わっている必要があります。/root/gitops/kustomize/out/hash-note.txtに、ハッシュ接尾辞のおかげで設定の変更がPodのロールアウトにつながるという点を、韓国語で書いてください。
argocdネームスペースに、kind: Application、metadata.name: platform-helmを作ってください。spec.source.helm.valueFilesにvalues-prod.yamlを、spec.source.helm.parametersに名前image.tagと値(例: 1.27.3)を入れ、spec.source.targetRevisionはHEADではない固定の値(例: v1.4.0)にしてください。
/root/gitops/kustomize/overlays/prod/オーバーレイを作ってください。resourcesは../../base、namespaceはgitops-prodとし、パッチでspec.replicasを3以上に、imagesでイメージのタグをdevとは違う値にします(例: name: nginx、newTag: 1.27.3)。ビルド結果を/root/gitops/kustomize/out/prod.yamlに保存してください。そのあとargocdネームスペースに、kind: Application、metadata.name: web-devを作ってください。spec.source.pathにoverlays/devが入っている必要があり、spec.source.kustomize.imagesにイメージのオーバーライドを最低1つ入れます。

参考

ステップ7・8のApplicationを作るには、Argo CDのCRDが先に登録されている必要があります。前のラボと同じく、/opt/crds/のオフラインバンドルから探して適用してください(grep -l applications.argoproj.io /opt/crds/*.yaml)。
kustomize buildは、標準出力に結果を出します。リダイレクトの前に、出力ディレクトリ(/root/gitops/kustomize/out/)を先に作っておいてください。
名前の接頭辞が付いていても、パッチはベースに書かれた元の名前で対象を探します。もし対象が見つからないというエラーが出たら、patchesの代わりに旧式のpatchesStrategicMergeで書いてもかまいません。
よくあるミス1は、devのreplicasを1にしようとしてベースを直してしまうことです。そうするとprodまで1になります。ベースは共通項、環境固有の値はオーバーレイです。
よくあるミス2は、オーバーレイを直してもう一度ビルドしないことです。採点はout/*.yamlファイルを読むので、設定を直すたびに、該当するビルド結果を新しく保存する必要があります。

kustomizeのベースを構成する

ベースの指示書は/root/gitops/kustomize/base/kustomization.yamlです。/opt/lab/fixtures/gitops/seed/deployment.yamlとservice.yamlを/root/gitops/kustomize/base/にコピーし、同じディレクトリにkustomization.yamlを作ってください。apiVersion: kustomize.config.k8s.io/v1beta1、kind: Kustomizationで、resourcesに2つのファイル名を書きます。ベースのspec.replicasは2にします(ベースが1だと失敗扱いになります)。

kustomization.yamlはマニフェストではなく指示書です。resourcesに書いた名前は、同じディレクトリに実際にある必要があります。

ベースのビルド結果を保存する

kustomize build /root/gitops/kustomize/base > /root/gitops/kustomize/out/base.yamlで結果を保存してください。結果にkind: Deploymentとkind: Serviceがあり、kind: Kustomizationは入っていてはいけません。

kustomize build 디렉터리の標準出力をファイルに受け取ります(プレースホルダーはディレクトリです)。結果に指示書自身が混ざって出てはいけません。それは成果物ではないからです。

名前の接頭辞と共通ラベルを付ける

ベースのkustomization.yamlにnamePrefix: labhub-を入れ、共通ラベルapp.kubernetes.io/part-of: labhub-platformを追加してください(labels:の下に- pairs:の形か、commonLabels:のどちらも認められます)。もう一度ビルドしてout/base.yamlを更新すると、Deploymentの名前がlabhub-webになり、Serviceのmetadata.labelsにもそのラベルが付いている必要があります。

名前の変形とラベルの付与は、どちらもベースのkustomizationで宣言します。ラベルは、新式のlabelsのpairsか、旧式のcommonLabelsのどちらでも大丈夫です。直したらもう一度ビルドしないと、結果のファイルが変わりません。

devのオーバーレイを作る

/root/gitops/kustomize/overlays/dev/kustomization.yamlを作ってください。resourcesの最初の項目は../../base、namespaceはgitops-dev、nameSuffixは-devです。kustomize build /root/gitops/kustomize/overlays/dev > /root/gitops/kustomize/out/dev.yamlで保存してください。

オーバーレイは、ベースを相対パスでresourcesに入れます。ネームスペースと名前の接尾辞はオーバーレイが決め、ビルド結果はdev専用のファイルとして別に保存してください。

パッチでベースを上書きする

devのオーバーレイに戦略的マージパッチのファイル(例: patch-deployment.yaml)を置いて、kustomization.yamlのpatchesにそのパスを書いてください。パッチは、Deploymentのspec.replicasを1に下げ、コンテナwebに環境変数LOG_LEVEL=debugを追加する必要があります。パッチファイルのmetadata.nameは、ベースに書かれた元の名前のwebです。ベースのreplicasは2のままである必要があります。もう一度ビルドしてout/dev.yamlを更新してください。

ベースには触れません。パッチファイルにはベースに書かれた元の名前を書き、コンテナ名が合っていてはじめてマージされます。

ジェネレーターとハッシュ接尾辞をつなげる

devのオーバーレイのkustomization.yamlに、configMapGeneratorで名前app-configのConfigMapを作ってください(例: literalsにLOG_FORMAT=json)。そしてステップ5のパッチで、コンテナwebがenvFromのconfigMapRef.name: app-configでそれを参照するようにしてください。もう一度ビルドすると、ConfigMapの名前の末尾に内容のハッシュが付き、Deploymentの参照名もそのハッシュ付きの名前に変わっている必要があります。/root/gitops/kustomize/out/hash-note.txtに、ハッシュ接尾辞のおかげで設定の変更がPodのロールアウトにつながるという点を、韓国語で書いてください。

ジェネレーターが作った名前の末尾には、内容のハッシュが付きます。ワークロードがそのConfigMapを参照していれば、参照名も一緒に更新されます。これがなぜ役に立つのかが、このステップの核心です。

Helmソースを使うApplicationを書く

argocdネームスペースに、kind: Application、metadata.name: platform-helmを作ってください。spec.source.helm.valueFilesにvalues-prod.yamlを、spec.source.helm.parametersに名前image.tagと値(例: 1.27.3)を入れ、spec.source.targetRevisionはHEADではない固定の値(例: v1.4.0)にしてください。

環境別の値ファイルと、デプロイごとに変わる個別のパラメーターは、別々の場所に入ります。リビジョンをブランチの最新にしておくと、同じ宣言が時点ごとに違うものをデプロイします。

オーバーレイベースのApplicationとprodのビルド

/root/gitops/kustomize/overlays/prod/オーバーレイを作ってください。resourcesは../../base、namespaceはgitops-prodとし、パッチでspec.replicasを3以上に、imagesでイメージのタグをdevとは違う値にします(例: name: nginx、newTag: 1.27.3)。ビルド結果を/root/gitops/kustomize/out/prod.yamlに保存してください。そのあとargocdネームスペースに、kind: Application、metadata.name: web-devを作ってください。spec.source.pathにoverlays/devが入っている必要があり、spec.source.kustomize.imagesにイメージのオーバーライドを最低1つ入れます。

prodのオーバーレイは、devと同じベースを使いつつ、ネームスペース・レプリカ数・イメージのタグが違っている必要があります。Application側にも、イメージのタグを差し替える場所が別にあります。