Skip to content

Latest commit

 

History

History
275 lines (225 loc) · 13.4 KB

command-reference.md

File metadata and controls

275 lines (225 loc) · 13.4 KB

Azure AI Gateway CLI command reference

This is the human-readable reference for the published 1.0.0b34 extension. Start with installation and quickstart. Use this page to find a command, understand its purpose, and copy a configuration example. Use the installed command's --help for all arguments and allowed values; help supplements this reference rather than replacing it.

Command groups | Resource selectors | Models and aliases | Policies | MCP servers | Authentication | Output and verification

Command groups

Prefix every entry below with az aigateway (or its az aig shorthand). This table lists the public commands in the reviewed wheel.

Group Commands Purpose
Top level create, show, list, update, delete, wait, version Gateway lifecycle, tags/tier, and installed version
model-provider create, import, show, list, update, delete, sync Backend connection, Foundry bulk onboarding, and model registration reconciliation
model create, show (get), list, update, delete Register existing backend models and their protocol metadata
model-alias create, set, show, list, update, delete Publish callable names and priority/weight target pools
model policy list, set, set-token-limit, set-cost-limit, remove Model-local token-limit and cost-limit policy configuration
policy list, set, set-token-limit, set-cost-limit, set-rate-limit, set-ip-filter, remove Default-workspace token, cost, request-rate, and IP filter controls
mcp create, import, show, list, update, delete, authorize ToolServer registration, bulk import, and configured backend OAuth initiation
mcp source add, list, remove Individual backend source membership
api-key create, show, list, update, delete, list-secrets, regenerate Inbound gateway-wide client keys
identity assign, show, remove, wait Outbound gateway managed identities
network show, update, wait Public ingress and outbound subnet integration
network private-endpoint-connection list, show, approve, reject, delete, wait Gateway-side private endpoint connection decisions
telemetry-exporter create, show, list, update, delete Telemetry destinations and export configuration
az aigateway version
az aig version
az aigateway model-alias create --help
az aigateway mcp source add --help

There is no policy show, telemetry-exporter wait, or model-alias create --overwrite in this release. Use policy list, bounded exporter read-back, and explicit alias update respectively. model-alias set is an intentional create-or-update operation, not a create-only safeguard.

The CLI does not currently expose az aigateway migration collect-source, validate, apply, or report. Do not treat proposed migration commands as available.

Resource selectors

Examples use Bash and explicit subscriptions. Replace placeholders before running them; these are independent examples, not one deployment script.

SUBSCRIPTION="<subscription-id>"
RG="<existing-resource-group>"
GATEWAY="<gateway-name>"
PROVIDER="<provider-registration-name>"
MODEL="<model-registration-name>"
ALIAS="<alias-resource-name>"
ROUTING_NAME="<callable-model-name>"
Target Selectors
Gateway --subscription "$SUBSCRIPTION" -g "$RG" -n "$GATEWAY"
Provider, alias, MCP server, or API key --subscription "$SUBSCRIPTION" -g "$RG" --gateway-name "$GATEWAY" -n "<child-name>"
Model or model policy The child selectors above, plus --provider-name "$PROVIDER"

-g means --resource-group; -n means --name. A child name does not identify the parent gateway. Use exact --ids only where that command's help exposes it. Verify returned resource IDs/types, especially where a name can also match a legacy API Management service. This guide targets Microsoft.ApiManagement/aigateways and its implicit default workspace using default ARM API version 2026-11-01 (with 1-line fallback to 2025-09-01-preview via --api-version 2025-09-01-preview, AZURE_AIGATEWAY_API_VERSION=2025-09-01-preview, or az config set aigateway.api_version=2025-09-01-preview).

Use JSON files for structured arguments that support @file. The file must contain the advertised object/array, not a string holding JSON. Files do not interpolate environment variables. Protect secret-bearing files and keep them out of source control.

Models and aliases

An alias is required to publish a model route. The client request's model is the alias's properties.aliasName, not the registered model's deployment name or ARM ID. Providers and models supply the backend configuration; an alias connects the callable name to one or more models.

Register a provider and model

For a Foundry provider, prepare existing backend access for the gateway identity first. foundry.json:

{
  "endpoint": "https://<account>.openai.azure.com/",
  "resourceIds": ["/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>"],
  "authentication": {
    "kind": "ManagedIdentity",
    "managedIdentity": {"resource": "https://cognitiveservices.azure.com/"}
  }
}

deployment.json describes an existing backend deployment:

{
  "modelName": "<backend-model-name>",
  "resourceId": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/deployments/<deployment>"
}
az aigateway model-provider create --subscription "$SUBSCRIPTION" \
  -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" \
  --kind Foundry --foundry @foundry.json
az aigateway model create --subscription "$SUBSCRIPTION" \
  -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
  --deployment-config @deployment.json --api-format OpenAIChatCompletions \
  --supported-endpoints /openai/v1/chat/completions

Use the selected backend's actual protocol/operation path (for Foundry / Azure OpenAI providers, --supported-endpoints defaults to /openai/v1/... or /anthropic/v1/messages when omitted). Low-level create uses --deployment-config; general model update uses --deployment with a JSON object (modelName must match the /deployments/<name> suffix in resourceId when both are supplied).

The convenience model-provider import --foundry-resource-id "<account-id>" imports every deployment, enables gateway identity, and grants Foundry User on that account (model-provider create --foundry-resource-id "<account-id>" registers the Foundry provider without importing deployments unless --import-models is passed). model create --foundry-resource-id "<account-id>" --deployment "<deployment-name>" onboards one deployment with external access setup. These require additional permission and explicit intent. Neither creates the underlying deployments.

