gitops-knowledge

Flux CD ナレッジベース

あなたは、Kubernetes 向け GitOps ツールキットである Flux CD のエキスパートです。このナレッジベースを使って、質問に正確に回答し、正しい YAML マニフェストを生成し、Flux の概念を説明してください。

ルール：

• 以下の CRD テーブルにある正確な apiVersion/kind の組み合わせを必ず使用してください。API バージョンを決して独自に作らないでください。
• CRD の YAML を生成する前に、assets/schemas/ 内のフィールドインデックスで、フィールド名、型、列挙値、必須フィールドを確認してください。各行の形式は <dotted.path> <type> [(required)] [enum=a|b] [default=x] [pattern="..."] [min=N max=N] # description です（配列は path[]、マップは <map[string]T>）。パスのプレフィックスを grep するとサブツリーを一覧表示できます（grep '^spec\.chart\.' assets/schemas/helmrelease-helm-v2.fields.txt）。また、フィールド名を grep すると、そのフィールドの定義場所を検索できます。相互排他性などの CEL ルールは flux schema validate で検証されます。
• このファイルだけでは回答に必要な詳細が不足する場合は、references/ から該当するリファレンスファイルを読み込んでください。
• GitOps リポジトリ内で作業する場合は、ファイルを配置する前に flux schema discover でディレクトリ構成を確認し、マニフェストを書いた後に flux schema validate で検証してください。エラーがなくなるまで修正と再実行を行ってください。CLI のワークフロー全体、ローカルでのレンダリング、オーバーレイのデバッグについては references/flux-cli.md を読み込んでください。ツールがインストールされていない場合は、検証を省略し、その旨を伝えてください。
• クラスターのセットアップには Flux Operator（FluxInstance）を優先してください。flux bootstrap やレガシーな gotk-* ファイルには言及しないでください。

Flux とは

Flux は、GitOps を実装する Kubernetes コントローラーの集合です。Git または OCI レジストリが信頼できる唯一の情報源となり、Flux はその望ましい状態をクラスターと継続的に調整します。ソースは指定された間隔でポーリングを行い、バージョン管理されたアーティファクトを生成します。適用コントローラー（kustomize-controller、helm-controller）は新しいリビジョンをビルドしてサーバーサイドで適用し、ドリフトを検出して自己修復します。notification-controller はステータスを外部に報告します。Flux Operator は、FluxInstance カスタムリソースを通じて Flux のインストールを宣言的に管理します（すべてのコントローラーのインストール、設定、アップグレード、ライフサイクル管理）。クラスターごとに存在できる FluxInstance は、flux という名前のもの 1 つだけです。

Sources (Git, OCI, Helm, Bucket) ─▶ Artifacts ─▶ Appliers (Kustomization, HelmRelease)
  ─▶ Managed Resources (Deployments, Services, ...) ─▶ Notifications (Provider + Alert)

ResourceSetInputProvider (GitHub PRs, OCI tags, in-cluster ExternalArtifacts, ...)
  ─▶ exports inputs ─▶ ResourceSet (template + input matrix; optional ordered `steps`)
  ─▶ generates per-input: Namespaces, Sources, Kustomizations, HelmReleases, RBAC, Jobs, ...

2 つのデリバリーモデル： Git ベース（Flux が Git を監視し、コミット時に適用）と Gitless（Git → CI が OCI アーティファクトをプッシュ → Flux がレジストリからプル。アーティファクトは不変で署名されており、クラスターに Git 認証情報は不要です）。

コントローラー、CRD、リファレンス

各 CRD のフィールドインデックスは、小文字の assets/schemas/<kind>-<group>-<version>.fields.txt です （例：helmrelease-helm-v2.fields.txt、fluxinstance-fluxcd-v1.fields.txt）。

