gitops-repo-audit

GitOps リポジトリ監査ツール

Flux CD に特化した GitOps リポジトリ監査ツールです。GitOps リポジトリを調査し、問題を特定し、マニフェストを検証し、セキュリティ態勢を監査して、改善に向けた実行可能な推奨事項を提示します。

リポジトリを監査するときは、以下のワークフローに従ってください。深さはユーザーの依頼に応じて調整します。「HelmReleases は正しく設定されていますか？」のような対象を絞った質問では全体のワークフローは必要ありませんが、「このリポジトリを監査してください」のような幅広い依頼では必要です。

分析ワークフロー

フェーズ 1：調査

詳細を掘り下げる前に、リポジトリを把握します。

1. 同梱の調査スクリプトを実行し、Kubernetes リソースのインベントリを取得します。

   scripts/discover.sh -d <repo-root>
   

   このスクリプトは flux-schema discover をラップし、トップレベルの inventory オブジェクト（kind／apiVersion／$schema と並列）を含む JSON を出力します。inventory には、ファイル数、リソース数、行数をまとめた summary、各ディレクトリを kubernetes-manifests、kustomize-overlay、helm-chart、terraform に分類する directories マップ、group/version/Kind ごとの件数を含む resources マップ、ファイルごとにすべての Flux リソースを列挙する flux マップがあります。.inventory 以下のフィールドを確認してください。複数ドキュメントを含むファイルにも対応しています。
2. repo-patterns.md を読み、ヒューリスティック表と照合してリポジトリのパターンを分類します。
3. クラスターを検出します。clusters/ 以下のディレクトリ、または FluxInstance リソースを探します。FluxInstance を読み、クラスターの構成を把握します。
4. flux-system/ 以下に gotk-sync.yaml があるか確認します。存在する場合は flux bootstrap が使用されたことを示します。FluxInstance リソースを使って Flux Operator に移行することを推奨してください。レポートには必ず移行ガイドの URL を含めてください：https://fluxoperator.dev/docs/guides/migration/

フェーズ 2：マニフェスト検証

同梱の検証スクリプトを実行し、Kubernetes スキーマと Kustomize ビルドを確認します。フェーズ 4～5 で有効なマニフェストを grep できるよう、レンダリング済みのバンドルを一時ファイルに書き出してください（リポジトリ内には書き込まないでください）。mktemp を使ってパスを一意にし、同じマシンで監査が同時に実行されても、互いのバンドルが上書きされないようにします。一時ディレクトリに書き込めない場合は、mktemp が失敗し、スクリプトはバンドルなしで実行されます。

bundle="$(mktemp "${TMPDIR:-/tmp}/flux-audit-bundle.XXXXXX" 2>/dev/null || true)"
scripts/validate.sh -d <repo-root> ${bundle:+-b "$bundle"}

すべてのマニフェストと、各 Kustomize オーバーレイのレンダリング結果を検証します。無効なリソースと失敗したビルドの件数を出力し、ゼロ以外の終了コードで終了します。暗号化された Secret や、スキーマがないサードパーティ製 CRD は適切に処理されます。「skipped」は想定内であり、失敗ではないものとして扱ってください。-b フラグを指定すると、すべてのマニフェストとレンダリング済みオーバーレイを $bundle に統合し、それぞれに # === file/kustomize-overlay: … === という出所を示すコメントを付けます。

-e <dir> を使うと、検証対象から除外するディレクトリを追加できます。

リポジトリで名前や名前空間に変数を代入している場合（name: apps-${app_env} など）、生の ${...} テキストに対してスキーマの正規表現チェックが失敗します。リポジトリの変数 ConfigMap と postBuild.substitute のリテラルから dotenv ファイルを作成して（一時パスに書き出してください）、-E <dotenv> を指定して再実行します。これにより、クラスターから見た状態を再現する flux envsubst 適用後のマニフェストを検証できます。

フェーズ 3：API 互換性

非推奨の Flux API バージョンがないか確認します。

