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	可使用 Spot	是
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. 先在 dev 中测试 - 经过 hlg 后再推广到 prd
4. 保留现有标签 - 它们用于控制 ApplicationSet 的目标匹配
5. 使用密钥存储凭据 - 切勿将凭据硬编码在 values 文件中