Deploy resources with ARM templates and Azure CLI

This article explains how to use Azure CLI with Azure Resource Manager templates (ARM templates) to deploy your resources to Azure. If you aren't familiar with the concepts of deploying and managing your Azure solutions, see template deployment overview.

The deployment commands changed in Azure CLI version 2.2.0. The examples in this article require Azure CLI version 2.2.0 or later.

To run this sample, install the latest version of the Azure CLI. To start, run az login to create a connection with Azure.

Samples for the Azure CLI are written for the bash shell. To run this sample in Windows PowerShell or Command Prompt, you may need to change elements of the script.

If you don't have Azure CLI installed, you can use the Cloud Shell.

Deployment scope

You can target your deployment to a resource group, subscription, management group, or tenant. In most cases, you'll target deployment to a resource group. To apply policies and role assignments across a larger scope, use subscription, management group, or tenant deployments. When deploying to a subscription, you can create a resource group and deploy resources to it.

Depending on the scope of the deployment, you use different commands.

The examples in this article use resource group deployments.

Deploy local template

When deploying resources to Azure, you:

  1. Sign in to your Azure account
  2. Create a resource group that serves as the container for the deployed resources. The name of the resource group can only include alphanumeric characters, periods, underscores, hyphens, and parenthesis. It can be up to 90 characters. It can't end in a period.
  3. Deploy to the resource group the template that defines the resources to create.

A template can include parameters that enable you to customize the deployment. For example, you can provide values that are tailored for a particular environment (such as dev, test, and production). The sample template defines a parameter for the storage account SKU.

The following example creates a resource group, and deploys a template from your local machine:

az group create --name ExampleGroup --location "Central US"
az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters storageAccountType=Standard_GRS

The deployment can take a few minutes to complete. When it finishes, you see a message that includes the result:

"provisioningState": "Succeeded",

Deployment name

In the preceding example, you named the deployment ExampleDeployment. If you don't provide a name for the deployment, the name of the template file is used. For example, if you deploy a template named azuredeploy.json and don't specify a deployment name, the deployment is named azuredeploy.

Every time you run a deployment, an entry is added to the resource group's deployment history with the deployment name. If you run another deployment and give it the same name, the earlier entry is replaced with the current deployment. If you want to maintain unique entries in the deployment history, give each deployment a unique name.

To create a unique name, you can assign a random number.

deploymentName='ExampleDeployment'$RANDOM

Or, add a date value.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

If you run concurrent deployments to the same resource group with the same deployment name, only the last deployment is completed. Any deployments with the same name that haven't finished are replaced by the last deployment. For example, if you run a deployment named newStorage that deploys a storage account named storage1, and at the same time run another deployment named newStorage that deploys a storage account named storage2, you deploy only one storage account. The resulting storage account is named storage2.

However, if you run a deployment named newStorage that deploys a storage account named storage1, and immediately after it completes you run another deployment named newStorage that deploys a storage account named storage2, then you have two storage accounts. One is named storage1, and the other is named storage2. But, you only have one entry in the deployment history.

When you specify a unique name for each deployment, you can run them concurrently without conflict. If you run a deployment named newStorage1 that deploys a storage account named storage1, and at the same time run another deployment named newStorage2 that deploys a storage account named storage2, then you have two storage accounts and two entries in the deployment history.

To avoid conflicts with concurrent deployments and to ensure unique entries in the deployment history, give each deployment a unique name.

Deploy remote template

Instead of storing ARM templates on your local machine, you may prefer to store them in an external location. You can store templates in a source control repository (such as GitHub). Or, you can store them in an Azure storage account for shared access in your organization.

To deploy an external template, use the template-uri parameter. Use the URI in the example to deploy the sample template from GitHub.

az group create --name ExampleGroup --location "Central US"
az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

