Deploy resources with Resource Manager templates and Resource Manager REST API

This article explains how to use the Resource Manager REST API with Resource Manager templates to deploy your resources to Azure.

Tip

For help with debugging an error during deployment, see:

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.

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

Deploy with the REST API

  1. Set common parameters and headers, including authentication tokens.
  2. If you do not have an existing resource group, create a resource group. Provide your subscription ID, the name of the new resource group, and location that you need for your solution. For more information, see Create a resource group.

     PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>?api-version=2015-01-01
       <common headers>
       {
         "location": "West US",
         "tags": {
            "tagname1": "tagvalue1"
         }
       }
    
  3. Validate your deployment before executing it by running the Validate a template deployment operation. When testing the deployment, provide parameters exactly as you would when executing the deployment (shown in the next step).
  4. Create a deployment. Provide your subscription ID, the name of the resource group, the name of the deployment, and a link to your template. For information about the template file, see Parameter file. For more information about the REST API to create a resource group, see Create a template deployment. Notice the mode is set to Incremental. 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.

     PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>/providers/Microsoft.Resources/deployments/<YourDeploymentName>?api-version=2015-01-01
       <common headers>
       {
         "properties": {
           "templateLink": {
             "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json",
             "contentVersion": "1.0.0.0"
           },
           "mode": "Incremental",
           "parametersLink": {
             "uri": "http://mystorageaccount.blob.core.windows.net/templates/parameters.json",
             "contentVersion": "1.0.0.0"
           }
         }
       }
    

    If you want to log response content, request content, or both, include debugSetting in the request.

     "debugSetting": {
       "detailLevel": "requestContent, responseContent"
     }
    

    You can set up your storage account to use a shared access signature (SAS) token. For more information, see Delegating Access with a Shared Access Signature.

  5. Get the status of the template deployment. For more information, see Get information about a template deployment.

       GET https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>/providers/Microsoft.Resources/deployments/<YourDeploymentName>?api-version=2015-01-01
        <common headers>
    

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" 
            }   
        }
   }
}

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

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.

Next steps