Create a template deployment

Article
03/18/2016

Create a template deployment of resources. Templates can be nested as shown in an example below.

Note

You need to Create a resource group before you can deploy resources.

Request

See Common parameters and headers for headers and parameters that are used by all requests related to template deployments.

Method	Request URI
PUT	https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/microsoft.resources/deployments/{deployment-name}?api-version={api-version}

Replace {resource-group-name} with the name of the resource group to which you want to deploy resources. Replace {deployment-name} with the name of the new deployment.

The template and the deployment parameters can be provided directly in the request or from a file stored in Azure storage. The following example shows using a link to a template file and a link to a parameters file in storage:

{
  "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",      
    },
    "debugSetting": {
      "detailLevel": "requestContent, responseContent"
    }
  }
}

The following example shows a request to create a website with a template body and deployment parameters specified in the request:

{
  "properties": {
    "template": {
      "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
      "contentVersion": "1.0.0.0",
      "variables": { "myWorkerSize": 0 },
      "parameters": {
        "siteName": { "type": "string" },
        "hostingPlanName": { "type": "string" },
        "siteLocation": { "type": "string" },
        "sku": { 
          "type": "string",
          "allowedValues": [ "Free", "Shared", "Basic", "Standard" ],
          "defaultValue": "Free"
        },
        "workerSize": {
          "type": "string",
          "allowedValues": [ "0", "1", "2" ],
          "defaultValue": "0"
        }
      },
      "resources": [ {
        "name": "myplan1",
        "type": "Microsoft.Web/serverfarms",
        "apiVersion": "2015-01-01",
        "location": "West US",
        "tags": { "dept": "test" },
        "properties": {
          "Name": "myplan1",
          "sku": "Free",
          "workerSize": "[variables('myWorkerSize')]",
          "numberOfWorkers": 1
        }
      },
      {
        "name": "[parameters('siteName')]",
        "type": "Microsoft.Web/sites",
        "apiVersion": "2015-01-01",
        "location": "[parameters('siteLocation')]",
        "tags": {
          "[concat('hidden-related:', resourceGroup().id, 
            '/providers/Microsoft.Web/serverfarms/', 
            parameters('hostingPlanName'))]": "Resource"
        },
        "dependsOn": [
          "[concat('Microsoft.Web/serverfarms/', parameters('hostingPlanName'))]"
        ],
        "properties": {
          "name": "[parameters('siteName')]",
          "serverFarm": "[parameters('hostingPlanName')]"
        },
        "resources": [ {
          "name": "MSDeploy",
          "type": "Extensions",
          "apiVersion": "2015-01-01",
          "dependsOn": [
            "[concat('Microsoft.Web/Sites/', parameters('siteName'))]"
          ],
          "properties": {
            "packageUri": "https://auxmktplceprod.blob.core.windows.net/packages/ASPNETEmptySite.zip",
            "dbType": "None",
            "connectionString": "",
            "setParameters": { "Application Path": "[parameters('siteName')]" }
          }
        } ]
      } ] 
     },
     "mode": "Incremental",
     "parameters": {
       "siteName": { "value": "mysite1" }, 
       "hostingPlanName": { "value": "myplan1" },
       "siteLocation": { "value": "West US" },
       "sku": { "value": "Free" },"workerSize": { "value": "0" }
    }
  }
}

In the above example, if you set mode to Complete, only the service plan and web site will exist in the resource group after deployment. Other existing resources will be deleted.

The following example shows a template that specifies another template. Only the root-level template is allowed Complete for the deployment mode.

{
  "properties": {
    "template": {
      "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
      "contentVersion": "1.0.0.0",
      "parameters": {
        "childParameter": { "type": "string" }
      },
      "resources": [ {
        "name": "Sub-deployment",
        "type": "Microsoft.Resources/deployments",
        "apiVersion": "2015-01-01",
        "properties": {
          "mode": "Incremental",
          "templateLink": {
            "uri": "http://mystorageaccount.blob.core.windows.net/templates/template.json",
            "contentVersion": "1.0.0.0",
          },
          "parameters": {
            "subParameterName": { "value": "[parameters('childParameter')]" }
          }
        }
      } ] 
    }
  }
}

properties

Element name	Required	Type	Description
templateLink	No	Collection	Specifies a collection of information about the template file. You specify this element when you need to point to an existing template. Either the templateLink element or the template element must be used, but not both.
template	No	Complex Type	Specifies the JSON definition for the template. You use this element when you want to pass the template syntax directly in the request rather than link to an existing template. Either the templateLink element or the template element must be used, but not both. For more information about the template schema, see Authoring Azure Resource Manager templates.
mode	Yes	String	Specifies the mode that is used to deploy resources. This value could be either Incremental or Complete. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In complete mode resources are deployed and existing resources in the resource group not included in the template are deleted.
parametersLink	No	Collection	Specifies the collection of information about the parameters file. You use this element to link to an existing parameters file. Either the parametersLink element or the parameters element can be used, but not both.
parameters	No	Collection	Specifies the name and value pairs that define the deployment parameters for the template. You use this element when you want to provide the parameter values directly in the request rather than link to an existing parameter file. Either the parametersLink element or the parameters element is used, but not both. For more information about template parameters, see Authoring Azure Resource Manager templates.
debugSetting	No	Collection	Specifies the information to log for debugging.

templateLink

