argocd-cluster-bootstrapping

ArgoCD クラスターブートストラップスキル

ArgoCD で管理されるマルチリポジトリ GitOps 環境に、新しい Kubernetes クラスターをブートストラップするための完全なガイドです。

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

• 新しい AKS／EKS／GKE クラスターをプロビジョニングし、ArgoCD と統合する場合
• 既存のクラスターを ArgoCD ハブに登録する場合
• ApplicationSet のターゲット指定に適したラベルを付けてクラスターシークレットを作成する場合
• 新しいビジネスユニット向けに ArgoCD プロジェクトを設定する場合
• 新しいクラスター向けにマルチソース ApplicationSet を設定する場合
• クラスターの接続や同期に関する問題をトラブルシューティングする場合
• マルチリポジトリ GitOps アーキテクチャを理解する場合

クイックスタート

1. 事前チェックリスト

# Verify ArgoCD CLI is installed
argocd version --client

# Verify kubectl access to hub cluster
kubectl config use-context aks-cafehyna-default
kubectl get nodes

# Verify access to target cluster
kubectl config use-context <new-cluster-context>
kubectl get nodes

2. クラスターを登録する（3 ステップ）

# Step 1: Add cluster to ArgoCD
argocd cluster add <cluster-context> --name <developer-friendly-name>

# Step 2: Create cluster secret with labels (GitOps)
# See templates/cluster-secret.yaml

# Step 3: Create ArgoCD Project (GitOps)
# See templates/argocd-project.yaml

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

# Sync the master ApplicationSet to pick up new cluster
argocd app sync applicationset-master --resource-filter kind=ApplicationSet

アーキテクチャの概要

┌─────────────────────────────────────────────────────────────────────┐
│                        HUB CLUSTER                                  │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    ArgoCD Server                             │   │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│   │
│  │  │ApplicationSet│ │  Projects   │ │    Cluster Secrets     ││   │
│  │  │  Controller  │ │  (RBAC)     │ │  (Labels for targeting)││   │
│  │  └─────────────┘ └─────────────┘ └─────────────────────────┘│   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│ DEV Cluster │      │ HLG Cluster │      │ PRD Cluster │
│  (Spot OK)  │      │  (Staging)  │      │ (HA Config) │
└─────────────┘      └─────────────┘      └─────────────┘

リポジトリ構成

infra-team/                          # Infrastructure repository
├── applicationset/                  # ApplicationSet definitions
│   ├── kube-addons/                # Add-on ApplicationSets
│   └── applications/               # Business app ApplicationSets
├── argocd-clusters/                # Cluster registration secrets
├── argocd-projects/                # Project definitions (RBAC)
└── applicationset-templates/       # Reusable templates

argo-cd-helm-values/                # Values repository (separate security)
└── kube-addons/
    └── <component>/
        └── <cluster-name>/
            └── values.yaml         # Per-cluster overrides

主な概念

命名規則（重要）

コンテキスト	開発者名	Azure AKS 名
ArgoCD	cafehyna-dev	aks-cafehyna-dev
シークレット	開発者名を使用	-
ラベル	開発者名を使用	-

クラスターラベル（必須）

labels:
  argocd.argoproj.io/secret-type: cluster
  environment: dev|hlg|prd|hub
  region: brazilsouth|eastus2
  cluster-name: <developer-friendly-name>
  node-type: spot|standard|mixed
  connection-type: internal|external
  tier: platform|application

環境の特性

環境	同期ポリシー	レプリカ数	ノードの種類	プルーニング
dev	自動	1	スポット可	あり
hlg	手動	2	混在	あり
prd	手動	3	標準	なし

参考ドキュメント

• ワークフロー全体 - ブートストラップ手順をステップごとに説明
• テンプレート - すぐに使える YAML テンプレート
• ツールとコマンド - CLI リファレンスとスクリプト
• ベストプラクティス - セキュリティ、トラブルシューティング、パターン
• アーキテクチャの詳細 - システムの詳細な解説

よくあるタスク

新しい開発クラスターを追加する

# Use the bootstrap script
./scripts/bootstrap-cluster.sh \
  --name cafehyna-dev-02 \
  --environment dev \
  --region brazilsouth \
  --node-type spot

接続をトラブルシューティングする

# Check cluster health
argocd cluster get <cluster-name>

# Verify secret labels
kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster

# Test ApplicationSet targeting
argocd appset get <appset-name> --show-params

安全ルール

1. 管理対象クラスターでは kubectl apply を絶対に使用しないでください - すべての変更は Git 経由で行います
2. コミット前に必ず検証してください - pre-commit run --all-files を実行します
3. まず開発環境でテストしてください - hlg を経由してから prd に昇格します
4. 既存のラベルを維持してください - ラベルは ApplicationSet のターゲット指定を制御します
5. 認証情報にはシークレットを使用してください - values ファイルに直接記述しないでください