1. 同梱のチェック用スクリプトを実行します。

   scripts/check-deprecated.sh -d <repo-root>
   

   flux migrate -f . --dry-run を実行し、該当箇所ごとにファイル名と行番号、種類、移行先バージョンを出力します。終了コードは次のとおりです。

   • 0：スキャン完了、非推奨 API は見つかりませんでした
   • 1：スキャン完了、非推奨 API が見つかりました
   • 2：スキャン未完了。移行行が一部出力されていても、フェーズ 3 は正常ではなく失敗として、出力とともに報告してください

2. 非推奨 API が見つかった場合は、api-migration.md の手順を含めてください。Notification の v1beta3（Alert、Provider）は 2.10 で非推奨になりましたが、引き続き提供されています。これは Critical ではなく Warning としてください。Alert の spec.summary と Provider の spec.proxy／spec.interval は、どのバージョンでも指摘してください（v1 で削除されています）。

フェーズ 4：ベストプラクティスの評価

best-practices.md を全文読み、要約しないでください。該当する各カテゴリについて、リポジトリを評価してください。すべてのチェック項目がすべてのリポジトリに当てはまるわけではありません。リポジトリのパターン、規模、成熟度に基づいて判断してください。

調査で判明した内容に特に関連するカテゴリに注目してください。

• モノレポですか？構造、ArtifactGenerator の使用状況、依存関係の連鎖を確認します
• ディレクトリ駆動型のモノレポ（ArtifactGenerator の pathPattern と ExternalArtifact プロバイダー）ですか？そのように分類します。アプリごとに手書きの Kustomization がないことは欠落ではなく、意図した設計です
• マルチリポジトリのフリートですか？RBAC、マルチテナンシー、サービスアカウントを確認します
• HelmRelease がありますか？修復、ドリフト検出、バージョン管理を確認します
• valuesFrom または substituteFrom がありますか？参照先の ConfigMap／Secret をリポジトリ内で探し、reconcile.fluxcd.io/watch: "Enabled" ラベルが付いていることを確認します。このラベルがない場合、これらのリソースへの変更は次の間隔まで調整をトリガーしません
• イメージの自動化がありますか？ImagePolicy のセマンティックバージョン範囲と更新パスを確認します
• ResourceSet がありますか？dependsOn の名前空間、wait: true（spec.steps を使用する場合は必須）、Job のアノテーション（force、ttlSecondsAfterFinished を指定しないこと、冪等性がある場合に限り recreateOnFailure）、ステップとアプライヤーのタイムアウトを確認します。ResourceSet Pipelines and Jobs を参照してください
• ArtifactGenerator がありますか？FluxInstance に source-watcher が記載されていることを確認します。また、オーバーレイが ../../base を参照している場合は、pathPattern ジェネレーターがベースとオーバーレイの両方をコピーすることを確認します
• postBuild.substitute または変数用 ConfigMap がありますか？置換される値が YAML インジケーター（>=1.0.0 など）で始まっていないこと、spec.images[].name がベースマニフェストに記述されたイメージ参照と一致すること、substituteFrom の参照先が同じ名前空間に存在することを確認します。Post-Build Substitution を参照してください
• Kustomize オーバーレイがありますか？（記述されている場合は）$bundle を grep して、レンダリング後のリソースを確認します。オーバーレイの patch／images によって実効マニフェストが変わることがあります。行番号は生ファイルから引用してください

類似するリソース間の一貫性も確認してください。たとえば、ある HelmRelease では新しい install.strategy パターンを使い、ほかでは従来の install.remediation.retries を使っている場合は、その不一致を指摘し、新しいパターンに統一するよう提案してください。

YAML の変更を提案する前に、assets/schemas/ のフィールドインデックスを照合し、フィールド名、型、階層が正確であることを確認してください。インデックスファイルは {kind}-{group}-{version}.fields.txt という命名規則に従います（例：helmrelease-helm-v2.fields.txt、kustomization-kustomize-v1.fields.txt）。各行はドット区切りのフィールドパスです。パスのプレフィックスを指定して grep すると、サブツリーを一覧表示できます（例：grep '^spec\.install\.' assets/schemas/helmrelease-helm-v2.fields.txt）。または、フィールド名を grep して、その所在を確認できます。 チェックリストの要約から YAML の構造を推測しないでください。

