Claude CodeでArgoCD GitOpsを設計する：自動デプロイ・差分検知・ロールバック

#claudecode #kubernetes #devops #argocd

Claude CodeでArgoCD GitOpsを設計する：自動デプロイ・差分検知・ロールバック

ArgoCDを使ったGitOpsは、Kubernetesのデプロイ管理をコードで完全に制御できる強力な手法です。本記事では、Claude Codeを活用してArgoCDの設計・実装を効率的に進める方法を解説します。

CLAUDE.mdルールで設計原則を定義する

Claude Codeで開発する際、CLAUDE.mdにGitOps設計のルールを明示することが重要です。

# GitOps設計ルール

## リポジトリ分離
- アプリコード: app-repo（開発者が変更）
- 設定リポジトリ: config-repo（ArgoCDが参照）
- 2つを絶対に混在させない

## 環境別デプロイ戦略
- dev: 自動同期（auto-sync有効）、imageタグ自動更新
- staging: 自動同期、本番相当の設定でテスト
- prod: 手動承認必須、SyncWaveでDB移行を先行実行

## SyncWave順序
1. Wave 0: Namespace, RBAC, Secret
2. Wave 1: DB Migration Job (PreSync Hook)
3. Wave 2: Deployment, Service
4. Wave 3: Ingress, HPA

このCLAUDE.mdを読み込ませることで、Claude Codeが設計原則に沿ったYAMLを生成してくれます。

ApplicationSet YAML（dev/staging/prod 3環境）

ApplicationSetを使うと、1つのテンプレートから3環境分のApplicationを自動生成できます。

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp-applicationset
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: dev
            cluster: https://kubernetes.default.svc
            namespace: myapp-dev
            autoSync: "true"
            selfHeal: "true"
          - env: staging
            cluster: https://staging-cluster.example.com
            namespace: myapp-staging
            autoSync: "true"
            selfHeal: "true"
          - env: prod
            cluster: https://prod-cluster.example.com
            namespace: myapp-prod
            autoSync: "false"
            selfHeal: "false"
  template:
    metadata:
      name: 'myapp-{{env}}'
      annotations:
        notifications.argoproj.io/subscribe.on-sync-succeeded.slack: deployments
    spec:
      project: default
      source:
        repoURL: https://github.com/myorg/config-repo
        targetRevision: HEAD
        path: 'envs/{{env}}'
      destination:
        server: '{{cluster}}'
        namespace: '{{namespace}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: '{{selfHeal}}'
        syncOptions:
          - CreateNamespace=true
          - ServerSideApply=true
        retry:
          limit: 3
          backoff:
            duration: 10s
            factor: 2
            maxDuration: 3m

ポイント：

devとstagingはautoSync: trueで自動反映
prodはautoSync: falseにして手動承認ゲートを設ける
selfHeal: trueでクラスタの手動変更を自動で元に戻す（prod除く）

GitHub Actions：config-repoのimageタグ自動更新

アプリのビルド完了後、config-repo側のimageタグを書き換えるワークフローです。

# .github/workflows/update-image-tag.yml（app-repo側）
name: Build and Update Image Tag

on:
  push:
    branches: [main]

env:
  IMAGE_NAME: ghcr.io/myorg/myapp
  CONFIG_REPO: myorg/config-repo

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    outputs:
      image_tag: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4

      - name: Generate image tag
        id: meta
        run: echo "version=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT

      - name: Build and push Docker image
        run: |
          docker build -t $IMAGE_NAME:${{ steps.meta.outputs.version }} .
          docker push $IMAGE_NAME:${{ steps.meta.outputs.version }}

  update-config-repo:
    needs: build-and-push
    runs-on: ubuntu-latest
    steps:
      - name: Checkout config-repo
        uses: actions/checkout@v4
        with:
          repository: ${{ env.CONFIG_REPO }}
          token: ${{ secrets.CONFIG_REPO_TOKEN }}

      - name: Update image tag (dev)
        run: |
          IMAGE_TAG=${{ needs.build-and-push.outputs.image_tag }}
          cd envs/dev
          kustomize edit set image $IMAGE_NAME:$IMAGE_TAG

      - name: Commit and push
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "chore: update myapp image tag to ${{ needs.build-and-push.outputs.image_tag }}"
          git push

フロー：

app-repoへのpushでDockerイメージをビルド
config-repo内のenvs/dev/kustomization.yamlのimageタグを書き換え
ArgoCDがconfig-repoの変化を検知して自動同期

staging/prodへの昇格は、別のワークフローまたはPRベースで管理します。

SyncWave + PreSync Job でDBマイグレーションを安全に実行

アプリのデプロイ前にDBスキーマを移行するには、SyncWaveとPreSync Hookを組み合わせます。

# db-migration-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
    argocd.argoproj.io/sync-wave: "1"
spec:
  backoffLimit: 3
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migration
          image: ghcr.io/myorg/myapp:latest
          command: ["python", "manage.py", "migrate", "--noinput"]
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: url
      initContainers:
        - name: wait-for-db
          image: busybox
          command:
            - sh
            - -c
            - |
              until nc -z postgres-service 5432; do
                echo "Waiting for DB..."
                sleep 2
              done

# deployment.yaml（Wave 2で実行）
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  annotations:
    argocd.argoproj.io/sync-wave: "2"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: ghcr.io/myorg/myapp:latest
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5

SyncWave実行順序：

Wave 1（PreSync）: db-migration Job
  ↓ Job完了を待機
Wave 2: Deployment, Service
  ↓
Wave 3: Ingress, HPA

Migration Jobが失敗した場合、ArgoCDはSyncを中断してDeploymentを更新しません。アトミックなデプロイを実現します。

ロールバック戦略

ArgoCDのロールバックはGitのrevertと連動します。

# CLIでの手動ロールバック
argocd app history myapp-prod
# ID  DATE       REVISION
# 3   2026-03-11 abc1234
# 2   2026-03-10 def5678  ← これに戻す

argocd app rollback myapp-prod 2

自動ロールバック（Argo Rollouts連携）：

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: myapp
spec:
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: {duration: 5m}
        - setWeight: 50
        - pause: {duration: 5m}
        - setWeight: 100
      analysis:
        templates:
          - templateName: error-rate-check
        startingStep: 1
        args:
          - name: service-name
            value: myapp-canary

エラーレートが閾値を超えた場合、Rolloutは自動的にカナリアをゼロにロールバックします。

まとめ

ApplicationSetを使うと、1つのYAMLテンプレートでdev/staging/prodの3環境を管理でき、環境ごとの差分（autoSync有無など）をgeneratorsで表現できる
Image Updater / GitHub Actionsでapp-repoのビルド結果をconfig-repoに自動反映し、GitOpsの「唯一の真実はGit」原則を守った自動化パイプラインを構築できる
SyncWaveとPreSync Hookの組み合わせでDBマイグレーションをDeployment前に確実に実行し、Migrationが失敗したらデプロイを止めるアトミックなデプロイを実現できる
Claude CodeにCLAUDE.mdで設計原則を与えることで、リポジトリ分離・環境別戦略・Wave順序といったGitOpsのベストプラクティスに沿ったYAMLを一貫して生成させることができる