implementing-gitops

GitOps ワークフロー

Git をインフラストラクチャとアプリケーションの設定における唯一の信頼できる情報源として使用し、宣言型のプルベースデプロイモデルで Kubernetes の GitOps 継続的デリバリーを実装します。

使用する場面

以下の場合に GitOps ワークフローを使用します。

• Kubernetes のデプロイ： Kubernetes クラスターへのアプリケーションとインフラストラクチャのデプロイを自動化する
• マルチクラスター管理： 開発、ステージング、本番、エッジの各クラスターにまたがるデプロイを管理する
• 継続的デリバリー： 自動調整を伴うプルベースの CD パイプラインを実装する
• ドリフト検出： 望ましい状態からの設定ドリフトを自動的に検出して修正する
• 監査要件： コンプライアンスのため、Git コミットを通じて完全な監査証跡を維持する
• 段階的デリバリー： カナリア、ブルーグリーン、またはローリングデプロイ戦略を実装する
• 災害復旧： GitOps のブートストラッププロセスでクラスターを迅速に復旧できるようにする

トリガーキーワード：「Kubernetes にデプロイ」「ArgoCD のセットアップ」「Flux のブートストラップ」「GitOps パイプライン」「環境の昇格」「マルチクラスターのデプロイ」「自動調整」

GitOps の基本原則

1. 唯一の信頼できる情報源としての Git

すべてのシステム設定を Git リポジトリに保存します。手動での kubectl apply やクラスターの変更は行いません。すべての Kubernetes リソース、環境固有のオーバーレイ、インフラストラクチャ設定、アプリケーションのデプロイには、宣言型マニフェスト（YAML）を使用します。

2. プルベースのデプロイ

クラスター内で動作するオペレーターが Git から変更を取得し、自動的に適用します。これにより、CI/CD パイプラインにクラスターの認証情報が不要になり、エアギャップ環境をサポートでき、継続的な調整による自己修復が可能になり、CI/CD が簡素化されます。

3. 自動調整

GitOps オペレーターは、実際のクラスターの状態と Git 内の望ましい状態を継続的に比較し、継続的なループを通じて差異を調整します。Git を監視し、実際の状態を比較し、差異を適用し、ステータスを報告して、これを繰り返します。

4. 宣言型の設定

望ましい状態を定義するには、命令型スクリプトではなく、宣言型の Kubernetes マニフェストを使用します。

ツールの選択

ArgoCD と Flux の比較

判断要因	ArgoCD を選ぶ	Flux を選ぶ
チームの好み	Web UI による視覚的な管理	CLI/API を中心としたワークフロー
学習曲線	UI による導入のしやすさ	学習は難しいものの、柔軟性が高い
アーキテクチャ	モノリシックなステートフルコントローラー	モジュール式のステートレスコントローラー
マルチテナンシー	組み込みの RBAC とプロジェクト	Kubernetes ネイティブの RBAC
リソース使用量	多い（UI コンポーネントを含む）	少ない（最小限のコントローラー）
最適な用途	GitOps への移行	プラットフォームエンジニアリング

ハイブリッドアプローチ： インフラストラクチャには Flux、アプリケーションには ArgoCD を使用するチームもあります。

ArgoCD の実装パターンについては、references/argocd-patterns.md を参照してください。 Flux の実装パターンについては、references/flux-patterns.md を参照してください。 Kustomize のオーバーレイパターンについては、references/kustomize-overlays.md を参照してください。

クイックスタート

ArgoCD のインストール

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

基本的なアプリケーション：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/repo.git
    targetRevision: HEAD
    path: k8s/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Flux のブートストラップ

flux bootstrap github \
  --owner=myorg \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production

基本的な Kustomization：

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: myapp
  namespace: flux-system
spec:
  interval: 10m
  path: "./k8s/prod"
  prune: true
  sourceRef:
    kind: GitRepository
    name: myapp

完全な例については、examples/argocd/ と examples/flux/ を参照してください。

