Skip to content

Latest commit

 

History

History
116 lines (73 loc) · 16.2 KB

README.md

File metadata and controls

116 lines (73 loc) · 16.2 KB
Raw

Azure Resource Group Deployment Task

Overview

This task is used to create or update a resource group in Azure using the Azure Resource Manager templates. The task is also used to start, stop, restart and delete virtual machines in a Resource Group, or to delete a resource group, including all the resources within the resource group.

What's new in Version 2.0

  • Works with Xplat agents (Windows, Linux or OSX)
  • Supports Template JSONs located at any publicly accessible http/https URLs. 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
  • Supports viewing/editing template parameters in a grid by clicking on “…” next to Override template 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.
  • NAT rule mapping for VMs that are backed by an Load balancer
  • "Resource group" field is now renamed as "VM details for WinRM" and is included into the section "Advanced deployment options for virtual machines".
  • "Enable prerequisites" dropdown now includes the option to configure deployment group agents on to each of the virtual machines provisioned in the resource group.
  • 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.

Contact Information

Please report a problem at Developer Community Forum if you are facing problems in making this task work. You can also share feedback about the task like, what more functionality should be added to the task, what other tasks you would like to have, at the same place.

Prerequisite for the task

Azure Subscription

To deploy to Azure, an Azure subscription has to be linked to Team Foundation Server or to Visual Studio Team Services using the Services tab in the Account Administration section. Add the Azure subscription to use in the Build or Release Management definition by opening the Account Administration screen (gear icon on the top-right of the screen) and then click on the Services Tab. Create a service endpoint of 'Azure Resource Manager' type. For more troubleshooting guidance around endpoint creation, refer this.

For Azure MSDN accounts, one can either use a Service Principal or a work account. It's easy to create a work account as shown below:

  1. Create an user in the Azure Active Directory from the portal (this is the old Azure portal). After adding the account, the following two things need to be done to use the account in Team Services:
  • Add the Active Directory account to the co-administrators in the subscription. Go to the Settings and then click on administrators and add the account as a co-admin like, testuser@joehotmail.onmicrosoft.com
  • Login to the portal with this Active Directory account wiz. testuser@joehotmail.onmicrosoft.com, and change the password. Initially a temporary password is created and that needs to be changed at the first login.
  1. Add that user and password in the service connections in Team Services and deployments will work with that account.

Azure PowerShell

The task needs the Azure PowerShell version to be installed on the automation agent, and that can be done easily using the Azure PowerShell Installer v1.0.2. Refer to "Supported Azure and AzureRM module versions" section below for recommended versions.

Parameters of the task:

The parameters of the task are described in details, including examples, to show how to input the parameters. The parameters listed with a * are required parameters for the task:

  • Azure Subscription*: Select the service connection for the Azure Subscription where the Resource Group will be created/updated, or where the resource group is located for starting/stopping/restarting/deleting virtual machines in it, or for deleting the resource group. To configure new service connection, select the Azure subscription from the list and click 'Authorize'. If your subscription is not listed or if you want to use an existing Service Principal, you can setup an Azure service connection using 'Manage' link.

  • Action*: Select the action to be performed on the resource group. Following actions are available:

    • Create or Update Resource Group: creates a new resource group or to update an existing one (using Azure Resource Manager templates).
    • Select Resource Group: reads the Resource Group information from Azure and creates an Output Variable with the VMs in the Resource Group. Read more about Output Variables here.
    • Start, Stop, Deallocate, Restart, Delete Virtual Machines
    • Delete Resource Group

  • Resource Group*: Enter the name of the resource group. If this is an existing resource group, and the selected action is to create or update the resource group, then the task will update the resource group with the resources specified in the Azure template. If no Resource Group with the name exists in the subscription, then a new one will be created.

  • Location*: The location where the resource group will be created. If an existing resource group is updated, then this parameter will be ignored.

The following parameters are shown when the selected action is to create or update a resource group:

  • Template location: The location of the Template & the Parameters JSON files. Select "Linked Artifact" if the files are part of the linked code/build artifacts. Select "URL of the file" if the JSON files are located at any publicly accessible http/https URLs. 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.

  • Template and its Parameters: The templates and the templates parameters file are the Azure templates available at GitHub or in the Azure gallery. To get started immediately use this template that is available on GitHub.

    • These files can be either be located at any publicly accessible http/https URLs or be in a checked in the Version Control or they can be part of the build itself. If the files are part of the Build, use the pre-defined system variables provided by the Build to specify their location. The variables to use are $(Build.Repository.LocalPath), if the templates are checked-in but are not built, or $(Agent.BuildDirectory), if the templates are built as part of the solution. Be sure to specify the full path like $(Build.Repository.LocalPath)\Azure Templates\AzureRGDeploy.json. Wildcards like **\*.json or **\*.param.json are also supported and there needs to be only one file that matches the search pattern at the location. If more than one file matches the search pattern, then the task will error out.

