AzureResourceGroupDeployment@2 - Azure resource group deployment v2 task

Deploy an Azure Resource Manager (ARM) template to a resource group and manage virtual machines.

Deploy an Azure resource manager (ARM) template to a resource group. You can also start, stop, delete, and deallocate all Virtual Machines (VM) in a resource group.

Deploy, start, stop, delete Azure Resource Groups.

Syntax

# Azure resource group deployment v2
# Deploy an Azure Resource Manager (ARM) template to a resource group and manage virtual machines.
- task: AzureResourceGroupDeployment@2
  inputs:
  # Azure Details
    azureSubscription: # string. Alias: ConnectedServiceName. Required. Azure subscription. 
    action: 'Create Or Update Resource Group' # 'Create Or Update Resource Group' | 'Select Resource Group' | 'Start' | 'Stop' | 'StopWithDeallocate' | 'Restart' | 'Delete' | 'DeleteRG'. Required. Action. Default: Create Or Update Resource Group.
    resourceGroupName: # string. Required. Resource group. 
    #location: # string. Required when action = Create Or Update Resource Group. Location. 
  # Template
    templateLocation: 'Linked artifact' # 'Linked artifact' | 'URL of the file'. Required. Template location. Default: Linked artifact.
    #csmFileLink: # string. Required when templateLocation = URL of the file. Template link. 
    #csmParametersFileLink: # string. Optional. Use when templateLocation = URL of the file. Template parameters link. 
    #csmFile: # string. Required when templateLocation = Linked artifact. Template. 
    #csmParametersFile: # string. Optional. Use when templateLocation = Linked artifact. Template parameters. 
    #overrideParameters: # string. Override template parameters. 
    deploymentMode: 'Incremental' # 'Incremental' | 'Complete' | 'Validation'. Required. Deployment mode. Default: Incremental.
  # Advanced deployment options for virtual machines
    #enableDeploymentPrerequisites: 'None' # 'None' | 'ConfigureVMwithWinRM' | 'ConfigureVMWithDGAgent'. Enable prerequisites. Default: None.
    #teamServicesConnection: # string. Alias: deploymentGroupEndpoint. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Azure Pipelines service connection. 
    #teamProject: # string. Alias: project. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Team project. 
    #deploymentGroupName: # string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Deployment Group. 
    #copyAzureVMTags: true # boolean. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Copy Azure VM tags to agents. Default: true.
    #runAgentServiceAsUser: false # boolean. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Run agent service as a user. Default: false.
    #userName: # string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent && runAgentServiceAsUser = true. User name. 
    #password: # string. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent && runAgentServiceAsUser = true. Password. 
    #outputVariable: # string. Optional. Use when enableDeploymentPrerequisites = ConfigureVMwithWinRM || enableDeploymentPrerequisites = None. VM details for WinRM. 
  # Advanced
    #deploymentName: # string. Deployment name. 
    #deploymentOutputs: # string. Deployment outputs. 
    #addSpnToEnvironment: false # boolean. Access service principal details in override parameters. Default: false.
# Azure Resource Group Deployment v2
# Deploy an Azure resource manager (ARM) template to a resource group. You can also start, stop, delete, deallocate all Virtual Machines (VM) in a resource group.
- task: AzureResourceGroupDeployment@2
  inputs:
  # Azure Details
    azureSubscription: # string. Alias: ConnectedServiceName. Required. Azure subscription. 
    action: 'Create Or Update Resource Group' # 'Create Or Update Resource Group' | 'Select Resource Group' | 'Start' | 'Stop' | 'StopWithDeallocate' | 'Restart' | 'Delete' | 'DeleteRG'. Required. Action. Default: Create Or Update Resource Group.
    resourceGroupName: # string. Required. Resource group. 
    #location: # string. Required when action = Create Or Update Resource Group. Location. 
  # Template
    templateLocation: 'Linked artifact' # 'Linked artifact' | 'URL of the file'. Required. Template location. Default: Linked artifact.
    #csmFileLink: # string. Required when templateLocation = URL of the file. Template link. 
    #csmParametersFileLink: # string. Optional. Use when templateLocation = URL of the file. Template parameters link. 
    #csmFile: # string. Required when templateLocation = Linked artifact. Template. 
    #csmParametersFile: # string. Optional. Use when templateLocation = Linked artifact. Template parameters. 
    #overrideParameters: # string. Override template parameters. 
    deploymentMode: 'Incremental' # 'Incremental' | 'Complete' | 'Validation'. Required. Deployment mode. Default: Incremental.
  # Advanced deployment options for virtual machines
    #enableDeploymentPrerequisites: 'None' # 'None' | 'ConfigureVMwithWinRM' | 'ConfigureVMWithDGAgent'. Enable prerequisites. Default: None.
    #teamServicesConnection: # string. Alias: deploymentGroupEndpoint. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Azure Pipelines/TFS service connection. 
    #teamProject: # string. Alias: project. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Team project. 
    #deploymentGroupName: # string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Deployment Group. 
    #copyAzureVMTags: true # boolean. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Copy Azure VM tags to agents. Default: true.
    #runAgentServiceAsUser: false # boolean. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Run agent service as a user. Default: false.
    #userName: # string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent && runAgentServiceAsUser = true. User name. 
    #password: # string. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent && runAgentServiceAsUser = true. Password. 
    #outputVariable: # string. Optional. Use when enableDeploymentPrerequisites = ConfigureVMwithWinRM || enableDeploymentPrerequisites = None. VM details for WinRM. 
  # Outputs
    #deploymentOutputs: # string. Deployment outputs.
