Skip to main content

​
Overview

With EKS clusters deployed and cluster access configured, the next step is to bootstrap ArgoCD and deploy the Kubernetes baseline components. ArgoCD uses an app-of-apps pattern to manage all cluster resources declaratively.
Before proceeding, ensure you have kubectl access to the cluster. See Cluster Access for setup instructions.

​
Architecture

The kit uses a three-tier app-of-apps pattern: 
argocd-app-of-apps (root)
├── argocd                    → Self-manages ArgoCD installation
├── infrastructure-app-of-apps → Manages infrastructure components
│   ├── cert-manager
│   ├── traefik
│   ├── external-secrets
│   ├── external-dns
│   ├── karpenter
│   ├── cloudnative-pg
│   ├── signoz-k8s-infra
│   └── reloader
└── services-app-of-apps      → Manages application deployments
    ├── go-backend
    └── go-backend-helm
Each ArgoCD Application points to rendered manifests in kubernetes/rendered/{cluster}/.

​
Update Repository URLs

Before deploying, update the Git repository URLs to point to your fork:
1

Update ArgoCD application sources

The Application manifests reference the Git repository. Update the repoURL in the source templates:kubernetes/src/argocd/argocd/templates/Application.argocd-app-of-apps.yaml:
spec:
  source:
    repoURL: "git@github.com:<YOUR_ORG>/<your-repo>.git"  # Update this
    targetRevision: main
    path: kubernetes/rendered/{{ .Values.cluster }}/argocd/argocd
Update this URL in all Application templates:
  • kubernetes/src/argocd/argocd/templates/Application.*.yaml
  • kubernetes/src/argocd/infrastructure/templates/Application.GENERATOR.yaml
  • kubernetes/src/argocd/services/templates/Application.GENERATOR.yaml
2

Render updated manifests

After updating the source files, render the manifests for your cluster:
mise run //kubernetes/src/argocd:render-all staging
mise run //kubernetes/src/infrastructure:render-all staging
mise run //kubernetes/src/services:render-all staging
Replace staging with production for production clusters.
3

Commit the changes

git add .
git commit -m "chore: update ArgoCD repository URLs for fork"
git push

​
Create Deploy Key

ArgoCD needs SSH access to clone your private repository. Run the bootstrap task to generate a deploy key and create the Kubernetes secret:
1

Generate deploy key and create secret

cd kubernetes/bootstrap
mise run create-deploy-key "git@github.com:<YOUR_ORG>/<your-repo>.git"
2

Add the public key to GitHub

The command outputs the public key. Add it to your repository:
  1. Go to your repository Settings → Deploy keys
  2. Click Add deploy key
  3. Title: ArgoCD Deploy Key
  4. Paste the public key from the command output
  5. Leave Allow write access unchecked (read-only is sufficient for GitOps)
  6. Click Add key
The private key is stored as a Kubernetes Secret (repo-kube-starter-kit) in the argocd namespace. ArgoCD automatically discovers it via the argocd.argoproj.io/secret-type=repository label.

​
Configure GitHub OAuth (Optional)

If you want to enable GitHub OAuth for ArgoCD login (recommended for production), you need to store the OAuth app secret in AWS Secrets Manager.
1

Create a GitHub OAuth App

  1. Go to your GitHub organization Settings → Developer settings → OAuth Apps
  2. Click New OAuth App
  3. Fill in the details:
    • Application name: ArgoCD Staging
    • Homepage URL: https://argocd.staging.<YOUR_DOMAIN>
    • Authorization callback URL: https://argocd.staging.<YOUR_DOMAIN>/api/dex/callback
  4. Click Register application
  5. Generate a new client secret and save both the Client ID and Client Secret
2

Store the secret in AWS Secrets Manager

export REGION="us-east-2"  # Your AWS region
export CLUSTER_NAME="<your-cluster-name>"

aws secretsmanager create-secret \
  --name "${CLUSTER_NAME}-argocd-github-dex" \
  --secret-string '{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}' \
  --region ${REGION}
See the ArgoCD Dex documentation for more details on SSO configuration.

​
Bootstrap ArgoCD

Only ArgoCD itself needs to be manually deployed. Once running, ArgoCD will deploy and manage all other infrastructure components automatically. 
cd kubernetes/bootstrap
mise run install-argocd staging
This task:
  1. Applies ArgoCD manifests (handles CRD ordering automatically)
  2. Waits for ArgoCD deployments to be ready
  3. Applies AppProjects
  4. Applies Applications
