overview.md

Overview

This extension provides several build / release tasks to allow you to integrate with Azure DevTest Labs.

1. Create VM
2. Delete VM
3. Create Custom Image
4. Delete Custom Image
5. Create Environment
6. Update Environment
7. Delete Environment

You can find more details about Azure DevTest Labs here.

Warning

When deleting any resources connected to the lab or the lab itself this is a permanent and hard deletion. At this time we do not support restoring any deleted resources.

Create VM

The task allows you to create a lab VM using an ARM template generated from your Lab.

You can generate the ARM template by selecting all the configurations required to create a lab VM and also adding artifacts which you want to apply after the VM is created.

Required Parameters

The task requires the following inputs:

Parameter	Description	Notes
Azure RM Subscription	Azure Resource Manager subscription to configure before running.	This is required to connect to Azure on your behalf.
Lab	Lab in which the resource will be created.	This is a pick list generated as a result of selecting a subscription. Selecting a name from the list will extract the corresponding Lab ID. The Lab ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}. Variables in the form $(varName) are allowed.
Virtual Machine Name	Name of the virtual machine to be created within the selected lab.	This name will replace the value for the template parameter -newVMName. As such, it is expected to be in your ARM template.
Template File	Path to the ARM template.	You can generate the ARM template from the View ARM template section when creating a Lab VM. Select the ARM template by browsing to the file that you have saved in your Azure DevOps source control. It can be either a relative path in a build output or a relative path inside an artifacts package.

Optional Parameters

Parameter	Description	Notes
Parameters File	The input parameters file.	Use either a parameters file or the parameters overrides or both.
Parameter Overrides	ARM template parameters to use.	You can use any system variable such as $(Build.BuildNumber) or $(Release.ReleaseName). Similarly, you can create custom variables such as User.Name and User.Password, where the latter can be marked as a secret.

Optional Parameters - Advanced Options

The following advanced options can be specified on the task to help control the behavior of deployment:

Parameter	Description	Notes
Fail on artifact error	Fail the task if any artifact fails to apply successfully.
Retry the deployment following any failure	Retry the deployment when failing to create the lab VM or if any artifact fails to apply successfully.
Number of times to retry the deployment	Number of times to retry the deployment when an error occurs.	This can be either while creating the lab VM or if any artifact fails to apply successfully.
Delete the failed lab VM before retrying	Delete the failed lab VM before retrying to create a new lab VM.	This is used to clean up.
Delete the failed deployment before retrying	Delete the failed deployment before retrying to create the lab VM.	This is used to clean up.
Append the retry iteration number to the VM name	Append the retry iteration number to the lab VM name before retrying (i.e. newVMName-1).	This may cause your lab VM name to be longer than allowed.
Number of minutes to wait in case the apply artifacts operation is still running	Number of minutes to wait for the apply artifacts operation to complete after the deployment has indicated completion.

Output Variables

The task can produce the following outputs into corresponding variables:

Variable	Description	Notes
labVmId	Variable set to the created lab VM ID.	The variable can be referred as $(labVmId) in subsequent tasks. To qualify, make sure to set the task's Reference name under Output Variables. For example, using a reference name like vm will allow you to use the variable as $(vm.labVmId).

Delete VM

The task allows you to delete a lab VM.

Required Parameters

The task requires the following inputs:

Parameter	Description	Notes
Azure RM Subscription	Azure Resource Manager subscription to configure before running.	This is required to connect to Azure on your behalf.
Lab	Lab from which the resource will be deleted.	This is a pick list generated as a result of selecting a subscription. Selecting a name from the list will extract the corresponding Lab ID. The Lab ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}. Variables in the form $(varName) are allowed.
Virtual Machine	Virtual Machine that will be deleted.	This is a pick list generated as a result of selecting a lab. Selecting a name from the list will extract the corresponding Virtual Machine ID. The Virtual Machine ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/virtualMachines/{vmName}. Variables in the form $(varName) are allowed. For example, you can use any variable such as $(labVmId), the output of calling Create Azure DevTest Labs VM.

