ArgoCD Cluster Bootstrapping Skill Skill

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

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

Agent Skills: ArgoCD Cluster Bootstrapping Skill

Skill Files