Deploy resources with Resource Manager templates and Azure CLI

This topic explains how to use Azure CLI 2.0 with Resource Manager templates to deploy your resources to Azure. If you are not familiar with the concepts of deploying and managing your Azure solutions, see Azure Resource Manager overview.

The Resource Manager template you deploy can either be a local file on your machine, or an external file that is located in a repository like GitHub. The template you deploy in this article is available in the Sample template section, or as a storage account template in GitHub.

To run this sample, make sure you have installed the latest Azure CLI 2.0. To start, run az login to create a connection with Azure.

This sample works in a Bash shell. For options on running Azure CLI scripts on Windows client, see Running the Azure CLI in Windows.

If you do not have Azure CLI installed, you can use the Cloud Shell.

Deploy local template

When deploying resources to Azure, you:

  1. Log 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 cannot 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 login

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 external 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 login

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 should not include sensitive data. If you need to specify sensitive data (like an admin password), pass that value as a secure parameter. However, if you do not 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. However, you must first load your template into the file share for your Cloud Shell. If you have not used Cloud Shell, see Overview of Azure Cloud Shell for information about setting it up.

  1. Log 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 Files.

    Select files

  5. Select the file share for Cloud Shell. The name pattern is cs-<user>-<domain>-com-<uniqueGuid>.

    Select file share

  6. Select Add directory.

    Add directory

  7. Name it templates, and select Okay.

    Name directory

  8. Select your new directory.

    Select directory

  9. Select Upload.

    Select upload

  10. Find and upload your template.

    Upload file

  11. 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-file clouddrive/templates/azuredeploy.json --parameters storageAccountType=Standard_GRS

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 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 multiple parameter files for different deployment scenarios, and then pass in the appropriate parameter file.

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

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, attempting to pass 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 could not 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
}

Incremental and complete deployments

When deploying your resources, you specify that the deployment is either an incremental update or a complete update. The primary difference between these two modes is how Resource Manager handles existing resources in the resource group that are not in the template:

  • In complete mode, Resource Manager deletes resources that exist in the resource group but are not specified in the template.
  • In incremental mode, Resource Manager leaves unchanged resources that exist in the resource group but are not specified in the template.

For both modes, Resource Manager attempts to provision all resources specified in the template. If the resource already exists in the resource group and its settings are unchanged, the operation results in no change. If you change the settings for a resource, the resource is provisioned with those new settings. If you attempt to update the location or type of an existing resource, the deployment fails with an error. Instead, deploy a new resource with the location or type that you need.

By default, Resource Manager uses the incremental mode.

To illustrate the difference between incremental and complete modes, consider the following scenario.

Existing Resource Group contains:

  • Resource A
  • Resource B
  • Resource C

Template defines:

  • Resource A
  • Resource B
  • Resource D

When deployed in incremental mode, the resource group contains:

  • Resource A
  • Resource B
  • Resource C
  • Resource D

When deployed in complete mode, Resource C is deleted. The resource group contains:

  • Resource A
  • Resource B
  • Resource D

To use complete mode, use the mode parameter:

az group deployment create \
    --name ExampleDeployment \
    --mode Complete \
    --resource-group ExampleGroup \
    --template-file storage.json \
    --parameters storageAccountType=Standard_GRS

Sample template

The following template is used for the examples in this topic. Copy and save it as a file named storage.json. To understand how to create this template, see Create your first Azure Resource Manager template.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ],
      "metadata": {
        "description": "Storage Account type"
      }
    }
  },
  "variables": {
    "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "name": "[variables('storageAccountName')]",
      "apiVersion": "2016-01-01",
      "location": "[resourceGroup().location]",
      "sku": {
          "name": "[parameters('storageAccountType')]"
      },
      "kind": "Storage", 
      "properties": {
      }
    }
  ],
  "outputs": {
      "storageAccountName": {
          "type": "string",
          "value": "[variables('storageAccountName')]"
      }
  }
}

Next steps