# YAML Syntax is not supported in TFS 2018.
# Use the classic designer to add and configure tasks.
# See the following Inputs section for details on the inputs that this task supports.

Inputs

azureSubscription - Azure subscription
Input alias: ConnectedServiceName. string. Required.

Selects the service connection that contains an Azure Subscription for the deployment.


action - Action
string. Required. Allowed values: Create Or Update Resource Group, Select Resource Group (Configure virtual machine deployment options), Start (Start virtual machines), Stop (Stop virtual machines), StopWithDeallocate (Stop and deallocate virtual machines), Restart (Restart virtual machines), Delete (Delete virtual machines), DeleteRG (Delete resource group). Default value: Create Or Update Resource Group.

The action to be performed on the Azure resources or resource group.


resourceGroupName - Resource group
string. Required.

Provides the name of the resource group.


location - Location
string. Required when action = Create Or Update Resource Group.

The location to deploy the resource group. If the resource group already exists in the subscription, then this value will be ignored.


templateLocation - Template location
string. Required. Allowed values: Linked artifact, URL of the file. Default value: Linked artifact.

Select either Linked artifact or URL of the file.


csmFileLink - Template link
string. Required when templateLocation = URL of the file.

Specifies the URL of the template file. An example URL: https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-vm-simple-windows/azuredeploy.json

To deploy a template stored in a private storage account, retrieve and include the shared access signature (SAS) token in the URL of the template. Example: <blob_storage_url>/template.json?<SAStoken>

To upload a template file (or a linked template) to a storage account and generate a SAS token, use the Azure file copy task or follow the steps using PowerShell or Azure CLI.

To view the template parameters in a grid, click on ... next to the override template parameters text box. This feature requires that CORS rules are enabled at the source. If the templates are in an Azure storage blob, see Understanding CORS requests to enable CORS.


csmParametersFileLink - Template parameters link
string. Optional. Use when templateLocation = URL of the file.

Specifies the URL of the parameters file. Example: https://raw.githubusercontent.com/Azure/...

To use a file stored in a private storage account, retrieve and include the shared access signature (SAS) token in the URL of the template. Example: <blob_storage_url>/template.json?<SAStoken> To upload a parameters file to a storage account and generate a SAS token, you could use Azure file copy task or follow the steps using PowerShell or Azure CLI.

To view the template parameters in a grid, click on ... next to the override template parameters text box. This feature requires that CORS rules are enabled at the source. If the templates are in an Azure storage blob, see Understanding CORS requests to enable CORS.


csmFile - Template
string. Required when templateLocation = Linked artifact.

Specifies the path or a pattern pointing to the Azure Resource Manager template. Learn more about Azure Resource Manager templates. To get started immediately, use this sample template.


csmParametersFile - Template parameters
string. Optional. Use when templateLocation = Linked artifact.

Specifies the URL of the parameters file. An example URL: https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-vm-simple-windows/azuredeploy.parameters.json

To use a file stored in a private storage account, retrieve and include the shared access signature (SAS) token in the URL of the template. Example: <blob_storage_url>/template.json?<SAStoken> To upload a parameters file to a storage account and generate a SAS token, use the Azure file copy task or follow the steps using PowerShell or Azure CLI.

To view the template parameters in a grid, click on ... next to the override template parameters text box. This feature requires that CORS rules are enabled at the source. If the templates are in an Azure storage blob, see Understanding CORS requests to enable CORS.


overrideParameters - Override template parameters
string.

Specifies the template parameters to override.