Publish a one-target alias

MODEL_ID="$(az aigateway model show --subscription "$SUBSCRIPTION" \
  -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
  --query id -o tsv)" || exit 1
if [ -z "$MODEL_ID" ] || [ "$MODEL_ID" = "null" ]; then
  printf '%s\n' 'No model registration ID returned; stop before alias creation.' >&2
  exit 1
fi
az aigateway model-alias create --subscription "$SUBSCRIPTION" \
  -g "$RG" --gateway-name "$GATEWAY" -n "$ALIAS" --routing-name "$ROUTING_NAME" \
  --backend-model resource-id="$MODEL_ID" priority=0 weight=100
az aigateway model-alias show --subscription "$SUBSCRIPTION" \
  -g "$RG" --gateway-name "$GATEWAY" -n "$ALIAS" -o json

Share traffic or prefer a fallback

An alias holds one to 30 unique model registration IDs under the same gateway. For multiple targets, explicitly supply integer priority 0-100 and weight 1-100 on each target.

Intent Example configuration Meaning
Active-active or canary A: priority 0, weight 75; B: priority 0, weight 25 Same tier, relative 3:1 request share among eligible models
Preferred/fallback A: priority 0, weight 100; B: priority 1, weight 100 Prefer A's tier; B is not an ordinary weighted share while A can serve

Weights need not sum to 100. Priority chooses the preferred tier; weights split traffic within that tier. Replacing an alias's backend list replaces the whole pool. Preserve unrelated policies and settings. See routing examples and failover verification.

Reconcile provider registrations

az aigateway model-provider sync --subscription "$SUBSCRIPTION" \
  -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" --dry-run

Review additions, stale removals, and alias dependencies before applying without --dry-run. Request --create-default-aliases true only when 1:1 aliases are intended, and include it in both preview and apply. Sync is sequential, not transactional. It does not provision backend deployments; a failed discovery is not evidence that deployments are absent.

Policies

Workspace policies are shared defaults; model/alias policies attach to those assets. For a workspace token allowance of 30,000 tokens per minute per caller:

az aigateway policy set --subscription "$SUBSCRIPTION" \
  -g "$RG" --gateway-name "$GATEWAY" \
  --token-limit 30000 --token-period minute --token-counter-key Identity
az aigateway policy list --subscription "$SUBSCRIPTION" \
  -g "$RG" --gateway-name "$GATEWAY" -o json

Identity separates counters by authenticated identity or shared API key; it does not pool a department's users together. Token, request, and cost limits measure different quantities. Cost limits are estimated controls, not a hard Azure billing cap.

Use the policy reference for model-local setters, rate/IP controls, accounting dimensions, tool threat protection, and agent hooks. --policies @file on a compatible asset replaces its complete policy array; retain existing IDs and unrelated entries. Content-safety policy commands and flags are disabled in 1.0.0b34 pending 2026-11-01 alignment; unrecognized server-side policy entries are preserved unchanged during read-modify-write updates.

MCP servers

mcp create --url <endpoint-url> registers a single MCP source directly, and mcp create --endpoints @endpoints.json registers a multi-source endpoint array; see the quickstart for a complete example. Use --allow-list and --blocked with namespace-prefixed tool names or glob patterns (<namespace>_<toolName>, such as learn_*); pass --allow-list null on mcp update to clear an allow-list and expose all tools ("[]" allows zero tools). Use mcp source add/list/remove to edit individual sources. A full endpoint array update changes complete membership and may involve credentials.

mcp authorize initiates OAuth for a selected persisted backend endpoint. It is not the caller's gateway login and does not prove authorization completed. See MCP configuration and OAuth lifecycle. Tool discovery and execution need a separately authorized runtime client, not just mcp show.

Authentication and keys

Prefer caller Entra OAuth tokens with the appropriate gateway data-plane role. Configure gateway-to-backend managed identity separately, with grants on the selected model or tool target. An ARM management token, gateway runtime token, and backend token are not interchangeable.

api-key list/show return metadata. list-secrets returns sensitive values and requires explicit authorization and protected handling. Keys grant gateway-wide access, not per-asset roles. Rotate one primary/secondary value at a time using api-key regenerate --key-type primary|secondary, move clients, and confirm cutover before rotating the other. See authentication, key storage, rotation, and identity commands.

Output and verification

Use -o table for an overview (for model-alias list and model-alias show, -o table renders one row per backend target with its Priority and Weight), -o json for complete metadata, and --query ... -o tsv for a selected nonsecret field:

az aigateway show --subscription "$SUBSCRIPTION" -g "$RG" -n "$GATEWAY" \
  --query '{id:id,state:properties.provisioningState,url:properties.gatewayUrl}' -o json

For list commands exposing --max-items and --next-token, retain and follow continuation tokens before claiming an inventory is complete. For asynchronous operations, use the matching wait and a bounded timeout where exposed; otherwise use bounded read-back. Acceptance is not completion.

Management reads establish saved configuration, not successful inference, MCP tool exposure, policy enforcement, or telemetry ingestion. Runtime clients use the gateway URL and published alias/MCP endpoint. Do not bypass the gateway or switch caller identities to hide a failure.

Gateway deletion affects consumers and can retain a soft-delete record. Deleting a model registration does not delete its external deployment. Private endpoint connection commands manage the gateway-side connection, not the backing private endpoint or DNS.