virtual_machines

Creates, updates, deletes, gets or lists a virtual_machines resource.

Overview

Name	virtual_machines
Type	Resource
Id	azure.dev_test_labs.virtual_machines

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	The identifier of the resource.
name	string	The name of the resource.
allowClaim	boolean	Indicates whether another user can take ownership of the virtual machine.
applicableSchedule	object	The applicable schedule for the virtual machine.
artifactDeploymentStatus	object	The artifact deployment status for the virtual machine.
artifacts	array	The artifacts to be installed on the virtual machine.
computeId	string	The resource identifier (Microsoft.Compute) of the virtual machine.
computeVm	object	The compute virtual machine properties.
createdByUser	string	The email address of creator of the virtual machine.
createdByUserId	string	The object identifier of the creator of the virtual machine.
createdDate	string (date-time)	The creation date of the virtual machine.
customImageId	string	The custom image identifier of the virtual machine.
dataDiskParameters	array	New or existing data disks to attach to the virtual machine after creation.
disallowPublicIpAddress	boolean	Indicates whether the virtual machine is to be created without a public IP address.
environmentId	string	The resource ID of the environment that contains this virtual machine, if any.
expirationDate	string (date-time)	The expiration date for VM.
fqdn	string	The fully-qualified domain name of the virtual machine.
galleryImageReference	object	The Microsoft Azure Marketplace image reference of the virtual machine.
isAuthenticationWithSshKey	boolean	Indicates whether this virtual machine uses an SSH key for authentication.
labSubnetName	string	The lab subnet name of the virtual machine.
labVirtualNetworkId	string	The lab virtual network identifier of the virtual machine.
lastKnownPowerState	string	Last known compute power state captured in DTL.
location	string	The location of the resource.
networkInterface	object	The network interface properties.
notes	string	The notes of the virtual machine.
osType	string	The OS type of the virtual machine.
ownerObjectId	string	The object identifier of the owner of the virtual machine.
ownerUserPrincipalName	string	The user principal name of the virtual machine owner.
password	string	The password of the virtual machine administrator.
planId	string	The id of the plan associated with the virtual machine image.
provisioningState	string	The provisioning status of the resource.
scheduleParameters	array	Virtual Machine schedules to be created.
size	string	The size of the virtual machine.
sshKey	string	The SSH key of the virtual machine administrator.
storageType	string	Storage type to use for virtual machine (i.e. Standard, Premium).
tags	object	The tags of the resource.
type	string	The type of the resource.
uniqueIdentifier	string	The unique immutable identifier of a resource (Guid).
userName	string	The user name of the virtual machine.
virtualMachineCreationSource	string	Tells source of creation of lab virtual machine. Output property only. Known values are: "FromCustomImage", "FromGalleryImage", and "FromSharedGalleryImage".

list

