Manage a virtual machine in Azure DevTest Labs

VSTS | TFS 2018 | TFS 2017 | TFS 2015

The Azure DevTest Labs service lets you quickly provision development and test environments using reusable templates. You can use pre-created images, minimize waste with quotas and policies, and minimize costs by using automated shutdown.

By using an extension installed in Visual Studio Team Services (VSTS) or Team Foundation Server (TFS) you can easily integrate your build and release pipeline with Azure DevTest Labs. The extension installs three tasks to create a VM, create a custom image from a VM, and delete a VM. This makes it easy to, for example, quickly deploy a "golden image" for specific test task, then delete it when the test is finished.

This example shows how to create and deploy a VM, create a custom image, then delete the VM. It does so as one complete pipeline, though it reality you would use the tasks individually in your own custom build-test-deploy pipeline.

Get set up

Start by installing the Azure DevTest Labs Tasks extension from Visual Studio Marketplace:

  • For VSTS, choose Install
  • For TFS, choose Download and install the extension on your server.

Create an Azure RM template

Carry out these tasks to create the Azure Resource Manager (ARM) template that you can use to create an Azure Virtual Machine on demand.

  1. Follow the steps in these documents on the Azure website to create an ARM template in your subscription.

  2. Follow the steps in these documents on the Azure website to save the ARM template as a file on your computer. Name the file CreateVMTemplate.json.

  3. Edit the CreateVMTemplate.json file as described in this post on Tarun Arora's blog to configure it for Windows Remote Management (WinRM).

    WinRM access is required to use deploy tasks such as Azure File Copy and PowerShell on Target Machines.

  4. Check the template into your source control system.

  5. Open a text editor and copy the following script into it.

    Param( [string] $labVmId)
    
    $labVmComputeId = (Get-AzureRmResource -Id $labVmId).Properties.ComputeId
    
    # Get lab VM resource group name
    $labVmRgName = (Get-AzureRmResource -Id $labVmComputeId).ResourceGroupName
    
    # Get the lab VM Name
    $labVmName = (Get-AzureRmResource -Id $labVmId).Name
    
    # Get lab VM public IP address
    $labVMIpAddress = (Get-AzureRmPublicIpAddress -ResourceGroupName $labVmRgName
                       -Name $labVmName).IpAddress
    
    # Get lab VM FQDN
    $labVMFqdn = (Get-AzureRmPublicIpAddress -ResourceGroupName $labVmRgName
                  -Name $labVmName).DnsSettings.Fqdn
    
    # Set a variable labVmRgName to store the lab VM resource group name
    Write-Host "##vso[task.setvariable variable=labVmRgName;]$labVmRgName"
    
    # Set a variable labVMIpAddress to store the lab VM Ip address
    Write-Host "##vso[task.setvariable variable=labVMIpAddress;]$labVMIpAddress"
    
    # Set a variable labVMFqdn to store the lab VM FQDN name
    Write-Host "##vso[task.setvariable variable=labVMFqdn;]$labVMFqdn"
    
    
  6. Check the script into your source control system. Name it something like GetLabVMParams.ps1.

    This script, when run on the agent as part of the release definition, collects values that you'll need to deploy your app to the VM if you use task steps such as Azure File Copy or PowerShell on Target Machines. These are the tasks you typically use to deploy apps to an Azure VM, and they require values such as the VM Resource Group name, IP address, and fully-qualified domain name (FDQN).

Deploy