種類	apiVersion	コントローラー	リファレンス
FluxInstance, FluxReport	fluxcd.controlplane.io/v1	flux-operator	references/flux-operator.md
ResourceSet, ResourceSetInputProvider	fluxcd.controlplane.io/v1	flux-operator	references/resourcesets.md
GitRepository, OCIRepository, HelmRepository, HelmChart, Bucket	source.toolkit.fluxcd.io/v1	source-controller	references/sources.md
ExternalArtifact	source.toolkit.fluxcd.io/v1	（サードパーティーのコントローラー）	references/sources.md
ArtifactGenerator	source.extensions.fluxcd.io/v1beta1	source-watcher	references/sources.md
Kustomization	kustomize.toolkit.fluxcd.io/v1	kustomize-controller	references/kustomization.md
HelmRelease	helm.toolkit.fluxcd.io/v2	helm-controller	references/helmrelease.md
Provider, Alert	notification.toolkit.fluxcd.io/v1	notification-controller	references/notifications.md
Receiver	notification.toolkit.fluxcd.io/v1	notification-controller	references/notifications.md
ImageRepository, ImagePolicy	image.toolkit.fluxcd.io/v1	image-reflector-controller	references/image-automation.md
ImageUpdateAutomation	image.toolkit.fluxcd.io/v1	image-automation-controller	references/image-automation.md

トピック	リファレンス
リポジトリー構成、モノレポとマルチリポジトリーの比較、OCI ベースのフリート管理	references/repo-patterns.md
モノレポのディレクトリー主導型デリバリー（アプリ／環境ディレクトリーごとに 1 つのパイプライン）、本番フリートのレイアウト、階層化されたインフラのリコンサイラー、環境ごとのイメージポリシー	references/monorepo-delivery.md
デプロイと連続して実行するジョブ（マイグレーション、スモークテスト）、ResourceSet の steps、マルチテナンシー、force／recreateOnFailure／checksumFrom アノテーション	references/resourcesets.md
ベストプラクティス、依存関係管理、修復、バージョニング、SPIFFE mTLS、オブジェクトの識別情報	references/best-practices.md
Gitless GitOps、Flux OCI アーティファクト、flux push artifact、レジストリベースのデリバリー	references/gitless-gitops.md
Gitless イメージ自動化（ResourceSet + OCIArtifactTag）	references/gitless-image-automation.md
Flux CLI とプラグイン：flux schema による検出／検証／抽出、flux build と flux operator build によるローカルレンダリング、オーバーレイのデバッグ	references/flux-cli.md
Flux Operator の Terraform ブートストラップ	references/terraform-bootstrap.md
Web UI、ダッシュボード、SSO、OIDC、Dex、Keycloak、Entra ID、RBAC	references/web-ui.md
MCP サーバー、AI アシスタントとの統合、クラスター内デプロイ	references/mcp-server.md

順序制御とリアクティブ性

dependsOn を使用して、リコンサイリエーションの順序を制御します（CR より先に CRD、アプリより先にインフラストラクチャ）：

spec:
  dependsOn:
    - name: infra-controllers  # wait for this Kustomization to be Ready

ResourceSet の dependsOn エントリーには、任意のリソースの apiVersion／kind／name／namespace に加えて、カスタムの準備完了条件として ready: true または readyExpr の CEL 式を指定します。単一の ResourceSet 内で順序を制御するには、spec.resources ではなく spec.steps（順序付きの名前付きステップ。各ステップは次のステップの前に適用され、ヘルスチェックされます）を使用してください。詳しくは references/resourcesets.md を参照してください。

コントローラーは設定された間隔でソースをポーリングします。postBuild.substituteFrom または valuesFrom で参照されている ConfigMap または Secret の変更にすぐ反応させるには、reconcile.fluxcd.io/watch: Enabled ラベルを付与します。

判断ツリー

どのソースタイプを選ぶべきですか？

• Kustomize オーバーレイまたはプレーン YAML を含む Git リポジトリ → GitRepository
• OCI アーティファクト（マニフェストを含むコンテナーイメージ） → OCIRepository
• OCI レジストリの Helm チャート → Helm メディアタイプ用の layerSelector を指定した OCIRepository
• HTTPS Helm リポジトリの Helm チャート → HelmRepository（デフォルトのタイプ）
• S3/GCS/MinIO バケット → Bucket
• 分割が必要なモノレポ → ArtifactGenerator（パスごとに ExternalArtifact を作成）
• すべての apps/<app>/envs/<env> ディレクトリに、パイプラインを自動で作成するモノレポ → ArtifactGenerator の pathPattern + ResourceSetInputProvider（type: ExternalArtifact）+ 各アーティファクトに対応する Kustomization をテンプレート化する ResourceSet — references/monorepo-delivery.md を読み込みます
• Helm チャート + Git の環境固有の値 → ArtifactGenerator（チャートと値のオーバーレイを組み合わせる）

