gitops-workflows

GitOps ワークフロー

コアワークフロー：GitOps の実装

この判断ツリーを使って、開始地点を決めます。

Do you have GitOps installed?
├─ NO → Need to choose a tool
│   └─ Want UI + easy onboarding? → ArgoCD (Workflow 1)
│   └─ Want modularity + platform engineering? → Flux (Workflow 2)
└─ YES → What's your goal?
    ├─ Sync issues / troubleshooting → Workflow 7
    ├─ Multi-cluster deployment → Workflow 4
    ├─ Secrets management → Workflow 5
    ├─ Progressive delivery → Workflow 6
    ├─ Repository structure → Workflow 3
    └─ Tool comparison → Read references/argocd_vs_flux.md

---

1. 初期セットアップ：ArgoCD 3.x

最新バージョン：v3.1.9（安定版）、v3.2.0-rc4（2025 年 10 月）

クイックインストール

# Create namespace
kubectl create namespace argocd

# Install ArgoCD 3.x
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.1.9/manifests/install.yaml

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

# Port forward to access UI
kubectl port-forward svc/argocd-server -n argocd 8080:443
# Access: https://localhost:8080

→ テンプレート：assets/argocd/install-argocd-3.x.yaml

ArgoCD 3.x の主な変更点

• 破壊的変更：アノテーションベースの追跡（デフォルト。従来はラベル）、RBAC ログの適用を有効化、レガシーメトリクスを削除
• 新機能：きめ細かな RBAC（リソース単位の権限）、改善されたデフォルト設定（リソースの除外）、シークレットオペレーターの推奨

最初のアプリケーションをデプロイする

# CLI method
argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

# Sync application
argocd app sync guestbook

ヘルスチェック

# List all applications and their sync/health status
argocd app list

# Get detailed status for a specific application
argocd app get <app-name>

# Check applications via kubectl (no ArgoCD CLI needed)
kubectl get applications.argoproj.io -A

---

2. 初期セットアップ：Flux 2.7

最新バージョン：v2.7.1（2025 年 10 月）

クイックインストール

# Install Flux CLI
brew install fluxcd/tap/flux  # macOS
# or: curl -s https://fluxcd.io/install.sh | sudo bash

# Check prerequisites
flux check --pre

# Bootstrap Flux (GitHub)
export GITHUB_TOKEN=<your-token>
flux bootstrap github \
  --owner=<org> \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production \
  --personal

# Enable source-watcher (Flux 2.7+)
flux install --components-extra=source-watcher

→ テンプレート：assets/flux/flux-bootstrap-github.sh

Flux 2.7 の新機能

• ✅ イメージ自動化が GA に
• ✅ ExternalArtifact および ArtifactGenerator API
• ✅ パフォーマンスを向上させる source-watcher コンポーネント
• ✅ OpenTelemetry のトレーシングをサポート
• ✅ 準備状況の評価に CEL 式を使用

最初のアプリケーションをデプロイする

# gitrepository.yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/stefanprodan/podinfo
  ref:
    branch: master
---
# kustomization.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 5m
  path: "./kustomize"
  prune: true
  sourceRef:
    kind: GitRepository
    name: podinfo

ヘルスチェック

# Check all Flux resources across namespaces
flux get all -A

# Check Git sources
flux get sources git

# Check kustomization status
flux get kustomizations

---

3. リポジトリ構造の設計

判断：モノレポかポリレポか？

モノレポパターン

最適な用途：スタートアップ、小規模チーム（アプリ数 20 未満）、単一チーム

gitops-repo/
├── apps/
│   ├── frontend/
│   ├── backend/
│   └── database/
├── infrastructure/
│   ├── ingress/
│   ├── monitoring/
│   └── secrets/
└── clusters/
    ├── dev/
    ├── staging/
    └── production/

ポリレポパターン

最適な用途：大規模な組織、複数のチーム、明確な境界

infrastructure-repo/     (Platform team)
app-team-1-repo/        (Team 1)
app-team-2-repo/        (Team 2)

環境構造（Kustomize）

app/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── replica-patch.yaml
    ├── staging/
    └── production/

→ 参考資料：references/repo_patterns.md | → スクリプト：python3 scripts/validate_gitops_repo.py /path/to/repo

---

4. マルチクラスターのデプロイ

ArgoCD ApplicationSets

クラスタージェネレーター（すべてのクラスターにデプロイ）：

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-apps
spec:
  generators:
  - cluster:
      selector:
        matchLabels:
          environment: production
  template:
    metadata:
      name: '{{name}}-myapp'
    spec:
      source:
        repoURL: https://github.com/org/apps
        path: myapp
      destination:
        server: '{{server}}'

→ テンプレート：assets/applicationsets/cluster-generator.yaml

パフォーマンス上の利点：デプロイが 83% 高速化（30 分 → 5 分）

ApplicationSets を生成する

# Cluster generator
python3 scripts/applicationset_generator.py cluster \
  --name my-apps \
  --repo-url https://github.com/org/repo \
  --output appset.yaml

