Contents
ArgoCD と GitOps の基礎
ArgoCD と GitOps を正しく理解すれば、Kubernetes 上でのデプロイ作業が 宣言的かつ自動化 されたフローに変わります。本節では、Git が唯一の真実源（Single Source of Truth）になる仕組みと、ArgoCD がその状態をどのように監視・同期するかを解説します。この記事全体で使用しているバージョンは ArgoCD v2.8.0（公式 Helm chart argo-cd の最新安定版）です。
ArgoCD の概要
ArgoCD は Kubernetes 向けの GitOps エンジンで、Git リポジトリとクラスター状態を常に比較し、差分があれば自動または手動で同期します。
- 宣言的管理：すべてのマニフェストを Git に保存
- 自動同期：
auto-syncを有効化すると差分が即時適用（必要に応じて手動も可） - UI/CLI：Web UI と
argocdCLI が提供する視覚的・操作的な管理インタフェース
GitOps の基本原則
GitOps は「Git が唯一の真実源」という前提で運用し、変更は必ずプルリクエスト（PR）経由で行います。CI がイメージビルドとテストを担当し、ArgoCD がデプロイを担うことで コード → ビルド → デプロイ の一貫したパイプラインが実現します。
- 単一ソース：インフラ定義もアプリケーションコードも同じリポジトリで管理
- 自動化：手作業の介入を最小限に抑えることでヒューマンエラーを削減
- 可観測性：すべての変更が Git のコミット履歴として残り、追跡可能
CI ツールとの連携パターン
CI と ArgoCD を組み合わせると、コード変更から本番デプロイまでを 完全自動化 できます。本章では代表的な CI ツール（GitHub Actions、GitLab CI、Jenkins）ごとにバージョン情報を明示した実装例を示します。使用するツールのバージョンは次の通りです。
| ツール | バージョン |
|---|---|
| GitHub Actions | actions/checkout@v4、docker/build-push-action@v5 |
| GitLab CI | 公式ランナー v16.3 |
| Jenkins | Declarative Pipeline（プラグイン pipeline-github-lib v1.12） |
| ArgoCD CLI | v2.8.0 |
GitHub Actions でのフロー
GitHub Actions はリポジトリ直下に workflow ファイルを書くだけで完結します。以下は ビルド → イメージプッシュ → マニフェスト更新 → ArgoCD 同期 の流れを示すサンプルです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
name: CI/CD Pipeline on: push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: # ソースコード取得（v4 が最新） - name: Checkout code uses: actions/checkout@v4 # Docker Buildx のセットアップ（v2 が推奨） - name: Set up Docker Buildx uses: docker/setup-buildx-action@v2 # イメージのビルド & プッシュ（v5 が最新） - name: Build & push image uses: docker/build-push-action@v5 with: context: . push: true tags: ghcr.io/${{ github.repository }}:${{ github.sha }} # kustomization.yaml のイメージタグを書き換えて Git にコミット - name: Update kustomization.yaml run: | sed -i "s|image:.*|image: ghcr.io/${{ github.repository }}:${{ github.sha }}|" manifests/kustomization.yaml git config --global user.email "ci@example.com" git config --global user.name "CI Bot" git add manifests/kustomization.yaml git commit -m "Update image tag ${{ github.sha }}" git push # ArgoCD の同期をトリガー（公式アクション v2 が推奨） - name: Trigger ArgoCD sync uses: argoproj/argocd-action@v2 with: app-name: my-app namespace: argocd |
ポイント：Git のコミットがトリガーになるため、ArgoCD は常に最新マニフェストを取得し、自動で同期します。
GitLab CI と Jenkins の統合例
GitLab CI と Jenkins を組み合わせると、CI のビルド・プッシュは GitLab が担当し、Jenkins がマニフェスト生成・ArgoCD 同期を行う形が取れます。以下のサンプルは GitLab CI（v16.3） → Jenkins Declarative Pipeline（v2.8.0 の CLI） の流れです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
# .gitlab-ci.yml (GitLab CI) stages: - build - push - trigger-jenkins build: stage: build image: docker:24.0-cli script: - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA . push_image: stage: push image: docker:24.0-cli script: - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA trigger_jenkins: stage: trigger-jenkins image: curlimages/curl:8.5 script: - | curl -X POST \ -F token=$JENKINS_TRIGGER_TOKEN \ -F ref=main \ https://jenkins.example.com/project/manifest-generator |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
// Jenkinsfile (Declarative Pipeline) pipeline { agent any environment { IMAGE_TAG = "${env.GIT_COMMIT}" } stages { stage('Generate Manifest') { steps { script { // kustomization.yaml に新しいイメージタグを書き込む sh """ cat <<EOF > manifests/kustomization.yaml resources: - deployment.yaml images: - name: my-app newTag: ${IMAGE_TAG} EOF """ } // Git 操作は公式プラグインで安全に実行 git url: 'git@github.com:my-org/my-repo.git', credentialsId: 'git-ssh-key' sh 'git add manifests/kustomization.yaml' sh "git commit -m \"Update image tag ${IMAGE_TAG}\"" sh 'git push origin main' } } stage('Sync ArgoCD') { steps { // argocd CLI (v2.8.0) を使用して同期 sh ''' argocd login argocd.example.com --username admin --password $ARGOCD_PWD --insecure argocd app sync my-app --auto-prune ''' } } } } |
ポイント：CI ツールごとに得意領域（ビルド、テスト、マニフェスト生成）を分割し、全体としてシンプルで保守性の高いパイプラインが構築できます。
マルチステージ・マルチクラスター設計
本番とステージングを別クラスターで運用することで障害影響範囲を限定し、リスクヘッジが可能です。本章では ArgoCD ApplicationSet と Kustomize / Helm を組み合わせた実装例を示します。使用している ArgoCD のバージョンは v2.8.0 で、ApplicationSet CRD は argoproj.io/v1alpha1 がデフォルトです。
環境分離とクラスター登録
マルチクラスター構成では、ArgoCD の ConfigMap argocd-cm に各クラスタ情報を記載します。以下は ステージング と 本番 の例です（トークンはシークレット管理で安全に注入してください）。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
apiVersion: v1 kind: ConfigMap metadata: name: argocd-cm namespace: argocd data: clusters: | - name: staging server: https://staging.example.com config: bearerToken: $STAGING_TOKEN # 環境変数で注入 - name: prod server: https://prod.example.com config: bearerToken: $PROD_TOKEN # 同上 |
ApplicationSet と Kustomize の連携例
list generator を用いると、環境ごとの Application オブジェクトを自動生成できます。以下は ステージング / 本番 向けの ApplicationSet 定義です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: myapp-set spec: generators: - list: elements: - cluster: staging namespace: dev overlay: overlays/staging - cluster: prod namespace: prod overlay: overlays/prod template: metadata: name: '{{cluster}}-myapp' spec: project: default source: repoURL: https://github.com/my-org/myapp-config.git targetRevision: HEAD path: . kustomize: # overlay ディレクトリを動的に指定 overlays: - '{{overlay}}' destination: server: 'https://{{cluster}}.example.com' namespace: '{{namespace}}' syncPolicy: automated: prune: true selfHeal: true |
Helm を使う場合のポイント
Helm アプリケーションでも同様に helm.valuesFiles に環境別ファイルを指定します。例として values-staging.yaml と values-prod.yaml を用意し、ApplicationSet のテンプレート内で切り替えます。
|
1 2 3 4 5 |
source: helm: valueFiles: - values-{{cluster}}.yaml # staging / prod に自動展開 |
まとめ：ApplicationSet と Kustomize/Helm を活用すれば、環境ごとの差分管理がコードベースで一元化され、クラスター追加や削除も最小の手間で実現できます。
セキュリティとロールバック戦略
機密情報の漏洩やデプロイ失敗は運用上の大きなリスクです。本章では シークレット管理 と 自動ロールバック のベストプラクティスを、使用ツールのバージョンとともに具体的に示します。利用する Sealed Secrets は v0.20.5（Helm chart sealed-secrets）、External Secrets Operator は v0.9.6 を想定しています。
シークレット管理のベストプラクティス
ArgoCD 自体はシークレットを直接扱わない設計です。代替手段として以下が主流です。
1. Sealed Secrets の運用方法（環境別コントローラ）
Sealed Secrets は コントローラのネームスペース を任意に設定できるため、ステージング・本番で異なる名前空間にデプロイ可能です。Helm でインストールする際は次のように指定します。
|
1 2 3 4 5 |
helm repo add sealed-secrets https://bitnami-labs.github.io/sealed-secrets helm install sealed-secrets sealed-secrets/sealed-secrets \ --namespace kube-system \ # デフォルト（変更可） --set controller.namespace=sealed-secrets-prod # 本番環境例 |
上記のように controller.namespace を環境変数や Helmfile のオーバーライドで切り替えると、環境ごとのコントローラネームスペース が柔軟に設定できます。
シークレット作成手順は以下です（バージョン情報付き）：
|
1 2 3 4 5 6 7 8 9 10 |
# 1. 平文 Secret を作成 kubectl create secret generic db-cred \ --from-literal=username=admin \ --from-literal=password=$(openssl rand -base64 12) \ --dry-run=client -o yaml > db-secret.yaml # 2. Sealed Secrets に変換（コントローラネームスペースを指定） kubeseal --controller-namespace sealed-secrets-prod \ < db-secret.yaml > db-secret.sealed.yaml |
db-secret.sealed.yaml を Git にコミットすれば、対応するクラスターの Sealed Secrets コントローラが自動復号し、通常の Secret として展開します。
2. External Secrets Operator の活用
外部 KMS（AWS Secrets Manager、GCP Secret Manager 等）と連携し、ランタイムでシークレットを取得するパターンです。以下は AWS Secret Store を参照する例です（バージョン v0.9.6）。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
apiVersion: external-secrets.io/v1beta1 kind: SecretStore metadata: name: aws-secret-store spec: provider: aws: service: SecretsManager region: us-east-1 --- apiVersion: external-secrets.io/v1beta1 kind: ExternalSecret metadata: name: api-key spec: secretStoreRef: name: aws-secret-store kind: SecretStore target: name: api-key # 作成される Kubernetes Secret 名 dataFrom: - extract: key: /prod/api/key |
ベストプラクティス：平文シークレットは Git に決して保存せず、必ず Sealed Secrets または ExternalSecrets で暗号化・外部参照を行うこと。
自動ロールバックとヘルスチェック
デプロイ失敗時に自動で前バージョンへ復帰させるには Argo Rollouts と ArgoCD の healthChecks を組み合わせます。使用している Argo Rollouts は v1.7.0 です。
Canary デプロイの設定例（Argo Rollouts）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
apiVersion: argoproj.io/v1alpha1 kind: Rollout metadata: name: myapp-rollout spec: replicas: 3 strategy: canary: steps: - setWeight: 25 - pause: {duration: 5m} - setWeight: 50 - analysis: templates: - templateName: success-rate - pause: {duration: 2m} - setWeight: 100 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: myapp image: ghcr.io/my-org/myapp:${IMAGE_TAG} |
ヘルスチェック用 AnalysisTemplate
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
apiVersion: argoproj.io/v1alpha1 kind: AnalysisTemplate metadata: name: success-rate spec: metrics: - name: success-rate interval: 30s failureLimit: 3 # 連続失敗回数が閾値に達したらロールバック provider: prometheus: address: http://prometheus.monitoring.svc:9090 query: | sum(rate(request_success[1m])) / sum(rate(request_total[1m])) |
failureLimit と interval を本番環境で十分にテストし、失敗判定が早すぎないよう調整してください。これにより、Canary が期待した成功率を下回った場合は自動的に前バージョンへロールバックされます。
運用・可観測性・トラブルシューティング
運用フェーズでは アクセス制御 と モニタリング が鍵となります。本章では RBAC 設計例、Prometheus/Grafana でのメトリクス取得、そしてよくある障害と対策をまとめます。ArgoCD の UI は v2.8.0、Metrics エンドポイントは /metrics（Prometheus フォーマット）です。
RBAC 設計と監査ログ活用
ArgoCD の AppProject でチーム単位の権限を分離し、Kubernetes の RoleBinding と組み合わせます。以下は 開発チーム向け read‑only プロジェクト の例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
apiVersion: argoproj.io/v1alpha1 kind: AppProject metadata: name: dev-team spec: sourceRepos: - https://github.com/my-org/dev-repo.git destinations: - namespace: dev server: '*' clusterResourceWhitelist: - group: '*' kind: '*' roles: - name: read-only description: "Read‑only access for developers" policies: - p, proj:dev-team:read-only, applications, get, *, allow groups: - dev-readers |
監査ログは ArgoCD のサーバー起動時に --loglevel=info を指定し、Kubernetes の audit ポリシーと併せて外部 SIEM（例：Datadog, Splunk）へ転送します。
Prometheus / Grafana による可観測性
ArgoCD が提供する /metrics エンドポイントは標準的な Prometheus メトリクスです。以下の ServiceMonitor を作成すれば、Prometheus Operator が自動で取得できます（バージョン 0.55）。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: argocd-metrics labels: release: prometheus spec: selector: matchLabels: app.kubernetes.io/name: argocd-server endpoints: - port: metrics interval: 30s |
Grafana の公式テンプレート（ID 12169）をインポートすると、同期成功率・エラー数・リソース差分 が一目で把握できます。さらに argocd_app_sync_total や argocd_app_health_status{status="Healthy"} などのクエリで独自ダッシュボードを拡張してください。
よくある落とし穴と対策
| 落とし穴 | 原因 | 推奨対策 |
|---|---|---|
| マニフェストのコンフリクト | 手動でクラスターを変更したまま Git が古い状態に同期しようとする | selfHeal: true を有効化し、手動変更は原則禁止。定期的に argocd app diff で差分確認 |
| シークレットが平文でコミット | Sealed Secrets の生成漏れや CI が失敗した場合 | CI パイプラインで git diff --check と kube-linter を実行し、平文シークレット検出時はビルドを失敗させる |
| ロールバックが機能しない | Rollout の analysis 設定ミスや閾値が緩すぎる | 本番環境で事前に ベンチマークテスト を行い、failureLimit と interval を適切に設定 |
| 監査ログが欠損 | ログローテーション設定不足、永続化ボリューム未設定 | logrotate または Cloud Logging の永続保存ポリシーを導入し、最低 30 日分の保持を確保 |
導入チェックリストと次のアクション
以下の項目を順に確認すれば、設計から本番運用までスムーズに移行できます。完了したら必ず ✔️ を付けて進めましょう。
- [ ] ArgoCD のインストール：Helm (
argo-cdchart v5.48.0) または Kustomize で v2.8.0 をデプロイ - [ ] Git リポジトリ構成の整備：
base/,overlays/staging/,overlays/prod/のディレクトリを作成し、Kustomize または Helm のベースを置く - [ ] CI パイプライン実装：GitHub Actions（v4/v5）または GitLab CI（v16.3）でビルド・プッシュ・マニフェスト更新を自動化
- [ ] ApplicationSet 定義：list generator で環境別
Applicationを自動生成し、selfHealとpruneを有効化 - [ ] シークレット暗号化：Sealed Secrets（v0.20.5）を環境ごとのネームスペースにデプロイ、または External Secrets Operator（v0.9.6）で外部 KMS と連携
- [ ] ロールバック設定：Argo Rollouts（v1.7.0）の Canary デプロイと AnalysisTemplate によるヘルスチェックを有効化
- [ ] RBAC ポリシー：AppProject と Kubernetes RoleBinding で最小権限のアクセス制御を実装
- [ ] 監査ログ収集：ArgoCD の
--loglevel=info設定と K8s audit を SIEM に転送 - [ ] 可観測性基盤：Prometheus ServiceMonitor と Grafana ダッシュボード（ID 12169）を構築し、メトリクスのアラート設定も追加
- [ ] テスト運用：ステージングクラスターでフルサイクルを最低 2 回実施し、差分・ロールバック・監査ログを確認
次のステップ
- GitOps フローの実行：CI がトリガーしたプッシュ → ArgoCD の自動同期が正常に完了することを検証。
- 障害シナリオのシミュレーション：意図的に Canary 失敗させ、ロールバックが期待通りに機能するか確認。
- 運用ドキュメント化：本チェックリストと実装例を社内 Wiki にまとめ、担当者間で共有。
全体まとめ
- ArgoCD v2.8.0 と最新の CI ツール（GitHub Actions@v4, GitLab Runner v16.3, Jenkins Declarative）を組み合わせることで、コード変更から本番デプロイまでのフローが完全自動化できます。
- ApplicationSet + Kustomize/Helm によるマルチクラスター管理は、環境ごとの差分をコードで一元管理でき、スケールアウトも容易です。
- シークレットは Sealed Secrets（環境別ネームスペース） または External Secrets Operator で暗号化・外部参照し、平文コミットを防止します。
- Argo Rollouts の Canary + AnalysisTemplate によるヘルスチェックで失敗時の自動ロールバックを実装し、リスクを最小化できます。
- RBAC、監査ログ、Prometheus/Grafana による可観測性を整備すれば、運用中のトラブルも迅速に検知・対処可能です。
このガイドラインとチェックリストに沿って実装すれば、堅牢かつ拡張性の高い GitOps 基盤が構築できるでしょう。ぜひ本番環境で試し、継続的な改善サイクルを回してください。