Name	Datatype	Description
id	string	The identifier of the resource.
name	string	The name of the resource.
allowClaim	boolean	Indicates whether another user can take ownership of the virtual machine.
applicableSchedule	object	The applicable schedule for the virtual machine.
artifactDeploymentStatus	object	The artifact deployment status for the virtual machine.
artifacts	array	The artifacts to be installed on the virtual machine.
computeId	string	The resource identifier (Microsoft.Compute) of the virtual machine.
computeVm	object	The compute virtual machine properties.
createdByUser	string	The email address of creator of the virtual machine.
createdByUserId	string	The object identifier of the creator of the virtual machine.
createdDate	string (date-time)	The creation date of the virtual machine.
customImageId	string	The custom image identifier of the virtual machine.
dataDiskParameters	array	New or existing data disks to attach to the virtual machine after creation.
disallowPublicIpAddress	boolean	Indicates whether the virtual machine is to be created without a public IP address.
environmentId	string	The resource ID of the environment that contains this virtual machine, if any.
expirationDate	string (date-time)	The expiration date for VM.
fqdn	string	The fully-qualified domain name of the virtual machine.
galleryImageReference	object	The Microsoft Azure Marketplace image reference of the virtual machine.
isAuthenticationWithSshKey	boolean	Indicates whether this virtual machine uses an SSH key for authentication.
labSubnetName	string	The lab subnet name of the virtual machine.
labVirtualNetworkId	string	The lab virtual network identifier of the virtual machine.
lastKnownPowerState	string	Last known compute power state captured in DTL.
location	string	The location of the resource.
networkInterface	object	The network interface properties.
notes	string	The notes of the virtual machine.
osType	string	The OS type of the virtual machine.
ownerObjectId	string	The object identifier of the owner of the virtual machine.
ownerUserPrincipalName	string	The user principal name of the virtual machine owner.
password	string	The password of the virtual machine administrator.
planId	string	The id of the plan associated with the virtual machine image.
provisioningState	string	The provisioning status of the resource.
scheduleParameters	array	Virtual Machine schedules to be created.
size	string	The size of the virtual machine.
sshKey	string	The SSH key of the virtual machine administrator.
storageType	string	Storage type to use for virtual machine (i.e. Standard, Premium).
tags	object	The tags of the resource.
type	string	The type of the resource.
uniqueIdentifier	string	The unique immutable identifier of a resource (Guid).
userName	string	The user name of the virtual machine.
virtualMachineCreationSource	string	Tells source of creation of lab virtual machine. Output property only. Known values are: "FromCustomImage", "FromGalleryImage", and "FromSharedGalleryImage".

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	resource_group_name, lab_name, name, subscription_id	$expand	Get virtual machine.
list	select	resource_group_name, lab_name, subscription_id	$expand, $filter, $top, $orderby	List virtual machines in a given lab.
create_or_update	insert	resource_group_name, lab_name, name, subscription_id		Create or replace an existing virtual machine. This operation can take a while to complete.
update	update	resource_group_name, lab_name, name, subscription_id		Allows modifying tags of virtual machines. All other properties will be ignored.
create_or_update	replace	resource_group_name, lab_name, name, subscription_id		Create or replace an existing virtual machine. This operation can take a while to complete.
delete	delete	resource_group_name, lab_name, name, subscription_id		Delete virtual machine. This operation can take a while to complete.
list_applicable_schedules	exec	resource_group_name, lab_name, name, subscription_id		Lists the applicable start/stop schedules, if any.
get_rdp_file_contents	exec	resource_group_name, lab_name, name, subscription_id		Gets a string that represents the contents of the RDP file for the virtual machine.
add_data_disk	exec	resource_group_name, lab_name, name, subscription_id		Attach a new or existing data disk to virtual machine. This operation can take a while to complete.
apply_artifacts	exec	resource_group_name, lab_name, name, subscription_id		Apply artifacts to virtual machine. This operation can take a while to complete.
claim	exec	resource_group_name, lab_name, name, subscription_id		Take ownership of an existing virtual machine This operation can take a while to complete.
detach_data_disk	exec	resource_group_name, lab_name, name, subscription_id		Detach the specified disk from the virtual machine. This operation can take a while to complete.
redeploy	exec	resource_group_name, lab_name, name, subscription_id		Redeploy a virtual machine This operation can take a while to complete.
resize	exec	resource_group_name, lab_name, name, subscription_id		Resize Virtual Machine. This operation can take a while to complete.
restart	exec	resource_group_name, lab_name, name, subscription_id		Restart a virtual machine. This operation can take a while to complete.
start	exec	resource_group_name, lab_name, name, subscription_id		Start a virtual machine. This operation can take a while to complete.
stop	exec	resource_group_name, lab_name, name, subscription_id		Stop a virtual machine This operation can take a while to complete.
transfer_disks	exec	resource_group_name, lab_name, name, subscription_id		Transfers all data disks attached to the virtual machine to be owned by the current user. This operation can take a while to complete.
un_claim	exec	resource_group_name, lab_name, name, subscription_id		Release ownership of an existing virtual machine This operation can take a while to complete.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
lab_name	string	The name of the lab. Required.
name	string	The name of the virtual machine. Required.
resource_group_name	string	The name of the resource group. Required.
subscription_id	string
$expand	string	Specify the $expand query. Example: 'properties($expand=artifacts,computeVm,networkInterface,applicableSchedule)'. Default value is None.
$filter	string	The filter to apply to the operation. Example: '$filter=contains(name,'myName'). Default value is None.
$orderby	string	The ordering expression for the results, using OData notation. Example: '$orderby=name desc'. Default value is None.
$top	integer	The maximum number of resources to return from the operation. Example: '$top=10'. Default value is None.

SELECT examples

get

Get virtual machine.

SELECT
id,
name,
allowClaim,
applicableSchedule,
artifactDeploymentStatus,
artifacts,
computeId,
computeVm,
createdByUser,
createdByUserId,
createdDate,
customImageId,
dataDiskParameters,
disallowPublicIpAddress,
environmentId,
expirationDate,
fqdn,
galleryImageReference,
isAuthenticationWithSshKey,
labSubnetName,
labVirtualNetworkId,
lastKnownPowerState,
location,
networkInterface,
notes,
osType,
ownerObjectId,
ownerUserPrincipalName,
password,
planId,
provisioningState,
scheduleParameters,
size,
sshKey,
storageType,
tags,
type,
uniqueIdentifier,
userName,
virtualMachineCreationSource
FROM azure.dev_test_labs.virtual_machines
WHERE resource_group_name = '{{ resource_group_name }}' -- required
AND lab_name = '{{ lab_name }}' -- required
AND name = '{{ name }}' -- required
AND subscription_id = '{{ subscription_id }}' -- required
AND $expand = '{{ $expand }}'
;