To view the template parameters in a grid, click on ... next to the override parameters textbox. This feature requires that CORS rules are enabled at the source. If the templates are in the Azure storage blob, reference this string to enable CORS, or type the template parameters to override in the textbox.

Example: -storageName fabrikam -adminUsername $(vmusername) -adminPassword (ConvertTo-SecureString -String '$(password)' -AsPlainText -Force) -azureKeyVaultName $(fabrikamFibre).

If the parameter value has multiple words, enclose the words in quotes, even if you're passing the value by using variables. For example, -name "parameter value" -name2 "$(var)". To override object type parameters, use stringified JSON objects. For example, -options ["option1"] -map {"key1": "value1" }.


deploymentMode - Deployment mode
string. Required. Allowed values: Incremental, Complete, Validation (Validation only). Default value: Incremental.

The Incremental mode handles deployments as incremental updates to the resource group. It leaves unchanged resources that exist in the resource group but are not specified in the template.

Complete mode deletes resources that are not in your template. Complete mode takes relatively more time than incremental mode. If the task times out, consider increasing the timeout or changing to the Incremental mode.

Warning

Complete mode will delete all the existing resources in the resource group that are not specified in the template. Do review if the resource group you're deploying to doesn't contain any necessary resources that are not specified in the template.

Validate mode enables you to find problems with the template before creating actual resources.

Note

The Validate mode always creates a resource group, even if no resources are deployed.

Learn more about deployment modes.


enableDeploymentPrerequisites - Enable prerequisites
string. Allowed values: None, ConfigureVMwithWinRM (Configure with WinRM agent), ConfigureVMWithDGAgent (Configure with Deployment Group agent). Default value: None.

Applicable only when the resource group contains virtual machines.

Choosing the Deployment Group option configures the Deployment Group agent on each of the virtual machines.

Selecting the WinRM option configures the Windows Remote Management (WinRM) listener over HTTPS protocol on port 5986 using a self-signed certificate. This configuration is required for performing deployment operation on Azure machines. If the target virtual machines are backed by a load balancer, ensure the Inbound NAT rules are configured for target port (5986).


teamServicesConnection - Azure Pipelines service connection
Input alias: deploymentGroupEndpoint. string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent.

Specifies the service connection to connect to an Azure DevOps organization or collection for agent registration.

You can create a service connection using +New and then selecting Token-based authentication. You need a personal access token(PAT) to setup a service connection. ​Click Manage to update the service connection details.


teamServicesConnection - Azure Pipelines/TFS service connection
Input alias: deploymentGroupEndpoint. string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent.

Specifies the service connection to connect to an Azure DevOps organization or collection for agent registration.

You can create a service connection using +New and then selecting Token-based authentication. You need a personal access token(PAT) to setup a service connection. ​Click Manage to update the service connection details.


teamServicesConnection - TFS/VSTS endpoint
Input alias: deploymentGroupEndpoint. string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent.

Registering agents with the deployment group requires access to your Visual Studio project.

Click Add to create an endpoint using a personal access token (PAT) with its scope restricted to Deployment Group and the default expiration time of 90 days. Click Manage to update endpoint details.​


teamProject - Team project
Input alias: project. string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent.

Specifies the Team Project which defines the deployment group.


deploymentGroupName - Deployment Group
string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent.

Specifies the deployment group against which the agent(s) will be registered. Learn more about deployment groups.


copyAzureVMTags - Copy Azure VM tags to agents
boolean. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Default value: true.

Chooses if the configured tags on the Azure VM need to be copied to the corresponding deployment group agent.

​By default, all Azure tags are copied following the format: Key: Value. Example: A Role : Web Azure tag would be copied as-is to the agent machine.

Learn more about using tags for Azure resources.


runAgentServiceAsUser - Run agent service as a user
boolean. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent. Default value: false.

Runs the agent service as a user other than the default user if the value is set to true.

The default user is NT AUTHORITY\\SYSTEM in Windows and root in Linux.


userName - User name
string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent && runAgentServiceAsUser = true.

The username to run the agent service on the virtual machines.

For domain users, specify values as domain\username or username@domain.com. For local users, specify username.

It is assumed that the same domain user or a local user with the same name, respectively, is present on all the virtual machines in the resource group.


password - Password
string. Optional. Use when enableDeploymentPrerequisites = ConfigureVMWithDGAgent && runAgentServiceAsUser = true.

The password for the user to run the agent service on the Windows VMs.

It is assumed that the password is the same for the specified user on all the VMs.

It can accept variables defined in build or release pipelines as $(passwordVariable). You may mark the variable as secret to secure it.

For Linux VMs, a password is not required and will be ignored.


