gitops-principles

GitOps の原則スキル

Kubernetes 環境で GitOps の手法を実装するための完全ガイドです。宣言型のインフラストラクチャとアプリケーションの唯一の信頼できる情報源として Git を使用する運用フレームワークです。

GitOps とは？

GitOps は、インフラストラクチャとアプリケーションの望ましい状態を定義するために、Git リポジトリを信頼できる情報源として使用する一連のプラクティスです。自動化されたプロセスにより、本番環境がリポジトリに記述された状態と一致するようにします。

OpenGitOps の定義（CNCF）

GitOps は、OpenGitOps プロジェクト（CNCF の一部）が定めた4 つの基本原則によって定義されています。

原則	説明
1. 宣言型	システム全体を宣言型で記述する必要があります
2. バージョン管理され、不変であること	望ましい状態は、不変性、バージョン管理、保持を保証する方法で保存されます
3. 自動的に取得されること	ソフトウェアエージェントがソースから望ましい状態を自動的に取得します
4. 継続的に調整されること	エージェントが継続的に状態を監視し、望ましい状態の適用を試みます

コアコンセプトのクイックリファレンス

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

┌─────────────────────────────────────────────────────────────────┐
│                        GIT REPOSITORY                           │
│  (Single Source of Truth for Desired State)                    │
├─────────────────────────────────────────────────────────────────┤
│  manifests/                                                     │
│  ├── base/                    # Base configurations             │
│  │   ├── deployment.yaml                                        │
│  │   ├── service.yaml                                           │
│  │   └── kustomization.yaml                                     │
│  └── overlays/                # Environment-specific            │
│      ├── dev/                                                   │
│      ├── staging/                                               │
│      └── production/                                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ Pull (not Push)
┌─────────────────────────────────────────────────────────────────┐
│                      GITOPS CONTROLLER                          │
│  (ArgoCD / Flux / Kargo)                                       │
│  - Continuously watches Git repository                          │
│  - Compares desired state vs actual state                       │
│  - Reconciles differences automatically                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ Apply
┌─────────────────────────────────────────────────────────────────┐
│                    KUBERNETES CLUSTER                           │
│  (Actual State / Runtime Environment)                          │
└─────────────────────────────────────────────────────────────────┘

プッシュモデルとプルモデル

プッシュモデル（従来の CI/CD）	プルモデル（GitOps）
CI システムがクラスターに変更をプッシュします	エージェントが Git から変更を取得します
CI にクラスターの認証情報が必要です	認証情報はクラスター内に保持されます
特定の時点でのデプロイ	継続的な調整
ドリフトが検出されません	ドリフトが自動的に修正されます
手動でのロールバックプロセス	ロールバック = git revert

GitOps の主なメリット

1. 監査可能性：Git の履歴 = デプロイの履歴
2. セキュリティ：クラスターへの外部アクセスが不要です
3. 信頼性：ドリフトを自動的に修正します
4. 速度：PR のマージでデプロイできます
5. ロールバック：簡単な git revert
6. 災害復旧：Git からクラスター全体を再デプロイできます

リポジトリ戦略

モノレポとポリレポ

モノレポ（すべての環境を 1 つのリポジトリに格納）：

gitops-repo/
├── apps/
│   ├── app-a/
│   │   ├── base/
│   │   └── overlays/
│   │       ├── dev/
│   │       ├── staging/
│   │       └── prod/
│   └── app-b/
└── infrastructure/
    ├── monitoring/
    └── networking/

ポリレポ（リポジトリを分離）：

# Repository per concern
app-a-config/          # App A manifests
app-b-config/          # App B manifests
infrastructure/        # Shared infrastructure
cluster-bootstrap/     # Cluster setup

複数リポジトリのパターン（このプロジェクト）

セキュリティ境界のため、インフラストラクチャと値を分離します。

infra-team/                    # Base configurations, ApplicationSets
├── applications/              # ArgoCD Application definitions
└── helm-base-values/          # Default Helm values

argo-cd-helm-values/           # Environment-specific overrides
├── dev/                       # Development values
├── stg/                       # Staging values
└── prd/                       # Production values

メリット：

• リポジトリごとに異なるアクセス制御を設定できます
• 関心事を分離できます
• 環境固有のシークレットを分離できます

ブランチ戦略

環境ブランチ

