Deploy resources with Resource Manager templates and Azure PowerShell

By Tom FitzMacken Updated: 08/15/2016

Contributors:

+11

Edit on GitHub

PowerShell Azure CLI Portal REST API .NET Java Python Node Ruby

In this article:

Quick steps to deployment
Incremental and complete deployments
Deploy with PowerShell
Deploy template from storage with SAS token
Parameter file
Parameter precedence
Next steps
Comments

This topic explains how to use Azure PowerShell with Resource Manager templates to deploy your resources to Azure.

Tip:

For help with debugging an error during deployment, see:

View deployment operations with Azure PowerShell to learn about getting information that helps you troubleshoot your error
Troubleshoot common errors when deploying resources to Azure with Azure Resource Manager to learn how to resolve common deployment errors

Your template can be either a local file or an external file that is available through a URI. When your template resides in a storage account, you can restrict access to the template and provide a shared access signature (SAS) token during deployment.

Quick steps to deployment

This article describes all the different options available to you during deployment. However, often you only need two simple commands. To quickly get started with deployment, use the following commands:

New-AzureRmResourceGroup -Name ExampleResourceGroup -Location "West US"
New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup -TemplateFile <PathToTemplate> -TemplateParameterFile <PathToParameterFile>

To learn more about options for deployment that might be better suited to your scenario, continue reading this article.

Incremental and complete deployments

By default, Resource Manager handles deployments as incremental updates to the resource group. With incremental deployment, Resource Manager:

leaves unchanged resources that exist in the resource group but are not specified in the template
adds resources that are specified in the template but do not exist in the resource group
does not re-provision resources that exist in the resource group in the same condition defined in the template
re-provisions existing resources that have updated settings in the template

With complete deployment, Resource Manager:

deletes resources that exist in the resource group but are not specified in the template
adds resources that are specified in the template but do not exist in the resource group
does not re-provision resources that exist in the resource group in the same condition defined in the template
re-provisions existing resources that have updated settings in the template

You specify the type of deployment through the Mode property.

Deploy with PowerShell

Log in to your Azure account.

Add-AzureRmAccount

A summary of your account is returned.

Environment : AzureCloud
Account     : [email protected]
...

If you have multiple subscriptions, provide the subscription ID you wish to use for deployment with the Set-AzureRmContext command.
```
Set-AzureRmContext -SubscriptionID <YourSubscriptionId>
```
Typically, when deploying a new template, you want to create a resource group to contain the resources. If you have an existing resource group that you wish to deploy to, you can skip this step and simply use that resource group.

To create a resource group, provide a name and location for your resource group.
```
New-AzureRmResourceGroup -Name ExampleResourceGroup -Location "West US"
```
A summary of the new resource group is returned.
```
ResourceGroupName : ExampleResourceGroup
Location          : westus
ProvisioningState : Succeeded
Tags              :
Permissions       :
     Actions  NotActions
     =======  ==========
     *
ResourceId        : /subscriptions/######/resourceGroups/ExampleResourceGroup
```
Before executing your deployment, you can validate your deployment settings. The Test-AzureRmResourceGroupDeployment cmdlet enables you to find problems before creating actual resources. The following example shows how to validate a deployment.
```
Test-AzureRmResourceGroupDeployment -ResourceGroupName ExampleResourceGroup -TemplateFile <PathToTemplate>
```
To deploy resources to your resource group, run the New-AzureRmResourceGroupDeployment command and provide the necessary parameters. The parameters include a name for your deployment, the name of your resource group, the path or URL to the template you created, and any other parameters needed for your scenario. If the Mode parameter is not specified, the default value of Incremental is used. To run a complete deployment, set Mode to Complete. Be careful when using the complete mode as you can inadvertently delete resources that are not in your template.

To deploy a local template, use the TemplateFile parameter:
```
New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup -TemplateFile <PathToTemplate>
```
To deploy an external template, use TemplateUri parameter:
```
New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup -TemplateUri <LinkToTemplate>
```
You have the following options for providing parameter values:
1. Use inline parameters.
```
New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup -TemplateFile <PathToTemplate> -myParameterName "parameterValue"
```
2. Use a parameter object.
```
$parameters = @{"<ParameterName>"="<Parameter Value>"}
New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup -TemplateFile <PathToTemplate> -TemplateParameterObject $parameters
```
3. Use a local parameter file. For information about the template file, see Parameter file.
```
New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup -TemplateFile <PathToTemplate> -TemplateParameterFile <PathToParameterFile>
```
4. Use an external parameter file. For information about the template file, see Parameter file.
```
New-AzureRmResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup -TemplateUri <LinkToTemplate> -TemplateParameterUri <LinkToParameterFile>
```
  When you use an external parameter file, you cannot pass other values either inline or from a local file. For more information, see Parameter precedence.
