Azure Resource Group Deployment task

02/10/2020
8 minutes to read

Azure Pipelines

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, Validate
    #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 Azure Resource Manager 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?. 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. 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?. 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://aka.ms/sampletemplate.
`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. Validate 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. Check out this article for more details: https://docs.microsoft.com/azure/devops/pipelines/process/phases?tabs=yaml.

Portal Deployment

Check out this doc on how to identify if the error came from the Azure portal: https://docs.microsoft.com/azure/azure-resource-manager/templates/deployment-history?tabs=azure-portal.

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 has failed, please check the error message. It should point you to the resource and parameter that is invalid.

In addition, refer to this article regarding structure and syntax of ARM Templates: https://docs.microsoft.com/azure/azure-resource-manager/templates/template-syntax.

Open source

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