exec.azurerm.compute.virtual_machine¶

Azure Resource Manager (ARM) Compute Virtual Machine Execution Module

New in version 1.0.0.

Changed in version 2.0.0,: 4.0.0

maintainer:

configuration:

This module requires Azure Resource Manager credentials to be passed as keyword arguments to every function or via acct in order to work properly.

Required provider parameters:

if using username and password:

subscription_id
username
password

if using a service principal:

subscription_id
tenant
client_id
secret

Optional provider parameters:

cloud_environment: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. Possible values:

AZURE_PUBLIC_CLOUD (default)

AZURE_CHINA_CLOUD

AZURE_US_GOV_CLOUD

AZURE_GERMAN_CLOUD

idem_azurerm.exec.azurerm.compute.virtual_machine.assess_patches(hub, ctx, name, resource_group, **kwargs)¶

New in version 4.0.0.

Assess patches on the VM.

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.assess_patches testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.capture(hub, ctx, name, destination_name, resource_group, prefix='capture-', overwrite=False, **kwargs)¶

New in version 1.0.0.

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

Parameters:	name – The name of the virtual machine. destination_name – The destination container name. resource_group – The resource group name assigned to the virtual machine. prefix – (Default: ‘capture-’) The captured virtual hard disk’s name prefix. overwrite – (Default: False) Overwrite the destination disk in case of conflict.

CLI Example:

azurerm.compute.virtual_machine.capture testvm testcontainer testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.convert_to_managed_disks(hub, ctx, name, resource_group, **kwargs)¶

New in version 1.0.0.

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

Parameters:	name – The name of the virtual machine to convert. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.convert_to_managed_disks testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.create_or_update(hub, ctx, name, resource_group, vm_size, admin_username='idem', os_disk_create_option='FromImage', os_disk_size_gb=30, ssh_public_keys=None, disable_password_auth=None, custom_data=None, allow_extensions=None, enable_automatic_updates=None, time_zone=None, allocate_public_ip=False, create_interfaces=True, network_resource_group=None, virtual_network=None, subnet=None, network_interfaces=None, os_managed_disk=None, os_disk_vhd_uri=None, os_disk_image_uri=None, os_type=None, os_disk_name=None, os_disk_simplename=None, data_disk_simplenames=None, os_disk_caching=None, os_write_accel=None, os_ephemeral_disk=None, ultra_ssd_enabled=None, image=None, boot_diags_enabled=None, diag_storage_uri=None, admin_password=None, max_price=None, provision_vm_agent=True, userdata_file=None, userdata=None, enable_disk_enc=False, disk_enc_keyvault=None, disk_enc_volume_type=None, disk_enc_kek_url=None, data_disks=None, availability_set=None, virtual_machine_scale_set=None, proximity_placement_group=None, host=None, host_group=None, extensions_time_budget=None, **kwargs)¶

New in version 1.0.0.

Changed in version 2.0.0,: 4.0.0

Create or update a virtual machine.

Parameters:

name – The virtual machine to create.
resource_group – The resource group name assigned to the virtual machine.
vm_size – The size of the virtual machine.
admin_username – Specifies the name of the administrator account.
os_disk_create_option – (attach, from_image, or empty) Specifies how the virtual machine should be created. The “attach” value is used when you are using a specialized disk to create the virtual machine. The “from_image” value is used when you are using an image to create the virtual machine. If you are using a platform image, you also use the image_reference element. If you are using a marketplace image, you also use the plan element.
os_disk_size_gb – Specifies the size of an empty OS disk in gigabytes. This element can be used to overwrite the size of the disk in a virtual machine image.
ssh_public_keys – The list of SSH public keys used to authenticate with Linux based VMs.
disable_password_auth – (only on Linux) Specifies whether password authentication should be disabled when SSH public keys are provided.
custom_data – (only on Linux) Specifies a base-64 encoded string of custom data for cloud-init (not user-data scripts). The base-64 encoded string is decoded to a binary array that is saved as a file on the Virtual Machine. The maximum length of the binary array is 65535 bytes. For using cloud-init for your VM, see Using cloud-init to customize a Linux VM during creation
allow_extensions – Specifies whether extension operations should be allowed on the virtual machine. This may only be set to False when no extensions are present on the virtual machine.
enable_automatic_updates – (only on Windows) Indicates whether Automatic Updates is enabled for the Windows virtual machine. Default value is true. For virtual machine scale sets, this property can be updated and updates will take effect on OS reprovisioning.
time_zone – (only on Windows) Specifies the time zone of the virtual machine. e.g. “Pacific Standard Time”
allocate_public_ip – Create and attach a public IP object to the VM.
create_interfaces – Create network interfaces to attach to the VM if none are provided.
network_resource_group – Specify the resource group of the network components referenced in this module.
virtual_network – Virtual network for the subnet which will contain the network interfaces.
subnet – Subnet to which the network interfaces will be attached.
network_interfaces – A list of network interface references ({“id”: “/full/path/to/object”}) to attach.
os_managed_disk – A managed disk resource ID or dictionary containing the managed disk parameters. If a dictionary is provided, “storage_account_type” can be passed in additional to the “id”. Storage account type for the managed disk can include: ‘Standard_LRS’, ‘Premium_LRS’, ‘StandardSSD_LRS’, ‘UltraSSD_LRS’. NOTE: UltraSSD_LRS can only be used with data disks.
os_disk_vhd_uri – The virtual hard disk for the OS ({“uri”: “/full/path/to/object”}).
os_disk_image_uri – The source user image virtual hard disk ({“uri”: “/full/path/to/object”}). The virtual hard disk will be copied before being attached to the virtual machine. If SourceImage is provided, the destination virtual hard drive must not exist.
os_type – (linux or windows) This property allows you to specify the type of the OS that is included in the disk if creating a VM from user-image or a specialized VHD.
os_disk_name – The OS disk name. Note that setting this may cause conflicts upon re-deployment of a virtual machine if the old OS disk isn’t cleaned up. Use os_disk_create_option=”attach” to attach a named disk.
os_disk_simplename – If set to True, a “simple” name is used for the OS disk name instead of the randomized name used by default in Azure. Note that setting this may cause conflicts upon re-deployment of a virtual machine if the old OS disk isn’t cleaned up. Use os_disk_create_option=”attach” to attach a named disk.
data_disk_simplenames – If set to True, a “simple” name is used for data disk names instead of the randomized names used by default in Azure. Note that setting this may cause conflicts upon re-deployment of a virtual machine if the old disk isn’t cleaned up. Use create_option=”attach” to attach a named disk.
os_disk_caching – (read_only, read_write, or none) Specifies the caching requirements. Defaults to “None” for Standard storage and “ReadOnly” for Premium storage.
os_write_accel – Boolean value specifies whether write accelerator should be enabled or disabled on the disk.
os_ephemeral_disk – Boolean value to enable ephemeral “diff” OS disk. Ephemeral OS disks are created on the local virtual machine (VM) storage and not saved to the remote Azure Storage.
ultra_ssd_enabled – The flag that enables or disables a capability to have one or more managed data disks with UltraSSD_LRS storage account type on the VM or VMSS. Managed disks with storage account type UltraSSD_LRS can be added to a virtual machine or virtual machine scale set only if this property is enabled.
image – A pipe-delimited representation of an image to use, in the format of “publisher|offer|sku|version”. Examples - “OpenLogic|CentOS|7.7|latest” or “Canonical|UbuntuServer|18.04-LTS|latest”
boot_diags_enabled – Enables boots diagnostics on the Virtual Machine. Required for use of the diag_storage_uri parameter.
diag_storage_uri – Enables boots diagnostics on the Virtual Machine by passing the URI of the storage account to use for placing the console output and screenshot.
admin_password – Specifies the password of the administrator account. Note that there are minimum length, maximum length, and complexity requirements imposed on this password. See the Azure documentation for details.
provision_vm_agent – Indicates whether virtual machine agent should be provisioned on the virtual machine. When this property is not specified in the request body, default behavior is to set it to true. This will ensure that VM Agent is installed on the VM so that extensions can be added to the VM later. If attempting to set this value, os_type should also be set in order to ensure the proper OS configuration is used.
userdata_file – This parameter can contain a local or web path for a userdata script. If a local file is used, then the contents of that file will override the contents of the userdata parameter. If a web source is used, then the userdata parameter should contain the command to execute the script file. For instance, if a file location of https://raw.githubusercontent.com/saltstack/salt-bootstrap/stable/bootstrap-salt.sh is used then the userdata parameter would contain “./bootstrap-salt.sh” along with any desired arguments. Note that PowerShell execution policy may cause issues here. For PowerShell files, considered signed scripts or the more insecure “powershell -ExecutionPolicy Unrestricted -File ./bootstrap-salt.ps1” addition to the command.
userdata – This parameter is used to pass text to be executed on a system. The native shell will be used on a given host operating system.
max_price – Specifies the maximum price you are willing to pay for a Azure Spot VM/VMSS. This price is in US Dollars. This price will be compared with the current Azure Spot price for the VM size. Also, the prices are compared at the time of create/update of Azure Spot VM/VMSS and the operation will only succeed if max_price is greater than the current Azure Spot price. The max_price will also be used for evicting a Azure Spot VM/VMSS if the current Azure Spot price goes beyond the maxPrice after creation of VM/VMSS. Possible values are any decimal value greater than zero (example: 0.01538) or -1 indicates default price to be up-to on-demand. You can set the max_price to -1 to indicate that the Azure Spot VM/VMSS should not be evicted for price reasons. Also, the default max price is -1 if it is not provided by you.
priority – (low or regular) Specifies the priority for the virtual machine.
eviction_policy – (deallocate or delete) Specifies the eviction policy for the Azure Spot virtual machine.
license_type – (Windows_Client or Windows_Server) Specifies that the image or disk that is being used was licensed on-premises. This element is only used for images that contain the Windows Server operating system.
zones – A list of the virtual machine zones.
availability_set – The resource ID of the availability set that the virtual machine should be assigned to. Virtual machines specified in the same availability set are allocated to different nodes to maximize availability. For more information about availability sets, see Manage the availability of virtual machines. Currently, a VM can only be added to availability set at creation time. An existing VM cannot be added to an availability set. This parameter cannot be specified if the virtual_machine_scale_set parameter is also specified.
virtual_machine_scale_set – The resource ID of the virtual machine scale set that the virtual machine should be assigned to. Virtual machines specified in the same virtual machine scale set are allocated to different nodes to maximize availability. Currently, a VM can only be added to virtual machine scale set at creation time. An existing VM cannot be added to a virtual machine scale set. This parameter cannot be specified if the availability_set parameter is also specified.
proximity_placement_group – The resource ID of the proximity placement group that the virtual machine should be assigned to.
host – The resource ID of the dedicated host that the virtual machine resides in. This parameter cannot be specified if the host_group parameter is also specified.
host_group – The resource ID of the dedicated host group that the virtual machine resides in. This parameter cannot be specified if the host parameter is also specified.
extensions_time_budget – Specifies the time alloted for all extensions to start. The time duration should be between 15 minutes and 120 minutes (inclusive) and should be specified in ISO 8601 format. The default value is 90 minutes (PT1H30M).