outputVariable - VM details for WinRM
string. Optional. Use when enableDeploymentPrerequisites = ConfigureVMwithWinRM || enableDeploymentPrerequisites = None.

Required when an existing resource group is selected. Provides a name for the resource group variable. The variable can be used as $(variableName) to refer to the resource group in subsequent tasks, such as in PowerShell on Target Machines task for deploying applications.

Valid only when the selected action is Create, Update, or Select.


deploymentName - Deployment name
string.

Specifies the name of the resource group deployment to create.


deploymentOutputs - Deployment outputs
string.

Provides a name for the output variable, which contains the outputs section of the current deployment object in string format. Use the ConvertFrom-Json PowerShell cmdlet to parse the JSON object and access the individual output values.


addSpnToEnvironment - Access service principal details in override parameters
boolean. Default value: false.

Adds the service principal ID and key of the Azure endpoint chosen to be the script's execution environment. The variables $servicePrincipalId and $servicePrincipalKey can be in override parameters, such as -key $servicePrincipalKey.


Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

What's new in task version 2

  • Works with cross-platform agents (Linux, macOS, or Windows)
  • Supports Template JSONs located at any publicly accessible http/https URLs.
  • Enhanced UX for Override parameters which can now be viewed/edited in a grid.
  • NAT rule mapping for VMs which are backed by an Load balancer.
  • "Resource group" field is now renamed as "VM details for  WinRM" and is included in the section "Advanced deployment options for virtual machines".
  • Limitations:
    • No support for Classic subscriptions. Only ARM subscriptions are supported.
    • No support for PowerShell syntax as the task is now node.js based. Ensure the case sensitivity of the parameter names match, when you override the template parameters. Also, remove the PowerShell cmdlets like "ConvertTo-SecureString" when you migrate from version 1.0 to version 2.0.

Troubleshooting

Error: Internal Server Error

These issues are mostly transient in nature. There are multiple reasons why it could be happening:

  • One of the Azure services you're trying to deploy is undergoing maintenance in the region you're trying to deploy to. Keep an eye out on https://status.azure.com/ to check downtimes of Azure Services.
  • Azure Pipelines service itself is going through maintenance. Keep an eye out on https://status.dev.azure.com/ for downtimes.

However, we've seen some instances where this is due to an error in the ARM template, such as the Azure service you're trying to deploy doesn't support the region you've chosen for the resource.

Error: Timeout

Timeout issues could be coming from two places:

  • Azure Pipelines Agent
  • Portal Deployment

You can identify if the timeout is from portal, by checking for the portal deployment link that'll be in the task logs. If there's no link, this is likely due to Azure Pipelines agent. If there's a link, follow the link to see if there's a timeout that has happened in the portal deployment.

Error: CORS rules to be enabled while overriding parameters

If the template file is being referred from a BLOB, while overriding parameters in the pipeline, you might see the following warning message:

Warning: Failed to download the file from template path.

This feature requires the CORS rules to be enabled at the source. If templates are in Azure storage blob, see Cross-origin resource sharing support to enable CORS.

Besides enabling CORS, ensure that the SAS token specified in the link of the template is "srt-sco". This token is required for you to download the file and proceed.

Azure Pipelines Agent

If the issue is coming from Azure Pipelines agent, you can increase the timeout by setting timeoutInMinutes as key in the YAML to 0. For more information, see Specify jobs in your pipeline.

Portal Deployment

Check out this doc on how to identify if the error came from the Azure portal: View deployment history with Azure Resource Manager.

In case of portal deployment, try setting "timeoutInMinutes" in the ARM template to "0". If not specified, the value assumed is 60 minutes. 0 makes sure the deployment will run for as long as it can to succeed.

This could also be happening because of transient issues in the system. Keep an eye on https://status.dev.azure.com/ to check if there's a downtime in Azure Pipelines service.

Error: Azure Resource Manager (ARM) template failed validation

This issue happens mostly because of an invalid parameter in the ARM template, such as an unsupported SKU or region. If the validation fails, check the error message. It should point you to the resource and parameter that's invalid.

This issue also might occur because of multiline strings. Currently, the Azure Resource Group Deployment task doesn't support multiline strings in an ARM template or parameter JSON file.

In addition, refer to this article regarding structure and syntax of ARM Templates: Understand the structure and syntax of ARM templates.

Requirements

Requirement Description
Pipeline types YAML, Classic build, Classic release
Runs on Agent, DeploymentGroup
Demands None
Capabilities This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions Any
Settable variables Any
Agent version 2.119.1 or greater
Task category Deploy