gitops-principles-skill

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-enabled 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
シールドシークレット	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. 同期の失敗：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-enabled Kubernetes