list

List virtual machines in a given lab.

SELECT
id,
name,
allowClaim,
applicableSchedule,
artifactDeploymentStatus,
artifacts,
computeId,
computeVm,
createdByUser,
createdByUserId,
createdDate,
customImageId,
dataDiskParameters,
disallowPublicIpAddress,
environmentId,
expirationDate,
fqdn,
galleryImageReference,
isAuthenticationWithSshKey,
labSubnetName,
labVirtualNetworkId,
lastKnownPowerState,
location,
networkInterface,
notes,
osType,
ownerObjectId,
ownerUserPrincipalName,
password,
planId,
provisioningState,
scheduleParameters,
size,
sshKey,
storageType,
tags,
type,
uniqueIdentifier,
userName,
virtualMachineCreationSource
FROM azure.dev_test_labs.virtual_machines
WHERE resource_group_name = '{{ resource_group_name }}' -- required
AND lab_name = '{{ lab_name }}' -- required
AND subscription_id = '{{ subscription_id }}' -- required
AND $expand = '{{ $expand }}'
AND $filter = '{{ $filter }}'
AND $top = '{{ $top }}'
AND $orderby = '{{ $orderby }}'
;

INSERT examples

create_or_update

Create or replace an existing virtual machine. This operation can take a while to complete.

INSERT INTO azure.dev_test_labs.virtual_machines (
location,
tags,
properties,
resource_group_name,
lab_name,
name,
subscription_id
)
SELECT 
'{{ location }}',
'{{ tags }}',
'{{ properties }}',
'{{ resource_group_name }}',
'{{ lab_name }}',
'{{ name }}',
'{{ subscription_id }}'
RETURNING
id,
name,
location,
properties,
tags,
type
;

Manifest

# Description fields are for documentation purposes
- name: virtual_machines
props:
  - name: resource_group_name
    value: "{{ resource_group_name }}"
    description: Required parameter for the virtual_machines resource.
  - name: lab_name
    value: "{{ lab_name }}"
    description: Required parameter for the virtual_machines resource.
  - name: name
    value: "{{ name }}"
    description: Required parameter for the virtual_machines resource.
  - name: subscription_id
    value: "{{ subscription_id }}"
    description: Required parameter for the virtual_machines resource.
  - name: location
    value: "{{ location }}"
    description: |
      The location of the resource.
  - name: tags
    value: "{{ tags }}"
    description: |
      The tags of the resource.
  - name: properties
    value:
      notes: "{{ notes }}"
      ownerObjectId: "{{ ownerObjectId }}"
      ownerUserPrincipalName: "{{ ownerUserPrincipalName }}"
      createdDate: "{{ createdDate }}"
      customImageId: "{{ customImageId }}"
      size: "{{ size }}"
      userName: "{{ userName }}"
      password: "{{ password }}"
      sshKey: "{{ sshKey }}"
      isAuthenticationWithSshKey: {{ isAuthenticationWithSshKey }}
      labSubnetName: "{{ labSubnetName }}"
      labVirtualNetworkId: "{{ labVirtualNetworkId }}"
      disallowPublicIpAddress: {{ disallowPublicIpAddress }}
      artifacts:
        - artifactId: "{{ artifactId }}"
          artifactTitle: "{{ artifactTitle }}"
          parameters: "{{ parameters }}"
          status: "{{ status }}"
          deploymentStatusMessage: "{{ deploymentStatusMessage }}"
          vmExtensionStatusMessage: "{{ vmExtensionStatusMessage }}"
          installTime: "{{ installTime }}"
      galleryImageReference:
        offer: "{{ offer }}"
        publisher: "{{ publisher }}"
        sku: "{{ sku }}"
        osType: "{{ osType }}"
        version: "{{ version }}"
      planId: "{{ planId }}"
      networkInterface:
        virtualNetworkId: "{{ virtualNetworkId }}"
        subnetId: "{{ subnetId }}"
        publicIpAddressId: "{{ publicIpAddressId }}"
        publicIpAddress: "{{ publicIpAddress }}"
        privateIpAddress: "{{ privateIpAddress }}"
        dnsName: "{{ dnsName }}"
        rdpAuthority: "{{ rdpAuthority }}"
        sshAuthority: "{{ sshAuthority }}"
        sharedPublicIpAddressConfiguration:
          inboundNatRules:
            - transportProtocol: "{{ transportProtocol }}"
              frontendPort: {{ frontendPort }}
              backendPort: {{ backendPort }}
      expirationDate: "{{ expirationDate }}"
      allowClaim: {{ allowClaim }}
      storageType: "{{ storageType }}"
      environmentId: "{{ environmentId }}"
      dataDiskParameters:
        - attachNewDataDiskOptions:
            diskSizeGiB: {{ diskSizeGiB }}
            diskName: "{{ diskName }}"
            diskType: "{{ diskType }}"
          existingLabDiskId: "{{ existingLabDiskId }}"
          hostCaching: "{{ hostCaching }}"
      scheduleParameters:
        - name: "{{ name }}"
          location: "{{ location }}"
          tags: "{{ tags }}"
          properties:
            status: "{{ status }}"
            taskType: "{{ taskType }}"
            weeklyRecurrence:
              weekdays:
                - "{{ weekdays }}"
              time: "{{ time }}"
            dailyRecurrence:
              time: "{{ time }}"
            hourlyRecurrence:
              minute: {{ minute }}
            timeZoneId: "{{ timeZoneId }}"
            notificationSettings:
              status: "{{ status }}"
              timeInMinutes: {{ timeInMinutes }}
              webhookUrl: "{{ webhookUrl }}"
              emailRecipient: "{{ emailRecipient }}"
              notificationLocale: "{{ notificationLocale }}"
            targetResourceId: "{{ targetResourceId }}"

