virtual_machines

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

Overview

Name	virtual_machines
Type	Resource
Id	azure.compute.virtual_machines

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	Resource Id
name	string	Resource name
etag	string	Etag is property returned in Create/Update/Get response of the VM, so that customer can supply it in the header to ensure optimistic updates.
extendedLocation	object	The extended location of the Virtual Machine.
identity	object	The identity of the virtual machine, if configured.
location	string	Resource location
managedBy	string	ManagedBy is set to Virtual Machine Scale Set(VMSS) flex ARM resourceID, if the VM is part of the VMSS. This property is used by platform for internal resource group delete optimization.
plan	object	Specifies information about the marketplace image used to create the virtual machine. This element is only used for marketplace images. Before you can use a marketplace image from an API, you must enable the image for programmatic use. In the Azure portal, find the marketplace image that you want to use and then click Want to deploy programmatically, Get Started ->. Enter any required information and then click Save.
properties	object	Describes the properties of a Virtual Machine.
resources	array	The virtual machine child extension resources.
tags	object	Resource tags
type	string	Resource type
zones	array	The virtual machine zones.

list_by_location

Name	Datatype	Description
id	string	Resource Id
name	string	Resource name
etag	string	Etag is property returned in Create/Update/Get response of the VM, so that customer can supply it in the header to ensure optimistic updates.
extendedLocation	object	The extended location of the Virtual Machine.
identity	object	The identity of the virtual machine, if configured.
location	string	Resource location
managedBy	string	ManagedBy is set to Virtual Machine Scale Set(VMSS) flex ARM resourceID, if the VM is part of the VMSS. This property is used by platform for internal resource group delete optimization.
plan	object	Specifies information about the marketplace image used to create the virtual machine. This element is only used for marketplace images. Before you can use a marketplace image from an API, you must enable the image for programmatic use. In the Azure portal, find the marketplace image that you want to use and then click Want to deploy programmatically, Get Started ->. Enter any required information and then click Save.
properties	object	Describes the properties of a Virtual Machine.
resources	array	The virtual machine child extension resources.
tags	object	Resource tags
type	string	Resource type
zones	array	The virtual machine zones.

list

Name	Datatype	Description
id	string	Resource Id
name	string	Resource name
etag	string	Etag is property returned in Create/Update/Get response of the VM, so that customer can supply it in the header to ensure optimistic updates.
extendedLocation	object	The extended location of the Virtual Machine.
identity	object	The identity of the virtual machine, if configured.
location	string	Resource location
managedBy	string	ManagedBy is set to Virtual Machine Scale Set(VMSS) flex ARM resourceID, if the VM is part of the VMSS. This property is used by platform for internal resource group delete optimization.
plan	object	Specifies information about the marketplace image used to create the virtual machine. This element is only used for marketplace images. Before you can use a marketplace image from an API, you must enable the image for programmatic use. In the Azure portal, find the marketplace image that you want to use and then click Want to deploy programmatically, Get Started ->. Enter any required information and then click Save.
properties	object	Describes the properties of a Virtual Machine.
resources	array	The virtual machine child extension resources.
tags	object	Resource tags
type	string	Resource type
zones	array	The virtual machine zones.

list_all