ArgoCD will then automatically deploy all infrastructure components (cert-manager, external-secrets, external-dns, traefik, etc.) and services.

​
Verify Bootstrap

1

Verify deploy key secret exists

The deploy key secret should have been created by the bootstrap task:
kubectl get secrets -n argocd | grep repo-kube-starter-kit
2

Verify ArgoCD can sync

Check the ArgoCD Applications:
kubectl get applications -n argocd
You should see:
  • argocd-app-of-apps - Synced
  • infrastructure-app-of-apps - Synced
  • services-app-of-apps - Synced
From here, ArgoCD manages everything automatically.
It may take several minutes for all applications to become healthy as reconciliation loops complete. During this time:
  • Infrastructure components are deployed and start up
  • External Secrets syncs secrets from AWS Secrets Manager
  • Pods restart to pick up new secrets/configurations
  • External DNS creates DNS records
  • Cert Manager issues TLS certificates
You can monitor progress in the ArgoCD UI or by running kubectl get applications -n argocd.

​
Access ArgoCD UI

Once external-dns creates the DNS records, ArgoCD is accessible at https://argocd.<environment>.<YOUR_DOMAIN> (e.g., https://argocd.staging.example.com). Alternatively, use port-forwarding for immediate access: 
kubectl port-forward svc/argocd-server -n argocd 8080:443
Open https://localhost:8080 in your browser.

​
Login

If you configured GitHub OAuth, use the Log in via GitHub button. Otherwise, use the admin password: 
kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath="{.data.password}" | base64 -d
Login with username admin and the retrieved password.
The admin user is enabled by default for initial bootstrap and debugging. Once you’ve configured SSO (GitHub OAuth), consider disabling the admin user by setting admin.enabled: "false" in kubernetes/src/infrastructure/argocd/values.yaml.

​
Infrastructure Components

The following components are included in the Kubernetes baseline:
ComponentBootstrapPurpose
argocdManualGitOps continuous delivery
cert-managerArgoCDTLS certificate automation with Let’s Encrypt
external-secretsArgoCDSyncs secrets from AWS Secrets Manager
external-dnsArgoCDAutomatic DNS record management in Route53
traefikArgoCDIngress controller for routing external traffic
karpenterArgoCDDynamic node provisioning and autoscaling
cloudnative-pgArgoCDPostgreSQL operator for in-cluster databases
signoz-k8s-infraArgoCDOpenTelemetry collectors for observability
reloaderArgoCDRestarts pods when ConfigMaps/Secrets change
ebs-csi-driver-resourcesArgoCDStorageClass for encrypted EBS volumes
Only ArgoCD is deployed manually during bootstrap. All other components are deployed automatically by ArgoCD once it syncs with the repository.

​
Verify Deployment

1

Check all Applications are synced

kubectl get applications -n argocd
All applications should show Synced and Healthy status.
2

Verify infrastructure pods

kubectl get pods -n cert-manager
kubectl get pods -n traefik
kubectl get pods -n external-secrets
kubectl get pods -n karpenter
All pods should be Running.
3

Check ingress is working

kubectl get ingress -A
Ingresses should have an ADDRESS assigned (the load balancer DNS name).
4

Verify DNS records

Once external-dns is running, check Route53 for new records:
aws route53 list-resource-record-sets \
  --hosted-zone-id "<your-zone-id>" \
  --query "ResourceRecordSets[?Type=='A' || Type=='CNAME']"

​
Enable/Disable Components

To enable or disable infrastructure components, edit kubernetes/src/argocd/infrastructure/values.yaml: 
applications:
  argocd:
    enabled: true
  cert-manager:
    enabled: true
  cloudnative-pg:
    enabled: true
  envoy-gateway:
    enabled: false  # Disabled by default
  # ... other components
After changing, render and push: 
mise run //kubernetes/src/infrastructure:render-all "<CLUSTER>"
git add . && git commit -m "chore: enable/disable components"
git push
ArgoCD will automatically sync the changes.

​
Next Steps

With the Kubernetes baseline deployed, proceed to Local Development Setup to set up KinD, Tilt, and mirrord for local development.