main ────────────────────────────────────► Production
  │
  └──► staging ──────────────────────────► Staging cluster
         │
         └──► develop ───────────────────► Development cluster

オーバーレイを使用したトランクベース（推奨）

main ────────────────────────────────────► All environments
  │
  ├── overlays/dev/       → Dev cluster
  ├── overlays/staging/   → Staging cluster
  └── overlays/prod/      → Prod cluster

リリースブランチ

main
  │
  ├── release/v1.0 ──────► Production (v1.0)
  ├── release/v1.1 ──────► Production (v1.1)
  └── release/v2.0 ──────► Production (v2.0)

同期ポリシーと戦略

自動同期

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

手動同期（本番環境で推奨）

syncPolicy:
  automated: null     # Require explicit sync

同期オプション

オプション	ユースケース
CreateNamespace=true	存在しない名前空間を自動作成します
PruneLast=true	同期の成功後に削除します
ServerSideApply=true	大きな CRD を処理します
ApplyOutOfSyncOnly=true	パフォーマンスを最適化します
Replace=true	リソースの置き換えを強制します

宣言型の構成パターン

Kustomize パターン

# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patchesStrategicMerge:
  - replica-patch.yaml
images:
  - name: myapp
    newTag: v1.2.3

Helm パターン

# Application pointing to Helm chart
spec:
  source:
    repoURL: https://charts.example.com
    chart: my-app
    targetRevision: 1.2.3
    helm:
      releaseName: my-app
      valueFiles:
        - values.yaml
        - values-prod.yaml

複数ソースのパターン

spec:
  sources:
    - repoURL: https://charts.bitnami.com/bitnami
      chart: nginx
      targetRevision: 15.0.0
      helm:
        valueFiles:
          - $values/nginx/values-prod.yaml
    - repoURL: https://github.com/org/values.git
      targetRevision: main
      ref: values

プログレッシブデリバリーとの統合

GitOps により、プログレッシブデリバリーのパターンを利用できます。

ブルーグリーンデプロイ

# Two applications, traffic shift via Ingress/Service
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-blue
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-green

Argo Rollouts によるカナリアデプロイ

apiVersion: argoproj.io/v1alpha1
kind: Rollout
spec:
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: {duration: 5m}
        - setWeight: 50
        - pause: {duration: 10m}

環境の昇格（Kargo）

Warehouse → Dev Stage → Staging Stage → Production Stage
    │           │              │               │
    └── Freight promotion through environments ───┘

クラウドプロバイダーとの統合

Azure Arc 対応 Kubernetes と AKS

Azure では、Microsoft.ArgoCD クラスター拡張機能を通じて、管理された ArgoCD エクスペリエンスを提供しています。

# Simple installation (single node)
az k8s-extension create \
  --resource-group <rg> --cluster-name <cluster> \
  --cluster-type managedClusters \
  --name argocd \
  --extension-type Microsoft.ArgoCD \
  --release-train preview \
  --config deployWithHighAvailability=false

# Production with workload identity (recommended)
# Use Bicep template - see references/azure-arc-integration.md

主なメリット：

機能	説明
インストールの管理	Azure がデプロイとアップグレードを処理します
ワークロード ID	シークレットを使わずに Azure AD 認証を行います
マルチクラスター	ハイブリッド環境全体で一貫した GitOps を実現します
Azure との統合	ACR、Key Vault、Azure AD をネイティブにサポートします

前提条件：

• Azure Arc に接続されたクラスター、または MSI ベースの AKS クラスター
• Microsoft.KubernetesConfiguration プロバイダーの登録
• k8s-extension CLI 拡張機能のインストール

完全なセットアップガイドについては、references/azure-arc-integration.md を参照してください。

---

セキュリティに関する考慮事項

シークレット管理

シークレットを Git に保存しないでください！ 以下を使用します。

アプローチ	ツール
外部シークレット	External Secrets Operator
Sealed Secrets	Bitnami Sealed Secrets
SOPS	Mozilla SOPS 暗号化
Vault	HashiCorp Vault + CSI
クラウド KMS	AWS/Azure/GCP Key Management

RBAC のベストプラクティス

# Limit ArgoCD to specific namespaces
apiVersion: argoproj.io/v1alpha1
kind: AppProject
spec:
  destinations:
    - namespace: 'team-a-*'
      server: https://kubernetes.default.svc
  sourceRepos:
    - 'https://github.com/org/team-a-*'