フェーズ 5：セキュリティレビュー

security-audit.md を最後まで読みます。該当する各カテゴリに照らしてリポジトリを監査します。チェックリストの最後にあるスキャン手順を使用して、よくある問題を見つけます。

調査で見つかった内容に関連性の高いカテゴリを重点的に確認します。

• シークレットがある場合：シークレット管理（SOPS、External Secrets）を確認します
• プライベートソースがある場合：ソース認証と Workload Identity を確認します
• OCI ソースがある場合：サプライチェーンセキュリティ（Cosign による検証、変更不能なタグ）を確認します
• マルチテナントの場合：RBAC、サービスアカウント、名前空間をまたぐ参照、アドミッションポリシーを確認します
• FluxInstance がある場合：オペレーターのセキュリティ設定（マルチテナント、ネットワークポリシー）を確認します
• 名前空間をまたぐ sourceRef がある場合：必ず報告します。重大度はテナント構成によって異なります。マルチテナントのリポジトリでは Critical、単一チームのリポジトリでは Warning、multitenant: false が FluxInstance で明示的に設定され、参照が ResourceSet によって生成される場合（ディレクトリ駆動型モノレポ）に限り Info です
• type: ExternalArtifact の ResourceSetInputProvider がある場合：マルチテナントクラスターでは、serviceAccountName と selectors[].namespace: "*" のスコープを確認します
• イメージ自動化がある場合：プッシュ認証情報の分離とブランチの分離を確認します
• Kustomize オーバーレイがある場合：$bundle（記述されている場合）を grep し、レンダリング後のセキュリティフィールドを確認します。たとえば、オーバーレイパッチによって弱められた securityContext や付け替えられたイメージタグなど、ベースファイルでは確認できないものが該当します

フェーズ 6：レポート

該当する場合は、次のセクションを含む Markdown レポートとして調査結果をまとめます。

1. 概要 — リポジトリ名、リポジトリ URL、分類（パターン名）、クラスター、Flux/K8s リソース数、全体ステータス
2. ディレクトリ構造 — リポジトリの構成と、ディレクトリがクラスター／環境にどう対応するか
3. 検証結果 — エラーが見つかった場合
4. API 準拠状況 — 非推奨 API が見つかった場合は、移行手順を含めます
5. ベストプラクティス — 具体的な調査結果を示し、チェックリストに照らして評価します
6. セキュリティ — シークレット、RBAC、ネットワークポリシー、マルチテナント
7. 推奨事項 — 重大度順：Critical、Warning、Info

Flux CRD リファレンス

YAML の変更を推奨する前に、この表で API バージョンを確認し、フィールドインデックスを grep してください。