Name	Datatype	Description
id	string	Resource Id
name	string	Resource name
etag	string	Etag is property returned in Create/Update/Get response of the VM, so that customer can supply it in the header to ensure optimistic updates.
extendedLocation	object	The extended location of the Virtual Machine.
identity	object	The identity of the virtual machine, if configured.
location	string	Resource location
managedBy	string	ManagedBy is set to Virtual Machine Scale Set(VMSS) flex ARM resourceID, if the VM is part of the VMSS. This property is used by platform for internal resource group delete optimization.
plan	object	Specifies information about the marketplace image used to create the virtual machine. This element is only used for marketplace images. Before you can use a marketplace image from an API, you must enable the image for programmatic use. In the Azure portal, find the marketplace image that you want to use and then click Want to deploy programmatically, Get Started ->. Enter any required information and then click Save.
properties	object	Describes the properties of a Virtual Machine.
resources	array	The virtual machine child extension resources.
tags	object	Resource tags
type	string	Resource type
zones	array	The virtual machine zones.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	resourceGroupName, vmName, subscriptionId	$expand	Retrieves information about the model view or the instance view of a virtual machine.
list_by_location	select	location, subscriptionId		Gets all the virtual machines under the specified subscription for the specified location.
list	select	resourceGroupName, subscriptionId	$filter, $expand	Lists all of the virtual machines in the specified resource group. Use the nextLink property in the response to get the next page of virtual machines.
list_all	select	subscriptionId	statusOnly, $filter, $expand	Lists all of the virtual machines in the specified subscription. Use the nextLink property in the response to get the next page of virtual machines.
create_or_update	insert	resourceGroupName, vmName, subscriptionId	If-Match, If-None-Match	The operation to create or update a virtual machine. Please note some properties can be set only during virtual machine creation.
update	update	resourceGroupName, vmName, subscriptionId	If-Match, If-None-Match	The operation to update a virtual machine.
delete	delete	resourceGroupName, vmName, subscriptionId	forceDeletion	The operation to delete a virtual machine.
run_command	exec	resourceGroupName, vmName, subscriptionId, commandId		Run command on the VM.
capture	exec	resourceGroupName, vmName, subscriptionId, vhdPrefix, destinationContainerName, overwriteVhds		Captures the VM by copying virtual hard disks of the VM and outputs a template that can be used to create similar VMs.
instance_view	exec	resourceGroupName, vmName, subscriptionId		Retrieves information about the run-time state of a virtual machine.
convert_to_managed_disks	exec	resourceGroupName, vmName, subscriptionId		Converts virtual machine disks from blob-based to managed disks. Virtual machine must be stop-deallocated before invoking this operation.
deallocate	exec	resourceGroupName, vmName, subscriptionId	hibernate	Shuts down the virtual machine and releases the compute resources. You are not billed for the compute resources that this virtual machine uses.
generalize	exec	resourceGroupName, vmName, subscriptionId		Sets the OS state of the virtual machine to generalized. It is recommended to sysprep the virtual machine before performing this operation. For Windows, please refer to Create a managed image of a generalized VM in Azure. For Linux, please refer to How to create an image of a virtual machine or VHD.
power_off	exec	resourceGroupName, vmName, subscriptionId	skipShutdown	The operation to power off (stop) a virtual machine. The virtual machine can be restarted with the same provisioned resources. You are still charged for this virtual machine.
reapply	exec	resourceGroupName, vmName, subscriptionId		The operation to reapply a virtual machine's state.
restart	exec	resourceGroupName, vmName, subscriptionId		The operation to restart a virtual machine.
start	exec	resourceGroupName, vmName, subscriptionId		The operation to start a virtual machine.
redeploy	exec	resourceGroupName, vmName, subscriptionId		Shuts down the virtual machine, moves it to a new node, and powers it back on.
reimage	exec	resourceGroupName, vmName, subscriptionId		Reimages (upgrade the operating system) a virtual machine which don't have a ephemeral OS disk, for virtual machines who have a ephemeral OS disk the virtual machine is reset to initial state. NOTE: The retaining of old OS disk depends on the value of deleteOption of OS disk. If deleteOption is detach, the old OS disk will be preserved after reimage. If deleteOption is delete, the old OS disk will be deleted after reimage. The deleteOption of the OS disk should be updated accordingly before performing the reimage.
retrieve_boot_diagnostics_data	exec	resourceGroupName, vmName, subscriptionId	sasUriExpirationTimeInMinutes	The operation to retrieve SAS URIs for a virtual machine's boot diagnostic logs.
perform_maintenance	exec	resourceGroupName, vmName, subscriptionId		The operation to perform maintenance on a virtual machine.
simulate_eviction	exec	resourceGroupName, vmName, subscriptionId		The operation to simulate the eviction of spot virtual machine.
assess_patches	exec	resourceGroupName, vmName, subscriptionId		Assess patches on the VM.
install_patches	exec	resourceGroupName, vmName, subscriptionId, rebootSetting		Installs patches on the VM.
attach_detach_data_disks	exec	resourceGroupName, vmName, subscriptionId		Attach and detach data disks to/from the virtual machine.

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
location	string	The location for which virtual machines under the subscription are queried.
resourceGroupName	string	The name of the resource group.
subscriptionId	string	Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.
vmName	string	The name of the virtual machine.
$expand	string	The expand expression to apply on operation. 'instanceView' enables fetching run time status of all Virtual Machines, this can only be specified if a valid $filter option is specified
$filter	string	The system query option to filter VMs returned in the response. Allowed value is 'virtualMachineScaleSet/id' eq /subscriptions/{subId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmssName}'
If-Match	string	The ETag of the transformation. Omit this value to always overwrite the current resource. Specify the last-seen ETag value to prevent accidentally overwriting concurrent changes.
If-None-Match	string	Set to '*' to allow a new record set to be created, but to prevent updating an existing record set. Other values will result in error from server as they are not supported.
forceDeletion	boolean	Optional parameter to force delete virtual machines.
hibernate	boolean	Optional parameter to hibernate a virtual machine.
sasUriExpirationTimeInMinutes	integer (int32)	Expiration duration in minutes for the SAS URIs with a value between 1 to 1440 minutes. Note: If not specified, SAS URIs will be generated with a default expiration duration of 120 minutes.
skipShutdown	boolean	The parameter to request non-graceful VM shutdown. True value for this flag indicates non-graceful shutdown whereas false indicates otherwise. Default value for this flag is false if not specified
statusOnly	string	statusOnly=true enables fetching run time status of all Virtual Machines in the subscription.

