Architecture
High-Level Overview
┌─────────────┐ ┌─────────┐ ┌──────────────────┐ ┌────────────┐
│ GitHub │────▶│ ArgoCD │────▶│ Kubernetes │────▶│ Services │
│ (GitOps) │ │ │ │ Cluster │ │ (Pods) │
└─────────────┘ └─────────┘ └──────────────────┘ └────────────┘
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ MetalLB │◀── Load Balancer │
│ └────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ Ingress │◀── NGINX │
│ │ Controller│ Controller │
│ └────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ cert- │◀── TLS │
│ │ manager │ Manager │
│ └────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ External │◀── DNS │
│ │ DNS │ (Cloudflare) │
│ └────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ Calico │◀── CNI │
│ │ │ Networking │
│ └────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ Local │◀── Storage │
│ │ Path │ Provisioner │
│ └────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ │
│ │ Prometheus │◀── Monitoring │
│ │ + Grafana │ Stack │
│ └────────────┘ │
Deployment Flow
- Make Changes → Edit Helm charts or application configs in Git
- Push to Git →
git commit && git push - Create Release →
make prepare-releasecreates a Git tag - Deploy →
make deploy ENV=devupdates ArgoCD Application targetRevision - ArgoCD Syncs → Watches tags and automatically applies changes to cluster
Repository Structure
.
├── Makefile # Local development automation
├── charts/ # Helm charts
│ ├── argocd-project/ # AppProject definitions
│ ├── namespace-manager/ # User application chart
│ └── system-apps/ # System applications (ArgoCD Apps)
│ └── templates/ # ArgoCD Application templates
├── cluster/ # Environment-specific configurations
│ ├── dev/
│ │ ├── config.yaml
│ │ └── argocd-values.yaml
│ └── qa/
│ └── config.yaml
├── build/scripts/ # Automation scripts
│ ├── bootstrap.sh # Cluster setup
│ ├── deploy.sh # Deploy via tags
│ └── prepare-release.sh # Create releases
└── docs/ # Documentation
Key Concepts
Environments
Defined in cluster/<env>/config.yaml. Each environment has its own config:
clusterEnv: dev
clusterPath: cluster/dev
apps:
namespace-manager:
enabled: true
destinationNamespace: default
App Types
| Type | Location | Examples |
|---|---|---|
| System Apps | charts/system-apps/templates/ | ArgoCD, cert-manager, MetalLB, NGINX Ingress, External-DNS |
| User Apps | charts/applications/templates/ | Websites, services |
ArgoCD Projects
Defined in charts/argocd-project/values.yaml. Controls what repos and namespaces are allowed.
Release & Deploy Workflow
# 1. Make changes and push
git add . && git commit -m "Add new feature" && git push
# 2. Create release (creates Git tag with commit history)
make prepare-release REPO_ARGS="--repo owner/repo --message 'Release v1.0.0'"
# 3. Deploy to environment
make deploy ENV=dev
Version Behavior
make deploy ENV=dev→ Always jumps to latest tagmake deploy ENV=dev VERSION=v1.0.0→ Uses version comparison (skip if already at that version)make deploy ENV=dev --force→ Force deploy even if same version