Create Custom Image

The task allows you to create a custom image in your lab based on an existing lab VM.

Required Parameters

The task requires the following inputs:

Parameter	Description	Notes
Azure RM Subscription	Azure Resource Manager subscription to configure before running.	This is required to connect to Azure on your behalf.
Lab	Lab in which the resource will be created.	This is a pick list generated as a result of selecting a subscription. Selecting a name from the list will extract the corresponding Lab ID. The Lab ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}. Variables in the form $(varName) are allowed.
Custom Image Name	Name of the custom image that will be created.	You can use any variable such as $(Build.BuildNumber) or $(Release.ReleaseName) when in a build or a release, respectively.
Source Lab VM	Source Lab VM from which the resource will be created.	The source lab VM must be in the selected lab, as the custom image will be created using its VHD file. Selecting a name from the list will extract the corresponding Lab VM ID. The Lab VM ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/virtualMachines/{vmName}. Variables in the form $(varName) are allowed. For example, you can use any variable such as $(labVmId), the output of calling Create Azure DevTest Labs VM.
OS Type	Type of operating system of the source lab VM.	This is a pick list whose allowed values are Linux or Windows.
Linux OS State	Value indicating how to prepare the source lab VM for custom image creation.	(When OS Type = Linux) This is a pick list whose allowed values are NonDeprovisioned, DeprovisionRequested or DeprovisionRequested. See Deprovisioning for more information.
Windows OS State	Value indicating how to prepare the the source lab VM for custom image creation.	(When OS Type = Windows) This is a pick list whose allowed values are NonSysprepped, SysprepRequested or SysprepRequested. See Sysprep for more information.

Optional Parameters

Parameter	Description	Notes
Description	Description of the custom image that will be created.	If left blank, an auto-generated string will be used as the description.

Output Variables

The task can produce the following outputs into corresponding variables:

Variable	Description	Notes
customImageId	Variable set to the created custom image ID.	The variable can be referred as $(customImageId) in subsequent tasks. To qualify, make sure to set the task's Reference name under Output Variables. For example, using a reference name like ci will allow you to use the variable as $(ci.customImageId).

Delete Custom Image

The task allows you to delete a custom image from the selected lab.

Required Parameters

The task requires the following inputs:

Parameter	Description	Notes
Azure RM Subscription	Azure Resource Manager subscription to configure before running.	This is required to connect to Azure on your behalf.
Lab	Lab from which the resource will be deleted.	This is a pick list generated as a result of selecting a subscription. Selecting a name from the list will extract the corresponding Lab ID. The Lab ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}. Variables in the form $(varName) are allowed.
Custom Image	Custom Image that will be deleted.	This is a pick list generated as a result of selecting a lab. Selecting a name from the list will extract the corresponding Custom Image ID. The Custom Image ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/customImages/{ciName}. Variables in the form $(varName) are allowed. For example, you can use any variable such as $(customImageId), which is the output of calling Create Azure DevTest Labs Custom Image.

Create Environment

The task allows you to create an environment in the selected lab.

Required Parameters

The task requires the following inputs:

Parameter	Description	Notes
Azure RM Subscription	Azure Resource Manager subscription to configure before running.	This is required to connect to Azure on your behalf.
Lab	Lab in which the resource will be created.	This is a pick list generated as a result of selecting a subscription. Selecting a name from the list will extract the corresponding Lab ID. The Lab ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}. Variables in the form $(varName) are allowed.
Environment Name	Name of the environment to be created within the selected lab.
Repository	_Repository from which to pick a template.	This is a pick list generated as a result of selecting a lab. Selecting a name from the list will extract the corresponding Repository ID. The Repository ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/artifactSources/{repoName}. Variables in the form $(varName) are allowed.
Template	Template that should be used to create an environment.	This is a pick list generated as a result of selecting a repository. Selecting a name from the list will extract the corresponding Template ID. The Template ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/artifactSources/{repoName}/armTemplates/{templateName}. Variables in the form $(varName) are allowed.

