Your platform team is about to put every model and tool that the company's apps and agents use behind one governed entry point. Before anyone can publish a model, issue a key, or set a budget, you need the gateway itself. In this lab you create a shared AI Gateway, find its runtime URL and managed identity, and learn your way around the portal so you're ready for the rest of the labs.
Transcript
Welcome to Lab one of the Azure AI Gateway labs. In three minutes, you'll provision your own gateway from the portal, find its runtime URL and managed identity, and learn where everything lives. Here's what provisioning does. You choose a name, a resource group, and a region. Azure creates the AI Gateway, with a system-assigned managed identity, and there's nothing to size. You get back one runtime URL for every app and agent. In the AI Gateway portal, open the gateway switcher at the top, and choose Create new gateway. The dialog suggests a unique name and confirms it's available. Select refresh to generate another. The name becomes part of your runtime URL, so keep it to twenty-four characters or fewer. Pick your subscription, and create a new resource group, or reuse an existing one. Then choose a region. This lab uses East US 2, but any available region works. Expand Advanced. The system-assigned managed identity is on by default. Keep it. The gateway uses it to reach Foundry and other Entra-protected backends, so your apps never hold provider keys. Under Networking, keep public routing for this lab. Private routing reaches private backends through secure outbound connections, and it can't be changed after creation. Select Create gateway. All gateways tracks progress live: creating the resource group, deploying, then activating. About a minute and a half later, it shows Succeeded, with the runtime URL right in the list. Home now shows your new gateway in the switcher. The setup guide lists what's next: add a model, test it, and apply policies. That's where lab two picks up. A quick tour. Discover is the catalog developers browse. Models and MCP servers are what you publish. Access holds Entra ID role assignments and API keys. Policies are your guardrails. Monitoring shows usage, cost, and traces. And Networking is read-only after creation. Open Managed identities. The system-assigned identity is enabled, with its principal ID. In later labs, you grant it access to Foundry, so the gateway authenticates outbound for you. Now verify from a terminal. Read the host name from the resource, then call a model route without a key. HTTP 404 is what you want. DNS, TLS, and the gateway all answer. There are simply no models yet. Prefer automation? A single Azure CLI call creates the AI gateways resource. Or use a short Bicep file that outputs the URL and principal ID. The lab includes both, plus a Jupyter notebook. Keep this gateway, because every later lab reuses it. When you finish the labs, delete the resource group. Next up: lab two.
Before you begin
One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.
- Check your subscription and permissionsBefore your first lab
- Choose where to run commandsEvery track except the portal
- Sign in to AzureOn your own machine. Cloud Shell is already signed in.
- Install the
aigatewayextensionThe Azure CLI tracks and the Verify steps - Register the resource providersOnce per subscription, before you create a gateway with the Azure CLI
- Find the available regionsBefore you choose a location
- Clone the labs repoThe Bicep + azd and Terraform tracks, the notebooks, and the code samples
You've done the one-time setup that this lab uses.
Every later lab reuses this one-time setup.
On the Bicep + azd and Terraform tracks, azd up or terraform apply creates the resource group and the
gateway and names them for you, so you can skip the variables at the end of this section.
- For the portal track: a browser and your Azure account.
- A region where the Foundry models of the later labs are available too.
- Recommended reading: How AI Gateway works.
Set your variables
Set these variables once. Every track and the Verify section reuse them.
# Make the subscription that you use for the labs the current one, so that every command runs in it
az account set --subscription "<subscription-id>" &&
echo "🆔 Current subscription: $(az account show --query name -o tsv)"
# Name the resource group and the gateway, and choose the region
export RG="<resource-group>" # for example rg-ai-gateway-labs
export GATEWAY="<gateway>" # globally unique, 24 characters or fewer, part of the runtime URL
export LOCATION="<location>" # a Name from the list of available regions, for example eastus2
echo "📝 Gateway $GATEWAY in $RG ($LOCATION)"# Make the subscription that you use for the labs the current one, so that every command runs in it
az account set --subscription "<subscription-id>"
if ($?) { Write-Host "🆔 Current subscription: $(az account show --query name -o tsv)" }
# Name the resource group and the gateway, and choose the region
$RG = "<resource-group>" # for example rg-ai-gateway-labs
$GATEWAY = "<gateway>" # globally unique, 24 characters or fewer, part of the runtime URL
$LOCATION = "<location>" # a Name from the list of available regions, for example eastus2
Write-Host "📝 Gateway $GATEWAY in $RG ($LOCATION)"Create the resource group in the same region as the gateway, so that defaults line up. The gateway name must be 1–24 characters: letters, digits, and hyphens, starting with a letter and not ending with a hyphen.
How it works
An AI Gateway is an Azure Resource Manager resource of type Microsoft.ApiManagement/aigateways. You manage it
in the AI Gateway portal, which is separate from the Azure portal, or through
Azure Resource Manager with the CLI, REST, or Bicep. It's a standalone resource: models, MCP servers, keys, and
policies all live on it. There's no capacity to size, so the only real decisions are the name, the region, and the
resource group.
| Property | Value |
|---|---|
| Resource type | Microsoft.ApiManagement/aigateways (API version 2026-11-01) |
| Regions | The list grows over time. List them as in Find the available regions |
| Name | 1–24 characters: letters, digits, and hyphens. Its first 10 characters start the runtime host name |
| Runtime URL | https:// + properties.frontend.defaultHostname: the name's first 10 characters, a hyphen, a 13-character hash, and .<region>-01.ai.gateway.azure.com. A gateway named aigw-labs-001 in East US 2 answers at a URL like https://aigw-labs-k3v7qz2m9xw4p.eastus2-01.ai.gateway.azure.com. Always read it from the gateway; you can't build it from the name |
| Runtime routes | Models under /default/models/…, MCP servers under /default/toolservers/<server>/mcp |
| Outbound identity | A system-assigned managed identity, used to call Foundry and other Microsoft Entra–protected backends |
| SKU | Standard, the default for the portal, az aigateway create, and templates that omit sku. The labs' Bicep templates omit sku and get Standard |
| Provisioning time | A few minutes, often less |
Everything you publish later lives in the gateway's default workspace. That's why every runtime route
starts with /default/. Applications authenticate inbound with an API key or a Microsoft Entra token. The
gateway authenticates outbound to each backend, usually with its managed identity, so apps never hold
provider credentials.
Create the gateway
Pick one track. Each track produces the same result: a gateway named <gateway> in <resource-group>, with a
system-assigned managed identity. The Bicep + azd track picks the names for you: aigw- plus six unique characters,
in rg-aigw-lab01.
Sign in to the AI Gateway portal
Open the AI Gateway portal and sign in with your Azure account. If this is your first gateway, the portal takes you straight into gateway creation. If you already have a gateway, open the gateway switcher in the top bar and start creating a new one from there.
Enter the gateway details
In Create AI gateway, enter a globally unique Name of 24 characters or fewer, or select
Generate a new name. Then choose the subscription, a Resource group (New or Existing), and the
Region. With New, the portal suggests ai-gateway-<gateway>. Under Advanced, keep Enable system-assigned managed identity selected, Public network access set to Enabled, and
Public routing. Private routing connects the gateway to private backends through a virtual network. You can
also add, change, or remove it later under Networking. Lab 18 covers it.
If you set Public network access to Disabled, the gateway rejects calls from the internet with 403
Public network access is disabled for this resource., so keep it Enabled for these labs.
The subscription picker lists every subscription you can see. Subscriptions where you lack Azure AI Gateway write access, such as the Contributor role on the subscription, are disabled, and the portal explains why.
Watch it provision
Select Create gateway. All gateways opens with the banner Gateway creation is in progress. The gateway's Provisioning status moves through Creating resource group (when you chose New), InProgress, and Activating to Succeeded, which can take up to about 20 minutes. You can use other gateways while it runs, but you can't select the new one until it's ready. Creating a gateway provisions only the AI Gateway runtime, as the Azure CLI and Bicep + azd tracks do.
Open the setup guide on Home
When the status shows Succeeded, select the gateway's name. Home opens with the Set up your gateway guide, in three steps: Add a model, Test a model, and Apply policies. Leave it for now. You publish your first model in the next lab, and the guide stays on Home until you finish it.
The gateway switcher in the top bar shows <gateway>, and Home shows the setup guide.
If you haven't yet, register the resource providers in this
subscription: the gateway lives in Microsoft.ApiManagement.
Create a resource group
# Create the resource group that holds the gateway, in the gateway's region
az group create --name "$RG" --location "$LOCATION" --output none &&
echo "📦 Resource group $RG is ready in $LOCATION"Create the AI gateway
az aigateway create only needs the name, the region, and the managed identity. Without --sku, the gateway gets
the service's default SKU, Standard, like a gateway that you create in the portal. There's no capacity or
publisher to set. The command waits until provisioning finishes, usually within a few minutes.
# Create the gateway in the default Standard SKU with a system-assigned managed identity, and wait until it's ready
az aigateway create -g "$RG" -n "$GATEWAY" --location "$LOCATION" --system-assigned true -o none &&
echo "🚀 Gateway $GATEWAY is ready in $LOCATION"# Create the gateway in the default Standard SKU with a system-assigned managed identity, and wait until it's ready
az aigateway create -g $RG -n $GATEWAY --location $LOCATION --system-assigned true -o none
if ($?) { Write-Host "🚀 Gateway $GATEWAY is ready in $LOCATION" }Add --no-wait to return right away, then run az aigateway wait -g "$RG" -n "$GATEWAY" --created when you
need the gateway.
Read the runtime URL and identity
# Show the gateway's SKU and state, its runtime host name, and the principal ID of its managed identity
echo "📊 Gateway $GATEWAY, its runtime host, and its identity:"
az aigateway show -g "$RG" -n "$GATEWAY" \
--query "{name:name, location:location, sku:sku.name, state:properties.provisioningState, host:properties.frontend.defaultHostname, principalId:identity.principalId}" \
-o table# Show the gateway's SKU and state, its runtime host name, and the principal ID of its managed identity
Write-Host "📊 Gateway $GATEWAY, its runtime host, and its identity:"
az aigateway show -g $RG -n $GATEWAY `
--query "{name:name, location:location, sku:sku.name, state:properties.provisioningState, host:properties.frontend.defaultHostname, principalId:identity.principalId}" `
-o tableThe table shows the Standard SKU, Succeeded, a Host like aigw-labs-k3v7qz2m9xw4p.eastus2-01.ai.gateway.azure.com,
and a PrincipalId GUID.
What you need: the Setup guide tasks from Before you begin. azd up creates the resource
group and the gateway, so you don't need the variables.
Review the template
infra/gateway.bicep declares the gateway. It follows the AI Gateway reference sample. It creates the AI gateway
(Microsoft.ApiManagement/aigateways) with a system-assigned identity. It omits sku, so the gateway gets the
default SKU, Standard. There's no capacity or publisher to set, and no other resource to create alongside it.
| Parameter | Description |
|---|---|
gatewayName | Required. The gateway name, 24 characters or fewer |
location | eastus2 (default), or another region where AI Gateway is available |
tags | Optional. Tags applied to the gateway |
backendSubnetId | Optional. A delegated subnet for outbound virtual network integration. You can also add, change, or remove it after creation. See Lab 18 |
// Provisions an Azure AI Gateway (Microsoft.ApiManagement/aigateways) with a system-assigned managed identity.
// It omits sku, so the resource provider applies its default (Standard). This follows the AI Gateway reference sample:
// https://github.com/Azure-Samples/simple-foundry-hosted-agent-python-aigateway/blob/main/infra/ai-gateway/main.bicep
// The lab's main.bicep calls it with azd, and other labs call it as a module. You can also deploy it on its own
// to an existing resource group with "az deployment group create".
targetScope = 'resourceGroup'
@description('Gateway name. It becomes the first label of the runtime host name, so use letters, numbers, and hyphens (max 24 characters).')
@minLength(1)
@maxLength(24)
param gatewayName string
@description('Region for the gateway. Pick one where AI Gateway is available. List them with az provider show --namespace Microsoft.ApiManagement (Setup guide, Find the available regions).')
param location string = 'eastus2'
@description('Tags applied to the gateway.')
param tags object = {}
@description('Optional delegated subnet resource ID for outbound virtual network integration. You can also add, change, or remove it after the gateway is created.')
param backendSubnetId string = ''
#disable-next-line BCP081
resource aiGateway 'Microsoft.ApiManagement/aigateways@2026-11-01' = {
name: gatewayName
location: location
tags: tags
identity: {
type: 'SystemAssigned'
}
properties: empty(backendSubnetId) ? {} : { backend: { subnet: { id: backendSubnetId } } }
}
output gatewayName string = aiGateway.name
output gatewayUrl string = 'https://${aiGateway.properties.frontend.defaultHostname}'
output gatewayId string = aiGateway.id
output principalId string = aiGateway.identity.principalIdinfra/main.bicep is the template that azd deploys. It creates the resource group rg-<environment name>, then
calls infra/gateway.bicep with the name aigw- plus six characters that are unique to your subscription,
environment, and region. Its outputs become azd environment values:
// Lab 01 with azd: "azd up" creates the resource group rg-<environment name>, then calls gateway.bicep to create
// an AI gateway with a unique name.
targetScope = 'subscription'
@description('azd environment name. The resource group is rg-<environmentName>.')
@minLength(1)
@maxLength(60)
param environmentName string
@description('Region for every resource. Pick one where AI Gateway is available. List them with az provider show --namespace Microsoft.ApiManagement (Setup guide, Find the available regions).')
@metadata({ azd: { type: 'location' } })
param location string
var suffix = take(uniqueString(subscription().id, environmentName, location), 6)
var tags = { 'azd-env-name': environmentName }
resource rg 'Microsoft.Resources/resourceGroups@2024-03-01' = {
name: 'rg-${environmentName}'
location: location
tags: tags
}
// The lab's template: the gateway with a system-assigned identity, in the default SKU.
module gateway 'gateway.bicep' = {
name: 'aigw-gateway'
scope: rg
params: {
gatewayName: 'aigw-${suffix}'
location: location
tags: tags
}
}
output AZURE_RESOURCE_GROUP string = rg.name
output AI_GATEWAY_NAME string = gateway.outputs.gatewayName
output AI_GATEWAY_ID string = gateway.outputs.gatewayId
output AI_GATEWAY_URL string = gateway.outputs.gatewayUrl
output AI_GATEWAY_PRINCIPAL_ID string = gateway.outputs.principalIdLater labs reuse infra/gateway.bicep as a module. You can also deploy it on its own to a resource group you
already have, with az deployment group create, as Go further shows.
Bicep has no type definitions yet for Microsoft.ApiManagement/aigateways. As in the reference sample, the
#disable-next-line BCP081 line silences the warning about it. Without this line, the build shows a BCP081
warning, which doesn't block the deployment.
Deploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab01 in your current subscription, then provision
the resource group and the gateway. It takes about three minutes.
# Move into the lab's folder, which holds the azd project
cd ~/aigateway/labs/01-provision-gateway &&
echo "📂 Lab folder: $(pwd)"
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab01 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "📝 azd environment aigw-lab01 deploys to eastus2"
# Provision the resource group and the gateway
azd up &&
echo "🚀 Gateway $(azd env get-value AI_GATEWAY_NAME) is deployed"# Move into the lab's folder, which holds the azd project
Set-Location ~/aigateway/labs/01-provision-gateway
if ($?) { Write-Host "📂 Lab folder: $(Get-Location)" }
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab01 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "📝 azd environment aigw-lab01 deploys to eastus2" }
# Provision the resource group and the gateway
azd up
if ($?) { Write-Host "🚀 Gateway $(azd env get-value AI_GATEWAY_NAME) is deployed" }For another region, use its name from Find the available regions.
Read the outputs
Set the variables that Verify and Go further use from azd's environment values, then print the runtime URL and the gateway's principal ID.
# Read the resource group, the gateway name, and the region from azd's environment values
export RG="$(azd env get-value AZURE_RESOURCE_GROUP)"
export GATEWAY="$(azd env get-value AI_GATEWAY_NAME)"
export LOCATION="$(azd env get-value AZURE_LOCATION)"
echo "📝 Gateway $GATEWAY in $RG ($LOCATION)"
# Print the gateway's runtime URL and the principal ID of its managed identity
echo "🌐 Runtime URL: $(azd env get-value AI_GATEWAY_URL)"
echo "👤 Gateway identity: $(azd env get-value AI_GATEWAY_PRINCIPAL_ID)"# Read the resource group, the gateway name, and the region from azd's environment values
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$LOCATION = azd env get-value AZURE_LOCATION
Write-Host "📝 Gateway $GATEWAY in $RG ($LOCATION)"
# Print the gateway's runtime URL and the principal ID of its managed identity
Write-Host "🌐 Runtime URL: $(azd env get-value AI_GATEWAY_URL)"
Write-Host "👤 Gateway identity: $(azd env get-value AI_GATEWAY_PRINCIPAL_ID)"azd up ended with SUCCESS. The commands print a runtime URL like
🌐 Runtime URL: https://aigw-x7k2q-k3v7qz2m9xw4p.eastus2-01.ai.gateway.azure.com, and 👤 Gateway identity: with a
principal ID GUID.
What you need: the Setup guide tasks from Before you begin, plus Terraform 1.9 or later, as
in Deploy a lab with Terraform. terraform apply creates the resource
group and the gateway, so you don't need the variables.
Review the configuration
terraform/gateway/main.tf declares the gateway, as a module that later labs reuse. It follows the AI Gateway
Terraform reference sample. The azapi provider
sends the gateway's API version, 2026-11-01, as is, because the azurerm provider has no AI Gateway resource yet.
Like the Bicep template, it omits sku, so the gateway gets the default SKU, Standard, and it turns on the
system-assigned identity:
# An Azure AI Gateway (Microsoft.ApiManagement/aigateways) with a system-assigned managed identity. It omits sku,
# so the resource provider applies its default (Standard). AI Gateway resources have no Terraform schema yet, so
# azapi sends the body as is. Lab 01 calls this module, and other labs reuse it.
terraform {
required_providers {
azapi = {
source = "Azure/azapi"
}
}
}
resource "azapi_resource" "gateway" {
type = "Microsoft.ApiManagement/aigateways@2026-11-01"
name = var.gateway_name
parent_id = var.resource_group_id
location = var.location
tags = var.tags
identity {
type = "SystemAssigned"
}
# The optional backend subnet turns on outbound virtual network integration.
body = {
properties = var.backend_subnet_id == "" ? {} : { backend = { subnet = { id = var.backend_subnet_id } } }
}
schema_validation_enabled = false
response_export_values = ["properties.frontend.defaultHostname"]
# Activation can take longer than azapi's default 30 minutes in some regions.
timeouts {
create = "60m"
}
}terraform/main.tf creates the resource group rg-<environment_name>, with aigw-lab01-tf as the default
environment name, and calls the module with a unique gateway name:
# Lab 01 with Terraform: creates the resource group rg-<environment_name>, then calls the gateway module to create
# an AI gateway with a unique name.
data "azapi_client_config" "current" {}
locals {
suffix = substr(sha1("${data.azapi_client_config.current.subscription_id}/${var.environment_name}/${var.location}"), 0, 6)
tags = { "environment-name" = var.environment_name }
}
resource "azurerm_resource_group" "rg" {
name = "rg-${var.environment_name}"
location = var.location
tags = local.tags
}
# The lab's module: the gateway with a system-assigned identity, in the default SKU.
module "gateway" {
source = "./gateway"
gateway_name = "aigw-${local.suffix}"
resource_group_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
}Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, then plan and apply the resource group and the gateway. It takes about five minutes, most of it while the new gateway activates.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/01-provision-gateway/terraform &&
echo "📂 Terraform folder: $(pwd)"
# Deploy to the Azure CLI's current subscription
export ARM_SUBSCRIPTION_ID="$(az account show --query id --output tsv)" &&
echo "📍 Subscription: $ARM_SUBSCRIPTION_ID"
# Download the providers, then plan and apply the resource group and the gateway
terraform init &&
terraform plan -out tfplan &&
terraform apply tfplan &&
echo "🚀 Gateway $(terraform output -raw ai_gateway_name) is deployed"# Move into the lab's Terraform folder
Set-Location ~/aigateway/labs/01-provision-gateway/terraform
if ($?) { Write-Host "📂 Terraform folder: $(Get-Location)" }
# Deploy to the Azure CLI's current subscription
$env:ARM_SUBSCRIPTION_ID = az account show --query id --output tsv
if ($?) { Write-Host "📍 Subscription: $env:ARM_SUBSCRIPTION_ID" }
# Download the providers, then plan and apply the resource group and the gateway
terraform init
if ($?) { terraform plan -out tfplan }
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "🚀 Gateway $(terraform output -raw ai_gateway_name) is deployed" }The configuration deploys to eastus2. For another region, run export TF_VAR_location=<region> (PowerShell:
$env:TF_VAR_location = "<region>") with its name from Find the available regions
before terraform plan.
Read the outputs
Set the variables that Verify and Go further use from the Terraform outputs, then print the runtime URL and the gateway's principal ID.
# Read the resource group, the gateway name, and the region from the Terraform outputs
export RG="$(terraform output -raw azure_resource_group)"
export GATEWAY="$(terraform output -raw ai_gateway_name)"
export LOCATION="$(terraform output -raw azure_location)"
echo "📝 Gateway $GATEWAY in $RG ($LOCATION)"
# Print the gateway's runtime URL and the principal ID of its managed identity
echo "🌐 Runtime URL: $(terraform output -raw ai_gateway_url)"
echo "👤 Gateway identity: $(terraform output -raw ai_gateway_principal_id)"# Read the resource group, the gateway name, and the region from the Terraform outputs
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$LOCATION = terraform output -raw azure_location
Write-Host "📝 Gateway $GATEWAY in $RG ($LOCATION)"
# Print the gateway's runtime URL and the principal ID of its managed identity
Write-Host "🌐 Runtime URL: $(terraform output -raw ai_gateway_url)"
Write-Host "👤 Gateway identity: $(terraform output -raw ai_gateway_principal_id)"terraform apply ended with Apply complete! Resources: 2 added, 0 changed, 0 destroyed. The commands print a
runtime URL like 🌐 Runtime URL: https://aigw-x7k2q-k3v7qz2m9xw4p.eastus2-01.ai.gateway.azure.com, and
👤 Gateway identity: with a principal ID GUID.
Verify
Call the runtime URL
Read the host name from the gateway rather than building it yourself, then send a request without a key. Any
HTTP status proves that DNS, TLS, and the gateway are up. A new gateway with no models answers 404; after you
add a model and a key in the next lab, a call without a key gets 400 or 401.
# Read the runtime host name from the gateway, and build the runtime URL from it
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
# Call the Chat Completions route without a key, and print only the HTTP status that the gateway answers with
curl -sS -o /dev/null -w "🌐 The gateway answered: HTTP %{http_code}\n" "${AI_GATEWAY_URL%/}/default/models/openai/v1/chat/completions"# Read the runtime host name from the gateway, and build the runtime URL from it
$env:AI_GATEWAY_URL = "https://$(az aigateway show -g $RG -n $GATEWAY --query properties.frontend.defaultHostname -o tsv)"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
# Call the Chat Completions route without a key, and print only the HTTP status that the gateway answers with
$status = (Invoke-WebRequest -Uri "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/models/openai/v1/chat/completions" `
-SkipHttpErrorCheck).StatusCode
if ($?) { Write-Host "🌐 The gateway answered: HTTP $status" }A Could not resolve host error means the gateway isn't ready yet. Wait a minute and try again.
Find the gateway on Home
Open the AI Gateway portal. If you created the gateway with the CLI, with Bicep and azd, or with Terraform, select it in the gateway switcher in the top bar. Home shows the setup guide for your new gateway.
Check the managed identity
Select Managed identities. On the Configure identities tab, the system-assigned identity is enabled.
Its principal ID matches principalId from the CLI output, AI_GATEWAY_PRINCIPAL_ID from azd, or
ai_gateway_principal_id from Terraform. In later labs
you grant this identity access to Foundry so that the gateway can call your models without keys.
Tour the portal
Use the left navigation to get familiar with each area. You visit most of them in later labs.
| Area | What you do there | Where you learn it |
|---|---|---|
| Home | Follow the Set up your gateway guide to add a model, test it, and apply policies | This lab |
| Catalog | Browse published models and MCP servers, try them in the playground, and copy endpoints and code samples | Lab 02 |
| Models | Import Foundry deployments, add custom models from other providers, and manage aliases, their routing, and their failover | Lab 02, Lab 03 |
| MCP servers | Publish MCP servers and control which tools are available | Lab 04, Lab 05 |
| Policies | Add token and request rate limits, cost limits, content safety, IP filters, and Agent hooks at gateway or asset scope | Lab 06, Lab 09 |
| Monitoring | Send telemetry to an OTLP destination and use the built-in dashboard and traces | Lab 13 |
| Access | Create runtime API keys on the API keys tab and grant Microsoft Entra roles on the Entra ID tab | Lab 10, Lab 11 |
| Managed identities | Manage the identities that the gateway uses to call backends | Lab 12 |
| Networking | Set public network access and private endpoints, and add, change, or remove outbound virtual network integration | Lab 18 |
The left navigation groups Models, MCP servers, Policies, and Monitoring under Manage, and Access, Managed identities, and Networking under Secure. The top bar holds the gateway switcher, the command palette (Search, or Ctrl+K, or ⌘K on macOS) to jump to any page, What's new, Documentation, notifications, and Share feedback.
The runtime URL answers with an HTTP status, the gateway appears on Home, and Managed identities shows the system-assigned identity enabled.
Go further
One gateway per environment. Run
azd env new <name>andazd uponce for each of dev, test, and production: every azd environment gets its own resource group and gateway. Keep the template in source control next to your app.Tag for ownership and chargeback. The template's
tagsparameter applies tags to the gateway, so set them when you create each environment's gateway. To add them to the gateway you have, deployinfra/gateway.bicepon its own from the lab folder:Bash# Deploy the gateway's template again with tags, which updates the gateway in place az deployment group create -g "$RG" --template-file infra/gateway.bicep --output none \ --parameters gatewayName="$GATEWAY" location="$LOCATION" \ tags='{"workload":"ai-gateway-labs","owner":"platform-team","costCenter":"1234"}' && echo "📝 Tags are set on gateway $GATEWAY"Use a user-assigned identity. When several gateways must share one backend identity, add a user-assigned identity on Managed identities. See Call backends with managed identities.
Clean up
The portal and CLI tracks of every later lab reuse the gateway, so keep it until you finish the labs you plan to do.
Delete the resource group
When you're done with all the labs, delete the resource group. That removes the gateway and everything else in the group. The command asks for confirmation.
# Delete the resource group, with the gateway and everything else in it, after you confirm
az group delete --name "$RG" &&
echo "🚮 Resource group $RG is deleted"# Delete the resource group, with the gateway and everything else in it, after you confirm
az group delete --name $RG
if ($?) { Write-Host "🚮 Resource group $RG is deleted" }Delete only the gateway
To keep the resource group, delete only the AI gateway. Deleting the gateway also deletes everything you published on it. If you created the gateway in the portal, delete it there instead: on All gateways, select More actions (…) on its row, then Delete.
# Delete the AI gateway, with everything that you published on it
az aigateway delete -g "$RG" -n "$GATEWAY" --yes &&
echo "🚮 Gateway $GATEWAY is deleted"# Delete the AI gateway, with everything that you published on it
az aigateway delete -g $RG -n $GATEWAY --yes
if ($?) { Write-Host "🚮 Gateway $GATEWAY is deleted" }Delete everything azd created
You don't need to keep this gateway for the Bicep + azd tracks of later labs: each of them creates its own gateway.
If you continue with the portal or CLI track of lab 02, you can keep it and use
its names instead: the resource group is rg-aigw-lab01, and azd env get-value AI_GATEWAY_NAME prints the gateway
name.
Otherwise, in the aigateway/labs/01-provision-gateway folder, delete the resource group with the gateway. It takes
up to ten minutes.
# Delete everything that azd up created, without asking you to confirm
azd down --purge --force &&
echo "🚮 Everything that azd up created is deleted"Delete everything Terraform created
You don't need to keep this gateway for the Terraform tracks of later labs: each of them creates its own gateway.
If you continue with the portal or CLI track of lab 02, you can keep it and use
its names instead: the resource group is rg-aigw-lab01-tf, and terraform output -raw ai_gateway_name prints the
gateway name.
Otherwise, in the aigateway/labs/01-provision-gateway/terraform folder, delete the resource group with the
gateway. It takes a few minutes.
# Delete everything that terraform apply created, without asking you to confirm
terraform destroy -auto-approve &&
echo "🚮 Everything that terraform apply created is deleted"Next steps
- Publish a Foundry model and make your first call: import a model, create a key, and call it.
- Issue and rotate runtime API keys: give each app its own key.
- How AI Gateway works: the concepts behind models, tools, policies, and identity.
- Docs: Configure AI Gateway in the portal and AI Gateway CLI quickstart.