Azure AI Gateway Labs
Documentation Open portal
Foundations · Lab 01

Provision your AI Gateway

Create the shared Azure AI Gateway that your apps and agents will call, from the AI Gateway portal, the Azure CLI, Bicep and azd, or Terraform, then take a guided tour of the portal.

Beginner 15 min PortalCLIBicepTerraformNotebook Updated
Watch video Notebook Source Edit

What you'll do

  • Find the regions where AI Gateway is available, and create a gateway in one from the portal, the Azure CLI, Bicep and azd, or Terraform
  • Find the gateway's runtime URL and its system-assigned managed identity
  • Confirm that the runtime endpoint answers over HTTPS
  • Navigate the AI Gateway portal and know which area manages what

Before you start

No prerequisite labs. Start here.

Tracks: Portal, Azure CLI, Bicep + azd, Terraform, Notebook

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.

Narrated walkthrough: create an AI Gateway in the portal and tour it (3 min)
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.

Download the captions (WebVTT)

Before you begin

One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.

Every later lab reuses this one-time setup.

Tip

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)"
Important

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.

PropertyValue
Resource typeMicrosoft.ApiManagement/aigateways (API version 2026-11-01)
RegionsThe list grows over time. List them as in Find the available regions
Name1–24 characters: letters, digits, and hyphens. Its first 10 characters start the runtime host name
Runtime URLhttps:// + 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 routesModels under /default/models/…, MCP servers under /default/toolservers/<server>/mcp
Outbound identityA system-assigned managed identity, used to call Foundry and other Microsoft Entra–protected backends
SKUStandard, the default for the portal, az aigateway create, and templates that omit sku. The labs' Bicep templates omit sku and get Standard
Provisioning timeA 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.

Choose your track
1

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.

2

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.

Note

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.

3

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.

4

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.

Checkpoint

The gateway switcher in the top bar shows <gateway>, and Home shows the setup guide.

Verify

1

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"

A Could not resolve host error means the gateway isn't ready yet. Wait a minute and try again.

2

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.

3

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.

Managed identities › Configure identities shows the system-assigned identity with its principal ID and tenant ID. You can add user-assigned identities here too.
4

Tour the portal

Use the left navigation to get familiar with each area. You visit most of them in later labs.

AreaWhat you do thereWhere you learn it
HomeFollow the Set up your gateway guide to add a model, test it, and apply policiesThis lab
CatalogBrowse published models and MCP servers, try them in the playground, and copy endpoints and code samplesLab 02
ModelsImport Foundry deployments, add custom models from other providers, and manage aliases, their routing, and their failoverLab 02, Lab 03
MCP serversPublish MCP servers and control which tools are availableLab 04, Lab 05
PoliciesAdd token and request rate limits, cost limits, content safety, IP filters, and Agent hooks at gateway or asset scopeLab 06, Lab 09
MonitoringSend telemetry to an OTLP destination and use the built-in dashboard and tracesLab 13
AccessCreate runtime API keys on the API keys tab and grant Microsoft Entra roles on the Entra ID tabLab 10, Lab 11
Managed identitiesManage the identities that the gateway uses to call backendsLab 12
NetworkingSet public network access and private endpoints, and add, change, or remove outbound virtual network integrationLab 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.

Checkpoint

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> and azd up once 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 tags parameter applies tags to the gateway, so set them when you create each environment's gateway. To add them to the gateway you have, deploy infra/gateway.bicep on 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.

Choose your track
1

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"
2

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"

Next steps

Finished the lab?

Mark it complete to track your progress across paths. It's saved only in this browser.