Optional Parameters

Parameter	Description	Notes
Parameters File	The input parameters file.	Use either a parameters file or the parameters overrides or both.
Parameter Overrides	ARM template parameters to use.	You can use any system variable such as $(Build.BuildNumber) or $(Release.ReleaseName). Similarly, you can create custom variables such as User.Name and User.Password, where the latter can be marked as a secret.
Create output variables based on the environment template output.	_ Create output variables resulting from the creation of the environment._	Any variables that are defined in the outputs section of the ARM template will have a corresponding variable created for use in subsequent build / release tasks.

Output Variables

The task can produce the following outputs into corresponding variables:

Variable	Description	Notes
environmentResourceId	Variable set to the created environment ID.	The variable can be referred as $(environmentResourceId) in subsequent tasks. To qualify, make sure to set the task's Reference name under Output Variables. For example, using a reference name like env will allow you to use the variable as $(env.environmentResourceId).
environmentResourceGroupId	Variable set to the resource group of the created environment.	The variable can be referred as $(environmentResourceGroupId) in subsequent tasks. To qualify, make sure to set the task's Reference name under Output Variables. For example, using a reference name like env will allow you to use the variable as $(env.environmentResourceGroupId).

Update Environment

The task allows you to update an environment with new resources by deploying an ARM template.

Required Parameters

The task requires the following inputs:

Parameter	Description	Notes
Azure RM Subscription	Azure Resource Manager subscription to configure before running.	This is required to connect to Azure on your behalf.
Lab	Lab in which the resource will be updated.	This is a pick list generated as a result of selecting a subscription. Selecting a name from the list will extract the corresponding Lab ID. The Lab ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}. Variables in the form $(varName) are allowed.
Environment	Environment that will be updated.	This is a pick list generated as a result of selecting a lab. Selecting a name from the list will extract the corresponding Environment ID. The Environment ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/users/@me/environments/{envName}. Variables in the form $(varName) are allowed.
Template File	Path to the ARM template to use to update the environment.	The file is expected to be stored in your source control. It can contain any resources that are allowed by an environment.

Optional Parameters

Parameter	Description	Notes
Parameters File	The input parameters file.	Use either a parameters file or the parameters overrides or both.
Parameter Overrides	ARM template parameters to use.	You can use any system variable such as $(Build.BuildNumber) or $(Release.ReleaseName). Similarly, you can create custom variables such as User.Name and User.Password, where the latter can be marked as a secret.
Create output variables based on the environment template output.	_ Create output variables resulting from the creation of the environment._	Any variables that are defined in the outputs section of the ARM template will have a corresponding variable created for use in subsequent build/release tasks.

Output Variables

If enabled, the task can produce the following output variables. Note that you will need to define a Reference Name (i.e. <refName> such as env) under the Output Variables section to correctly reference the variables in the list.

Delete Environment

The task allows you to delete an environment.

Required Parameters

The task requires the following inputs:

Parameter	Description	Notes
Azure RM Subscription	Azure Resource Manager subscription to configure before running.	This is required to connect to Azure on your behalf.
Lab	Lab in which the resource will be deleted.	This is a pick list generated as a result of selecting a subscription. Selecting a name from the list will extract the corresponding Lab ID. The Lab ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}. Variables in the form $(varName) are allowed.
Environment	Environment that will be deleted.	This is a pick list generated as a result of selecting a lab. Selecting a name from the list will extract the corresponding Environment ID. The Environment ID is a value in the form /subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.DevTestLab/labs/{labName}/users/@me/environments/{envName}. Variables in the form $(varName) are allowed. For example, you can use any variable such as $(environmentResourceId), which is the output of calling Create Azure DevTest Labs Environment.