Deploy resources with Resource Manager templates and Azure PowerShell

This topic explains how to use Azure PowerShell with Resource Manager templates to deploy your resources to Azure. Your template can be either a local file or an external file that is available through a URI.

You can get the template (storage.json) used in these examples from the Create your first Azure Resource Manager template article. To use the template with these examples, create a JSON file and add the copied content.

Deploy local template

To quickly get started with deployment, use the following cmdlets to deploy a local template with inline parameters.

Login-AzureRmAccount

New-AzureRmResourceGroup -Name ExampleGroup -Location "South Central US"
New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\MyTemplates\storage.json -storageNamePrefix contoso -storageSKU Standard_GRS

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

ProvisioningState       : Succeeded

The preceding example created the resource group in your default subscription. To use a different subscription, add the Set-AzureRmContext cmdlet after logging in.

Deploy external template

To deploy an external template, use the TemplateUri parameter. The template can be at any publicly accessible URI (such as a file in storage account).

New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateUri https://raw.githubusercontent.com/exampleuser/MyTemplates/master/storage.json `
  -storageNamePrefix contoso -storageSKU Standard_GRS

You can protect your template by requiring a shared access signature (SAS) token for access. For information about deploying a template that requires a SAS token, see Deploy private template with SAS token.

Parameter files

The preceding examples showed how to pass parameters as inline values. You can specify parameter values in a file, and pass that file during deployment.

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": {
     "storageNamePrefix": {
         "value": "contoso"
     },
     "storageSKU": {
         "value": "Standard_GRS"
     }
  }
}

To pass a local parameter file, use the TemplateParameterFile parameter:

New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\MyTemplates\storage.json `
  -TemplateParameterFile c:\MyTemplates\storage.parameters.json

To pass an external parameter file, use the TemplateParameterUri parameter:

New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateUri https://raw.githubusercontent.com/exampleuser/MyTemplates/master/storage.json `
  -TemplateParameterUri https://raw.githubusercontent.com/exampleuser/MyTemplates/master/storage.parameters.json

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.

However, when you use an external parameter file, you cannot pass other values either inline or from a local file. When you specify a parameter file in the TemplateParameterUri parameter, all inline parameters are ignored. Provide all parameter values in the external file. If your template includes a sensitive value that you cannot include in the parameter file, either add that value to a key vault, or dynamically provide all parameter values inline.

If your template includes a parameter with the same name as one of the parameters in the PowerShell command, PowerShell presents the parameter from your template with the postfix FromTemplate. For example, a parameter named ResourceGroupName in your template conflicts with the ResourceGroupName parameter in the New-AzureRmResourceGroupDeployment cmdlet. You are prompted to provide a value for ResourceGroupNameFromTemplate. In general, you should avoid this confusion by not naming parameters with the same name as parameters used for deployment operations.

Test a deployment

To test your template and parameter values without actually deploying any resources, use Test-​Azure​Rm​Resource​Group​Deployment. It has all the same options for using local or remote files.

Test-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\MyTemplates\storage.json -storageNamePrefix contoso -storageSKU Standard_GRS

Log deployment content for debugging

Information about deployment operations is automatically logged in the activity logs. However, to log additional information about the deployment that may help you troubleshoot any deployment errors, use the DeploymentDebugLogLevel parameter. You can specify that request content, response content, or both be logged with the deployment operation.

New-AzureRmResourceGroupDeployment -Name ExampleDeployment -DeploymentDebugLogLevel All `
  -ResourceGroupName ExampleGroup -TemplateFile storage.json

For information about viewing the logs, see View activity logs to audit actions on resources.

Export Resource Manager template

For an existing resource group (deployed through PowerShell or one of the other methods like the portal), you can view the Resource Manager template for the resource group. Exporting the template offers two benefits:

  1. You can easily automate future deployments of the solution because all the infrastructure is defined in the template.
  2. You can become familiar with template syntax by looking at the JavaScript Object Notation (JSON) that represents your solution.

To view the template for a resource group, run the Export-AzureRmResourceGroup cmdlet.

Export-AzureRmResourceGroup -ResourceGroupName ExampleResourceGroup

For more information, see Export an Azure Resource Manager template from existing resources.

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. However, you cannot update the location or type of an existing resource. Instead, deploy a new resource with the location or type that you need.

By default, Resource Manager uses the incremental mode.

To use complete mode, use the Mode parameter:

New-AzureRmResourceGroupDeployment -Mode Complete -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup -TemplateFile c:\MyTemplates\storage.json 

Next steps