Virtual Machine Disk Encryption:

If you would like to enable disk encryption within the virtual machine you must set the enable_disk_enc parameter to True. Disk encryption utilizes a VM published by Microsoft.Azure.Security of extension type AzureDiskEncryptionForLinux or AzureDiskEncryption, depending on your virtual machine OS. More information about Disk Encryption and its requirements can be found in the links below.

Disk Encryption for Windows Virtual Machines: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/disk-encryption-overview

Disk Encryption for Linux Virtual Machines: https://docs.microsoft.com/en-us/azure/virtual-machines/linux/disk-encryption-overview

The following parameters may be used to implement virtual machine disk encryption:

param enable_disk_enc: This boolean flag will represent whether disk encryption has been enabled for the virtual machine. This is a required parameter.
disk_enc_keyvault: The resource ID of the key vault containing the disk encryption key, which is a Key Vault Secret. This is a required parameter.
disk_enc_volume_type: The volume type(s) that will be encrypted. Possible values include: ‘OS’, ‘Data’, and ‘All’. This is a required parameter.
disk_enc_kek_url: The Key Identifier URL for a Key Encryption Key (KEK). The KEK is used as an additional layer of security for encryption keys. Azure Disk Encryption will use the KEK to wrap the encryption secrets before writing to the Key Vault. The KEK must be in the same vault as the encryption secrets. This is an optional parameter.

