How to Deploy Azure OpenAI Models with Azure CLI

Azure AI Foundry offers a graphical way to deploy models, but Azure CLI is ideal when you want repeatable deployments, scripts, and CI/CD automation. This guide shows how to create, list, inspect, update, and troubleshoot Azure OpenAI deployments from a terminal.

What You Will Deploy

An Azure OpenAI resource is the Azure service instance that exposes an endpoint. A deployment is a named configuration for a particular model inside that resource. Your application calls the deployment name, not the raw model name.

If you have not created an Azure OpenAI resource yet, start with Creating Azure OpenAI Resource and Deploying Models - Step-by-Step Guide.

Prerequisites

Before you begin, make sure that you have:

• An Azure subscription with access to Azure OpenAI.
• An Azure OpenAI resource in a region that supports the model you want to use.
• Azure CLI installed and authenticated.
• Permission to manage deployments on the resource. Use least-privilege Azure RBAC in production.

Sign in and select the intended subscription:

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

Check that the Cognitive Services deployment commands are available:

az cognitiveservices account deployment --help

Model availability, versions, deployment types, and quota differ by region and subscription. Confirm the current supported models in Azure AI Foundry documentation before automating a deployment.

Set Variables

Using shell variables keeps commands concise and reduces accidental changes to the wrong resource.

RESOURCE_GROUP="rg-ai-demo"
AZURE_OPENAI_NAME="my-azure-openai-resource"
DEPLOYMENT_NAME="chat-model"
LOCATION="eastus"

Verify the resource exists and note its location:

az cognitiveservices account show \
  --name "$AZURE_OPENAI_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --query "{name:name, location:location, endpoint:properties.endpoint}" \
  --output table

Create a Model Deployment

Use az cognitiveservices account deployment create to create a named Azure OpenAI deployment. Replace the model name and version below with a combination available to your resource's region and quota.

az cognitiveservices account deployment create \
  --name "$AZURE_OPENAI_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --deployment-name "$DEPLOYMENT_NAME" \
  --model-name "gpt-4o-mini" \
  --model-version "<supported-model-version>" \
  --model-format "OpenAI" \
  --sku-name "Standard" \
  --sku-capacity 1

Understand the Important Parameters

Parameter	Purpose
--deployment-name	The name your application sends in API requests. Choose a stable, meaningful name such as chat-model or summarization-model.
--model-name	The Azure OpenAI model family to deploy.
--model-version	A model version available in your selected region.
--model-format OpenAI	Identifies the model format for Azure OpenAI deployments.
--sku-name and --sku-capacity	Control the deployment SKU and assigned capacity. Availability depends on the model and deployment type.

Do not place API keys, tokens, or subscription IDs in scripts committed to source control. For application access, prefer Microsoft Entra ID and managed identities where supported; otherwise, keep secrets in Azure Key Vault.

List Deployments

List every deployment in the Azure OpenAI resource:

az cognitiveservices account deployment list \
  --name "$AZURE_OPENAI_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --output table

To return selected fields as a compact table:

az cognitiveservices account deployment list \
  --name "$AZURE_OPENAI_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --query "[].{Deployment:name, Model:properties.model.name, Version:properties.model.version, SKU:sku.name, Capacity:sku.capacity}" \
  --output table

Inspect One Deployment

Use show when troubleshooting or before changing a deployment:

az cognitiveservices account deployment show \
  --name "$AZURE_OPENAI_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --deployment-name "$DEPLOYMENT_NAME" \
  --output json

The result lets you confirm the deployed model, version, SKU, and capacity. Capture this information in your deployment pipeline logs, but never log credentials.

Update a Deployment Safely

A deployment is updated by applying the desired configuration again with the same deployment name. First inspect the existing deployment, then update only after confirming model compatibility, quota, and application impact.

For example, to change capacity while retaining the same model and version:

az cognitiveservices account deployment create \
  --name "$AZURE_OPENAI_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --deployment-name "$DEPLOYMENT_NAME" \
  --model-name "gpt-4o-mini" \
  --model-version "<supported-model-version>" \
  --model-format "OpenAI" \
  --sku-name "Standard" \
  --sku-capacity 2

For production workloads, use a second deployment name when changing models or versions. Validate it with a small traffic slice before updating the application's configured deployment name. This gives you a straightforward rollback path.

Delete a Deployment

Delete only a deployment that is no longer used. This action stops applications that call that deployment name.

az cognitiveservices account deployment delete \
  --name "$AZURE_OPENAI_NAME" \
  --resource-group "$RESOURCE_GROUP" \
  --deployment-name "$DEPLOYMENT_NAME"

Run the list command afterwards to confirm that it has been removed.

Common Errors and Fixes

Model or Version Is Not Available in This Region

Cause: The selected model/version is unavailable for the resource location or your subscription.

Fix: Check the current Azure OpenAI model availability, then choose a supported version or create a resource in a suitable region. Do not assume that a model available in one region is available in another.

Insufficient Quota or Capacity

Cause: The subscription has insufficient quota for the selected model, SKU, or capacity.

Fix: Reduce the requested capacity for a test deployment, request the necessary quota in Azure, or use a supported alternative model. Confirm quota before deploying from CI/CD.

Authorization Failed or Operation Not Allowed

Cause: Your identity lacks permission on the Azure OpenAI resource or its resource group, or a recent RBAC change has not propagated yet.

Fix: Verify the signed-in account and subscription:

az account show --output table

Then ask an administrator to assign the minimum required role at the narrowest scope. Allow a few minutes after RBAC changes before retrying.

Deployment Name Already Exists

Cause: A deployment with that name already exists.

Fix: Inspect it using az cognitiveservices account deployment show. If it is intentional, update it with the approved desired configuration; otherwise, choose a new name rather than overwriting a production deployment unexpectedly.

CLI Command Is Missing or Outdated

Cause: Azure CLI is not installed or is too old for the command surface.

Fix: Update Azure CLI using the official installation instructions, sign in again, and rerun az cognitiveservices account deployment --help.

Production Checklist

Before connecting an application to the new deployment, verify that you have:

• Confirmed the model/version, region, SKU, and capacity.
• Used a descriptive deployment name that is separate from the underlying model name.
• Kept application configuration and secrets out of source control.
• Used Microsoft Entra ID or managed identity where possible, and Azure Key Vault for any required secrets.
• Set alerts for quota, failures, latency, and token usage.
• Tested a new model deployment before directing production traffic to it.
• Documented the rollback deployment name and owner.

Conclusion

Azure CLI makes Azure OpenAI deployments repeatable and suitable for infrastructure automation. Use it to create deployments consistently, inspect their configuration, and make deliberate updates with a clear rollback plan. Keep model availability and quota checks in your deployment process, because both can vary by region and subscription.

For portal-based resource setup, read Creating Azure OpenAI Resource and Deploying Models - Step-by-Step Guide.