Add blog post: Registering a Spoke Cluster to EKS ArgoCD Capability

Author: hustshawn

content/posts/registering-spoke-cluster-to-eks-argocd-capability.md

@@ -0,0 +1,190 @@
+---
+title: "Registering a Spoke Cluster to EKS ArgoCD Capability"
+date: 2026-01-06T14:39:01+08:00
+draft: false
+description: "Learn how to register spoke clusters to Amazon EKS ArgoCD Capability for multi-cluster GitOps deployments"
+tags: ["kubernetes", "argocd", "eks", "gitops", "aws"]
+categories: ["DevOps"]
+author: "Shawn Zhang"
+showToc: true
+TocOpen: false
+hidemeta: false
+comments: false
+disableHLJS: false
+disableShare: false
+searchHidden: false
+cover:
+    image: "https://d2908q01vomqb2.cloudfront.net/fe2ef495a1152561572949784c16bf23abb28057/2025/12/18/ArgoCD-EKS-Multi-Cluster.drawio.png"
+    alt: "Hub-and-Spoke Architecture for EKS ArgoCD Capability"
+    caption: "Source: AWS Containers Blog"
+    relative: false
+    hidden: false
+---
+
+## Overview
+
+[Amazon EKS Capabilities](https://docs.aws.amazon.com/eks/latest/userguide/capabilities.html) is a set of fully managed cluster features that accelerate developer velocity and offload the complexity of building and scaling with Kubernetes. Among these capabilities, the **ArgoCD Capability** provides a fully managed GitOps continuous deployment solution—eliminating the operational overhead of installing, maintaining, and scaling Argo CD controllers on your clusters.
+
+[Argo CD](https://argo-cd.readthedocs.io/) is a declarative, GitOps continuous delivery tool for Kubernetes. It follows the GitOps pattern where Git repositories serve as the single source of truth for defining the desired application state. Argo CD continuously monitors these repositories and automatically syncs the cluster state to match the desired configuration.
+
+With the EKS ArgoCD Capability, AWS handles scaling, upgrades, and inter-cluster communications, while providing native integrations with services like Amazon ECR, AWS Secrets Manager, and AWS CodeConnections.
+
+### Hub-and-Spoke Architecture
+
+A common deployment pattern is the **hub-and-spoke** topology: the ArgoCD Capability runs on a dedicated central EKS cluster (the hub) that serves as the control plane for GitOps operations, managing deployments to multiple workload clusters (spokes). This provides a single pane of glass to orchestrate deployments across clusters—whether they're in different regions, accounts, or have private API endpoints.
+
+![Hub-and-Spoke Architecture for EKS ArgoCD Capability](https://d2908q01vomqb2.cloudfront.net/fe2ef495a1152561572949784c16bf23abb28057/2025/12/18/ArgoCD-EKS-Multi-Cluster.drawio.png)
+*Figure: Hub-and-spoke topology for EKS ArgoCD Capability (Source: [AWS Containers Blog](https://aws.amazon.com/blogs/containers/deep-dive-streamlining-gitops-with-amazon-eks-capability-for-argo-cd/))*
+
+**This post focuses on registering a spoke cluster to an existing hub cluster with ArgoCD Capability enabled.**
+
+## Prerequisites
+
+- Hub cluster with ArgoCD Capability enabled
+- ArgoCD Capability IAM role ARN (e.g., `ArgoCDCapabilityRole`)
+- kubectl configured for hub cluster
+
+## Step 1: Grant ArgoCD Access to Spoke Cluster
+
+Create an access entry and associate cluster admin policy on the spoke cluster:
+
+```bash
+# Create access entry
+aws eks create-access-entry \
+  --cluster-name <spoke-cluster> \
+  --region <region> \
+  --principal-arn arn:aws:iam::<account-id>:role/ArgoCDCapabilityRole
+
+# Associate cluster admin policy
+aws eks associate-access-policy \
+  --cluster-name <spoke-cluster> \
+  --region <region> \
+  --principal-arn arn:aws:iam::<account-id>:role/ArgoCDCapabilityRole \
+  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
+  --access-scope type=cluster
+```
+
+## Step 2: Create ArgoCD Project
+
+Create a dedicated project for spoke workloads (skip if already exists):
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: AppProject
+metadata:
+  name: spoke-workloads
+  namespace: argocd
+spec:
+  destinations:
+    - namespace: '*'
+      name: <spoke-cluster>  # Add each spoke cluster
+  sourceRepos:
+    - '*'
+  clusterResourceWhitelist:
+    - group: '*'
+      kind: '*'
+  sourceNamespaces:
+    - argocd  # Required for apps in argocd namespace
+```
+
+To add more clusters to an existing project:
+
+```bash
+kubectl patch appproject spoke-workloads -n argocd --type=json \
+  -p='[{"op": "add", "path": "/spec/destinations/-", "value": {"namespace": "*", "name": "<new-spoke-cluster>"}}]'
+```
+
+## Step 3: Register Cluster via Secret
+
+Create a Kubernetes secret to register the spoke cluster:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: <spoke-cluster>
+  namespace: argocd
+  labels:
+    argocd.argoproj.io/secret-type: cluster
+    environment: dev  # Optional: for ApplicationSet selectors
+  annotations:
+    region: <region>  # Optional: metadata
+stringData:
+  name: <spoke-cluster>
+  server: arn:aws:eks:<region>:<account-id>:cluster/<spoke-cluster>
+  project: spoke-workloads
+```
+
+> **Important**: The `server` field must be the EKS cluster ARN, not the Kubernetes API URL or IAM role ARN.
+
+## Step 4: Deploy Application
+
+Create an ArgoCD Application targeting the spoke cluster:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: my-app
+  namespace: argocd
+spec:
+  project: spoke-workloads
+  source:
+    repoURL: https://github.com/org/repo
+    targetRevision: HEAD
+    path: .
+  destination:
+    name: <spoke-cluster>  # Matches the secret name
+    namespace: default
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+```
+
+## Quick Reference
+
+| Field | Value | Note |
+|-------|-------|------|
+| `server` in Secret | EKS cluster ARN | `arn:aws:eks:<region>:<account>:cluster/<name>` |
+| `destination.name` | Cluster secret name | Not the server URL |
+| `sourceNamespaces` | `argocd` | Required in AppProject |
+
+## Troubleshooting
+
+### Application stuck in Unknown status
+
+Check if the project allows the application:
+
+```bash
+kubectl get application <app-name> -n argocd -o jsonpath='{.status.conditions[*].message}'
+```
+
+If you see "not permitted to use project", ensure `sourceNamespaces: [argocd]` is set in the AppProject.
+
+### Cluster not reachable
+
+Verify access entry exists:
+
+```bash
+aws eks list-access-entries --cluster-name <spoke-cluster> --region <region>
+```
+
+Verify access policy is associated:
+
+```bash
+aws eks list-associated-access-policies \
+  --cluster-name <spoke-cluster> \
+  --region <region> \
+  --principal-arn arn:aws:iam::<account-id>:role/ArgoCDCapabilityRole
+```
+
+### Force refresh application
+
+```bash
+kubectl patch application <app-name> -n argocd --type merge \
+  -p '{"metadata":{"annotations":{"argocd.argoproj.io/refresh":"hard"}}}'
+```
+