azurermVirtualMachine

Manages a Virtual Machine.

Disclaimers

-> Note: The azurermVirtualMachine resource has been superseded by the azurermLinuxVirtualMachine and azurermWindowsVirtualMachine resources. The existing azurermVirtualMachine resource will continue to be available throughout the 3.x releases however is in a feature-frozen state to maintain compatibility - new functionality will instead be added to the azurermLinuxVirtualMachine and azurermWindowsVirtualMachine resources.

\~> Note: Data Disks can be attached either directly on the azurermVirtualMachine resource, or using the azurermVirtualMachineDataDiskAttachment resource - but the two cannot be used together. If both are used against the same Virtual Machine, spurious changes will occur.

Example Usage (from an Azure Platform Image)

This example provisions a Virtual Machine with Managed Disks. Other examples of the azurermVirtualMachine resource can be found in the /examples/virtualMachines directory within the GitHub Repository

import * as cdktf from "cdktf";
/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as azurerm from "./.gen/providers/azurerm";
/*The following providers are missing schema information and might need manual adjustments to synthesize correctly: azurerm.
For a more precise conversion please use the --provider flag in convert.*/
/*Terraform Variables are not always the best fit for getting inputs in the context of Terraform CDK.
You can read more about this at https://cdk.tf/variables*/
const prefix = new cdktf.TerraformVariable(this, "prefix", {
  default: "tfvmex",
});
const azurermResourceGroupExample = new azurerm.resourceGroup.ResourceGroup(
  this,
  "example",
  {
    location: "West Europe",
    name: `\${${prefix.value}}-resources`,
  }
);
const azurermVirtualNetworkMain = new azurerm.virtualNetwork.VirtualNetwork(
  this,
  "main",
  {
    address_space: ["10.0.0.0/16"],
    location: azurermResourceGroupExample.location,
    name: `\${${prefix.value}}-network`,
    resource_group_name: azurermResourceGroupExample.name,
  }
);
const azurermSubnetInternal = new azurerm.subnet.Subnet(this, "internal", {
  address_prefixes: ["10.0.2.0/24"],
  name: "internal",
  resource_group_name: azurermResourceGroupExample.name,
  virtual_network_name: azurermVirtualNetworkMain.name,
});
const azurermNetworkInterfaceMain =
  new azurerm.networkInterface.NetworkInterface(this, "main_4", {
    ip_configuration: [
      {
        name: "testconfiguration1",
        private_ip_address_allocation: "Dynamic",
        subnet_id: azurermSubnetInternal.id,
      },
    ],
    location: azurermResourceGroupExample.location,
    name: `\${${prefix.value}}-nic`,
    resource_group_name: azurermResourceGroupExample.name,
  });
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermNetworkInterfaceMain.overrideLogicalId("main");
const azurermVirtualMachineMain = new azurerm.virtualMachine.VirtualMachine(
  this,
  "main_5",
  {
    location: azurermResourceGroupExample.location,
    name: `\${${prefix.value}}-vm`,
    network_interface_ids: [azurermNetworkInterfaceMain.id],
    os_profile: [
      {
        admin_password: "Password1234!",
        admin_username: "testadmin",
        computer_name: "hostname",
      },
    ],
    os_profile_linux_config: [
      {
        disable_password_authentication: false,
      },
    ],
    resource_group_name: azurermResourceGroupExample.name,
    storage_image_reference: [
      {
        offer: "UbuntuServer",
        publisher: "Canonical",
        sku: "16.04-LTS",
        version: "latest",
      },
    ],
    storage_os_disk: [
      {
        caching: "ReadWrite",
        create_option: "FromImage",
        managed_disk_type: "Standard_LRS",
        name: "myosdisk1",
      },
    ],
    tags: {
      environment: "staging",
    },
    vm_size: "Standard_DS1_v2",
  }
);
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermVirtualMachineMain.overrideLogicalId("main");

Argument Reference

The following arguments are supported:

name - (Required) Specifies the name of the Virtual Machine. Changing this forces a new resource to be created.
resourceGroupName - (Required) Specifies the name of the Resource Group in which the Virtual Machine should exist. Changing this forces a new resource to be created.
location - (Required) Specifies the Azure Region where the Virtual Machine exists. Changing this forces a new resource to be created.
networkInterfaceIds - (Required) A list of Network Interface IDs which should be associated with the Virtual Machine.
osProfileLinuxConfig - (Optional) (Required, when a Linux machine) An osProfileLinuxConfig block as defined below.
osProfileWindowsConfig - (Optional) (Required, when a Windows machine) An osProfileWindowsConfig block as defined below.
vmSize - (Required) Specifies the size of the Virtual Machine. See also Azure VM Naming Conventions.