UPDATE examples

update

Allows modifying tags of virtual machines. All other properties will be ignored.

UPDATE azure.dev_test_labs.virtual_machines
SET 
-- No updatable properties
WHERE 
resource_group_name = '{{ resource_group_name }}' --required
AND lab_name = '{{ lab_name }}' --required
AND name = '{{ name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
RETURNING
id,
name,
location,
properties,
tags,
type;

REPLACE examples

create_or_update

Create or replace an existing virtual machine. This operation can take a while to complete.

REPLACE azure.dev_test_labs.virtual_machines
SET 
location = '{{ location }}',
tags = '{{ tags }}',
properties = '{{ properties }}'
WHERE 
resource_group_name = '{{ resource_group_name }}' --required
AND lab_name = '{{ lab_name }}' --required
AND name = '{{ name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
RETURNING
id,
name,
location,
properties,
tags,
type;

DELETE examples

delete

Delete virtual machine. This operation can take a while to complete.

DELETE FROM azure.dev_test_labs.virtual_machines
WHERE resource_group_name = '{{ resource_group_name }}' --required
AND lab_name = '{{ lab_name }}' --required
AND name = '{{ name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
;

Lifecycle Methods

list_applicable_schedules

Lists the applicable start/stop schedules, if any.

EXEC azure.dev_test_labs.virtual_machines.list_applicable_schedules 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

get_rdp_file_contents

Gets a string that represents the contents of the RDP file for the virtual machine.

EXEC azure.dev_test_labs.virtual_machines.get_rdp_file_contents 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

add_data_disk

Attach a new or existing data disk to virtual machine. This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.add_data_disk 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required 
@@json=
'{
"attachNewDataDiskOptions": "{{ attachNewDataDiskOptions }}", 
"existingLabDiskId": "{{ existingLabDiskId }}", 
"hostCaching": "{{ hostCaching }}"
}'
;

apply_artifacts

Apply artifacts to virtual machine. This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.apply_artifacts 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required 
@@json=
'{
"artifactId": "{{ artifactId }}", 
"artifactTitle": "{{ artifactTitle }}", 
"parameters": "{{ parameters }}", 
"status": "{{ status }}", 
"deploymentStatusMessage": "{{ deploymentStatusMessage }}", 
"vmExtensionStatusMessage": "{{ vmExtensionStatusMessage }}", 
"installTime": "{{ installTime }}"
}'
;

claim

Take ownership of an existing virtual machine This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.claim 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

detach_data_disk

Detach the specified disk from the virtual machine. This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.detach_data_disk 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

redeploy

Redeploy a virtual machine This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.redeploy 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

resize

Resize Virtual Machine. This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.resize 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

restart

Restart a virtual machine. This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.restart 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

start

Start a virtual machine. This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.start 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

stop

Stop a virtual machine This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.stop 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

transfer_disks

Transfers all data disks attached to the virtual machine to be owned by the current user. This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.transfer_disks 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

un_claim

Release ownership of an existing virtual machine This operation can take a while to complete.

EXEC azure.dev_test_labs.virtual_machines.un_claim 
@resource_group_name='{{ resource_group_name }}' --required, 
@lab_name='{{ lab_name }}' --required, 
@name='{{ name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;