feat: add extension to setup fqdn for windows virtual machines

docs/modules/azure.md

@@ -25,6 +25,7 @@ lacks. Keep new inputs shaped the AVM way.
 | Module | What it does |
 |---|---|
 | [`azure-ptn-authorization-roledefinition-collection`](../../src/modules/azure-ptn-authorization-roledefinition-collection/) | Many role definitions from one map |
+| [`azure-ptn-compute-virtualmachine-windows-fqdn`](../../src/modules/azure-ptn-compute-virtualmachine-windows-fqdn/) | Windows VM in-guest primary DNS suffix set via CustomScriptExtension (so the guest FQDN matches its public DNS name), then applied by an ARM restart the apply blocks on until the VM is running again |
 | [`azure-ptn-network-dnszone-records`](../../src/modules/azure-ptn-network-dnszone-records/) | A, AAAA, CAA, CNAME, MX, NS, PTR, SRV and TXT records in an existing public zone |
 | [`azure-ptn-network-privatednszone-records`](../../src/modules/azure-ptn-network-privatednszone-records/) | A, AAAA, CNAME, MX, PTR, SRV and TXT records in an existing private zone |
 | [`azure-ptn-network-privatednszone-vnet-links`](../../src/modules/azure-ptn-network-privatednszone-vnet-links/) | Virtual network links across many zones |

src/modules/azure-ptn-compute-virtualmachine-windows-fqdn/main.tf

@@ -0,0 +1,79 @@
+# =============================================================================
+# WINDOWS VM PRIMARY DNS SUFFIX (Microsoft.Compute/virtualMachines/extensions)
+# =============================================================================
+# Sets the guest primary DNS suffix via a CustomScriptExtension, then applies it
+# with an ARM restart. Both are azapi: the extension is an azapi_resource and the
+# restart an azapi_resource_action, so the module depends only on azapi.
+#
+# The restart (not an in-guest `shutdown`) is deliberate: an in-guest reboot is
+# invisible to ARM, so Terraform can't wait on it; azapi blocks on the restart
+# LRO until the VM is running again.
+# =============================================================================
+
+locals {
+  # HKLM\...\Tcpip\Parameters - the keys the Computer Name dialog writes. The
+  # restart below applies them (the value is read at boot, however triggered).
+  set_dns_suffix_script = <<-PS
+    $ErrorActionPreference = 'Stop'
+    $suffix = '${var.dns_suffix}'
+    $key    = 'HKLM:\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters'
+    Set-ItemProperty -Path $key -Name 'Domain'                   -Value $suffix -Type String
+    Set-ItemProperty -Path $key -Name 'NV Domain'                -Value $suffix -Type String
+    Set-ItemProperty -Path $key -Name 'SyncDomainWithMembership' -Value 0       -Type DWord
+    Write-Output "Primary DNS suffix set to '$suffix'. Reboot required to take effect."
+    exit 0
+  PS
+
+  # -ExecutionPolicy is omitted: it governs script files, not the inline
+  # -EncodedCommand, so it would be a no-op here.
+  command_to_execute = "powershell.exe -NoProfile -EncodedCommand ${textencodebase64(local.set_dns_suffix_script, "UTF-16LE")}"
+}
+
+resource "azapi_resource" "dns_suffix" {
+  type      = "Microsoft.Compute/virtualMachines/extensions@2024-07-01"
+  name      = "SetPrimaryDnsSuffix"
+  parent_id = var.virtual_machine_id
+  location  = var.location
+  tags      = var.tags
+
+  # settings is a native object - azapi serializes the whole body to JSON, so no
+  # jsonencode() wrapper is needed around it.
+  body = {
+    properties = {
+      publisher                = "Microsoft.Compute"
+      type                     = "CustomScriptExtension"
+      typeHandlerVersion       = "1.10"
+      autoUpgradeMinorVersion  = true
+      provisionAfterExtensions = var.provision_after_extensions
+      settings = {
+        commandToExecute = local.command_to_execute
+      }
+    }
+  }
+}
+
+# -----------------------------------------------------------------------------
+# Apply the suffix with an ARM restart (blocks until the VM is running again)
+# -----------------------------------------------------------------------------
+# replace_triggered_by keys on the extension's body, which carries the settings
+# (and thus the suffix). It changes iff the script/suffix changes; tags are a
+# separate top-level attribute, not part of body, so they don't re-fire it.
+
+resource "azapi_resource_action" "reboot" {
+  count = var.reboot ? 1 : 0
+
+  type        = "Microsoft.Compute/virtualMachines@2024-07-01"
+  resource_id = var.virtual_machine_id
+  action      = "restart"
+  method      = "POST"
+
+  timeouts {
+    create = "15m"
+  }
+
+  lifecycle {
+    replace_triggered_by = [azapi_resource.dns_suffix.body]
+  }
+
+  depends_on = [azapi_resource.dns_suffix]
+}