SELECT examples

get

Retrieves information about the model view or the instance view of a virtual machine.

SELECT
id,
name,
etag,
extendedLocation,
identity,
location,
managedBy,
plan,
properties,
resources,
tags,
type,
zones
FROM azure.compute.virtual_machines
WHERE resourceGroupName = '{{ resourceGroupName }}' -- required
AND vmName = '{{ vmName }}' -- required
AND subscriptionId = '{{ subscriptionId }}' -- required
AND $expand = '{{ $expand }}'
;

list_by_location

Gets all the virtual machines under the specified subscription for the specified location.

SELECT
id,
name,
etag,
extendedLocation,
identity,
location,
managedBy,
plan,
properties,
resources,
tags,
type,
zones
FROM azure.compute.virtual_machines
WHERE location = '{{ location }}' -- required
AND subscriptionId = '{{ subscriptionId }}' -- required
;

list

Lists all of the virtual machines in the specified resource group. Use the nextLink property in the response to get the next page of virtual machines.

SELECT
id,
name,
etag,
extendedLocation,
identity,
location,
managedBy,
plan,
properties,
resources,
tags,
type,
zones
FROM azure.compute.virtual_machines
WHERE resourceGroupName = '{{ resourceGroupName }}' -- required
AND subscriptionId = '{{ subscriptionId }}' -- required
AND $filter = '{{ $filter }}'
AND $expand = '{{ $expand }}'
;

list_all

Lists all of the virtual machines in the specified subscription. Use the nextLink property in the response to get the next page of virtual machines.

SELECT
id,
name,
etag,
extendedLocation,
identity,
location,
managedBy,
plan,
properties,
resources,
tags,
type,
zones
FROM azure.compute.virtual_machines
WHERE subscriptionId = '{{ subscriptionId }}' -- required
AND statusOnly = '{{ statusOnly }}'
AND $filter = '{{ $filter }}'
AND $expand = '{{ $expand }}'
;

INSERT examples

create_or_update

The operation to create or update a virtual machine. Please note some properties can be set only during virtual machine creation.

