AzureResourceGroupDeployment@2 - Azure resource group deployment v2 task

發行項
02/27/2024

Deploy, start, stop, delete Azure Resource Groups.

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 when action = Create Or Update Resource Group. 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 && action = Create Or Update Resource Group.

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 && action = Create Or Update Resource Group.

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.

csmFile - Template
string. Required when templateLocation = Linked artifact && action = Create Or Update Resource Group.

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 && action = Create Or Update Resource Group.

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.

overrideParameters - Override template parameters
string. Optional. Use when action = Create Or Update Resource Group.

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 when action = Create Or Update Resource Group. 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. Optional. Use when action = Create Or Update Resource Group || action = Select Resource Group. 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 - TFS/VSTS endpoint
Input alias: deploymentGroupEndpoint. string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent && action = Create Or Update Resource Group || action = Select Resource Group.

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 && action = Create Or Update Resource Group || action = Select Resource Group.

Specifies the Team Project which defines the deployment group.

deploymentGroupName - Deployment Group
string. Required when enableDeploymentPrerequisites = ConfigureVMWithDGAgent && action = Create Or Update Resource Group || action = Select Resource Group.

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 && action = Create Or Update Resource Group || action = Select Resource Group. 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.

outputVariable - VM details for WinRM
string. Optional. Use when enableDeploymentPrerequisites = ConfigureVMwithWinRM || enableDeploymentPrerequisites = None && action = Create Or Update Resource Group || action = Select Resource Group.

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.

deploymentOutputs - Deployment outputs
string. Optional. Use when action = Create Or Update Resource Group.

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.

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

共用方式為