src/modules/azure-ptn-compute-virtualmachine-windows-fqdn/outputs.tf

@@ -0,0 +1,4 @@
+output "extension_id" {
+  description = "Resource ID of the CustomScriptExtension that sets the primary DNS suffix."
+  value       = azapi_resource.dns_suffix.id
+}

src/modules/azure-ptn-compute-virtualmachine-windows-fqdn/variables.tf

@@ -0,0 +1,48 @@
+variable "virtual_machine_id" {
+  description = "Resource ID of the Windows virtual machine whose in-guest primary DNS suffix this extension sets."
+  type        = string
+
+  validation {
+    condition     = can(regex("/providers/Microsoft.Compute/virtualMachines/", var.virtual_machine_id))
+    error_message = "virtual_machine_id must be a Microsoft.Compute/virtualMachines resource ID."
+  }
+}
+
+# azapi does not infer the extension's location from the parent VM, so the
+# caller must pass the VM's region. A VM extension is location-tracked and must
+# sit in the same region as its VM, so this has to equal the VM's location.
+variable "location" {
+  description = "Azure region of the target VM. A VM extension is a location-tracked resource and must match the VM's region (e.g. westeurope)."
+  type        = string
+}
+
+variable "dns_suffix" {
+  description = "Primary DNS suffix to write in-guest, e.g. westeurope.cloudapp.azure.com, so the machine's FQDN matches the public DNS name of its IP. Any lowercase DNS domain is accepted."
+  type        = string
+
+  validation {
+    condition     = can(regex("^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", var.dns_suffix))
+    error_message = "dns_suffix must be a valid lowercase DNS domain (e.g. westeurope.cloudapp.azure.com)."
+  }
+}
+
+variable "provision_after_extensions" {
+  description = "Names of same-VM extensions this suffix step must provision after — the guest agent holds it (and its reboot) until they finish. Empty means no ordering constraint. Example: [\"AADLoginForWindows\"], so the reboot cannot land mid Entra-join."
+  type        = list(string)
+  default     = []
+  nullable    = false
+}
+
+variable "tags" {
+  description = "Tags applied to the VM extension."
+  type        = map(string)
+  default     = {}
+  nullable    = false
+}
+
+variable "reboot" {
+  description = "Reboot the VM (via an ARM restart) after writing the suffix so it takes effect, and block the apply until the restart completes and the VM is running again. When it's false the module only writes the registry and the suffix stays inactive until the VM is rebooted by other means."
+  type        = bool
+  default     = true
+  nullable    = false
+}

src/modules/azure-ptn-compute-virtualmachine-windows-fqdn/versions.tf

@@ -0,0 +1,13 @@
+terraform {
+  required_version = ">= 1.15"
+
+  required_providers {
+    # The extension is an azapi_resource and the reboot an azapi_resource_action,
+    # so this module speaks only azapi. The parent VM stays an azurerm resource
+    # in the CALLER - only its id and location are passed in as strings.
+    azapi = {
+      source  = "Azure/azapi"
+      version = ">= 2.0, < 3.0"
+    }
+  }
+}