gitops-workflow

GitOps ワークフロー

ArgoCD と Flux を使用して Kubernetes のデプロイを自動化する GitOps ワークフローの完全ガイドです。

目的

OpenGitOps の原則に従い、ArgoCD または Flux CD を使用して、Kubernetes 向けの宣言型 Git ベースの継続的デリバリーを実装します。

このスキルを使用する場面

• Kubernetes クラスター向けに GitOps をセットアップする場合
• Git からのアプリケーションデプロイを自動化する場合
• プログレッシブデリバリー戦略を実装する場合
• マルチクラスターのデプロイを管理する場合
• 自動同期ポリシーを設定する場合
• GitOps でシークレット管理をセットアップする場合

このスキルを使用しない場面

• 一度限りの手動デプロイが必要な場合
• クラスターへのアクセスやリポジトリの権限を管理できない場合
• Kubernetes にデプロイしない場合

手順

1. リポジトリのレイアウトと望ましい状態の規約を定義します。
2. 変更されない、バージョンを固定した ArgoCD または Flux のインストールを確認し、認可されたクラスターのみを接続します。
3. 同期ポリシー、環境、プロモーションフローを設定します。
4. ロールバックとシークレットの処理を検証します。

安全性

• 承認なしで本番環境への自動同期を有効にしないでください。
• シークレットを Git に含めず、Sealed Secrets または外部シークレットマネージャーを使用してください。
• 書き込み前に、kube context、名前空間、影響を受けるリソース、ロールバックを確認してください。ダウンロードしたマニフェストは適用せずに確認し、確認済みのコミットまたはダイジェストに固定してください。変更される可能性があるリモート YAML を直接適用しないでください。自動同期、prune、force によってリソースが削除または再作成されることがあります。以下のスニペットはそれぞれ個別の例であり、本番環境で実行するコマンドの並びではありません。

OpenGitOps の原則

1. 宣言型 - システム全体を宣言型で記述します
2. バージョン管理され、不変 - 望ましい状態を Git に保存します
3. 自動的にプル - ソフトウェアエージェントが望ましい状態をプルします
4. 継続的に調整 - エージェントが実際の状態と望ましい状態を調整します

ArgoCD のセットアップ

1. インストール

# Create namespace
kubectl create namespace argocd

# Install ArgoCD
# Obtain the selected release manifest, review its complete content, then apply
# the reviewed local file to the authorized context:
kubectl apply -n argocd -f ./reviewed-argocd-install.yaml

# Get admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

参考： 詳細なセットアップについては references/argocd-setup.md を参照してください。

2. リポジトリ構成

gitops-repo/
├── apps/
│   ├── production/
│   │   ├── app1/
│   │   │   ├── kustomization.yaml
│   │   │   └── deployment.yaml
│   │   └── app2/
│   └── staging/
├── infrastructure/
│   ├── ingress-nginx/
│   ├── cert-manager/
│   └── monitoring/
└── argocd/
    ├── applications/
    └── projects/

3. アプリケーションの作成

以下の自動同期／prune の設定は、認可された非本番環境での例です。本番環境では、承認とプロモーションの管理体制が整うまで、自動同期の設定を省略してください。

# argocd/applications/my-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/gitops-repo
    targetRevision: main
    path: apps/production/my-app
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

4. App of Apps パターン

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: applications
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/gitops-repo
    targetRevision: main
    path: argocd/applications
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated: {}

Flux CD のセットアップ

1. インストール

# Install Flux CLI
brew install fluxcd/tap/flux

# Alternative: download the official installer, inspect it, then execute it
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -fsSLo "$tmpdir/flux-install.sh" https://fluxcd.io/install.sh
cat "$tmpdir/flux-install.sh"  # review the full installer before sudo
sudo bash "$tmpdir/flux-install.sh"

# Bootstrap Flux
flux bootstrap github \
  --owner=org \
  --repository=gitops-repo \
  --branch=main \
  --path=clusters/production \
  --personal

2. GitRepository の作成

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/org/my-app
  ref:
    branch: main

3. Kustomization の作成

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  path: ./deploy
  prune: true
  sourceRef:
    kind: GitRepository
    name: my-app

同期ポリシー

自動同期の設定

ArgoCD：

syncPolicy:
  automated:
    prune: true      # Delete resources not in Git
    selfHeal: true   # Reconcile manual changes
    allowEmpty: false
  retry:
    limit: 5
    backoff:
      duration: 5s
      factor: 2
      maxDuration: 3m

Flux：

spec:
  interval: 1m
  prune: true
  wait: true
  timeout: 5m

参考： references/sync-policies.md を参照してください。

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

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

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: my-app
spec:
  replicas: 5
  strategy:
    canary:
      steps:
      - setWeight: 20
      - pause: {duration: 1m}
      - setWeight: 50
      - pause: {duration: 2m}
      - setWeight: 100

ブルーグリーンデプロイ

strategy:
  blueGreen:
    activeService: my-app
    previewService: my-app-preview
    autoPromotionEnabled: false

シークレット管理

External Secrets Operator

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: db-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: aws-secrets-manager
    kind: SecretStore
  target:
    name: db-credentials
  data:
  - secretKey: password
    remoteRef:
      key: prod/db/password

Sealed Secrets

# Encrypt secret
kubeseal --format yaml < secret.yaml > sealed-secret.yaml

# Commit sealed-secret.yaml to Git

ベストプラクティス

1. 環境ごとに別のリポジトリまたはブランチを使用します
2. Git リポジトリに対するRBAC を実装します
3. 同期失敗の通知を有効化します
4. カスタムリソースに対するヘルスチェックを使用します
5. 本番環境に対する承認ゲートを実装します
6. シークレットを Git に含めないでください（External Secrets を使用します）
7. 構成にはApp of Apps パターンを使用します
8. ロールバックを容易にするためにリリースにタグを付けます
9. アラートを使用して同期状態を監視します
10. まずステージング環境で変更をテストします

トラブルシューティング

同期の失敗：

argocd app get my-app
# Inspect diff/health first; pruning is a separately authorized deletion action.

同期されていない状態：

argocd app diff my-app
# Force/replacement sync is not a routine fix; inspect the cause and disruption first.

関連スキル

• k8s-manifest-generator - マニフェストの作成
• helm-chart-scaffolding - アプリケーションのパッケージ化

制限事項

• このスキルは、タスクが上記の説明にある範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、停止して確認を求めてください。