# Matrix generator (cluster x apps)
python3 scripts/applicationset_generator.py matrix \
  --name my-apps \
  --cluster-label production \
  --directories app1,app2,app3 \
  --output appset.yaml

→ スクリプト：scripts/applicationset_generator.py

Flux マルチクラスター

ハブアンドスポーク：管理クラスターがすべてのクラスターを管理します

# Bootstrap each cluster
flux bootstrap github --context prod-cluster --path clusters/production
flux bootstrap github --context staging-cluster --path clusters/staging

→ 参考資料：references/multi_cluster.md

---

5. シークレット管理

プレーンテキストのシークレットを Git にコミットしないでください。 解決策を選択します。

判断マトリクス

ソリューション	複雑さ	最適な用途	2025 年の傾向
SOPS + age	中	Git 中心、柔軟性	↗️ 推奨
External Secrets Operator	中	クラウドネイティブ、動的	↗️ 拡大中
Sealed Secrets	低	シンプル、GitOps 優先	→ 安定

オプション 1：SOPS + age（2025 年推奨）

セットアップ：

# Generate age key
age-keygen -o key.txt
# Public key: age1...

# Create .sops.yaml
cat <<EOF > .sops.yaml
creation_rules:
  - path_regex: .*.yaml
    encrypted_regex: ^(data|stringData)$
    age: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
EOF

# Encrypt secret
kubectl create secret generic my-secret --dry-run=client -o yaml \
  --from-literal=password=supersecret > secret.yaml
sops -e secret.yaml > secret.enc.yaml

# Commit encrypted version
git add secret.enc.yaml .sops.yaml

→ テンプレート：assets/secrets/sops-age-config.yaml

オプション 2：External Secrets Operator（v0.20+）

最適な用途：クラウドネイティブアプリ、動的なシークレット、自動ローテーション

オプション 3：Sealed Secrets

最適な用途：シンプルなセットアップ、静的なシークレット、外部依存関係なし

→ 参考資料：references/secret_management.md

シークレットを監査する

python3 scripts/secret_audit.py /path/to/repo

→ スクリプト：scripts/secret_audit.py

---

6. 段階的デリバリー

Argo Rollouts（ArgoCD と連携）

カナリアデプロイ：

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

→ テンプレート：assets/progressive-delivery/argo-rollouts-canary.yaml

Flagger（Flux と連携）

メトリクス分析を伴うカナリア：

apiVersion: flagger.app/v1beta1
kind: Canary
metadata:
  name: my-app
spec:
  analysis:
    interval: 1m
    threshold: 5
    maxWeight: 50
    stepWeight: 10
    metrics:
    - name: request-success-rate
      thresholdRange:
        min: 99

→ 参考資料：references/progressive_delivery.md

---

7. トラブルシューティング

よくある問題

ArgoCD の OutOfSync：

# Check differences
argocd app diff my-app

# Sync application
argocd app sync my-app

# Check health
argocd app list
argocd app get my-app

Flux がリコンサイルしない：

# Check resources
flux get all

# Check specific kustomization
flux get kustomizations
kubectl describe kustomization my-app -n flux-system

# Force reconcile
flux reconcile kustomization my-app

ドリフトを検出する：

# ArgoCD drift detection
argocd app diff my-app

# Kubernetes manifest drift detection
kubectl diff -f <manifest.yaml>

→ 参考資料：references/troubleshooting.md

---

8. OCI アーティファクト（Flux 2.6 以降、2025 年 6 月に GA）

Helm チャートに OCIRepository を使用する

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
  name: podinfo-oci
spec:
  interval: 5m
  url: oci://ghcr.io/stefanprodan/charts/podinfo
  ref:
    semver: ">=6.0.0"
  verify:
    provider: cosign

→ テンプレート：assets/flux/oci-helmrelease.yaml

OCI アーティファクトを検証する

# Check OCI sources managed by Flux
flux get sources oci

# Get detailed OCI repository status via kubectl
kubectl get ocirepository -A -o json

→ リファレンス：references/oci_artifacts.md

クイックリファレンスコマンド

ArgoCD

argocd app list                    # List applications
argocd app get <app-name>          # Get application details
argocd app sync <app-name>         # Sync application
argocd app diff <app-name>         # View diff
argocd app delete <app-name>       # Delete application

Flux

flux check                                    # Check Flux status
flux get all                                  # Get all resources
flux reconcile source git <name>              # Reconcile immediately
flux reconcile kustomization <name>           # Reconcile kustomization
flux suspend kustomization <name>             # Suspend
flux resume kustomization <name>              # Resume
flux export source git --all > sources.yaml   # Export resources

リソースの概要

スクリプト：applicationset_generator.py | secret_audit.py | validate_gitops_repo.py

リファレンス：argocd_vs_flux.md | repo_patterns.md | secret_management.md | progressive_delivery.md | multi_cluster.md | troubleshooting.md | best_practices.md | oci_artifacts.md

テンプレート：argocd/install-argocd-3.x.yaml | applicationsets/cluster-generator.yaml | flux/flux-bootstrap-github.sh | flux/oci-helmrelease.yaml | secrets/sops-age-config.yaml | progressive-delivery/argo-rollouts-canary.yaml