availabilitySetId - (Optional) The ID of the Availability Set in which the Virtual Machine should exist. Changing this forces a new resource to be created.
bootDiagnostics - (Optional) A bootDiagnostics block as defined below.
additionalCapabilities - (Optional) An additionalCapabilities block as defined below.
deleteOsDiskOnTermination - (Optional) Should the OS Disk (either the Managed Disk / VHD Blob) be deleted when the Virtual Machine is destroyed? Defaults to false.

\~> Note: This setting works when instance is deleted via Terraform only and don't forget to delete disks manually if you deleted VM manually. It can increase spending.

deleteDataDisksOnTermination - (Optional) Should the Data Disks (either the Managed Disks / VHD Blobs) be deleted when the Virtual Machine is destroyed? Defaults to false.

-> Note: This setting works when instance is deleted via Terraform only and don't forget to delete disks manually if you deleted VM manually. It can increase spending.

identity - (Optional) An identity block as defined below.
licenseType - (Optional) Specifies the BYOL Type for this Virtual Machine. This is only applicable to Windows Virtual Machines. Possible values are windowsClient and windowsServer.
osProfile - (Optional) An osProfile block as defined below. Required when createOption in the storageOsDisk block is set to fromImage.
osProfileSecrets - (Optional) One or more osProfileSecrets blocks as defined below.
plan - (Optional) A plan block as defined below.
primaryNetworkInterfaceId - (Optional) The ID of the Network Interface (which must be attached to the Virtual Machine) which should be the Primary Network Interface for this Virtual Machine.
proximityPlacementGroupId - (Optional) The ID of the Proximity Placement Group to which this Virtual Machine should be assigned. Changing this forces a new resource to be created
storageDataDisk - (Optional) One or more storageDataDisk blocks as defined below.

\~> Please Note: Data Disks can also be attached either using this block or the azurermVirtualMachineDataDiskAttachment resource - but not both.

storageImageReference - (Optional) A storageImageReference block as defined below. Changing this forces a new resource to be created.
storageOsDisk - (Required) A storageOsDisk block as defined below.
tags - (Optional) A mapping of tags to assign to the Virtual Machine.
zones - (Optional) A list of a single item of the Availability Zone which the Virtual Machine should be allocated in. Changing this forces a new resource to be created.

-> Please Note: Availability Zones are only supported in several regions at this time.

For more information on the different example configurations, please check out the Azure documentation

An additionalUnattendConfig block supports the following:

pass - (Required) Specifies the name of the pass that the content applies to. The only allowable value is oobeSystem.
component - (Required) Specifies the name of the component to configure with the added content. The only allowable value is microsoftWindowsShellSetup.
settingName - (Required) Specifies the name of the setting to which the content applies. Possible values are: firstLogonCommands and autoLogon.
content - (Required) Specifies the base-64 encoded XML formatted content that is added to the unattend.xml file for the specified path and component.

A bootDiagnostics block supports the following:

enabled - (Required) Should Boot Diagnostics be enabled for this Virtual Machine?
storageUri - (Required) The Storage Account's Blob Endpoint which should hold the virtual machine's diagnostic files.

\~> NOTE: This needs to be the root of a Storage Account and not a Storage Container.

A additionalCapabilities block supports the following:

ultraSsdEnabled - (Required) Should Ultra SSD disk be enabled for this Virtual Machine? Changing this forces a new resource to be created.

-> Note: Azure Ultra Disk Storage is only available in a region that support availability zones and can only enabled on the following VM series: eSv3, dSv3, fSv3, lSv2, m and mv2. For more information see the azureUltraDiskStorage product documentation.

A identity block supports the following:

type - (Required) Specifies the type of Managed Service Identity that should be configured on this Virtual Machine. Possible values are systemAssigned, userAssigned, systemAssigned,UserAssigned (to enable both).

-> NOTE: Managed Service Identity previously required the installation of a VM Extension, but this information is now available via the Azure Instance Metadata Service.

\~> NOTE: When type is set to systemAssigned, identity the Principal ID can be retrieved after the virtual machine has been created. More details are available below. See documentation for additional information.

identityIds - (Optional) Specifies a list of User Assigned Managed Identity IDs to be assigned to this Virtual Machine.

\~> NOTE: This is required when type is set to userAssigned or systemAssigned,UserAssigned.