The preceding example requires a publicly accessible URI for the template, which works for most scenarios because your template shouldn't include sensitive data. If you need to specify sensitive data (like an admin password), pass that value as a secure parameter. However, if you don't want your template to be publicly accessible, you can protect it by storing it in a private storage container. For information about deploying a template that requires a shared access signature (SAS) token, see Deploy private template with SAS token.

Deploy template spec

Instead of deploying a local or remote template, you can create a template spec. The template spec is a resource in your Azure subscription that contains an ARM template. It makes it easy to securely share the template with users in your organization. You use Azure role-based access control (Azure RBAC) to grant access to the template spec. This feature is currently in preview.

The following examples show how to create and deploy a template spec. These commands are only available if you've signed up for the preview.

First, you create the template spec by providing the ARM template.

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

Then, you get the ID for template spec and deploy it.

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

For more information, see Azure Resource Manager template specs (Preview).

Preview changes

Before deploying your template, you can preview the changes the template will make to your environment. Use the what-if operation to verify that the template makes the changes that you expect. What-if also validates the template for errors.

Deploy template from Cloud Shell

You can use Cloud Shell to deploy your template. To deploy an external template, provide the URI of the template exactly as you would for any external deployment. To deploy a local template, you must first load your template into the storage account for your Cloud Shell. This section describes how to load the template to your cloud shell account, and deploy it as a local file. If you haven't used Cloud Shell, see Overview of Azure Cloud Shell for information about setting it up.

  1. Sign in to the Azure portal.

  2. Select your Cloud Shell resource group. The name pattern is cloud-shell-storage-<region>.

    Select resource group

  3. Select the storage account for your Cloud Shell.

    Select storage account

  4. Select Blobs.

    Select blobs

  5. Select + Container.

    Add container

  6. Give your container a name and an access level. The sample template in this article contains no sensitive information, so allow anonymous read access. Select OK.

    Provide container values

  7. Select the container you created.

    Select new container

  8. Select Upload.

    Upload blob

  9. Find and upload your template.

    Upload file

  10. After it has uploaded, select the template.

    Select new template

  11. Copy the URL.

    Copy URL

  12. Open the prompt.

    Open Cloud Shell

In the Cloud Shell, use the following commands:

az group create --name examplegroup --location "South Central US"
az deployment group create --resource-group examplegroup \
  --template-uri <copied URL> \
  --parameters storageAccountType=Standard_GRS

Parameters

To pass parameter values, you can use either inline parameters or a parameter file.

Inline parameters

To pass inline parameters, provide the values in parameters. For example, to pass a string and array to a template is a Bash shell, use:

az deployment group create \
  --resource-group testgroup \
  --template-file demotemplate.json \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

If you're using Azure CLI with Windows Command Prompt (CMD) or PowerShell, pass the array in the format: exampleArray="['value1','value2']".

You can also get the contents of file and provide that content as an inline parameter.

az deployment group create \
  --resource-group testgroup \
  --template-file demotemplate.json \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

Getting a parameter value from a file is helpful when you need to provide configuration values. For example, you can provide cloud-init values for a Linux virtual machine.

The arrayContent.json format is:

[
    "value1",
    "value2"
]

To pass in an object, for example, to set tags, use JSON. For example, your template might include a parameter like this one:

    "resourceTags": {
      "type": "object",
      "defaultValue": {
        "Cost Center": "IT Department"
      }
    }

In this case, you can pass in a JSON string to set the parameter as shown in the following Bash script:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $templateFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Use double quotes around the JSON that you want to pass into the object.

Parameter files

Rather than passing parameters as inline values in your script, you may find it easier to use a JSON file that contains the parameter values. The parameter file must be a local file. External parameter files aren't supported with Azure CLI.

For more information about the parameter file, see Create Resource Manager parameter file.

To pass a local parameter file, use @ to specify a local file named storage.parameters.json.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters @storage.parameters.json

Handle extended JSON format

To deploy a template with multi-line strings or comments using Azure CLI with version 2.3.0 or older, you must use the --handle-extended-json-format switch. For example:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Next steps