環境の昇格

ブランチベースの戦略： dev ブランチ → staging ブランチ → main ブランチ（本番） Kustomize ベースの戦略： k8s/base/ → k8s/overlays/{dev,staging,prod}/

昇格プロセス：

1. コードの変更を main ブランチにマージする
2. CI でタグ付きコンテナイメージをビルドする
3. 環境オーバーレイのイメージタグを更新する（Git コミット）
4. GitOps オペレーターが変更を検出してデプロイする
5. 環境でテストする
6. Git を更新して次の環境に昇格する

マルチ環境の ApplicationSet パターンについては、references/argocd-patterns.md を参照してください。

マルチクラスター管理

ArgoCD： argocd CLI で外部クラスターを登録し、ApplicationSets を使用してクラスターごとに Application を生成し、単一の ArgoCD インスタンスから管理します。

Flux： クラスターごとに Flux をブートストラップし、クラスター固有のパスを使用して同じ Git リポジトリを共有し、kubeConfig シークレットでリモートクラスターを設定します。

マルチクラスターのパターンについて詳しくは、references/multi-cluster.md を参照してください。

プログレッシブデリバリー

カナリアデプロイ： 新しいバージョンへトラフィックを徐々に移行し、ロールアウト中にメトリクスを監視し、失敗時に自動でロールバックします。

ブルーグリーンデプロイ： 古いバージョンと並行して新しいバージョンをデプロイし、トラフィックを一括で切り替え、問題が検出された場合は即座にロールバックします。

ArgoCD： プログレッシブデリバリーには Argo Rollouts を使用します。 Flux： 自動カナリア分析には Flagger を統合します。

プログレッシブデリバリー戦略と Argo Rollouts の例について詳しくは、references/progressive-delivery.md を参照してください。

シークレット管理

GitOps では設定を Git に保存する必要がありますが、シークレットは保護する必要があります。

ツール	アプローチ	セキュリティ	複雑さ
Sealed Secrets	Git 用にシークレットを暗号化	中	低
SOPS	KMS でファイルを暗号化	高	中
External Secrets	外部の Vault を参照	高	中
HashiCorp Vault	シークレットを一元管理	非常に高	高

シークレット管理の統合パターンについて詳しくは、references/secret-management.md を参照してください。

ドリフトの検出と修復

GitOps オペレーターは、Git（望ましい状態）とクラスター（実際の状態）の差異を継続的に監視します。

ArgoCD の自動セルフヒーリング：

syncPolicy:
  automated:
    prune: true      # Remove resources not in Git
    selfHeal: true   # Revert manual changes

Flux の自動リコンシリエーション：

spec:
  interval: 10m    # Check every 10 minutes
  prune: true      # Remove resources not in Git
  force: true      # Force apply on conflicts

手動操作：

# ArgoCD
argocd app get myapp           # View sync status
argocd app diff myapp          # Show differences
argocd app sync myapp          # Manually trigger sync

# Flux
flux get kustomizations              # View sync status
flux reconcile kustomization myapp   # Force immediate sync

ドリフト検出の戦略とトラブルシューティングについて詳しくは、references/drift-remediation.md を参照してください。

同期フックとライフサイクル

フックを使用して、同期の前後に操作を実行します。

PreSync フック（データベース移行）：

apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded

PostSync フック（スモークテスト）：

apiVersion: batch/v1
kind: Job
metadata:
  annotations:
    argocd.argoproj.io/hook: PostSync

同期フックの完全な例については、examples/argocd/sync-hooks.yaml を参照してください。

モニタリングと可観測性

主なメトリクス

• 同期ステータス： OutOfSync、Synced、Unknown
• 同期頻度： リコンシリエーションの発生頻度
• ドリフト検出： 設定のドリフトを検出するまでの時間
• 同期所要時間： 変更の適用にかかる時間
• 失敗率： 同期の失敗とその原因

