Getting started

This page sets up everything the Govern AI models and agents through an API gateway lab needs. Complete it once, then do any task — Task 1 through Task 7 — on its own or in order.

Your scenario: you’re a platform engineer at Citadel, standing up a central AI governance hub so every product team consumes AI through one governed gateway. This page deploys that hub (and a sample workload “spoke”) into your own Azure subscription.

Note: Some of the technologies used in this lab are in preview or in active development. You may experience some unexpected behavior, warnings, or errors.

⏳ This is the long pole. The azd up deployment below takes about 30–45 minutes (API Management is slow to provision). Start it early and read ahead through Task 1 while it runs.

Prerequisites

Before starting, ensure you have:

• An Azure subscription where you can deploy resources at subscription scope, with Owner (or Contributor plus User Access Administrator) permissions — azd up creates managed identities and assigns RBAC roles.
• Sufficient Azure OpenAI / AI Foundry model quota (for example, GPT-4.1 and DeepSeek-R1) in your target region.
• The lab tools installed — Azure CLI (az), Azure Developer CLI (azd), Python 3.13 or later, Git, and Visual Studio Code — or the included Devcontainer.
• Basic familiarity with the Azure services Citadel uses (API Management, AI Foundry, Cosmos DB, Key Vault, Event Hub) and with running Jupyter notebooks.

For the detailed install links, the permission rationale, and the Devcontainer option, see the repository’s Lab setup guide. Complete those steps before you begin.

Register Azure resource providers

Citadel uses several Azure resource providers that must be registered before deployment. Sign in and register them once:

az login
az account set --subscription "<your-subscription-name-or-id>"

az provider register --namespace Microsoft.AlertsManagement
az provider register --namespace Microsoft.ApiManagement
az provider register --namespace Microsoft.CognitiveServices
az provider register --namespace Microsoft.DocumentDB
az provider register --namespace Microsoft.EventHub
az provider register --namespace Microsoft.Insights
az provider register --namespace Microsoft.KeyVault
az provider register --namespace Microsoft.MachineLearningServices
az provider register --namespace Microsoft.ManagedIdentity
az provider register --namespace Microsoft.Network
az provider register --namespace Microsoft.OperationalInsights
az provider register --namespace Microsoft.Storage
az provider register --namespace Microsoft.Web
az provider register --namespace Microsoft.Logic
az provider register --namespace Microsoft.Cache

Registration can take a few minutes. It only needs to be done once per subscription.

Get the lab code

1. In VS Code, open the Command Palette (Ctrl+Shift+P), run Git: Clone, and enter:

    https://github.com/MicrosoftLearning/mslearn-ai-governance.git
   

2. Open the cloned repository folder in VS Code. The consolidated lab instructions live in Instructions/Exercises/, and the deployment templates, scripts, and validation notebooks this lab reuses live under workshop/ and bicep/.

Deploy the Citadel hub

Microsoft’s Azure Developer CLI (azd) provisions the entire Citadel hub in one pass.

1. Authenticate both CLIs (they share the same browser sign-in):

    az login
    azd auth login
   

2. Create an azd environment for the lab:

    azd env new citadel-workshop
   

3. Deploy. Sweden Central (swedencentral) is the recommended region for model quota:

    azd up
   

   Select your subscription and confirm the region when prompted. The deployment then runs for about 30–45 minutes.

   🔁 Transient errors: azd up is idempotent. If a resource (often a model deployment) fails with a transient error, just re-run azd up — it resumes where it left off.

4. If your deployment used the Developer APIM SKU, remove the default APIM products and subscriptions once azd up completes (the script only acts when the SKU is Developer):

    .\workshop\scripts\cleanup-apim-defaults.ps1
   

Deploy a sample spoke

The hub is the governance plane; a spoke is a sample onboarded workload — a standalone Azure AI Foundry account and project that consumes AI through the hub. Deploy one after azd up finishes. Pass a unique suffix so the script creates a distinct spoke resource group and unique resource names:

.\workshop\scripts\deploy-spoke-foundry.ps1 -SpokeSuffix 1

On macOS or Linux, use the equivalent shell script: ./workshop/scripts/deploy-spoke-foundry.sh --spoke-suffix 1

If your hub resource group is rg-citadel-demo-1, -SpokeSuffix 1 creates a spoke resource group named rg-citadel-demo-1-spoke-1. You don’t need to note any values down — the notebooks each read the resource names and endpoints directly from your azd environment at runtime.

Set up the Python environment

The tasks in this lab run Jupyter validation notebooks from the workshop/ folder. Set up the environment once.

1. Open the workshop folder in a terminal:

    cd workshop
   

2. Create and populate a virtual environment. Using uv (recommended):

    uv sync
   

   Or using pip with Python 3.13:

    py -3.13 -m venv .venv
    .venv\Scripts\Activate.ps1
    pip install -r requirements.txt
   

3. In VS Code, open any notebook under workshop/ and select the workshop/.venv interpreter as the Jupyter kernel. Each notebook’s Step 0 cell auto-discovers all the resource names and endpoints it needs from your azd environment — you don’t set anything manually.

🔐 Stay signed in. Keep az login active while you run notebooks; the notebooks use your Azure CLI credentials to discover resources and authenticate to the gateway.

Check you’re ready for a task

Each task needs the hub (and usually the spoke) deployed and your tools on the PATH. Before starting a task, run the preflight check from the Labfiles/G-govern-ai-through-a-gateway folder — it reads your local azd environment and tools and tells you what (if anything) is missing:

python setup/check_env.py --task 1

Swap 1 for the task number you’re about to start. It never changes anything and never makes network calls. That’s it — head to any task:

Next: Task 1 — Onboard AI backends and call the Universal LLM API