Deployment Flow

This document explains the complete GitOps deployment flow from code change to running application.

Overview

Two Deployment Modes

Mode 1: Local Deploy (Development)

Bypasses ArgoCD, deploys directly via Helm:

make deploy-app ENV=dev APP=namespace-manager

Flow:

1. Makefile calls build/scripts/deploy.sh
2. Script renders Helm templates locally
3. Applies manifests directly via kubectl apply
4. No Git tag required

note

Use this mode for rapid development and testing. For production, use GitOps mode.

Mode 2: GitOps Deploy (Production)

Uses Git tags + ArgoCD for automated sync:

# 1. Make changes and commit
git add . && git commit -m "Add feature" && git push

# 2. Create release tag
make prepare-release REPO_ARGS="--repo owner/repo --message 'Release v1.0.0'"

# 3. Deploy to environment
make deploy ENV=dev

Flow:

1. prepare-release.sh validates changes and creates Git tag
2. deploy.sh fetches latest tag and updates ArgoCD Application
3. ArgoCD detects change and syncs automatically
4. Helm templates rendered with environment-specific values
5. Manifests applied to cluster

Detailed GitOps Flow

Step 1: Code Change

# Modify Helm chart or config
vim charts/my-app/templates/deployment.yaml
vim cluster/dev/config.yaml

# Commit changes
git add .
git commit -m "Update my-app to v2.0"
git push origin main

Step 2: Create Release

make prepare-release REPO_ARGS="--repo simran2491/k8s-playground-cluster --message 'Release v1.0.0'"

What happens:

1. Script checks you're on main branch
2. Fetches latest from remote
3. Compares changes since last tag
4. Creates annotated Git tag (e.g., v1.0.0)
5. Pushes tag to GitHub
6. Optionally creates GitHub release

Step 3: Deploy

make deploy ENV=dev

What happens:

1. deploy.sh fetches latest tags
2. Gets current deployed version from ArgoCD
3. Compares versions
4. Renders system-apps Helm chart with new tag
5. Applies ArgoCD Application manifests

Step 4: ArgoCD Sync

ArgoCD automatically:

1. Detects Application manifest change
2. Fetches Helm chart from GitHub at specified tag
3. Renders templates with values
4. Compares desired vs actual state
5. Applies changes to cluster

Step 5: Resource Creation

Kubernetes creates:

1. Deployments → Pods scheduled on nodes
2. Services → ClusterIP/LoadBalancer endpoints
3. Ingress → HTTP routing rules
4. Certificates → cert-manager issues TLS certs
5. DNS Records → External-DNS creates DNS entries

Sync Wave Order

ArgoCD syncs applications in order using argocd.argoproj.io/sync-wave annotation:

Wave	Components	Why First
-1	ArgoCD, AppProject	Self-managing, must exist first
0	local-path-provisioner, namespace-manager	Storage and namespace foundation
1	cert-manager, MetalLB, NGINX Ingress, External-DNS	Core infrastructure and networking
2	Loki, kube-prometheus-stack, cluster-configs	Monitoring backend
3	grafana-alloy, promtail	Log collectors depend on Loki
4	User applications	Apps need all infrastructure

Environment-Specific Flow

Each environment has separate configuration:

cluster/dev/config.yaml    → clusterEnv: dev
cluster/qa/config.yaml     → clusterEnv: qa

To deploy to a specific environment:

# Deploy to dev
make deploy ENV=dev

# Deploy to qa
make deploy ENV=qa

Multi-Source Helm Charts

Some applications use multi-source Helm charts (e.g., Loki, Grafana Alloy):

spec:
  sources:
    - chart: loki
      repoURL: https://grafana.github.io/helm-charts
      targetRevision: 6.55.0
    - repoURL: https://github.com/simran2491/k8s-playground-cluster
      targetRevision: main
      ref: values

This allows:

• Using upstream Helm charts
• Overlaying custom values from the GitOps repository
• Maintaining separation between chart and configuration

Verification

After deployment, verify the sync status:

# Check ArgoCD app status
argocd app list

# Check specific app
argocd app get <app-name>

# Sync if needed
argocd app sync <app-name>

Rollback

To rollback to a previous version:

# Find previous tag
git tag --list | grep "^v" | sort -V

# Checkout previous version
git checkout <previous-tag>

# Redeploy
make deploy ENV=dev

Or via ArgoCD:

# Rollback ArgoCD app
argocd app rollback <app-name>