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

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

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

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)

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

argocd-cluster-bootstrapping

Safety Notice

Copy this and send it to your AI assistant to learn