Module 5: Core Commands & `azure.yaml` | AZD for Beginners

"Every azd project has a heart: the azure.yaml file. Learn it and the core commands, and you understand how azd thinks."

Level: Beginner · Time: ~2 days · Prerequisites: Module 4

Learning Objectives

By the end of this module, you will be able to:

Read and write a basic azure.yaml file
Explain what each core azd command does
Understand how azd maps your code to Azure services
Use hooks to run custom steps

1. The `azure.yaml` File

At the root of every azd project sits azure.yaml — the map that tells azd what your app contains and where each part should run. A minimal one looks like:

yaml

[object Object], ,[object Object],
,[object Object],
  ,[object Object],
    ,[object Object], ,[object Object],
    ,[object Object], ,[object Object],
    ,[object Object], ,[object Object],

This says: "There's one service called web, its code is in ./src, it's Python, and it should run on Azure Container Apps." The top-level name groups the whole project, and you can list multiple services under services: — a web frontend and an api backend, each with its own folder, language, and host. azd deploys them together but tracks them separately.

Concept: azure.yaml connects your code to your infrastructure. azd reads it to know what to build and which Azure resource to deploy each service into.

2. The Core Commands

You met these in Module 1 — here's what each really does:

Command	Action
`azd init`	Create/scaffold a project
`azd provision`	Create/update Azure resources (runs the Bicep)
`azd deploy`	Build and push your app code
`azd up`	`provision` + `deploy` together
`azd monitor`	Open monitoring dashboards
`azd env`	Manage environments and their variables
`azd down`	Delete all provisioned resources

Try this: Say out loud what each command changes: provision = the cloud resources, deploy = your code, up = both, down = gone. If you can narrate that, you understand azd's model.

3. Services and Hosts

The host value in azure.yaml tells azd where a service runs. azd supports many:

containerapp — Azure Container Apps
appservice — Azure App Service
function — Azure Functions
staticwebapp — Static Web Apps
aks — Azure Kubernetes Service

azd targets the right resource type for whichever host you name, so the same service can move from appservice to containerapp by changing one line (assuming the matching infrastructure exists).

Explain like I'm new: Think of host as choosing which kind of "home" your app lives in — a managed container, a classic web server, a serverless function. Same app code; azd handles the differences of each home.

4. Hooks: Your Custom Steps

Sometimes you need to run a command at a specific moment — say, seed a database after provisioning. azd hooks let you attach scripts to lifecycle events:

yaml

[object Object],
  ,[object Object],
    ,[object Object], ,[object Object],
    ,[object Object], ,[object Object],

This runs seed-data.sh right after azd provision finishes. There's a hook for each step — preprovision, postprovision, prepackage, predeploy, postdeploy — so you can build a frontend before packaging or run smoke tests immediately after a deploy.

Real-world use case: A team runs a postprovision hook to load sample data into their new database, so the moment azd up completes, the app isn't just live — it's already populated and demo-ready.

5. How It Fits Together

azd up reads azure.yaml, runs your Bicep to create resources, fires any hooks, then deploys each service to its host. Understanding this flow means you can read any azd template and know exactly what it will do — the same handful of pieces show up in every project.

Common mistake: Editing Azure resources by hand in the portal and expecting azd to know. azd's source of truth is your azure.yaml + Bicep — change those, then re-run azd, so your config and cloud stay in sync.

✅ Checkpoint

What is the job of azure.yaml?
What's the difference between azd provision and azd deploy?
What are hooks used for?

Answers: 1) It maps your app's services to their code folders, languages, and Azure hosts. 2) provision creates/updates Azure resources; deploy builds and pushes your app code. 3) Running custom scripts at lifecycle moments, e.g., seeding data after provisioning.

Key Takeaway: The azure.yaml file is the heart of an azd project — it maps each service to its code, language, and Azure host (Container Apps, App Service, Functions, and more). The core commands (init, provision, deploy, up, monitor, env, down) each act on a clear part of the lifecycle, and hooks let you run custom scripts at specific moments. Master these and you can read any azd template.

Further Learning

Part of "AZD for Beginners." Adapted from Microsoft's open AZD curriculum (MIT License).