baotoq/argocd-cluster-bootstrapping

ArgoCD Cluster Bootstrapping Skill

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

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

Quick Start

1. Pre-Flight Checklist

# 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. Register Cluster (3 Steps)

# 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. Deploy First Application

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

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) │
└─────────────┘      └─────────────┘      └─────────────┘

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

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 | - |

Cluster Labels (Required)

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

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 |

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

Common Tasks

Add New Dev Cluster

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

Troubleshoot Connectivity

# 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

Safety Rules

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