Carry out the following steps to create the release definition in Release Management.

  1. Open the Releases tab of the Build & Release hub and choose the "+" icon to create a new release definition.

  2. In the Create release definition dialog, select the Empty template and choose Next.

  3. In the next page, select Choose Later and then choose Create. This creates a new release definition with one default environment and no linked artifacts.

  4. In the new release definition, choose the ellipses (...) next to the environment name to open the shortcut menu and select Configure variables.

  5. In the Configure - environment dialog, enter the following values for the variables you will use in the release definition tasks:

    • vmName: Enter the name you assigned to the VM when you created the ARM template in the Azure portal.
    • userName: Enter the username you assigned to the VM when you created the ARM template in the Azure portal.
    • password: Enter the password you assigned to the VM when you created the ARM template in the Azure portal. Use the "padlock" icon to hide and secure the password.

  6. The first stage in this deployment is to create the VM you will use as the "golden image" for subsequent deployments. You create this within your Azure DevTestsLab instance using the task specially developed for this purpose. In the release definition, select + Add tasks and add an Azure DevTest Labs Create VM task from the Deploy tab.

  7. Configure the Azure DevTest Labs Create VM task as follows:

    Azure DevTest Labs Tasks Azure DevTest Labs Tasks - Create the VM to use for subsequent deployments.

    • Azure RM Subscription: Select a connection from the list under Available Azure Service Connections or create a more restricted permissions connection to your Azure subscription. For more details, see Azure Resource Manager service endpoint.

    • Lab Name: Select the name of the instance you created earlier.

    • Template Name: Enter the full path and name of the template file you saved into your source code repository. You can use the built-in properties of Release Management to simplify the path, for example: $(System.DefaultWorkingDirectory/Contoso/ARMTemplates/CreateVMTemplate.json.

    • Template Parameters: Enter the parameters for the variables defined in the template. Use the names of the variables you defined in the environment, for example: -newVMName '$(vmName)' -userName '$(userName)' -password (ConvertTo-SecureString -String '$(password)' -AsPlainText -Force).

    • Output Variables - Lab VM ID: You will need the ID of the newly created VM in subsequent steps. The default name of the environment variable that will automatically be populated with this ID is set in the Output Variables section. You can edit this if required, but remember to use the correct name in subsequent tasks. The Lab VM ID is in the form: /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/virtualMachines/{vmName}.

  8. The next stage is to execute the script you created earlier to collect the details of the DevTest Labs VM. In the release definition, select + Add tasks and add an Azure PowerShell task from the Deploy tab. Configure the task as follows:

    Azure PowerShell Deploy: Azure PowerShell - Execute the script to collect the details of the DevTest Labs VM.

    • Azure Connection Type: Azure Resource Manager.

    • Azure RM Subscription: Select a connection from the list under Available Azure Service Connections or create a more restricted permissions connection to your Azure subscription. For more details, see Azure Resource Manager service endpoint.

    • Script Type: Script File.

    • Script Path: Enter the full path and name of the script you saved into your source code repository. You can use the built-in properties of Release Management to simplify the path, for example: $(System.DefaultWorkingDirectory/Contoso/Scripts/GetLabVMParams.ps1.

    • Script Arguments: Enter as the script argument the name of the environment variable that was automatically populated with the ID of the lab VM by the previous task, for example: -labVmId '$(labVMId)'. |

    The script collects the values you will require and stores them in environment variables within the release definition so that you can easily refer to them in subsequent task steps.

  9. Now you can deploy your app to the new DevTest Labs VM. The tasks you will typically use for this are Azure File Copy and PowerShell on Target Machines.

    • The information about the VM you'll need for the parameters of these tasks is stored in three configuration variables named labVmRgName, labVMIpAddress, and labVMFqdn within the release definition.
    • If you just want to experiment with creating a DevTest Labs VM and a custom image, without deploying an app to it, just skip this step.

  10. The next stage is to create an image of the newly deployed VM in your Azure DevTest Labs instance. You can then use this image to create copies of the VM on demand, whenever you want to execute a dev task or run some tests. In the release definition, select + Add tasks and add an Azure DevTest Labs Create Custom Image task from the Deploy tab. Configure it as follows:

    Azure DevTest Labs Tasks Azure DevTest Labs Tasks - Create an image of the VM.

    • Azure RM Subscription: Select a connection from the list under Available Azure Service Connections or create a more restricted permissions connection to your Azure subscription. For more details, see Azure Resource Manager service endpoint.

    • Lab Name: Select the name of the instance you created earlier.

    • Custom Image Name: Enter a name for the custom image you will create.

    • Description: Optionally enter a description to make it easy to select the correct image later.

    • Source Lab VM - Source Lab VM ID: If you changed the default name of the environment variable that was automatically populated with the ID of the lab VM by an earlier task, edit it here. The default is $(labVMId).

    • Output Variables - Lab VM ID: You will need the ID of the newly created image when you want to manage or delete it. The default name of the environment variable that will automatically be populated with this ID is set in the Output Variables section. You can edit this if required.

  11. The final stage in this example is to delete the VM you deployed in your Azure DevTest Labs instance. In reality you will, of course, do this after you execute the dev tasks or run the tests you need on the deployed VM. In the release definition, select + Add tasks and add an Azure DevTest Labs Delete VM task from the Deploy tab. Configure it as follows:

    Azure DevTest Labs Tasks Azure DevTest Labs Tasks - Delete the VM.

    • Azure RM Subscription: Select a connection from the list under Available Azure Service Connections or create a more restricted permissions connection to your Azure subscription. For more details, see Azure Resource Manager service endpoint.

    • Lab VM ID: If you changed the default name of the environment variable that was automatically populated with the ID of the lab VM by an earlier task, edit it here. The default is $(labVMId).

  12. Enter a name for the release definition and save it.

  13. Create a new release, select the latest build, and deploy it to the single environment in the definition.

  14. At each stage, refresh the view of your DevTest Labs instance in the Azure portal to see the VM and image being created, and the VM being deleted again. You can now use the custom image to create VMs when required.

    For more information, or if you have any suggestions for improvements to the extension, visit the DevTest Labs feedback forum.

Q&A

I use Team Foundation Server on-premises and I don't see some of these features. Why not?

Some of these features are available only on VSTS and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.

Help and support