INSERT INTO azure.compute.virtual_machines (
data__plan,
data__properties,
data__identity,
data__zones,
data__extendedLocation,
data__location,
data__tags,
resourceGroupName,
vmName,
subscriptionId,
If-Match,
If-None-Match
)
SELECT 
'{{ plan }}',
'{{ properties }}',
'{{ identity }}',
'{{ zones }}',
'{{ extendedLocation }}',
'{{ location }}',
'{{ tags }}',
'{{ resourceGroupName }}',
'{{ vmName }}',
'{{ subscriptionId }}',
'{{ If-Match }}',
'{{ If-None-Match }}'
RETURNING
id,
name,
etag,
extendedLocation,
identity,
location,
managedBy,
plan,
properties,
resources,
tags,
type,
zones
;

Manifest

# Description fields are for documentation purposes
- name: virtual_machines
  props:
    - name: resourceGroupName
      value: string
      description: Required parameter for the virtual_machines resource.
    - name: vmName
      value: string
      description: Required parameter for the virtual_machines resource.
    - name: subscriptionId
      value: string
      description: Required parameter for the virtual_machines resource.
    - name: plan
      value: object
      description: |
        Specifies information about the marketplace image used to create the virtual machine. This element is only used for marketplace images. Before you can use a marketplace image from an API, you must enable the image for programmatic use.  In the Azure portal, find the marketplace image that you want to use and then click **Want to deploy programmatically, Get Started ->**. Enter any required information and then click **Save**.
    - name: properties
      value: object
      description: |
        Describes the properties of a Virtual Machine.
    - name: identity
      value: object
      description: |
        The identity of the virtual machine, if configured.
    - name: zones
      value: array
      description: |
        The virtual machine zones.
    - name: extendedLocation
      value: object
      description: |
        The extended location of the Virtual Machine.
    - name: location
      value: string
      description: |
        Resource location
    - name: tags
      value: object
      description: |
        Resource tags
    - name: If-Match
      value: string
      description: The ETag of the transformation. Omit this value to always overwrite the current resource. Specify the last-seen ETag value to prevent accidentally overwriting concurrent changes.
    - name: If-None-Match
      value: string
      description: Set to '*' to allow a new record set to be created, but to prevent updating an existing record set. Other values will result in error from server as they are not supported.

UPDATE examples

update

The operation to update a virtual machine.

UPDATE azure.compute.virtual_machines
SET 
data__plan = '{{ plan }}',
data__properties = '{{ properties }}',
data__identity = '{{ identity }}',
data__zones = '{{ zones }}',
data__tags = '{{ tags }}'
WHERE 
resourceGroupName = '{{ resourceGroupName }}' --required
AND vmName = '{{ vmName }}' --required
AND subscriptionId = '{{ subscriptionId }}' --required
AND If-Match = '{{ If-Match}}'
AND If-None-Match = '{{ If-None-Match}}'
RETURNING
id,
name,
etag,
extendedLocation,
identity,
location,
managedBy,
plan,
properties,
resources,
tags,
type,
zones;

DELETE examples

delete

The operation to delete a virtual machine.

DELETE FROM azure.compute.virtual_machines
WHERE resourceGroupName = '{{ resourceGroupName }}' --required
AND vmName = '{{ vmName }}' --required
AND subscriptionId = '{{ subscriptionId }}' --required
AND forceDeletion = '{{ forceDeletion }}'
;

Lifecycle Methods

run_command

Run command on the VM.

EXEC azure.compute.virtual_machines.run_command 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required 
@@json=
'{
"commandId": "{{ commandId }}", 
"script": "{{ script }}", 
"parameters": "{{ parameters }}"
}'
;

capture

Captures the VM by copying virtual hard disks of the VM and outputs a template that can be used to create similar VMs.

EXEC azure.compute.virtual_machines.capture 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required 
@@json=
'{
"vhdPrefix": "{{ vhdPrefix }}", 
"destinationContainerName": "{{ destinationContainerName }}", 
"overwriteVhds": {{ overwriteVhds }}
}'
;

