ほとんどの GitOps 構成では、CI パイプラインがイメージをビルドし、新しいタグを設定リポジトリに commit します。Flux には代替手段があります。2 つのオプションのコントローラーが、コンテナレジストリを監視し、ルールに一致する最新のタグを選び、その変更を自分で Git に commit します。クラスターは、Git の commit によってのみ変更されるため、監査証跡は保たれます。このガイドでは、公開されている podinfo イメージを使います。

部品の組み合わせ方

3 つのリソースが連携して動作します。

• ImageRepository は、レジストリをスキャンして、1 つのイメージのタグを調べます。
• ImagePolicy は、そのリストから 1 つのタグを選びます。たとえば、範囲内で最も高い semantic version です。
• ImageUpdateAutomation は、マーカーが指示する Git リポジトリ内の YAML を編集し、commit して push します。

3 つとも image.toolkit.fluxcd.io/v1 API を使います。古い v1beta2 バージョンは Flux 2.9 で CRD から削除されたため、アップグレードの前に、古いマニフェストを移行してください。

追加のコントローラーをインストールする

イメージのコントローラーは、デフォルトのインストールには含まれません。それらを追加して、もう一度 bootstrap し、Flux がリポジトリに push できるようにします。

flux bootstrap github \
  --owner=<your-github-user> \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/dev \
  --personal \
  --components-extra=image-reflector-controller,image-automation-controller \
  --read-write-key

bootstrap は繰り返しても安全です。新しいコントローラーのマニフェストを commit してインストールします。--read-write-key は、自動化が push できるように、deploy key を書き込み可能にします。kubectl get pods -n flux-system で確認します。

レジストリをスキャンする

apps/podinfo/image-repository.yaml（Deployment と同じフォルダー）:

apiVersion: image.toolkit.fluxcd.io/v1
kind: ImageRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  image: ghcr.io/stefanprodan/podinfo
  interval: 5m

プライベートレジストリの場合は、Docker レジストリの secret（kubectl create secret docker-registry または flux create secret oci で作成）を指す secretRef を追加します。

ポリシーでタグを選ぶ

apiVersion: image.toolkit.fluxcd.io/v1
kind: ImagePolicy
metadata:
  name: podinfo
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: podinfo
  policy:
    semver:
      range: 6.x

range: 6.x の semver は、最も高い 6.x のバージョンを選びます。他のポリシータイプには、numerical（最も高い数値）と alphabetical があり、ビルド番号や日付のようなタグに適しています。タグ名に基づくルールには、ポリシーに正規表現の filterTags を追加します。

更新する行にマークを付ける

Flux は、コメントでマークを付けた行を正確に更新します。apps/podinfo/deployment.yaml で：

    spec:
      containers:
        - name: podinfo
          image: ghcr.io/stefanprodan/podinfo:6.5.0 # {"$imagepolicy": "flux-system:podinfo"}

マーカーは namespace:policy-name です。デフォルトでは、イメージ参照全体が置き換えられます。タグだけを更新するには、{"$imagepolicy": "flux-system:podinfo:tag"} を使います。Helm の values や Kustomize の images のエントリでは、タグを保持する行に同じマーカーが使えます。マーカーのないものは、そのままにされます。

commit の方法を Flux に伝える

apiVersion: image.toolkit.fluxcd.io/v1
kind: ImageUpdateAutomation
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 30m
  sourceRef:
    kind: GitRepository
    name: flux-system
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        name: fluxcdbot
        email: fluxcdbot@users.noreply.github.com
      messageTemplate: |
        Automated image update

        {{range .Changed.Changes}}
        - {{.OldValue}} -> {{.NewValue}}
        {{end}}
    push:
      branch: main
  update:
    path: ./apps
    strategy: Setters

重要なポイントは次のとおりです。

• sourceRef は、commit 先の Git リポジトリです。書き込み可能である必要があり、そのために --read-write-key があります。
• checkout.ref.branch は開始元のブランチで、push.branch は commit の送り先です。
• update.path は、マーカーを探してスキャンするフォルダーを制限します。
• messageTemplate は、履歴が読みやすくなるように、commit メッセージを制御します。

main に直接 push すると、すべてが完全に自動になります。信頼を築いている間は、代わりに別のブランチに push し（たとえば push.branch: flux-image-updates）、納得したらプルリクエストをマージします。変更は、マージの後にはじめてクラスターに届きます。

動作を確認する

これらのファイルを commit して push し、各段階を確認します。

flux get image repository
flux get image policy
flux get image update

repository はスキャンされたタグの数を、policy は選択したタグを、update automation は最後に push した commit を示します。選択されたタグが YAML のものより新しければ、Git に commit が現れ、Flux は他の変更と同じようにそれを適用します。デバッグするには、各オブジェクトに kubectl describe を使います。間違ったマーカー、何にも一致しないポリシーの範囲、読み取り専用の deploy key が、よくある原因です。

どの方法を選ぶか

1 つのパイプラインがすでにプロモーションを担っており、何をリリースするかを決める場所を 1 つにしたい場合は、CI 主導の commit を使います。クラスターの設定リポジトリに、レジストリを自動的に追従させたい場合、たとえば dev 環境を最新のパッチリリースに保つには、Flux のイメージ自動化を使います。両者は共存できます。