A osProfile block supports the following:

computerName - (Required) Specifies the name of the Virtual Machine. Changing this forces a new resource to be created.
adminUsername - (Required) Specifies the name of the local administrator account.
adminPassword - (Optional) (Optional for Windows, Optional for Linux) The password associated with the local administrator account.

-> NOTE: If using Linux, it may be preferable to use SSH Key authentication (available in the osProfileLinuxConfig block) instead of password authentication.

\~> NOTE: adminPassword must be between 6-72 characters long and must satisfy at least 3 of password complexity requirements from the following:

Contains an uppercase character
Contains a lowercase character
Contains a numeric digit
Contains a special character
customData - (Optional) Specifies custom data to supply to the machine. On Linux-based systems, this can be used as a cloud-init script. On other systems, this will be copied as a file on disk. Internally, Terraform will base64 encode this value before sending it to the API. The maximum length of the binary array is 65535 bytes. Changing this forces a new resource to be created.

A osProfileLinuxConfig block supports the following:

disablePasswordAuthentication - (Required) Specifies whether password authentication should be disabled. If set to false, an adminPassword must be specified.
sshKeys - (Optional) One or more sshKeys blocks as defined below. This field is required if disablePasswordAuthentication is set to true.

A osProfileSecrets block supports the following:

sourceVaultId - (Required) Specifies the ID of the Key Vault to use.
vaultCertificates - (Optional) One or more vaultCertificates blocks as defined below.

A osProfileWindowsConfig block supports the following:

provisionVmAgent - (Optional) Should the Azure Virtual Machine Guest Agent be installed on this Virtual Machine? Defaults to false.

-> NOTE: This is different from the Default value used for this field within Azure.

enableAutomaticUpgrades - (Optional) Are automatic updates enabled on this Virtual Machine? Defaults to false
timezone - (Optional) Specifies the time zone of the virtual machine, the possible values are defined here. Changing this forces a new resource to be created.
winrm - (Optional) One or more winrm blocks as defined below.
additionalUnattendConfig - (Optional) An additionalUnattendConfig block as defined below.

A plan block supports the following:

name - (Required) Specifies the name of the image from the marketplace.
publisher - (Required) Specifies the publisher of the image.
product - (Required) Specifies the product of the image from the marketplace.

A sshKeys block supports the following:

keyData - (Required) The Public SSH Key which should be written to the path defined above.

\~> Note: Azure only supports RSA SSH2 key signatures of at least 2048 bits in length

-> NOTE: Rather than defining this in-line you can source this from a local file using the file function - for example keyData =File("~/Ssh/idRsaPub").

path - (Required) The path of the destination file on the virtual machine

-> NOTE: Due to a limitation in the Azure VM Agent the only allowed path is /home/{username}/Ssh/authorizedKeys.

A storageImageReference block supports the following:

This block provisions the Virtual Machine from one of two sources: an Azure Platform Image (e.g. Ubuntu/Windows Server) or a Custom Image.

To provision from an Azure Platform Image, the following fields are applicable:

publisher - (Optional) Specifies the publisher of the image used to create the virtual machine. Changing this forces a new resource to be created.
offer - (Optional) Specifies the offer of the image used to create the virtual machine. Changing this forces a new resource to be created.
sku - (Optional) Specifies the SKU of the image used to create the virtual machine. Changing this forces a new resource to be created.
version - (Optional) Specifies the version of the image used to create the virtual machine. Changing this forces a new resource to be created.

To provision a Custom Image, the following fields are applicable:

id - (Optional) Specifies the ID of the Custom Image which the Virtual Machine should be created from. Changing this forces a new resource to be created.

-> NOTE: An example of how to use this is available within the /examples/virtualMachines/virtualMachine/managedDisks/fromCustomImage directory within the GitHub Repository

A storageDataDisk block supports the following:

\~> NOTE: Data Disks can also be attached either using this block or the azurermVirtualMachineDataDiskAttachment resource - but not both.

name - (Required) The name of the Data Disk.
caching - (Optional) Specifies the caching requirements for the Data Disk. Possible values include none, readOnly and readWrite.
createOption - (Required) Specifies how the data disk should be created. Possible values are attach, fromImage and empty.

\~> NOTE: If using an image that does not have data to be written to the Data Disk, use empty as the create option in order to create the desired disk without any data.