コントローラー	Kind	apiVersion	フィールドインデックス
flux-operator	FluxInstance	fluxcd.controlplane.io/v1	fluxinstance-fluxcd-v1.fields.txt
flux-operator	FluxReport	fluxcd.controlplane.io/v1	fluxreport-fluxcd-v1.fields.txt
flux-operator	ResourceSet	fluxcd.controlplane.io/v1	resourceset-fluxcd-v1.fields.txt
flux-operator	ResourceSetInputProvider	fluxcd.controlplane.io/v1	resourcesetinputprovider-fluxcd-v1.fields.txt
source-controller	GitRepository	source.toolkit.fluxcd.io/v1	gitrepository-source-v1.fields.txt
source-controller	OCIRepository	source.toolkit.fluxcd.io/v1	ocirepository-source-v1.fields.txt
source-controller	Bucket	source.toolkit.fluxcd.io/v1	bucket-source-v1.fields.txt
source-controller	HelmRepository	source.toolkit.fluxcd.io/v1	helmrepository-source-v1.fields.txt
source-controller	HelmChart	source.toolkit.fluxcd.io/v1	helmchart-source-v1.fields.txt
source-controller	ExternalArtifact	source.toolkit.fluxcd.io/v1	externalartifact-source-v1.fields.txt
source-watcher	ArtifactGenerator	source.extensions.fluxcd.io/v1beta1	artifactgenerator-source-v1beta1.fields.txt
kustomize-controller	Kustomization	kustomize.toolkit.fluxcd.io/v1	kustomization-kustomize-v1.fields.txt
helm-controller	HelmRelease	helm.toolkit.fluxcd.io/v2	helmrelease-helm-v2.fields.txt
notification-controller	Provider	notification.toolkit.fluxcd.io/v1	provider-notification-v1.fields.txt
notification-controller	Alert	notification.toolkit.fluxcd.io/v1	alert-notification-v1.fields.txt
notification-controller	Receiver	notification.toolkit.fluxcd.io/v1	receiver-notification-v1.fields.txt
image-reflector-controller	ImageRepository	image.toolkit.fluxcd.io/v1	imagerepository-image-v1.fields.txt
image-reflector-controller	ImagePolicy	image.toolkit.fluxcd.io/v1	imagepolicy-image-v1.fields.txt
image-automation-controller	ImageUpdateAutomation	image.toolkit.fluxcd.io/v1	imageupdateautomation-image-v1.fields.txt

参照ファイルの読み込み

より詳しい情報が必要な場合は、参照ファイルを読み込んでください。

• repo-patterns.md — リポジトリの構成を分類するとき、またはパターンをユーザーに説明するとき
• flux-api-summary.md — Flux CRD のフィールドの使い方（ソース、アプライヤー、通知、イメージ自動化）を確認するとき
• flux-operator-api-summary.md — Flux Operator の CRD（FluxInstance、FluxReport、ResourceSet、ResourceSetInputProvider）を確認するとき
• best-practices.md — 運用プラクティスを評価するとき、またはレポートのベストプラクティスのセクションを作成するとき
• security-audit.md — セキュリティレビューの段階で、完全なチェックリストに照らして監査し、スキャン手順を使用するとき
• api-migration.md — 非推奨の API が見つかったときに、レポートに移行手順を含めるため

エッジケース

• Flux リポジトリではない場合：Flux CRD が見つからない場合は、その旨を明確に伝えてください。リポジトリでは ArgoCD、通常の kubectl、または別のツールを使用している可能性があります。無理に Flux の分析に当てはめないでください。
• ツールが混在している場合：Flux と CI ワークフロー、Terraform を組み合わせているリポジトリもあります。Flux の部分を分析し、その他のツールについても記載してください。
• SOPS で暗号化されたシークレット：sops: メタデータブロックを含むファイルは暗号化されています。形式不正な YAML として報告しないでください。検証スクリプトは SOPS メタデータを取り除くため、Secret の残りの部分は引き続き検証できます。
• 生成されたマニフェスト：flux-system/gotk-components.yaml は Flux bootstrap によって自動生成されます。Flux 自体が管理しているため、ベストプラクティスの分析対象にしないでください。
• kustomization.yaml がないリポジトリ：Kustomize を使わず、通常の YAML ディレクトリを使うリポジトリもあります。Flux はこれらを直接調整できます。kustomization.yaml がないことをエラーとして報告しないでください。
• 複数リポジトリの分析：関連する複数のリポジトリ（fleet + infra + apps）の分析を依頼された場合は、それぞれを個別に分析しつつ、リポジトリ間の関係（リポジトリ間の GitRepository/OCIRepository 参照）にも触れてください。
• postBuild の置換変数：${VARIABLE} のパターンを含むファイルでは、Flux の変数置換が使われています。調整時に解決されるため、壊れた YAML として報告しないでください。
• サードパーティの CRD：カタログスキーマのないリソース（例：cert-manager の ClusterIssuer）は「スキップ」と表示されます。これは想定どおりであり、検証の失敗ではありません。
• Kustomize のビルドファイル：apiVersion: kustomize.config.k8s.io/v1beta1 を含む kustomization.yaml ファイルは Kustomize のビルド設定であり、Flux CRD ではありません。