Element name	Required	Type	Description
uri	No	String	Specifies the URI that is used to locate the template file in storage. The blob must be publicly accessible. This element is required if the templateLink element is used.
contentVersion	No	String	Specifies the version of the template. The value must match the value of the contentVersion element in the template file. This element is required if the templateLink element is used.

parametersLink

Element name	Required	Type	Description
uri	No	String	Specifies the URI that is used to locate the parameters file in storage. The blob must be publicly accessible. This element is required if the parametersLink element is used.
contentVersion	No	String	Specifies the version of the deployment parameters. The value must match the value of the contentVersion element in the parameter file. This element is required if the parametersLink element is used.

debugSetting

Element name	Required	Type	Description
detailLevel	No	String	Specifies the type of information to log for debugging. The permitted values are none, requestContent, responseContent, or both requestContent and responseContent separated by a comma. The default is none. When setting this value, carefully consider the type of information you are passing in during deployment. By logging information about the request or response, you could potentially expose sensitive data that is retrieved through the deployment operations.

detailLevel

String

Specifies the type of information to log for debugging. The permitted values are none, requestContent, responseContent, or both requestContent and responseContent separated by a comma. The default is none.

When setting this value, carefully consider the type of information you are passing in during deployment. By logging information about the request or response, you could potentially expose sensitive data that is retrieved through the deployment operations.

Response

Status code: 201

The following example shows the response for a template deployment that gets its files from storage:

{ 
  "id": "/subscriptions/########-####-####-####-############/resourceGroups/myresourcegroup1/providers/microsoft.resources/deployments/mydeployment1",
  "name":"mydeployment1",
  "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",
    },
    "parameters":{
      "parameter1": {
        "type":"string",
        "value":"parameter1"
      }
    },
    "mode":"Incremental",
    "debugSetting":{"detailLevel":"RequestContent, ResponseContent"},
    "provisioningState":"Accepted",
    "timestamp":"2014-10-13T18:26:20.6229141Z",
    "correlationId":"d5062e45-6e9f-4fd3-a0a0-6b2c56b15757",
    "outputs": {
      "key1" : {
        "type":"string",           
        "value":"output1"
      }
    }, 
    "providers": [ {
      "namespace": "namespace1",
      "resourceTypes": [ {
        "resourceType": "resourceType1",
        "locations": ["westus"]
      } ]
    } ], 
    "dependencies": [ {
      "dependsOn": [ {
        "id":"resourceid1",
        "resourceType":"namespace1/resourcetype1",
        "resourceName":"resourcename1"
      } ],
      "id":"resourceid2",
      "resourceType":"namespace1/resourcetype2",
      "resourceName":"resourcename2"
    } ]  
  }
}

Element name	Description
id	Specifies the identifying URL of the deployment.
name	Specifies the name of the deployment.
uri	Specifies the URI for a file in storage.
contentVersion	Specifies the version of the file contents.
type	Specifies the type of the specified value.
value	Specifies the value that is assigned to the element.
mode	Specifies the mode that is used to deploy resources. This value will be Incremental or Complete.
debugSetting	Specifies the level of information to log for debugging.
provisioningState	Possible values are: Accepted Ready Canceled Failed Deleted Succeeded A resource may supply its own provisioning string that represents an intermediate state, such as Creating or Deleting.
timestamp	Specifies the time that the operation ran.
correlationId	Specifies a unique identifier for the deployment that can be used to find associated events in the event service.
namespace	Specifies the namespace of the resource provider.
resourceType	Specifies the type of the resource or resource provider.
resourceName	Specifies the name of a resource.
locations	Specifies the list of geo-locations where the resource is available.

The following example shows the response for a template and deployment parameters defined directly in the request:

{ 
  "id": "/subscriptions/########-####-####-#################/resourceGroups/myresourcegroup1/providers/microsoft.resources/deployments/mydeployment1",
  "name":"mydeployment1",
  "properties": {    
    "parameters":{
      "parameter1": {
        "type":"string",
        "value":"parameter1"
      }
    },
    "mode":"Incremental",
    "provisioningState":"Accepted",
    "timestamp":"2015-01-01T18:26:20.6229141Z",
    "correlationId":"d5062e45-6e9f-4fd3-a0a0-6b2c56b15757",
    "outputs": {
      "key1" : {
        "type":"string",           
        "value":"output1"
      }
    }, 
    "providers": [ {
      "namespace": "namespace1",
      "resourceTypes": [ {
        "resourceType": "resourceType1",
        "locations": ["westus"]
      } ]
    } ], 
    "dependencies": [ {
      "dependsOn": [ {
        "id":"resourceid1",
        "resourceType":"namespace1/resourcetype1",
        "resourceName":"resourcename1"
      }],
      "id":"resourceid2",
      "resourceType":"namespace1/resourcetype2",
      "resourceName":"resourcename2"
    }]  
  }
}

Remarks

To track the progress of a template deployment, see Get information about a template deployment operation. You can run multiple template deployments at the same time, if the deployments have different names. However, there is no way to guarantee the order of simultaneous deployments, so running more than one deployment that affects the same resource will produce unpredictable results.

For nested templates, deployment mode Complete is only allowed on the root-level template.

For all resources that you plan to deploy using the template, you must make sure that your subscription is registered with the resource provider that provides the resource. For more information, see Register a subscription with a resource provider. Before actually deploying anything, you can validate whether resources can be successfully deployed using your template. For more information, see Validate a template deployment. For more information about the structure of a template, see Authoring Azure Resource Manager templates.