☸️ Azure AKS GitOps Starter (Flux + Bicep)

There are a lot of hello-world clusters out there. This repo is not one of them.
It’s a deliberately boring, opinionated baseline for running workloads on Azure Kubernetes Service (AKS) using GitOps (Flux) and Bicep – the kind of thing you actually use as a reference in a real job.

Everything here is:

• Structured the way an SRE / Platform team expects.
• Written to be read by humans first, YAML second.
• Redacted: no tenant IDs, IPs, or real hostnames.

---

🎯 Scenario

“We want a small but real AKS environment that is:

• created via Bicep,
• configured via Flux GitOps, and
• promoted through environments using pull requests – all without committing secrets to Git.”

This repo focuses on:

• Bootstrap AKS with Bicep.
• Install Flux and point it at one or more Git paths.
• Define workload + platform config as repo structure.
• Provide runbooks for cutover, rollback, and day‑2 operations.

You can point interviewers or teammates at this repo and say:

“This is roughly how I’d stand up a small GitOps-driven AKS platform.”

---

🧱 Repo Layout

.
├─ README.md                     # Big picture, story, lifecycle
├─ RUNBOOK.md                    # Operator guide: bootstrap → operate → retire
├─ .gitignore                    # Clean defaults for infra + k8s YAML
├─ bicep/
│  ├─ main.bicep                 # Entry point: AKS cluster + supporting resources
│  └─ modules/
│     ├─ network.bicep           # VNet + subnets for AKS nodepools
│     ├─ aks.bicep               # AKS cluster definition (no secrets)
│     └─ flux.bicep              # Optional: Flux extension / configuration
├─ gitops/
│  ├─ clusters/
│  │  └─ dev/
│  │     └─ kustomization.yaml   # Example cluster-level GitOps config
│  └─ apps/
│     └─ demo-api/
│        ├─ kustomization.yaml
│        └─ deployment.yaml      # Tiny placeholder workload
├─ .github/
│  └─ workflows/
│     └─ aks-gitops-deploy.yml   # Example GitHub Actions flow
├─ scripts/
│  ├─ bootstrap-aks.ps1          # Deploy Bicep + install Flux
│  ├─ destroy-aks.ps1            # Tear down non-prod cluster
│  └─ sample-flux-values.json    # Example of safe, parameter-style config
└─ docs/
   ├─ OVERVIEW.md                # Why this exists and who it’s for
   ├─ ARCHITECTURE.md            # Diagrams & design notes
   ├─ CUTOVER_CHECKLIST.md       # Moving real workloads onto GitOps-managed AKS
   ├─ ROLLBACK.md                # How to back out AKS / GitOps changes
   └─ SECURITY.md                # Redaction + secret-handling approach

---

🔄 Lifecycle at a Glance

flowchart LR
  A[1️⃣ Plan] --> B[2️⃣ Bootstrap]
  B --> C[3️⃣ Wire GitOps]
  C --> D[4️⃣ Deploy Workloads]
  D --> E[5️⃣ Cutover Traffic]
  E --> F[6️⃣ Operate & Evolve]
  F --> G[7️⃣ Retire or Rebuild]

Loading

1️⃣ Plan

• Choose environments: e.g. dev, test, prod.
• Decide which bits are cluster config vs app config.
• Pick namespaces, ingress approach, and observability basics.

2️⃣ Bootstrap

• Deploy core infra with Bicep: resource group, VNet, AKS cluster.
• Enable required add‑ons (e.g. managed identity, Azure CNI).
• Generate/install Flux using either the CLI or extension.

3️⃣ Wire GitOps

• Point Flux at your gitops/clusters/<env> path.
• Define sources and kustomizations so cluster can sync itself.
• Keep secrets out of Git (use Secret Providers, external secret stores, etc.).

4️⃣ Deploy Workloads

• Add workloads under gitops/apps/*.
• Reference them from cluster kustomizations.
• Let Flux reconcile and watch the changes roll out.

5️⃣ Cutover Traffic

• Route traffic into AKS (Ingress Controller / Gateway / AppGW).
• Promote environment using PRs and tags.
• Use CUTOVER_CHECKLIST.md as a human-friendly script.

6️⃣ Operate & Evolve

• Tune nodepools, autoscaling, and quotas.
• Evolve GitOps structure as you add apps.
• Keep observability and SLOs in mind.

7️⃣ Retire or Rebuild

• For short-lived environments, destroy cleanly with destroy-aks.ps1.
• For bigger refactors, treat cluster recreation as cattle not pets.

---

🚀 Quickstart (Dev Sandbox)

All commands use placeholder names. Replace them in your private fork but don’t commit real IDs or secrets.

1. Clone and explore

git clone <your-repo-url>.git
cd <your-repo-folder>

Skim these first:

• bicep/main.bicep
• gitops/clusters/dev/kustomization.yaml
• docs/ARCHITECTURE.md

2. Bootstrap the cluster (dev only)

./scripts/bootstrap-aks.ps1 `
  -EnvironmentName "dev" `
  -Location "uksouth"

This script is intentionally conservative and only shows the shape of what you’d do. Wire in real parameters and identities in your own copy.

3. Connect Flux to this repo

• Configure Flux to use your GitHub repository URL.
• Point it at ./gitops/clusters/dev (path in the repo).
• Watch it pull down the demo-api workload and namespaces.

4. Iterate via GitOps

• Edit manifests in gitops/apps/demo-api/.
• Commit & push.
• Let Flux reconcile and watch changes apply to AKS.

---

🧪 Environments & Git Layout

A simple pattern you can grow from:

• gitops/clusters/dev/* – dev cluster overlays and kustomizations.
• gitops/clusters/prod/* – prod equivalents (not included, by design).
• gitops/apps/<service>/* – individual services and shared bits.

You can point multiple clusters at the same apps tree with different overlays, or keep each environment stricter and more isolated.

---

🛡️ Redaction & Safety

This repo is safe to show in interviews and portfolios as-is.

• ✅ No real IP ranges or hostnames
• ✅ No cluster names tied to a company
• ✅ No subscription, tenant, or object IDs
• ✅ No kubeconfig, no secrets, no key material
• ✅ Only synthetic examples and placeholders

See docs/SECURITY.md for how to adapt this safely to real environments.

---

📎 License

If you intend to open-source your variant, add a LICENSE file (MIT works well for portfolios) and reference it here.
For private / interview usage, you can note that the repo is “All rights reserved – portfolio use only” or similar in your fork.