NOTE: Follow the Azure Naming guidelines while specifying parameters, few important one mentioned in below table_

Kind Length Casing Valid Chars Globally Unique
Storage Account 3-24 lowercase alphanumeric Yes
Azure Resource Group 2-64 case-insensitive alphanumeric periods, underscores, hyphens and parenthesis and cannot end in a period No
Azure KeyVault 3-24 case-insensitive alphanumeric Yes
Azure DNS Name 3-63 lowercase alphanumeric and hyphens Yes

  • Override Template Parameters: The Override template parameters is used to override the parameters, like -storageAcctName azurerg -Username $(vmusername) -azureKeyVaultName $(fabrikamFibre). To avoid storing "secureString" parameters in plain text, it is recommended that you use secret variables, for example $(variableName). By clicking on “…” next to Override template parameters textbox, template parameters can be viewed/overridden in a grid. This feature requires that CORS rules are enabled at the source. If templates are in Azure storage blob, refer to this to enable CORS.

  • Deployment Mode: This specifies the deployment mode in which the Azure resources specified in the template have to be deployed. 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 syntactical problems with the template before creating actual resources. By default, incremental mode is used.

Advanced deployment options for virtual machines:

These options would be applicable only when the Resource group contains virtual machines.

  • Enable prerequisites: 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). Choosing Deployment group option would configure Deployment group agent on each of the virtual machines.

  • VM details for WinRM: 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. Also this field is visible only when "Enable Prerequisites" dropdown option is not Deployment Group.

Limitation: VM details produced during execution will only contain the VM hostname(s) and (public) ports, if any. Credentials to connect to the VM host(s) are to be provided explicitly in the subsequent tasks.

  • TFS/VSTS endpoint*: Agent registration with Deployment group requires access to your Visual Studio project.​ Click "Add" to create an endpoint using personal access token (PAT) with scope restricted to "Deployment Group" and a default expiration time of 90 days. ​Click "Manage" to update endpoint details.​

  • Team project*: Specify the Team Project which has the Deployment Group defined in it​.

  • Deployment Group: Specify an existing Deployment Group against which the Agent(s) will be registered.

  • Copy Azure VM tags to agents: 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 link

Pre-existing Deployment Group

When "Enable Prerequisites" dropdown option is "Configure with Deployment Group agent", this task downloads the agent installer on each of the machines and register them with an existing Deployment group. If there is no pre-existing Deployment group, you can create one in the Deployment groups hub.

Carry out the following steps to create a Deployment group:

  1. Open your Visual Studio Team Services account in your web browser
  2. Open the Deployment groups tab of the Build & Release hub and choose +Deployment group to create a new group
  3. Enter a name for the group in the Details tab and then choose "Create"

Setting up a virtual machine for WinRM HTTPS using Azure Templates:

Tasks like Azure File Copy, PowerShell on Target Machines, Visual Studio Test Agent Deployment run on the automation agent machine and copy files or deploy apps to Azure VMs using the WinRM HTTPS protocol. For these tasks to work properly, the WinRM HTTPS port (default port is 5986) needs to be opened and configured properly on the virtual machines. Opening the ports and configuring them with the certificates is done using the Azure templates. The sample template uploaded on GitHub shows how to enable the WinRM HTTPS protocol on Azure virtual machines and map them to a Public IP using the Azure resource providers' wiz. Network Interfaces, Load Balancers and Virtual Machines. In addition, it also shows how to specify the Azure Key Vault and its secret, and to download and install the certificate on the virtual machine.

Supported Azure and AzureRM module versions:

VSTS/TFS Release Recommended Azure Version Other Supported Versions
VSTS v1.3.2 v0.9.8
TFS 2015 Update 3 v1.3.2 v0.9.8
TFS 2015 Update 2 v1.0.2 v0.9.8
TFS 2015 Update 1 v0.9.8
TFS 2015 RTM v0.9.8