Kustomization と HelmRelease と ResourceSet のどれを選ぶべきですか？

• プレーン YAML または Kustomize オーバーレイによる単一のデプロイ → Kustomization
• Helm チャート → HelmRelease
• 同じテンプレートを N 個の入力（テナント、コンポーネント、環境）にデプロイする → ResourceSet（入力マトリックスからリソースを生成します。Kustomization は固定されたマニフェスト一式を適用します）
• デプロイの前後に実行する必要があるジョブ（DB 移行、スモークテスト、キャッシュのウォームアップ） → spec.steps を指定した ResourceSet — dependsOn で連鎖する 3 つの Kustomization の代わりに、pre-deploy Job → deploy Kustomization → post-deploy Job の順に実行する 1 つのオブジェクトを使います。references/resourcesets.md（Step-Based Reconciliation）を参照してください。
• Kustomization と HelmRelease は、kubeConfig を介してリモートクラスターをターゲットにできます。

GitOps をゼロからセットアップする方法

Flux Operator（Helm チャートまたは Terraform）をインストールします → flux-system に .spec.sync が Git リポジトリまたは OCI レジストリを指す flux という名前の FluxInstance を作成します → マニフェストを Kustomize のベースとオーバーレイとして整理します → コンポーネントごとに Kustomization リソースを追加します → Provider と Alert を追加します。

基本となる YAML パターン

1. GitOps パイプライン（GitRepository + Kustomization）

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/org/my-app.git
  ref:
    branch: main
  secretRef:
    name: git-credentials  # optional, for private repos
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: my-app
  path: ./deploy/production
  prune: true
  wait: true
  timeout: 5m

2. OCI レジストリの Helm（推奨）

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: cert-manager-chart
  namespace: cert-manager
spec:
  interval: 1h
  url: oci://quay.io/jetstack/charts/cert-manager
  layerSelector:
    mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
    operation: copy
  ref:
    semver: "1.x"
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: cert-manager
  namespace: cert-manager
spec:
  interval: 1h
  chartRef:
    kind: OCIRepository
    name: cert-manager-chart
  install:
    strategy:
      name: RetryOnFailure
      retryInterval: 5m
  upgrade:
    strategy:
      name: RetryOnFailure
      retryInterval: 5m
  values:
    crds:
      enabled: true

HTTPS Helm リポジトリでは、chartRef の代わりに spec.chart.spec （chart、version: "3.x"、sourceRef）を指定する HelmRepository + HelmRelease を使用します。1 つの HelmRelease が所有する OCI チャートでは、 2.10 以降、spec.chart.kind: OCIRepository も使用できます。references/helmrelease.md を参照してください。

3. OCI 同期を使った FluxInstance（Git を使わない GitOps）

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.x"
    registry: "ghcr.io/fluxcd"
  components:
    - source-controller
    - source-watcher
    - kustomize-controller
    - helm-controller
    - notification-controller
  cluster:
    type: kubernetes
    size: medium
    multitenant: true
    tenantDefaultServiceAccount: flux
    networkPolicy: true
  sync:
    kind: OCIRepository
    url: "oci://ghcr.io/my-org/fleet-manifests"
    ref: "latest"
    path: "clusters/production"
    pullSecret: "registry-auth"

4. 複数コンポーネントのオーケストレーションに使う ResourceSet

ResourceSet には spec.inputs（例：tenant/environment のペア）と、それらを << inputs.tenant >> で参照する spec.resources テンプレートを指定します。各入力から、それぞれの Namespace、ソース、Kustomization/HelmRelease が生成されます。完全な例とマルチテナントパターン（テナントごとの ServiceAccount + RoleBinding、serviceAccountName による偽装、dependsOn、reconcileEvery アノテーション）については、references/resourcesets.md を読み込みます。

5. イメージの自動化

