azurermWindowsVirtualMachine
Manages a Windows Virtual Machine.
Disclaimers
-> Note Terraform will automatically remove the OS Disk by default - this behaviour can be configured using the features
setting within the Provider block.
\~> Note All arguments including the administrator login and password will be stored in the raw state as plain-text. Read more about sensitive data in state.
\~> Note This resource does not support Unmanaged Disks. If you need to use Unmanaged Disks you can continue to use the azurermVirtualMachine
resource instead.
\~> Note This resource does not support attaching existing OS Disks. You can instead capture an image of the OS Disk or continue to use the azurermVirtualMachine
resource instead.
\~> In this release there's a known issue where the publicIpAddress
and publicIpAddresses
fields may not be fully populated for Dynamic Public IP's.
Example Usage
This example provisions a basic Windows Virtual Machine on an internal network. Additional examples of how to use the azurermWindowsVirtualMachine
resource can be found in the /examples/virtualMachines/windows
directory within the GitHub Repository.
/*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.*/
new azurerm.provider.AzurermProvider(this, "azurerm", {
features: [{}],
});
const azurermResourceGroupExample = new azurerm.resourceGroup.ResourceGroup(
this,
"example",
{
location: "West Europe",
name: "example-resources",
}
);
const azurermVirtualNetworkExample = new azurerm.virtualNetwork.VirtualNetwork(
this,
"example_2",
{
address_space: ["10.0.0.0/16"],
location: azurermResourceGroupExample.location,
name: "example-network",
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.*/
azurermVirtualNetworkExample.overrideLogicalId("example");
const azurermSubnetExample = new azurerm.subnet.Subnet(this, "example_3", {
address_prefixes: ["10.0.2.0/24"],
name: "internal",
resource_group_name: azurermResourceGroupExample.name,
virtual_network_name: azurermVirtualNetworkExample.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.*/
azurermSubnetExample.overrideLogicalId("example");
const azurermNetworkInterfaceExample =
new azurerm.networkInterface.NetworkInterface(this, "example_4", {
ip_configuration: [
{
name: "internal",
private_ip_address_allocation: "Dynamic",
subnet_id: azurermSubnetExample.id,
},
],
location: azurermResourceGroupExample.location,
name: "example-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.*/
azurermNetworkInterfaceExample.overrideLogicalId("example");
const azurermWindowsVirtualMachineExample =
new azurerm.windowsVirtualMachine.WindowsVirtualMachine(this, "example_5", {
admin_password: "P@$$w0rd1234!",
admin_username: "adminuser",
location: azurermResourceGroupExample.location,
name: "example-machine",
network_interface_ids: [azurermNetworkInterfaceExample.id],
os_disk: [
{
caching: "ReadWrite",
storage_account_type: "Standard_LRS",
},
],
resource_group_name: azurermResourceGroupExample.name,
size: "Standard_F2",
source_image_reference: [
{
offer: "WindowsServer",
publisher: "MicrosoftWindowsServer",
sku: "2016-Datacenter",
version: "latest",
},
],
});
/*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/
azurermWindowsVirtualMachineExample.overrideLogicalId("example");
Argument Reference
The following arguments are supported:
-
adminPassword
- (Required) The Password which should be used for the local-administrator on this Virtual Machine. Changing this forces a new resource to be created. -
adminUsername
- (Required) The username of the local administrator used for the Virtual Machine. Changing this forces a new resource to be created. -
location
- (Required) The Azure location where the Windows Virtual Machine should exist. Changing this forces a new resource to be created. -
name
- (Required) The name of the Windows Virtual Machine. Changing this forces a new resource to be created. -
networkInterfaceIds
- (Required). A list of Network Interface IDs which should be attached to this Virtual Machine. The first Network Interface ID in this list will be the Primary Network Interface on the Virtual Machine. -
osDisk
- (Required) AosDisk
block as defined below. -
resourceGroupName
- (Required) The name of the Resource Group in which the Windows Virtual Machine should be exist. Changing this forces a new resource to be created. -
size
- (Required) The SKU which should be used for this Virtual Machine, such asstandardF2
.
-
additionalCapabilities
- (Optional) AadditionalCapabilities
block as defined below. -
additionalUnattendContent
- (Optional) One or moreadditionalUnattendContent
blocks as defined below. Changing this forces a new resource to be created. -
allowExtensionOperations
- (Optional) Should Extension Operations be allowed on this Virtual Machine? Defaults totrue
. -
availabilitySetId
- (Optional) Specifies the ID of the Availability Set in which the Virtual Machine should exist. Changing this forces a new resource to be created. -
bootDiagnostics
- (Optional) AbootDiagnostics
block as defined below. -
capacityReservationGroupId
- (Optional) Specifies the ID of the Capacity Reservation Group which the Virtual Machine should be allocated to.
\~> NOTE: capacityReservationGroupId
cannot be used with availabilitySetId
or proximityPlacementGroupId
-
computerName
- (Optional) Specifies the Hostname which should be used for this Virtual Machine. If unspecified this defaults to the value for thename
field. If the value of thename
field is not a validcomputerName
, then you must specifycomputerName
. Changing this forces a new resource to be created. -
customData
- (Optional) The Base64-Encoded Custom Data which should be used for this Virtual Machine. Changing this forces a new resource to be created. -
dedicatedHostId
- (Optional) The ID of a Dedicated Host where this machine should be run on. Conflicts withdedicatedHostGroupId
. -
dedicatedHostGroupId
- (Optional) The ID of a Dedicated Host Group that this Windows Virtual Machine should be run within. Conflicts withdedicatedHostId
. -
edgeZone
- (Optional) Specifies the Edge Zone within the Azure Region where this Windows Virtual Machine should exist. Changing this forces a new Windows Virtual Machine to be created. -
enableAutomaticUpdates
- (Optional) Specifies if Automatic Updates are Enabled for the Windows Virtual Machine. Changing this forces a new resource to be created. Defaults totrue
. -
encryptionAtHostEnabled
- (Optional) Should all of the disks (including the temp disk) attached to this Virtual Machine be encrypted by enabling Encryption at Host? -
evictionPolicy
- (Optional) Specifies what should happen when the Virtual Machine is evicted for price reasons when using a Spot instance. Possible values aredeallocate
anddelete
. Changing this forces a new resource to be created.
-> NOTE: This can only be configured when priority
is set to spot
.
-
extensionsTimeBudget
- (Optional) Specifies the duration allocated 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. Defaults to 90 minutes (pt1H30M
). -
galleryApplication
- (Optional) AgalleryApplication
block as defined below. -
hotpatchingEnabled
- (Optional) Should the VM be patched without requiring a reboot? Possible values aretrue
orfalse
. Defaults tofalse
. For more information about hot patching please see the product documentation.
-> NOTE: Hotpatching can only be enabled if the patchMode
is set to automaticByPlatform
, the provisionVmAgent
is set to true
, your sourceImageReference
references a hotpatching enabled image, and the VM's size
is set to a Azure generation 2 VM. An example of how to correctly configure a Windows Virtual Machine to use the hotpatchingEnabled
field can be found in the /examples/virtualMachines/windows/hotpatchingEnabled
directory within the GitHub Repository.
-
identity
- (Optional) Anidentity
block as defined below. -
licenseType
- (Optional) Specifies the type of on-premise license (also known as Azure Hybrid Use Benefit) which should be used for this Virtual Machine. Possible values arenone
,windowsClient
andwindowsServer
. -
maxBidPrice
- (Optional) The maximum price you're willing to pay for this Virtual Machine, in US Dollars; which must be greater than the current spot price. If this bid price falls below the current spot price the Virtual Machine will be evicted using theevictionPolicy
. Defaults to1
, which means that the Virtual Machine should not be evicted for price reasons.
-> NOTE: This can only be configured when priority
is set to spot
.
patchAssessmentMode
- (Optional) Specifies the mode of VM Guest Patching for the Virtual Machine. Possible values areautomaticByPlatform
orimageDefault
. Defaults toimageDefault
.
-> NOTE: If the patchAssessmentMode
is set to automaticByPlatform
then the provisionVmAgent
field must be set to true
.
patchMode
- (Optional) Specifies the mode of in-guest patching to this Windows Virtual Machine. Possible values aremanual
,automaticByOs
andautomaticByPlatform
. Defaults toautomaticByOs
. For more information on patch modes please see the product documentation.
-> NOTE: If patchMode
is set to automaticByPlatform
then provisionVmAgent
must also be set to true
. If the Virtual Machine is using a hotpatching enabled image the patchMode
must always be set to automaticByPlatform
.
-
plan
- (Optional) Aplan
block as defined below. Changing this forces a new resource to be created. -
platformFaultDomain
- (Optional) Specifies the Platform Fault Domain in which this Windows Virtual Machine should be created. Defaults to1
, which means this will be automatically assigned to a fault domain that best maintains balance across the available fault domains. Changing this forces a new Windows Virtual Machine to be created. -
priority
- (Optional) Specifies the priority of this Virtual Machine. Possible values areregular
andspot
. Defaults toregular
. Changing this forces a new resource to be created. -
provisionVmAgent
- (Optional) Should the Azure VM Agent be provisioned on this Virtual Machine? Defaults totrue
. Changing this forces a new resource to be created.
\~> NOTE: If provisionVmAgent
is set to false
then allowExtensionOperations
must also be set to false
.
-
proximityPlacementGroupId
- (Optional) The ID of the Proximity Placement Group which the Virtual Machine should be assigned to. -
secret
- (Optional) One or moresecret
blocks as defined below. -
secureBootEnabled
- (Optional) Specifies if Secure Boot and Trusted Launch is enabled for the Virtual Machine. Changing this forces a new resource to be created. -
sourceImageId
- (Optional) The ID of the Image which this Virtual Machine should be created from. Changing this forces a new resource to be created. Possible Image ID types includeimageId
s,sharedImageId
s,sharedImageVersionId
s,communityGalleryImageId
s,communityGalleryImageVersionId
s,sharedGalleryImageId
s andsharedGalleryImageVersionId
s.
-> NOTE: One of either sourceImageId
or sourceImageReference
must be set.
sourceImageReference
- (Optional) AsourceImageReference
block as defined below. Changing this forces a new resource to be created.
-> NOTE: One of either sourceImageId
or sourceImageReference
must be set.
-
tags
- (Optional) A mapping of tags which should be assigned to this Virtual Machine. -
terminationNotification
- (Optional) AterminationNotification
block as defined below. -
timezone
- (Optional) Specifies the Time Zone which should be used by the Virtual Machine, the possible values are defined here. Changing this forces a new resource to be created. -
userData
- (Optional) The Base64-Encoded User Data which should be used for this Virtual Machine. -
virtualMachineScaleSetId
- (Optional) Specifies the Orchestrated Virtual Machine Scale Set that this Virtual Machine should be created within. Changing this forces a new resource to be created.
\~> NOTE: Orchestrated Virtual Machine Scale Sets can be provisioned using the azurermOrchestratedVirtualMachineScaleSet
resource.
-
vtpmEnabled
- (Optional) Specifies if vTPM (virtual Trusted Platform Module) and Trusted Launch is enabled for the Virtual Machine. Changing this forces a new resource to be created. -
winrmListener
- (Optional) One or morewinrmListener
blocks as defined below. Changing this forces a new resource to be created. -
zone
- *zones
- (Optional) Specifies the Availability Zone in which this Windows Virtual Machine should be located. Changing this forces a new Windows Virtual Machine to be created.
A additionalCapabilities
block supports the following:
ultraSsdEnabled
- (Optional) Should the capacity to enable Data Disks of theultraSsdLrs
storage account type be supported on this Virtual Machine? Defaults tofalse
.
A additionalUnattendContent
block supports the following:
-
content
- (Required) The XML formatted content that is added to the unattend.xml file for the specified path and component. Changing this forces a new resource to be created. -
setting
- (Required) The name of the setting to which the content applies. Possible values areautoLogon
andfirstLogonCommands
. Changing this forces a new resource to be created.
A bootDiagnostics
block supports the following:
storageAccountUri
- (Optional) The Primary/Secondary Endpoint for the Azure Storage Account which should be used to store Boot Diagnostics, including Console Output and Screenshots from the Hypervisor.
-> NOTE: Passing a null value will utilize a Managed Storage Account to store Boot Diagnostics.
A certificate
block supports the following:
-
store
- (Required) The certificate store on the Virtual Machine where the certificate should be added. -
url
- (Required) The Secret URL of a Key Vault Certificate.
-> NOTE: This can be sourced from the secretId
field within the azurermKeyVaultCertificate
Resource.
A diffDiskSettings
block supports the following:
-
option
- (Required) Specifies the Ephemeral Disk Settings for the OS Disk. At this time the only possible value islocal
. Changing this forces a new resource to be created. -
placement
- (Optional) Specifies where to store the Ephemeral Disk. Possible values arecacheDisk
andresourceDisk
. Defaults tocacheDisk
. Changing this forces a new resource to be created.
A galleryApplication
block supports the following:
-
versionId
- (Required) Specifies the Gallery Application Version resource ID. -
configurationBlobUri
- (Optional) Specifies the URI to an Azure Blob that will replace the default configuration for the package if provided. -
order
- (Optional) Specifies the order in which the packages have to be installed. Possible values are between0
and2,147,483,647
. -
tag
- (Optional) Specifies a passthrough value for more generic context. This field can be any validstring
value.
An identity
block supports the following:
-
type
- (Required) Specifies the type of Managed Service Identity that should be configured on this Windows Virtual Machine. Possible values aresystemAssigned
,userAssigned
,systemAssigned,UserAssigned
(to enable both). -
identityIds
- (Optional) Specifies a list of User Assigned Managed Identity IDs to be assigned to this Windows Virtual Machine.
\~> NOTE: This is required when type
is set to userAssigned
or systemAssigned,UserAssigned
.
A osDisk
block supports the following:
-
caching
- (Required) The Type of Caching which should be used for the Internal OS Disk. Possible values arenone
,readOnly
andreadWrite
. -
storageAccountType
- (Required) The Type of Storage Account which should back this the Internal OS Disk. Possible values arestandardLrs
,standardSsdLrs
,premiumLrs
,standardSsdZrs
andpremiumZrs
. Changing this forces a new resource to be created. -
diffDiskSettings
- (Optional) AdiffDiskSettings
block as defined above. Changing this forces a new resource to be created.
-> NOTE: diffDiskSettings
can only be set when caching
is set to readOnly
. More information can be found here
diskEncryptionSetId
- (Optional) The ID of the Disk Encryption Set which should be used to Encrypt this OS Disk. Conflicts withsecureVmDiskEncryptionSetId
.
-> NOTE: The Disk Encryption Set must have the reader
Role Assignment scoped on the Key Vault - in addition to an Access Policy to the Key Vault
diskSizeGb
- (Optional) The Size of the Internal OS Disk in GB, if you wish to vary from the size used in the image this Virtual Machine is sourced from.
-> NOTE: If specified this must be equal to or larger than the size of the Image the Virtual Machine is based on. When creating a larger disk than exists in the image you'll need to repartition the disk to use the remaining space.
-
name
- (Optional) The name which should be used for the Internal OS Disk. Changing this forces a new resource to be created. -
secureVmDiskEncryptionSetId
- (Optional) The ID of the Disk Encryption Set which should be used to Encrypt this OS Disk when the Virtual Machine is a Confidential VM. Conflicts withdiskEncryptionSetId
. Changing this forces a new resource to be created.
\~> NOTE: secureVmDiskEncryptionSetId
can only be specified when securityEncryptionType
is set to diskWithVmGuestState
.
securityEncryptionType
- (Optional) Encryption Type when the Virtual Machine is a Confidential VM. Possible values arevmGuestStateOnly
anddiskWithVmGuestState
. Changing this forces a new resource to be created.
\~> NOTE: vtpmEnabled
must be set to true
when securityEncryptionType
is specified.
\~> NOTE: encryptionAtHostEnabled
cannot be set to true
when securityEncryptionType
is set to diskWithVmGuestState
.
writeAcceleratorEnabled
- (Optional) Should Write Accelerator be Enabled for this OS Disk? Defaults tofalse
.
-> NOTE: This requires that the storageAccountType
is set to premiumLrs
and that caching
is set to none
.
A plan
block supports the following:
-
name
- (Required) Specifies the Name of the Marketplace Image this Virtual Machine should be created from. Changing this forces a new resource to be created. -
product
- (Required) Specifies the Product of the Marketplace Image this Virtual Machine should be created from. Changing this forces a new resource to be created. -
publisher
- (Required) Specifies the Publisher of the Marketplace Image this Virtual Machine should be created from. Changing this forces a new resource to be created.
-> NOTE: If you use the plan
block with one of Microsoft's marketplace images (e.g. publisher = "microsoftWindowsServer"
). This may prevent the purchase of the offer. An example Azure API error: theOffer: 'windowsServer'CannotBePurchasedBySubscription: '123456781223456789012123456789012'AsItIsNotToBeSoldInMarket: 'us'PleaseChooseASubscriptionWhichIsAssociatedWithADifferentMarket
A secret
block supports the following:
-
certificate
- (Required) One or morecertificate
blocks as defined above. -
keyVaultId
- (Required) The ID of the Key Vault from which all Secrets should be sourced.
The sourceImageReference
block supports the following:
-
publisher
- (Required) Specifies the publisher of the image used to create the virtual machines. Changing this forces a new resource to be created. -
offer
- (Required) Specifies the offer of the image used to create the virtual machines. Changing this forces a new resource to be created. -
sku
- (Required) Specifies the SKU of the image used to create the virtual machines. Changing this forces a new resource to be created. -
version
- (Required) Specifies the version of the image used to create the virtual machines. Changing this forces a new resource to be created.
A terminationNotification
block supports the following:
-
enabled
- (Required) Should the termination notification be enabled on this Virtual Machine? -
timeout
- (Optional) Length of time (in minutes, between5
and15
) a notification to be sent to the VM on the instance metadata server till the VM gets deleted. The time duration should be specified in ISO 8601 format. Defaults topt5M
.
\~> NOTE: For more information about the termination notification, please refer to this doc.
A winrmListener
block supports the following:
-
protocol
- (Required) Specifies the protocol of listener. Possible values arehttp
orhttps
. Changing this forces a new resource to be created. -
certificateUrl
- (Optional) The Secret URL of a Key Vault Certificate, which must be specified whenprotocol
is set tohttps
. Changing this forces a new resource to be created.
Attributes Reference
In addition to all arguments above, the following attributes are exported:
-
id
- The ID of the Windows Virtual Machine. -
identity
- Anidentity
block as documented below. -
privateIpAddress
- The Primary Private IP Address assigned to this Virtual Machine. -
privateIpAddresses
- A list of Private IP Addresses assigned to this Virtual Machine. -
publicIpAddress
- The Primary Public IP Address assigned to this Virtual Machine. -
publicIpAddresses
- A list of the Public IP Addresses assigned to this Virtual Machine. -
virtualMachineId
- A 128-bit identifier which uniquely identifies this Virtual Machine.
An identity
block exports the following:
-
principalId
- The Principal ID associated with this Managed Service Identity. -
tenantId
- The Tenant ID associated with this Managed Service Identity.
Timeouts
The timeouts
block allows you to specify timeouts for certain actions:
create
- (Defaults to 45 minutes) Used when creating the Windows Virtual Machine.update
- (Defaults to 45 minutes) Used when updating the Windows Virtual Machine.delete
- (Defaults to 45 minutes) Used when deleting the Windows Virtual Machine.read
- (Defaults to 5 minutes) Used when retrieving the Windows Virtual Machine.
Import
Windows Virtual Machines can be imported using the resourceId
, e.g.