Attaching Data Disks:

Data disks can be attached by passing a list of dictionaries in the data_disks parameter. The dictionaries in the list can have the following parameters:

lun: (optional int) Specifies the logical unit number of the data disk. This value is used to identify data disks within the VM and therefore must be unique for each data disk attached to a VM. If not provided, we increment the lun designator based upon the index within the provided list of disks.
name: (optional str) The disk name. Defaults to “{vm_name}-datadisk{lun}”
vhd: (optional str or dict) Virtual hard disk to use. If a URI string is provided, it will be nested under a “uri” key in a dictionary as expected by the SDK.
image: (optional str or dict) The source user image virtual hard disk. The virtual hard disk will be copied before being attached to the virtual machine. If image is provided, the destination virtual hard drive must not exist. If a URI string is provided, it will be nested under a “uri” key in a dictionary as expected by the SDK.
caching: (optional str - read_only, read_write, or none) Specifies the caching requirements. Defaults to “None” for Standard storage and “ReadOnly” for Premium storage.
write_accelerator_enabled: (optional bool - True or False) Specifies whether write accelerator should be enabled or disabled on the disk.
create_option: (optional str - attach, from_image, or empty) Specifies how the virtual machine should be created. The “attach” value is used when you are using a specialized disk to create the virtual machine. The “from_image” value is used when you are using an image to create the virtual machine. If you are using a platform image, you also use the image_reference element. If you are using a marketplace image, you also use the plan element.
disk_size_gb: (optional int) Specifies the size of an empty data disk in gigabytes. This element can be used to overwrite the size of the disk in a virtual machine image.
managed_disk: (optional str or dict) The managed disk parameters. If an ID string is provided, it will be nested under an “id” key in a dictionary as expected by the SDK. If a dictionary is provided, the “storage_account_type” parameter can be passed (accepts (Standard|Premium)_LRS or (Standard|Ultra)SSD_LRS).

CLI Example:

azurerm.compute.virtual_machine.create_or_update test_vm test_group

idem_azurerm.exec.azurerm.compute.virtual_machine.deallocate(hub, ctx, name, resource_group, **kwargs)¶

New in version 1.0.0.

Power off a virtual machine and deallocate compute resources.

Parameters:	name – The name of the virtual machine to deallocate. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.deallocate testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.delete(hub, ctx, name, resource_group, cleanup_disks=False, cleanup_data_disks=False, cleanup_interfaces=False, **kwargs)¶

New in version 1.0.0.

Delete a virtual machine.

Parameters:	name – The virtual machine to delete. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.delete testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.generalize(hub, ctx, name, resource_group, **kwargs)¶

New in version 1.0.0.