instance_view

Retrieves information about the run-time state of a virtual machine.

EXEC azure.compute.virtual_machines.instance_view 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

convert_to_managed_disks

Converts virtual machine disks from blob-based to managed disks. Virtual machine must be stop-deallocated before invoking this operation.

EXEC azure.compute.virtual_machines.convert_to_managed_disks 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

deallocate

Shuts down the virtual machine and releases the compute resources. You are not billed for the compute resources that this virtual machine uses.

EXEC azure.compute.virtual_machines.deallocate 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required, 
@hibernate={{ hibernate }}
;

generalize

Sets the OS state of the virtual machine to generalized. It is recommended to sysprep the virtual machine before performing this operation. For Windows, please refer to Create a managed image of a generalized VM in Azure. For Linux, please refer to How to create an image of a virtual machine or VHD.

EXEC azure.compute.virtual_machines.generalize 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

power_off

The operation to power off (stop) a virtual machine. The virtual machine can be restarted with the same provisioned resources. You are still charged for this virtual machine.

EXEC azure.compute.virtual_machines.power_off 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required, 
@skipShutdown={{ skipShutdown }}
;

reapply

The operation to reapply a virtual machine's state.

EXEC azure.compute.virtual_machines.reapply 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

restart

The operation to restart a virtual machine.

EXEC azure.compute.virtual_machines.restart 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

start

The operation to start a virtual machine.

EXEC azure.compute.virtual_machines.start 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

redeploy

Shuts down the virtual machine, moves it to a new node, and powers it back on.

EXEC azure.compute.virtual_machines.redeploy 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

reimage

Reimages (upgrade the operating system) a virtual machine which don't have a ephemeral OS disk, for virtual machines who have a ephemeral OS disk the virtual machine is reset to initial state. NOTE: The retaining of old OS disk depends on the value of deleteOption of OS disk. If deleteOption is detach, the old OS disk will be preserved after reimage. If deleteOption is delete, the old OS disk will be deleted after reimage. The deleteOption of the OS disk should be updated accordingly before performing the reimage.

EXEC azure.compute.virtual_machines.reimage 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required 
@@json=
'{
"tempDisk": {{ tempDisk }}, 
"exactVersion": "{{ exactVersion }}", 
"osProfile": "{{ osProfile }}"
}'
;

retrieve_boot_diagnostics_data

The operation to retrieve SAS URIs for a virtual machine's boot diagnostic logs.

EXEC azure.compute.virtual_machines.retrieve_boot_diagnostics_data 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required, 
@sasUriExpirationTimeInMinutes='{{ sasUriExpirationTimeInMinutes }}'
;

perform_maintenance

The operation to perform maintenance on a virtual machine.

EXEC azure.compute.virtual_machines.perform_maintenance 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

simulate_eviction

The operation to simulate the eviction of spot virtual machine.

EXEC azure.compute.virtual_machines.simulate_eviction 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

assess_patches

Assess patches on the VM.

EXEC azure.compute.virtual_machines.assess_patches 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required
;

install_patches

Installs patches on the VM.

EXEC azure.compute.virtual_machines.install_patches 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required 
@@json=
'{
"maximumDuration": "{{ maximumDuration }}", 
"rebootSetting": "{{ rebootSetting }}", 
"windowsParameters": "{{ windowsParameters }}", 
"linuxParameters": "{{ linuxParameters }}"
}'
;

attach_detach_data_disks

Attach and detach data disks to/from the virtual machine.

EXEC azure.compute.virtual_machines.attach_detach_data_disks 
@resourceGroupName='{{ resourceGroupName }}' --required, 
@vmName='{{ vmName }}' --required, 
@subscriptionId='{{ subscriptionId }}' --required 
@@json=
'{
"dataDisksToAttach": "{{ dataDisksToAttach }}", 
"dataDisksToDetach": "{{ dataDisksToDetach }}"
}'
;