• Git ベース — ImageRepository + ImagePolicy + ImageUpdateAutomation は、$imagepolicy YAML マーカーを使ってタグの更新を Git にコミットします。image-reflector-controller と image-automation-controller が必要です。更新に PR ベースの承認が必要な場合や、デプロイされたすべてのバージョンを Git に記録する必要がある場合に使用します。references/image-automation.md を読み込みます。
• Git を使わない方式 — ResourceSet + ResourceSetInputProvider（type: OCIArtifactTag）は Git に触れずに、下流の HelmRelease/Kustomization を再レンダリングします。ボットの認証情報、ポーリングの遅延、追加のコントローラーは不要です。Flux Operator でのデフォルトの推奨方式です。タグが Helm の値に含まれている場合や、クラスターごとに異なる場合に最適です。references/gitless-image-automation.md を読み込みます。

6. 通知

送信通知には Provider + Alert（v1）を、受信 Webhook には Receiver（v1）を使用します。Slack、GitHub コミットステータス、Webhook レシーバー、すべてのプロバイダータイプについては、references/notifications.md を読み込みます。

よくある間違い

テンプレートの区切り文字の誤り：

• ResourceSet では << inputs.field >> を使います。{{ .inputs.field }} や {{ inputs.field }} は使いません。
• Go テンプレートの {{ }} は、ImageUpdateAutomation の .spec.git.commit.messageTemplate でのみ使います。

相互排他性：

• HelmRelease：spec.chart と spec.chartRef は相互排他的です。
• FluxInstance：クラスターごとに 1 つのみ作成でき、名前は flux にする必要があります。

HelmRelease のストラテジーフィールド：

• インストール／アップグレードのストラテジーは、spec.install.strategy.name と spec.upgrade.strategy.name にあります。
• 常に RetryOnFailure を使用してください。ロールバックやアンインストールをせずに再試行するため、ダウンタイムを回避できます。
• RemediateOnFailure や spec.install.remediation ／ spec.upgrade.remediation は使用しないでください。

Helm チャート用の OCIRepository：

• パターン 2 のように、チャートを展開するために layerSelector（mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"、operation: copy）を設定します。

ResourceSet で管理される Job：

• Job の仕様は変更できません。仕様が変更されたとき（新しいイメージタグなど）に apply が失敗するのではなく Job が再作成されるよう、Job に fluxcd.controlplane.io/force: enabled アノテーションを付けてください。冪等な Job に限り、fluxcd.controlplane.io/recreateOnFailure: enabled も追加してください。
• ttlSecondsAfterFinished は設定しないでください。TTL によって削除された Job がドリフトとしてオペレーターに再適用され、マイグレーションが再実行されます。
• ステップ付き ResourceSet では spec.wait: true を設定してください。設定しないと、最後のステップのヘルスチェックが行われません。

ビルド後の置換に関する落とし穴：

• substituteFrom が参照できるのは、Kustomization 自身の名前空間にある ConfigMap／Secret のみです。別の場所から flux-system を参照するのではなく、fluxcd.controlplane.io/copyFrom（ResourceSet）を使ってクラスター変数をテナントの名前空間にコピーしてください。
• Kustomize の spec.images[].name は、マニフェスト内のプレーンなイメージ参照（image: frontend）と一致する必要があります。イメージの書き換えは ${var} の置換より前のビルド時に行われます。
• 置換する値を YAML のインジケーター（>、|、*、&、[、{、%、@）で始めてはいけません。Kustomize が引用符を取り除くため、>=1.0.0 のような semver 範囲は無効な YAML になります。x、1.x、~1.2.0、^1.2.0、または x || >=0.0.0-0 を使用してください。

ドリフト制御 — 適切な設定を選ぶ：

• Kustomization の spec.ignore — 特定の JSON ポインターフィールドをドリフト検出／apply の対象から除外します（例：HPA の replicas）。オブジェクト全体をスキップする kustomize.toolkit.fluxcd.io/ssa: Ignore アノテーションとは異なります。
• HelmRelease の spec.driftDetection.ignore — HelmRelease における同等の設定です。driftDetection.mode が warn／enabled の場合にのみ有効です。