Start with the thing you already know

You built an app. It runs on your laptop. But a laptop isn't the internet — for real users to reach it, the app has to live on rented computers in the cloud.

Renting those computers, wiring them together, locking them down, and then placing your app on top is a lot of fiddly setup. This repo does all of it. It splits the job into two folders:

The old way vs. the written-down way

You could build all this by hand: log into the Azure web portal, click through hundreds of menus, and hope you remember every setting next time. People did this for years. It's slow, and nobody can ever rebuild it exactly.

Instead, this repo writes the cloud down as files. That's the whole idea behind the phrase:

Infrastructure as Code (IaC) is the second card. The files in infra/ are written in a language called Bicep, which describes Azure resources.

A "resource" is just a thing you want to exist

Everything in Bicep is a resource: a network, a database, a lock. Here's a real one from infra/bicep/modules/dev/net.bicep — the private network the whole platform sits inside.

resource vnet 'Microsoft.Network/virtualNetworks@2024-05-01' = {
  name: '${prefix}-dev-vnet'
  location: location
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.x.x.x/16'
      ]
    }
  }
}

The magic word: idempotent

The best part of describing instead of clicking: you can run it again and again safely. Azure compares your files to what already exists and only changes the difference.

That property has a name: idempotent. It's why the files — not the running cloud — are the source of truth.

Check your understanding

Think of it as city zoning

A real city groups buildings into districts — industrial here, residential there — so things that belong together stay together. Azure does the same with a resource group. This repo gives each district its own folder under infra/bicep/modules/.

Meet the four neighborhoods

constants.bicep — the shared address book

Names and numbers (the region, the prefix, the network ranges) get reused across dozens of files. Hardcoding them everywhere is how typos creep in. So they live in one file and every blueprint reads from it.

@export()
var prefix = 'vs-plat'
@export()
var location = 'eastus2'
@export()
var aksNodesSubnetPrefix = '10.x.x.x/24'

manage.sh — one script, simple math

You don't run each .bicep file by hand. You run manage.sh with a short neighborhood/blueprint name, and it does the bookkeeping. The mapping is dead simple:

One special case: if the neighborhood is sub, there's no resource group to target yet (you're creating the groups), so it deploys at the whole-subscription level instead. A few handy flags change behavior without touching any blueprint:

The neighborhoods, in their own words

If the four folders could text each other about who depends on whom, it'd sound like this:

Check your understanding

A gated campus, not a street of shops

Most of this infrastructure is deliberately private. Picture a gated corporate campus: there are internal hallways between buildings, but no doors that open onto the public street. Data moves freely inside; the outside internet can't wander in.

The trick: pieces point at each other

Here's the elegant part. You never write "build the network first, then the subnet." Instead, the subnet simply mentions the network — and Azure infers the order from that mention.

resource aksNodesSubnet 'Microsoft.Network/virtualNetworks/subnets@2024-05-01' = {
  name: C.aksNodesSubnetName
  parent: vnet
  properties: {
    addressPrefix: C.aksNodesSubnetPrefix
    natGateway: {
      id: natGateway.id
    }
  }
}

Those two values — vnet and natGateway — are declared with the word existing, meaning "don't build these, just look them up." That's how separate blueprints reference each other's work.

Private DNS — the internal phone directory

One catch with private doors: the app still knows the database by its public-sounding name, like vs-plat-dev-psql.postgres.database.azure.com. DNS normally turns that name into a public address.

So the campus keeps its own private DNS zone: a phone book that quietly answers the same name with the private address instead. The app's code never changes — the name just resolves to the internal door.

Watch the build order unfold

Because every piece points at the ones it needs, Azure can only build them in one valid order. Step through it — notice nothing is built before the thing it depends on:

Check your understanding

Passwords in code are a time bomb

The naive way to let an app reach a database is to paste the password into a config file. The problem: that password now lives in your code, your backups, your chat history, and anyone who copies the repo gets the keys.

A managed identity is the app's badge

Azure can hand a resource an official, built-in identity — a managed identity. Think of it as a corporate badge with a photo: the building's systems recognize it, and you never had to invent or remember a password.

But there's a puzzle: the app runs inside Kubernetes, and Kubernetes has its own idea of identities. How do those two worlds trust each other? Through workload identity federation — a one-time "treaty" between them:

resource fedCred '...userAssignedIdentities/federatedIdentityCredentials@2024-11-30' = {
  name: 'aks-workload'
  parent: appUami
  properties: {
    issuer: aks.properties.oidcIssuerProfile.issuerURL
    subject: 'system:serviceaccount:${C.workloadNamespace}:${C.workloadServiceAccount}'
    audiences: [
      'api://AzureADTokenExchange'
    ]
  }
}

After this treaty exists, a pod running as that exact account can swap its Kubernetes token for a real Azure pass — no password anywhere.

Watch the handshake happen

When the app needs the database, here's the conversation behind the scenes. Notice nobody ever says a password:

When a secret is unavoidable: the vault

Some things genuinely are secrets — the CI runner's login token, for example. Those never go in the repo. They go in a Key Vault (a locked safe), and access is granted by role — not by sharing a key.

// Key Vault Secrets User (4633458b-...)
resource raSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(kv.id, principalId, 'KeyVaultSecretsUser')
  scope: kv
  properties: {
    roleDefinitionId: subscriptionResourceId(...)
    principalId: principalId
    principalType: 'ServicePrincipal'
  }
}

Check your understanding

From "build the land" to "move in"

Your app ships as a container: a sealed bundle that runs the same everywhere. Kubernetes runs containers inside pods, spread across the cluster that Bicep created.

But Kubernetes wants long, repetitive YAML files describing every pod, network rule, and setting. Writing those by hand for dev, then again for staging, then prod, is error-prone. That's the job of Helm.

One template, four environments

The chart ships a base values.yaml (the defaults), then a thin override file per environment. Deploying to dev? Helm stacks values-dev.yaml on top of the defaults. Only the differences are written down:

client:
  config:
    appEnv: "development"
    authAuthority: "https://auth.vs-platform.ai/realms/vs-platform"
workloadIdentityClientId: "<your-uami-client-id>"
ingress:
  host: "dev.vs-platform.ai"
course:
  enabled: true

The umbrella: three apps, one chart

This is an umbrella chart — it bundles everything the platform serves into one versioned package:

Each gets a Deployment (keep it running), a Service (a stable internal address), and they share an Ingress (the front-door routing rules).

Where infra and deployment shake hands

This is the moment the two halves of the course meet. Remember the app's badge from Module 4? Bicep created that identity and printed its id. Helm stamps that same id onto the Kubernetes account the pods run as:

kind: ServiceAccount
metadata:
  name: {{ .Values.serviceAccountName }}
  annotations:
    azure.workload.identity/client-id: {{ .Values.workloadIdentityClientId | quote }}

Trace one real request, end to end

Everything you've learned, in one journey: you open the site, and your click travels through the infrastructure Bicep built and the apps Helm deployed. Step through it:

Check your understanding

The pre-flight checklist

Pilots don't trust memory before takeoff — they run a checklist, every time. These are the items this codebase's own docs warn about. Skim them now; they'll save you an afternoon later.

Spot the bug

A teammate opens a pull request changing the API image. One line breaks a rule you just learned. Click the line you'd flag in review:

The whole journey, one map

Here's everything, in order. Each stage hands something to the next — the same dependency thinking from Module 3, scaled up to the entire platform:

Explore the architecture

Click any piece to see its job. Left side is what Bicep builds (infra/); right side is what Helm runs on top (deployment/):

Final check — put it all together