ネットワークポリシー

• GitOps コントローラーだけが Git にアクセスできるコンポーネントとなるようにします
• アプリケーションの名前空間からの送信トラフィックを制限します
• ネットワークポリシーを使用して環境を分離します

可観測性とデバッグ

ヘルスステータスの解釈

ステータス	意味	対応
Healthy	すべてのリソースが実行中です	なし
Progressing	デプロイが進行中です	待機します
Degraded	ヘルスチェックに失敗しました	調査します
Suspended	手動で一時停止されています	準備ができたら再開します
Missing	リソースが見つかりません	マニフェストを確認します

よくある問題のチェックリスト

1. Sync Failed：YAML 構文と RBAC 権限を確認します
2. OutOfSync：差分を比較し、ignoreDifferences を確認します
3. Degraded：Pod ログとリソース制限を確認します
4. Missing：名前空間を確認し、プルーニング設定を確認します

ドリフト検出

# Check application diff
argocd app diff myapp

# Force refresh from Git
argocd app get myapp --refresh

選択のためのクイックガイド

GitOps を使用する場面

• Kubernetes ネイティブなワークロード
• 複数の環境（dev/staging/prod）
• デプロイの監査証跡が必要な場合
• インフラストラクチャに関するチームでの共同作業
• 災害復旧の要件

GitOps が適さない場合

• 頻繁に変更される開発環境
• 宣言型設定を使用していないレガシーシステム
• リアルタイムでの設定変更が必要な場合
• 開発者 1 人、環境 1 つの場合

参考資料

詳細については、以下を参照してください。

• references/core-principles.md - 4 つの柱の詳細
• references/patterns-and-practices.md - ブランチとリポジトリのパターン
• references/tooling-ecosystem.md - ArgoCD、Flux、Kargo の比較
• references/anti-patterns.md - 避けるべきよくある間違い
• references/troubleshooting.md - デバッグガイド
• references/azure-arc-integration.md - Azure Arc と AKS の GitOps セットアップ

テンプレート

すぐに使えるテンプレートは templates/ にあります。

• application.yaml - ArgoCD Application の例
• applicationset.yaml - マルチクラスターのデプロイ
• kustomization.yaml - Kustomize オーバーレイの構造

スクリプト

ユーティリティスクリプトは scripts/ にあります。

• gitops-health-check.sh - GitOps のセットアップを検証します

外部リソース

• OpenGitOps の原則
• ArgoCD ドキュメント
• Flux ドキュメント
• Kargo ドキュメント
• GitOps ワーキンググループ
• ArgoCD を使用した Azure Arc GitOps
• Azure Arc 対応 Kubernetes

---

注意点

• selfHeal: true は kubectl edit と競合します： インシデント対応中に稼働中のリソースへパッチを適用すると、数秒以内に変更が元に戻されます。まず自動同期を一時停止するか、修正を Git にコミットしてください。
• モノレポと ApplicationSet の Git ジェネレーターは、コントローラーに大きな負荷をかけます： ディレクトリが変更されるたびに、すべてのアプリが再レンダリングされます。変更の多い main ブランチを持つ 200 アプリのリポジトリでは、コントローラーの CPU 使用率が高止まりする可能性があります。リポジトリを分割するか、ポーリングではなく Webhook を使用してください。
• PruneLast=true は Helm フックと衝突します： フックは同期中に実行され、プルーニングはその後に行われます。ポストインストールフックで作成されたリソースはレンダリング済みマニフェストに含まれないため、次の同期で削除されます。フックに Prune=false をアノテーションとして設定してください。
• ドリフトの修正は、コントローラーが変更を検知できるかどうかに依存します： ArgoCD の追跡対象外のリソース（External Secrets Operator が動的に作成する Secret など）は調整されないため、それらのドリフトは検知されません。明示的に ignoreDifferences を使用してください。
• Sealed Secrets はクラスターにスコープされます： クラスター A 用に暗号化された SealedSecret は、クラスター B では復号できません。マルチクラスターの GitOps にはクラスターごとのキー、または共有キーが必要です（共有キーはセキュリティモデルを損ないます）。
• git revert によるロールバックは、イメージタグが不変であることを前提とします： マニフェストを元に戻すとタグ文字列は元に戻りますが、可変タグ（例：:latest）は別のイメージを指している場合があります。確実にロールバックできるよう、ダイジェストを指定してください。