Deploy resources with Resource Manager templates and Azure CLI

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

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 either an Azure subscription or a resource group within a subscription. In most cases, you'll target deployment to a resource group. Use subscription deployments to apply policies and role assignments across the subscription. You also use subscription deployments to create a resource group and deploy resources to it. Depending on the scope of the deployment, you use different commands.

To deploy to a resource group, use az group deployment create:

az group deployment create --resource-group <resource-group-name> --template-file <path-to-template>

To deploy to a subscription, use az deployment create:

az deployment create --location <location> --template-file <path-to-template>

Currently, management group deployments are only supported through the REST API. See Deploy resources with Resource Manager templates and Resource Manager REST API.

The examples in this article use resource group deployments. For more information about subscription deployments, see Create resource groups and resources at the subscription level.

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 group deployment 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",

Deploy remote template

Instead of storing Resource Manager 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 group deployment 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 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 group deployment create --resource-group examplegroup \
  --template-uri <copied URL> \
  --parameters storageAccountType=Standard_GRS

Redeploy when deployment fails

This feature is also known as Rollback on error. When a deployment fails, you can automatically redeploy an earlier, successful deployment from your deployment history. To specify redeployment, use the --rollback-on-error parameter in the deployment command. This functionality is useful if you've got a known good state for your infrastructure deployment and want to revert to this state. There are a number of caveats and restrictions:

  • The redeployment is run exactly as it was run previously with the same parameters. You can't change the parameters.
  • The previous deployment is run using the complete mode. Any resources not included in the previous deployment are deleted, and any resource configurations are set to their previous state. Make sure you fully understand the deployment modes.
  • The redeployment only affects the resources, any data changes aren't affected.
  • This feature is only supported on Resource Group deployments, not subscription level deployments. For more information about subscription level deployment, see Create resource groups and resources at the subscription level.

To use this option, your deployments must have unique names so they can be identified in the history. If you don't have unique names, the current failed deployment might overwrite the previously successful deployment in the history. You can only use this option with root level deployments. Deployments from a nested template aren't available for redeployment.

To redeploy the last successful deployment, add the --rollback-on-error parameter as a flag.

az group deployment create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters storageAccountType=Standard_GRS \
  --rollback-on-error

To redeploy a specific deployment, use the --rollback-on-error parameter and provide the name of the deployment.

az group deployment create \
  --name ExampleDeployment02 \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters storageAccountType=Standard_GRS \
  --rollback-on-error ExampleDeployment01

The specified deployment must have succeeded.

Parameters

To pass parameter values, you can use either inline parameters or a parameter file. The preceding examples in this article show inline parameters.

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 group deployment create \
  --resource-group testgroup \
  --template-file demotemplate.json \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

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

az group deployment 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"
]

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.

The parameter file must be in the following format:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
     "storageAccountType": {
         "value": "Standard_GRS"
     }
  }
}

Notice that the parameters section includes a parameter name that matches the parameter defined in your template (storageAccountType). The parameter file contains a value for the parameter. This value is automatically passed to the template during deployment. You can create more than one parameter file, and then pass in the appropriate parameter file for the scenario.

Copy the preceding example and save it as a file named storage.parameters.json.

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

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

Parameter precedence

You can use inline parameters and a local parameter file in the same deployment operation. For example, you can specify some values in the local parameter file and add other values inline during deployment. If you provide values for a parameter in both the local parameter file and inline, the inline value takes precedence.

az group deployment create \
  --resource-group testgroup \
  --template-file demotemplate.json \
  --parameters @demotemplate.parameters.json \
  --parameters exampleArray=@arrtest.json

Test a template deployment

To test your template and parameter values without actually deploying any resources, use az group deployment validate.

az group deployment validate \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters @storage.parameters.json

If no errors are detected, the command returns information about the test deployment. In particular, notice that the error value is null.

{
  "error": null,
  "properties": {
      ...

If an error is detected, the command returns an error message. For example, passing an incorrect value for the storage account SKU, returns the following error:

{
  "error": {
    "code": "InvalidTemplate",
    "details": null,
    "message": "Deployment template validation failed: 'The provided value 'badSKU' for the template parameter 
      'storageAccountType' at line '13' and column '20' is not valid. The parameter value is not part of the allowed 
      value(s): 'Standard_LRS,Standard_ZRS,Standard_GRS,Standard_RAGRS,Premium_LRS'.'.",
    "target": null
  },
  "properties": null
}

If your template has a syntax error, the command returns an error indicating it couldn't parse the template. The message indicates the line number and position of the parsing error.

{
  "error": {
    "code": "InvalidTemplate",
    "details": null,
    "message": "Deployment template parse failed: 'After parsing a value an unexpected character was encountered:
      \". Path 'variables', line 31, position 3.'.",
    "target": null
  },
  "properties": null
}

Next steps