ArgoCD メトリクス： /metrics エンドポイントで公開（argocd_app_sync_total、argocd_app_info） Flux メトリクス： コントローラーから取得（gotk_reconcile_condition、gotk_reconcile_duration_seconds）

トラブルシューティング

よくある問題

同期が停止／OutOfSync：

• Git リポジトリにアクセスできることを確認します
• マニフェストが有効な YAML であることを確認します
• 同期ログでエラーを確認します
• リソースのファイナライザーを確認します

セルフヒーリングが機能しない：

• syncPolicy で selfHeal が有効になっていることを確認します
• オペレーターに書き込み権限があることを確認します
• リソースの所有権ラベルを確認します

シークレットを復号できない：

• SOPS／ESO コントローラーがインストールされていることを確認します
• KMS／Vault の認証情報を確認します
• 暗号化キーの設定を確認します

CLI クイックリファレンス

ArgoCD コマンド

argocd app create <name>          # Create application
argocd app get <name>              # View status
argocd app sync <name>             # Trigger sync
argocd app diff <name>             # Show drift
argocd app list                    # List all applications

Flux コマンド

flux create source git <name>      # Create Git source
flux create kustomization <name>   # Create kustomization
flux get all                       # View all resources
flux reconcile <kind> <name>       # Force reconciliation
flux logs                          # View controller logs

Kustomize コマンド

kustomize build k8s/overlays/prod  # Preview generated YAML
kubectl apply -k k8s/overlays/prod # Apply directly
kubectl diff -k k8s/overlays/prod  # Show differences

インストールスクリプト

すばやくセットアップするには、付属のインストールスクリプトを使用してください。

# Install ArgoCD
./scripts/install-argocd.sh

# Bootstrap Flux
export GITHUB_TOKEN=<token>
export GITHUB_OWNER=<org>
export GITHUB_REPO=fleet-infra
./scripts/install-flux.sh

# Check for drift
./scripts/check-drift.sh

# Promote environment
./scripts/promote-env.sh dev staging

サンプルファイル

examples/ ディレクトリに、動作する完全なサンプルが用意されています。

ArgoCD のサンプル：

• examples/argocd/application.yaml - 基本的な Application
• examples/argocd/applicationset.yaml - 複数環境向けの ApplicationSet
• examples/argocd/progressive-rollout.yaml - 段階的なロールアウト戦略
• examples/argocd/sync-hooks.yaml - PreSync/PostSync フック

Flux のサンプル：

• examples/flux/gitrepository.yaml - Git ソースの設定
• examples/flux/kustomization.yaml - Kustomization コントローラー
• examples/flux/helmrelease.yaml - Helm リリース管理
• examples/flux/ocirepository.yaml - OCI アーティファクトソース

Kustomize のサンプル：

• examples/kustomize/base/ - ベース設定
• examples/kustomize/overlays/{dev,staging,prod}/ - 環境オーバーレイ

ロールアウトのサンプル：

• examples/rollouts/canary.yaml - Argo Rollouts によるカナリアデプロイ
• examples/rollouts/blue-green.yaml - ブルーグリーンデプロイ戦略

関連スキル

• kubernetes-operations: Kubernetes の基本とリソース管理
• infrastructure-as-code: GitOps のデプロイ先となるクラスターのプロビジョニング
• building-ci-pipelines: CI でイメージをビルドし、GitOps でデプロイ
• secret-management: GitOps との Vault/ESO 統合
• deploying-applications: デプロイの仕組みとしての GitOps

概要

GitOps は、Git を唯一の信頼できる情報源として、Kubernetes 向けの自動化された宣言的な継続的デリバリーを実現します。UI 主導のワークフローには ArgoCD を、CLI/API を中心としたアプローチには Flux を選択してください。信頼性の高い大規模デプロイのために、自動調整、ドリフト検出、段階的デリバリーを実装します。本番環境に適した GitOps ワークフローを実現するため、シークレット管理、マルチクラスターオーケストレーション、災害復旧を統合します。