Applicationマニフェストを組み立てる

目標

Argo CDのApplicationマニフェストを、フィールド1つずつ積み上げて完成させ、そのアプリがデプロイするネームスペースとDeploymentを実際のクラスターに載せて、Argo CDが自分のリソースを見分ける方式まで、手で確認します。

なぜ重要なのか

Applicationは、「何を(source)どこに(destination)どんなルールで(syncPolicy)合わせるか」を書いた宣言文です。フィールド名を覚えるより、各フィールドが、どんな事故を防ぐために生まれたかを知ることが重要です。pruneを有効にしないと、Gitから削除したリソースがクラスターに永遠に残り、selfHealを有効にすると、手で直した値が元に戻され、ignoreDifferencesなしでHPAを使うと、Argo CDとHPAがreplicasをめぐって終わりなく争います。このラボで作るファイルは、それらの事故を1つずつ予防する順序で積み上がります。

ステップ

/root/capa-app/ディレクトリを作成し、その中にapplication.yamlを作成してください。apiVersionはargoproj.io/v1alpha1、kindはApplication、metadata.nameはguestbook、metadata.namespaceはargocdです。
同じファイルに、spec.projectをcapa-demo、spec.source.repoURLをhttps://gitea.homelab.internal/platform/guestbook.git、spec.source.targetRevisionをmain、spec.source.pathをoverlays/prodとして埋めてください。
spec.destination.serverをhttps://kubernetes.default.svc、spec.destination.namespaceをcapa-guestbookに指定してください。destination.nameは使わないでください。
spec.syncPolicy.automated.pruneとspec.syncPolicy.automated.selfHealを、どちらもtrueにし、spec.syncPolicy.syncOptionsに、CreateNamespace=trueとPruneLast=trueの2項目を入れてください。
spec.syncPolicy.retry.limitを5、spec.syncPolicy.retry.backoff.durationを5s、factorを2、maxDurationを3mに指定してください。
spec.ignoreDifferencesの最初の項目に、group: apps、kind: Deployment、jsonPointersに/spec/replicasを入れて、HPAが管理するフィールドを比較から除外してください。
クラスターに、ネームスペースcapa-guestbookを実際に作成し、ラベルapp.kubernetes.io/part-of=capaを付けてください。
ネームスペースcapa-guestbookに、Deploymentguestbook-uiを実際に作成してください。replicasは2、コンテナイメージはnginx:1.27で、そしてDeployment自身のアノテーションとしてargocd.argoproj.io/tracking-idを、Argo CDの形式に合わせて付けてください。アプリ名はguestbookです。

参考

ファイルの検証は、yq '.spec.syncPolicy' /root/capa-app/application.yamlのように、一部だけを取り出して見ると早いです。
実際のリソースは、kubectl create ... --dry-run=client -o yamlで骨組みを出力してから編集するほうが、打ち間違いが少ないです。
よくある間違い1: syncOptionsをマップで書くことです。文字列の配列です。
よくある間違い2: 追跡IDのコアグループの表記です。appsグループのリソースとコアグループのリソースで、形が違います。

作業ディレクトリとApplicationの骨格

/root/capa-app/ディレクトリを作成し、その中にapplication.yamlを作成してください。apiVersionはargoproj.io/v1alpha1、kindはApplication、metadata.nameはguestbook、metadata.namespaceはargocdです。

Applicationは、argoproj.ioグループのカスタムリソースです。metadata.namespaceは、デプロイ先ではなく、Applicationオブジェクト自身が存在する場所で、通常、Argo CDがインストールされたネームスペースです。

source: 何を取得するか

同じファイルに、spec.projectをcapa-demo、spec.source.repoURLをhttps://gitea.homelab.internal/platform/guestbook.git、spec.source.targetRevisionをmain、spec.source.pathをoverlays/prodとして埋めてください。

spec.sourceの下に、リポジトリのアドレス、リビジョン、パスの3つが入ります。targetRevisionは、ブランチ・タグ・コミットSHAのすべてを受け付け、本番ではHEADより、固定された名前を使うほうが安全です。

destination: どこに置くか

spec.destination.serverをhttps://kubernetes.default.svc、spec.destination.namespaceをcapa-guestbookに指定してください。destination.nameは使わないでください。

同じクラスター内にデプロイするときに使うアドレスが、決まっています。serverとnameは、同じものを指す2つの方式なので、同時に使ってはいけません。

自動同期とsyncOptions

spec.syncPolicy.automated.pruneとspec.syncPolicy.automated.selfHealを、どちらもtrueにし、spec.syncPolicy.syncOptionsに、CreateNamespace=trueとPruneLast=trueの2項目を入れてください。

automatedの下の2つのブール値は、それぞれ「Gitから削除したものを、クラスターからも削除するか」と「手で変えた値を、元に戻すか」を決めます。syncOptionsは文字列の配列で、キー=値の形式で書きます。

リトライのバックオフの設計

spec.syncPolicy.retry.limitを5、spec.syncPolicy.retry.backoff.durationを5s、factorを2、maxDurationを3mに指定してください。

backoffは、durationから始まり、毎回factor倍ずつ増えて、maxDurationで止まります。要求された値で計算すると、5秒、10秒、20秒、40秒、80秒になるかを、自分で掛けて確かめてください。

HPAが管理するフィールドをdiffから除外する

spec.ignoreDifferencesの最初の項目に、group: apps、kind: Deployment、jsonPointersに/spec/replicasを入れて、HPAが管理するフィールドを比較から除外してください。

ignoreDifferencesは配列で、各項目はgroup/kindで対象を絞ってから、jsonPointersでフィールドを指定します。JSON Pointerは、ドットではなくスラッシュでパスを書きます。

対象のネームスペースを実際に作成する

クラスターに、ネームスペースcapa-guestbookを実際に作成し、ラベルapp.kubernetes.io/part-of=capaを付けてください。

ここからは、ファイルではなく本物のクラスターです。kubectl create namespaceで作成してからlabelを付けるか、マニフェストを書いてapplyしてもかまいません。

追跡アノテーションまで付けたDeployment

ネームスペースcapa-guestbookに、Deploymentguestbook-uiを実際に作成してください。replicasは2、コンテナイメージはnginx:1.27で、そしてDeployment自身のアノテーションとしてargocd.argoproj.io/tracking-idを、Argo CDの形式に合わせて付けてください。アプリ名はguestbookです。

追跡IDの形式は、APP_NAME:GROUP/KIND:NAMESPACE/NAMEです。appsグループのDeploymentなので、GROUPの位置が空ではない点に注意してください。