Set the state of a virtual machine to ‘generalized’.

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.generalize testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.get(hub, ctx, name, resource_group, **kwargs)¶

New in version 1.0.0.

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

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.get testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.instance_view(hub, ctx, name, resource_group, **kwargs)¶

New in version 4.0.0.

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

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.instance_view testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.list_(hub, ctx, resource_group=None, **kwargs)¶

New in version 1.0.0.

Changed in version 4.0.0.

List all virtual machines within a subscription.

Parameters:	resource_group – The name of the resource group to limit the results.

CLI Example:

azurerm.compute.virtual_machine.list

idem_azurerm.exec.azurerm.compute.virtual_machine.list_available_sizes(hub, ctx, name, resource_group, **kwargs)¶

New in version 1.0.0.

Lists all available virtual machine sizes to which the specified virtual machine can be resized.

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.list_available_sizes testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.list_by_location(hub, ctx, location, **kwargs)¶

New in version 4.0.0.

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

Parameters:	location – The location for which virtual machines under the subscription are queried.

CLI Example:

azurerm.compute.virtual_machine.list "eastus"

idem_azurerm.exec.azurerm.compute.virtual_machine.perform_maintenance(hub, ctx, name, resource_group, **kwargs)¶

New in version 4.0.0.

The operation to perform maintenance on a virtual machine.

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.perform_maintenance testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.power_off(hub, ctx, name, resource_group, skip_shutdown=False, **kwargs)¶

New in version 1.0.0.

Changed in version 4.0.0.

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.

Parameters:	name – The name of the virtual machine to stop. resource_group – The resource group name assigned to the virtual machine. skip_shutdown – A boolean value representing wheter to request non-graceful VM shutdown. True value for this flag indicates non-graceful shutdown whereas False indicates otherwise. Defaults to False.

CLI Example:

azurerm.compute.virtual_machine.power_off testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.reapply(hub, ctx, name, resource_group, **kwargs)¶

New in version 4.0.0.

The operation to reapply a virtual machine’s state.

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.reapply testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.redeploy(hub, ctx, name, resource_group, **kwargs)¶

New in version 1.0.0.

Redeploy a virtual machine.

Parameters:	name – The name of the virtual machine to redeploy. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.redeploy testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.reimage(hub, ctx, name, resource_group, temp_disk=False, **kwargs)¶

New in version 4.0.0.

Reimages the virtual machine which has an ephemeral OS disk back to its initial state.

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine. temp_disk – A boolean value specifying whether to reimage temp disk. This parameter is only supported for VM/VMSS with Ephemral OS disk. Defaults to False.

CLI Example:

azurerm.compute.virtual_machine.reimage testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.restart(hub, ctx, name, resource_group, **kwargs)¶

New in version 1.0.0.

Restart a virtual machine.

Parameters:	name – The name of the virtual machine to restart. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.restart testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.retrieve_boot_diagnostics_data(hub, ctx, name, resource_group, sas_uri_expiration_time=None, **kwargs)¶

New in version 4.0.0.

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

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine. sas_uri_expiration_time – 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.

CLI Example:

azurerm.compute.virtual_machine.retrieve_boot_diagnostics_data testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.simulate_eviction(hub, ctx, name, resource_group, **kwargs)¶

New in version 4.0.0.

The operation to simulate the eviction of spot virtual machine. The eviction will occur within 30 minutes of calling the API.

Parameters:	name – The name of the virtual machine. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.simulate_eviction testvm testgroup

idem_azurerm.exec.azurerm.compute.virtual_machine.start(hub, ctx, name, resource_group, **kwargs)¶

New in version 1.0.0.

Power on (start) a virtual machine.

Parameters:	name – The name of the virtual machine to start. resource_group – The resource group name assigned to the virtual machine.

CLI Example:

azurerm.compute.virtual_machine.start testvm testgroup

exec.azurerm.compute.virtual_machine¶

idem-azurerm

Navigation

Related Topics