diskSizeGb - (Optional) Specifies the size of the data disk in gigabytes.
lun - (Required) Specifies the logical unit number of the data disk. This needs to be unique within all the Data Disks on the Virtual Machine.
writeAcceleratorEnabled - (Optional) Specifies if Write Accelerator is enabled on the disk. This can only be enabled on premiumLrs managed disks with no caching and M-Series VMs. Defaults to false.

The following properties apply when using Managed Disks:

managedDiskType - (Optional) Specifies the type of managed disk to create. Possible values are either standardLrs, standardSsdLrs, premiumLrs or ultraSsdLrs.

-> Note: managedDiskType of type ultraSsdLrs is currently in preview and are not available to subscriptions that have not requested onboarding to azureUltraDiskStorage preview. azureUltraDiskStorage is only available in eastUs2, northEurope, and southeastAsia regions. For more information see the azureUltraDiskStorage product documentation, product blog and FAQ. You must also set additionalCapabilitiesUltraSsdEnabled to true.

managedDiskId - (Optional) Specifies the ID of an Existing Managed Disk which should be attached to this Virtual Machine. When this field is set createOption must be set to attach.

The following properties apply when using Unmanaged Disks:

vhdUri - (Optional) Specifies the URI of the VHD file backing this Unmanaged Data Disk.

A storageOsDisk block supports the following:

name - (Required) Specifies the name of the OS Disk.
createOption - (Required) Specifies how the OS Disk should be created. Possible values are attach (managed disks only) and fromImage.
caching - (Optional) Specifies the caching requirements for the OS Disk. Possible values include none, readOnly and readWrite.
diskSizeGb - (Optional) Specifies the size of the OS Disk in gigabytes.
imageUri - (Optional) Specifies the Image URI in the format publisherName:offer:skus:version. This field can also specify the VHD URI of a custom VM image to clone. When cloning a Custom (Unmanaged) Disk Image the osType field must be set.
osType - (Optional) Specifies the Operating System on the OS Disk. Possible values are linux and windows.
writeAcceleratorEnabled - (Optional) Specifies if Write Accelerator is enabled on the disk. This can only be enabled on premiumLrs managed disks with no caching and M-Series VMs. Defaults to false.

The following properties apply when using Managed Disks:

managedDiskId - (Optional) Specifies the ID of an existing Managed Disk which should be attached as the OS Disk of this Virtual Machine. If this is set then the createOption must be set to attach. Changing this forces a new resource to be created.
managedDiskType - (Optional) Specifies the type of Managed Disk which should be created. Possible values are standardLrs, standardSsdLrs or premiumLrs.

The following properties apply when using Unmanaged Disks:

vhdUri - (Optional) Specifies the URI of the VHD file backing this Unmanaged OS Disk. Changing this forces a new resource to be created.

A vaultCertificates block supports the following:

certificateUrl - (Required) The ID of the Key Vault Secret. Stored secret is the Base64 encoding of a JSON Object that which is encoded in UTF-8 of which the contents need to be:

{
  "data":"<Base64-encoded-certificate>",
  "dataType":"pfx",
  "password":"<pfx-file-password>"
}

-> NOTE: If your certificate is stored in Azure Key Vault - this can be sourced from the secretId property on the azurermKeyVaultCertificate resource.

certificateStore - (Optional) (Required, on windows machines) Specifies the certificate store on the Virtual Machine where the certificate should be added to, such as my.

A winrm block supports the following:

protocol - (Required) Specifies the protocol of listener. Possible values are http or https.
certificateUrl - (Optional) The ID of the Key Vault Secret which contains the encrypted Certificate which should be installed on the Virtual Machine. This certificate must also be specified in the vaultCertificates block within the osProfileSecrets block.

-> NOTE: This can be sourced from the secretId field on the azurermKeyVaultCertificate resource.

Attributes Reference

The following attributes are exported:

id - The ID of the Virtual Machine.
identity - An identity block as defined below.

An identity block exports the following:

principalId - The Principal ID associated with this Managed Service Identity.

-> You can access the Principal ID via ${azurermVirtualMachineExampleIdentity0PrincipalId}

Timeouts

The timeouts block allows you to specify timeouts for certain actions:

create - (Defaults to 60 minutes) Used when creating the Virtual Machine.
update - (Defaults to 60 minutes) Used when updating the Virtual Machine.
read - (Defaults to 5 minutes) Used when retrieving the Virtual Machine.
delete - (Defaults to 60 minutes) Used when deleting the Virtual Machine.

Import

Virtual Machines can be imported using the resourceId, e.g.

terraform import azurerm_virtual_machine.example /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/mygroup1/providers/Microsoft.Compute/virtualMachines/machine1