argocd-cluster-bootstrapping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ArgoCD Cluster Bootstrapping Skill

ArgoCD集群引导技能

Complete guide for bootstrapping new Kubernetes clusters into a multi-repository GitOps environment managed by ArgoCD.

本指南详细介绍了如何将新Kubernetes集群引导至由ArgoCD管理的多仓库GitOps环境中。

When to Use This Skill

何时使用本技能

Provisioning a new AKS/EKS/GKE cluster and integrating it with ArgoCD
Registering an existing cluster with the ArgoCD hub
Creating cluster secrets with proper labels for ApplicationSet targeting
Setting up ArgoCD Projects for new business units
Configuring multi-source ApplicationSets for new clusters
Troubleshooting cluster connectivity or sync issues
Understanding the multi-repository GitOps architecture

预配新AKS/EKS/GKE集群并将其与ArgoCD集成
向ArgoCD中心集群注册现有集群
创建带有合适标签的集群密钥，用于ApplicationSet目标定位
为新业务单元创建ArgoCD Project
为新集群配置多源ApplicationSets
排查集群连接或同步问题
了解多仓库GitOps架构

Quick Start

快速开始

1. Pre-Flight Checklist

1. 预检查清单

bash

undefined

bash

undefined

Verify ArgoCD CLI is installed

验证ArgoCD CLI是否已安装

argocd version --client

Verify kubectl access to hub cluster

验证对中心集群的kubectl访问权限

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

undefined

kubectl config use-context <new-cluster-context> kubectl get nodes

undefined

2. Register Cluster (3 Steps)

2. 注册集群（3步骤）

bash

undefined

bash

undefined

Step 1: Add cluster to ArgoCD

步骤1：将集群添加至ArgoCD

argocd cluster add <cluster-context> --name <developer-friendly-name>

argocd cluster add <cluster-context> --name <开发者友好名称>

Step 2: Create cluster secret with labels (GitOps)

步骤2：创建带标签的集群密钥（GitOps方式）

See templates/cluster-secret.yaml

参考templates/cluster-secret.yaml

Step 3: Create ArgoCD Project (GitOps)

步骤3：创建ArgoCD Project（GitOps方式）

See templates/argocd-project.yaml

参考templates/argocd-project.yaml

undefined

undefined

3. Deploy First Application

3. 部署首个应用

bash

undefined

bash

undefined

Sync the master ApplicationSet to pick up new cluster

同步主ApplicationSet以识别新集群

argocd app sync applicationset-master --resource-filter kind=ApplicationSet

undefined

argocd app sync applicationset-master --resource-filter kind=ApplicationSet

undefined

Architecture Overview

架构概述

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

┌─────────────────────────────────────────────────────────────────────┐
│                        中心集群（HUB CLUSTER）                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    ArgoCD Server                             │   │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐│   │
│  │  │ApplicationSet│ │  Projects   │ │    Cluster Secrets     ││   │
│  │  │  Controller  │ │  (RBAC)     │ │  (用于目标定位的标签)││   │
│  │  └─────────────┘ └─────────────┘ └─────────────────────────┘│   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│ 开发集群（DEV Cluster） │      │ 预发布集群（HLG Cluster） │      │ 生产集群（PRD Cluster） │
│  (可使用Spot实例)  │      │  (Staging环境)  │      │ (高可用配置) │
└─────────────┘      └─────────────┘      └─────────────┘

Repository Structure

仓库结构

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

infra-team/                          # 基础设施仓库
├── applicationset/                  # ApplicationSet定义
│   ├── kube-addons/                # 附加组件ApplicationSets
│   └── applications/               # 业务应用ApplicationSets
├── argocd-clusters/                # 集群注册密钥
├── argocd-projects/                # Project定义（RBAC）
└── applicationset-templates/       # 可复用模板

argo-cd-helm-values/                # 值文件仓库（独立安全管控）
└── kube-addons/
    └── <component>/
        └── <cluster-name>/
            └── values.yaml         # 集群专属覆盖配置

Key Concepts

核心概念

Naming Convention (Critical)

命名规范（至关重要）

Context	Developer Name	Azure AKS Name
ArgoCD	`cafehyna-dev`	`aks-cafehyna-dev`
Secrets	Uses developer name	-
Labels	Uses developer name	-

上下文	开发者友好名称	Azure AKS名称
ArgoCD	`cafehyna-dev`	`aks-cafehyna-dev`
密钥	使用开发者友好名称	-
标签	使用开发者友好名称	-

Cluster Labels (Required)

集群标签（必填）

yaml

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

yaml

labels:
  argocd.argoproj.io/secret-type: cluster
  environment: dev|hlg|prd|hub
  region: brazilsouth|eastus2
  cluster-name: <开发者友好名称>
  node-type: spot|standard|mixed
  connection-type: internal|external
  tier: platform|application

Environment Characteristics

环境特性

Environment	Sync Policy	Replicas	Node Type	Prune
dev	Automated	1	Spot OK	Yes
hlg	Manual	2	Mixed	Yes
prd	Manual	3	Standard	No

环境	同步策略	副本数	节点类型	清理（Prune）
dev	自动同步	1	可使用Spot实例	是
hlg	手动同步	2	混合类型	是
prd	手动同步	3	标准类型	否

Reference Documentation

参考文档

Complete Workflow - Step-by-step bootstrapping process
Templates - Ready-to-use YAML templates
Tools & Commands - CLI reference and scripts
Best Practices - Security, troubleshooting, patterns
Architecture Details - Deep dive into the system

完整工作流 - 分步引导流程
模板 - 可直接使用的YAML模板
工具与命令 - CLI参考与脚本
最佳实践 - 安全、排障与模式
架构细节 - 系统深度解析

Common Tasks

常见任务

Add New Dev Cluster

添加新开发集群

bash

undefined

bash

undefined

Use the bootstrap script

使用引导脚本

./scripts/bootstrap-cluster.sh
--name cafehyna-dev-02
--environment dev
--region brazilsouth
--node-type spot

undefined

./scripts/bootstrap-cluster.sh
--name cafehyna-dev-02
--environment dev
--region brazilsouth
--node-type spot

undefined

Troubleshoot Connectivity

排查连接问题

bash

undefined

bash

undefined

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

测试ApplicationSet目标定位

argocd appset get <appset-name> --show-params

undefined

argocd appset get <appset-name> --show-params

undefined

Safety Rules

安全规则

Never use
kubectl apply
on managed clusters - All changes via Git
Always validate before commit - Run
```
pre-commit run --all-files
```
Test in dev first - Promote through hlg before prd
Preserve existing labels - They control ApplicationSet targeting
Use secrets for credentials - Never hardcode in values files

切勿在受管集群上使用
kubectl apply
- 所有变更需通过Git提交
提交前务必验证 - 运行
```
pre-commit run --all-files
```
先在开发环境测试 - 经过预发布环境后再推广至生产环境
保留现有标签 - 这些标签控制ApplicationSet的目标定位
使用密钥存储凭据 - 切勿在值文件中硬编码凭据