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.

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

Deployment scope

You can target your deployment to a management group, an Azure subscription, or a resource group. In most cases, you'll target deployments to a resource group. Use management group or subscription deployments to apply policies and role assignments across the specified scope. 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 Deployments - Create. The request is sent to:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-05-01

To deploy to a subscription, use Deployments - Create At Subscription Scope. The request is sent to:

PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-05-01

For more information about subscription level deployments, see Create resource groups and resources at the subscription level.

To deploy to a management group, use Deployments - Create At Management Group Scope. The request is sent to:

PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{groupId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-05-01

For more information about management group level deployments, see Create resources at the management group level.

The examples in this article use resource group deployments.

Deploy with the REST API

  1. Set common parameters and headers, including authentication tokens.

  2. If you don't 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=2019-05-01
    

    With a request body like:

    {
     "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. To deploy a template, provide your subscription ID, the name of the resource group, the name of the deployment in the request URI.

    PUT https://management.azure.com/subscriptions/<YourSubscriptionId>/resourcegroups/<YourResourceGroupName>/providers/Microsoft.Resources/deployments/<YourDeploymentName>?api-version=2019-05-01
    

    In the request body, provide a link to your template and parameter file. For more information about the parameter file, see Create Resource Manager parameter file.

    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 aren't in your template.

    {
     "properties": {
       "templateLink": {
         "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json",
         "contentVersion": "1.0.0.0"
       },
       "parametersLink": {
         "uri": "http://mystorageaccount.blob.core.windows.net/templates/parameters.json",
         "contentVersion": "1.0.0.0"
       },
       "mode": "Incremental"
     }
    }
    

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

    {
     "properties": {
       "templateLink": {
         "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json",
         "contentVersion": "1.0.0.0"
       },
       "parametersLink": {
         "uri": "http://mystorageaccount.blob.core.windows.net/templates/parameters.json",
         "contentVersion": "1.0.0.0"
       },
       "mode": "Incremental",
       "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.

    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.

  5. Instead of linking to files for the template and parameters, you can include them in the request body. The following example shows the request body with the template and parameter inline:

    {
       "properties": {
       "mode": "Incremental",
       "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"
             }
           },
           "location": {
             "type": "string",
             "defaultValue": "[resourceGroup().location]",
             "metadata": {
               "description": "Location for all resources."
             }
           }
         },
         "variables": {
           "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
         },
         "resources": [
           {
             "type": "Microsoft.Storage/storageAccounts",
             "name": "[variables('storageAccountName')]",
             "apiVersion": "2018-02-01",
             "location": "[parameters('location')]",
             "sku": {
               "name": "[parameters('storageAccountType')]"
             },
             "kind": "StorageV2",
             "properties": {}
           }
         ],
         "outputs": {
           "storageAccountName": {
             "type": "string",
             "value": "[variables('storageAccountName')]"
           }
         }
       },
       "parameters": {
         "location": {
           "value": "eastus2"
         }
       }
     }
    }
    
  6. To get the status of the template deployment, use Deployments - Get.

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

Next steps