Azure Resource Group Deployment task

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

Azure DevOps Services

Use this task to deploy, start, stop, and delete Azure Resource Groups.

YAML snippet

# Azure resource group deployment
# Deploy an Azure Resource Manager (ARM) template to a resource group and manage virtual machines
- task: AzureResourceGroupDeployment@2
  inputs:
    azureSubscription: 
    #action: 'Create Or Update Resource Group' # Options: create Or Update Resource Group, select Resource Group, start, stop, stopWithDeallocate, restart, delete, deleteRG
    resourceGroupName: 
    #location: # Required when action == Create Or Update Resource Group
    #templateLocation: 'Linked artifact' # Options: linked Artifact, uRL Of The File
    #csmFileLink: # Required when templateLocation == URL Of The File
    #csmParametersFileLink: # Optional
    #csmFile: # Required when  TemplateLocation == Linked Artifact
    #csmParametersFile: # Optional
    #overrideParameters: # Optional
    #deploymentMode: 'Incremental' # Options: Incremental, Complete, Validation
    #enableDeploymentPrerequisites: 'None' # Optional. Options: none, configureVMwithWinRM, configureVMWithDGAgent
    #teamServicesConnection: # Required when enableDeploymentPrerequisites == ConfigureVMWithDGAgent
    #teamProject: # Required when enableDeploymentPrerequisites == ConfigureVMWithDGAgent
    #deploymentGroupName: # Required when enableDeploymentPrerequisites == ConfigureVMWithDGAgent
    #copyAzureVMTags: true # Optional
    #runAgentServiceAsUser: # Optional
    #userName: # Required when enableDeploymentPrerequisites == ConfigureVMWithDGAgent && RunAgentServiceAsUser == True
    #password: # Optional
    #outputVariable: # Optional
    #deploymentName: # Optional
    #deploymentOutputs: # Optional
    #addSpnToEnvironment: false # Optional

Arguments

Argument	Description
ConnectedServiceName Azure subscription	(Required) Select the service connection that contains the Azure subscription for the deployment. Argument aliases: azureSubscription
action Action	(Required) Action to be performed on the Azure resources or resource group. Default value: Create Or Update Resource Group
resourceGroupName Resource group	(Required) Provide the name of a resource group.
location Location	(Required) Location for deploying the resource group. If the resource group already exists in the subscription, then this value will be ignored.
templateLocation Template location	(Required) Select either Linked artifact or URL of the file. Default value: Linked artifact
csmFileLink Template link	(Required) Specify the URL of the template file. Example: https://raw.githubusercontent.com/Azure/... 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, 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 Override template parameters text box. This feature requires that CORS rules are enabled at the source. If templates are in Azure storage blob, refer to this to enable CORS.
csmParametersFileLink Template parameters link	(Optional) Specify the URL of the parameters file. 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 Override template parameters text box. This feature requires that CORS rules are enabled at the source. If templates are in Azure storage blob, refer to this to enable CORS.
csmFile Template	(Required) Specify the path or a pattern pointing to the Azure Resource Manager template. For more information about the templates see https://aka.ms/azuretemplates. To get started immediately use template https://github.com/Azure/azure-quickstart-templates/tree/master/demos/vm-winrm-windows.
csmParametersFile Template parameters	(Optional) Specify the path or a pattern pointing for the parameters file for the Azure Resource Manager template.
overrideParameters Override template parameters	(Optional) To view the template parameters in a grid, click on ... next to Override Parameters textbox. This feature requires that CORS rules are enabled at the source. If templates are in Azure storage blob, refer to this to enable CORS. Or type the template parameters to override in the textbox. Example: -storageName fabrikam -adminUsername $(vmusername) -adminPassword $(password) -azureKeyVaultName $(fabrikamFibre). If the parameter value you're using has multiple words, enclose them in quotes, even if you're passing them 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	(Required) 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. Validation mode enables you to find problems with the template before creating actual resources. Note that this mode always creates a resource group, even if no resources are deployed. Default value: Incremental
enableDeploymentPrerequisites Enable prerequisites	(Optional) These options would be applicable only when the Resource group contains virtual machines. Choosing Deployment Group option would configure Deployment Group agent on each of the virtual machines. Selecting WinRM option configures 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 Inbound NAT rules are configured for target port (5986). Default value: None
deploymentGroupEndpoint Azure Pipelines service connection	(Required) Specify the service connection to connect to an Azure DevOps organization or collection for agent registration. You can create a service connection using +New, and select Token-based authentication. You need a personal access token (PAT) to set up a service connection. ​Click Manage to update the service connection details. Argument aliases: teamServicesConnection
project Team project	(Required) Specify the Team project which has the Deployment Group defined in it. Argument aliases: teamProject
deploymentGroupName Deployment Group	(Required) Specify the Deployment Group against which the Agent(s) will be registered. For more guidance, refer to Deployment Groups.
copyAzureVMTags Copy Azure VM tags to agents	(Optional) Choose if the tags configured on the Azure VM need to be copied to the corresponding Deployment Group agent. By default all Azure tags will be copied following the format Key: Value. Example: An Azure Tag "Role : Web" would be copied as-is to the Agent machine. For more information on how tag Azure resources refer to the link.
runAgentServiceAsUser Run agent service as a user	(Optional) Decide whether to run the agent service as a user other than the default. The default user is NT AUTHORITY\\SYSTEM in Windows and root in Linux.
userName User name	(Required) The username to run the agent service on the virtual machines. For domain users, please enter values as domain\\username or username@domain.com. For local users, please enter just the user name. 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	The password for the user to run the agent service on the Windows VMs. It is assumed that the password is same for the specified user on all the VMs. It can accept variable defined in build or release pipelines as $(passwordVariable). You may mark variable as secret to secure it. For linux VMs, a password is not required and will be ignored.
outputVariable VM details for WinRM	(Optional) Provide a name for the variable for the resource group. The variable can be used as $(variableName) to refer to the resource group in subsequent tasks like in the PowerShell on Target Machines task for deploying applications. Valid only when the selected action is Create, Update or Select, and required when an existing resource group is selected.
deploymentName Deployment name	(Optional) Specifies the name of the resource group deployment to create
deploymentOutputs Deployment outputs	(Optional) Provide a name for the variable for the output variable which will contain the outputs section of the current deployment object in string format. You can 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	Adds service principal ID and key of the Azure endpoint you chose to the script's execution environment. You can use these variables: $servicePrincipalId and $servicePrincipalKey in your override parameters like -key $servicePrincipalKey

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.

Open source

This task is open source on GitHub. Feedback and contributions are welcome.