After the resources have been deployed, you will see a summary of the deployment.
```
DeploymentName    : ExampleDeployment
ResourceGroupName : ExampleResourceGroup
ProvisioningState : Succeeded
Timestamp         : 4/14/2015 7:00:27 PM
Mode              : Incremental
...
```
If your template includes a parameter with the same name as one of the parameters in the PowerShell command to deploy the template, you are prompted to provide a value for that parameter 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.
If you want 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 ExampleResourceGroup -TemplateFile <PathOrLinkToTemplate>
```
For more information about using this debugging content to troubleshoot deployments, see Troubleshooting resource group deployments with Azure PowerShell.

Deploy template from storage with SAS token

You can add your templates to a storage account and link to them during deployment with a SAS token.

Important:

By following the steps below, the blob containing the template is accessible to only the account owner. However, when you create a SAS token for the blob, the blob is accessible to anyone with that URI. If another user intercepts the URI, that user is able to access the template. Using a SAS token is a good way of limiting access to your templates, but you should not include sensitive data like passwords directly in the template.

Add private template to storage account

The following steps set up a storage account for templates:

Create a resource group.

New-AzureRmResourceGroup -Name ManageGroup -Location "West US"

Create a storage account. The storage account name must be unique across Azure, so provide your own name for the account.

New-AzureRmStorageAccount -ResourceGroupName ManageGroup -Name storagecontosotemplates -Type Standard_LRS -Location "West US"

Set the current storage account.

Set-AzureRmCurrentStorageAccount -ResourceGroupName ManageGroup -Name storagecontosotemplates

Create a container. The permission is set to Off which means the container is only accessible to the owner.
```
New-AzureStorageContainer -Name templates -Permission Off
```

Add your template to the container.

Set-AzureStorageBlobContent -Container templates -File c:\Azure\Templates\azuredeploy.json

Provide SAS token during deployment

To deploy a private template in a storage account, retrieve a SAS token and include it in the URI for the template.

If you have changed the current storage account, set the current storage account to the one containing your templates.
```
Set-AzureRmCurrentStorageAccount -ResourceGroupName ManageGroup -Name storagecontosotemplates
```

Create a SAS token with read permissions and an expiry time to limit access. Retrieve the full URI of the template including the SAS token.

$templateuri = New-AzureStorageBlobSASToken -Container templates -Blob azuredeploy.json -Permission r -ExpiryTime (Get-Date).AddHours(2.0) -FullUri

Deploy the template by providing the URI that includes the SAS token.

New-AzureRmResourceGroupDeployment -ResourceGroupName ExampleResourceGroup -TemplateUri $templateuri

For an example of using a SAS token with linked templates, see Using linked templates with Azure Resource Manager.

Parameter file

If you use a parameter file to pass parameter values during deployment, you need to create a JSON file with a format similar to the following example.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "webSiteName": {
            "value": "ExampleSite"
        },
        "webSiteHostingPlanName": {
            "value": "DefaultPlan"
        },
        "webSiteLocation": {
            "value": "West US"
        },
        "adminPassword": {
            "reference": {
               "keyVault": {
                  "id": "/subscriptions/{guid}/resourceGroups/{group-name}/providers/Microsoft.KeyVault/vaults/{vault-name}"
               }, 
               "secretName": "sqlAdminPassword" 
            }   
        }
   }
}

If you need to provide a sensitive value for a parameter (such as a password), add that value to a key vault. Retrieve the key vault during deployment as shown in the previous example. For more information, see Pass secure values during deployment.

The size of the parameter file cannot be more than 64 KB.

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.

However, you cannot use inline parameters with an external parameter file. When you specify a parameter file in the TemplateParameterUri parameter, all inline parameters are ignored. You must 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 and reference the key vault in your external parameter file, or dynamically provide all parameter values inline.

For details about using a KeyVault reference to pass secure values, see Pass secure values during deployment.

Next steps

For an example of deploying resources through the .NET client library, see Deploy resources using .NET libraries and a template.
To define parameters in template, see Authoring templates.
For guidance on deploying your solution to different environments, see Development and test environments in Microsoft Azure.