name: argocd-cluster-bootstrapping
description: Complete ArgoCD cluster bootstrapping skill for multi-repository GitOps environments. Use when provisioning new Kubernetes clusters, registering clusters with ArgoCD, configuring ApplicationSets, setting up cluster secrets, or troubleshooting cluster connectivity issues.

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)

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

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