feat(vm,lxc): add wait_for_ip configuration for agent/network interfaces (#2362)

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>

Author: bpg

docs/resources/virtual_environment_container.md

@@ -249,6 +249,11 @@ output "ubuntu_container_public_key" {
 - `timeout_delete` - (Optional) Timeout for deleting a container in seconds (defaults to 60).
 - `timeout_update` - (Optional) Timeout for updating a container in seconds (defaults to 1800).
 - `unprivileged` - (Optional) Whether the container runs as unprivileged on the host (defaults to `false`).
+- `wait_for_ip` - (Optional) Configuration for waiting for specific IP address types when the container starts.
+    - `ipv4` - (Optional) Wait for at least one IPv4 address (non-loopback, non-link-local) (defaults to `false`).
+    - `ipv6` - (Optional) Wait for at least one IPv6 address (non-loopback, non-link-local) (defaults to `false`).
+
+    When `wait_for_ip` is not specified or both `ipv4` and `ipv6` are `false`, the provider waits for any valid global unicast address (IPv4 or IPv6). In dual-stack networks where DHCPv6 responds faster, this may result in only IPv6 addresses being available. Set `ipv4 = true` to ensure IPv4 address availability.
 - `vm_id` - (Optional) The container identifier
 - `features` - (Optional) The container feature flags. Changing flags (except nesting) is only allowed for `root@pam` authenticated user.
     - `nesting` - (Optional) Whether the container is nested (defaults to `false`)

docs/resources/virtual_environment_vm.md

@@ -137,6 +137,11 @@ output "ubuntu_vm_public_key" {
     - `type` - (Optional) The QEMU agent interface type (defaults to `virtio`).
         - `isa` - ISA Serial Port.
         - `virtio` - VirtIO (paravirtualized).
+    - `wait_for_ip` - (Optional) Configuration for waiting for specific IP address types when the VM starts.
+        - `ipv4` - (Optional) Wait for at least one IPv4 address (non-loopback, non-link-local) (defaults to `false`).
+        - `ipv6` - (Optional) Wait for at least one IPv6 address (non-loopback, non-link-local) (defaults to `false`).
+
+        When `wait_for_ip` is not specified or both `ipv4` and `ipv6` are `false`, the provider waits for any valid global unicast address (IPv4 or IPv6). In dual-stack networks where DHCPv6 responds faster, this may result in only IPv6 addresses being available. Set `ipv4 = true` to ensure IPv4 address availability.
 - `amd_sev` - (Optional) Secure Encrypted Virtualization (SEV) features by AMD CPUs.
     - `type` - (Optional) Enable standard SEV with `std` or enable experimental SEV-ES with the `es` option or enable experimental SEV-SNP with the `snp` option (defaults to `std`).
     - `allow_smt` - (Optional) Sets policy bit to allow Simultaneous Multi Threading (SMT)

example/resource_virtual_environment_container.tf

@@ -3,6 +3,10 @@ resource "proxmox_virtual_environment_container" "example_template" {
 
   start_on_boot = "true"
 
+  wait_for_ip {
+    ipv4 = true
+  }
+
   disk {
     datastore_id = var.virtual_environment_storage
     size         = 4
@@ -73,6 +77,10 @@ resource "proxmox_virtual_environment_container" "example" {
     vm_id = proxmox_virtual_environment_container.example_template.id
   }
 
+  wait_for_ip {
+    ipv4 = true
+  }
+
   tags = [
     "container",
   ]

example/resource_virtual_environment_trunks.tf

@@ -40,6 +40,9 @@ resource "proxmox_virtual_environment_vm" "trunks-example" {
 
   agent {
     enabled = true
+    wait_for_ip {
+      ipv4 = true
+    }
   }
 
   serial_device {}

example/resource_virtual_environment_vm.tf

@@ -5,6 +5,9 @@ locals {
 resource "proxmox_virtual_environment_vm" "example_template" {
   agent {
     enabled = true
+    wait_for_ip {
+      ipv4 = true
+    }
   }
 
   bios        = "ovmf"
@@ -147,6 +150,13 @@ resource "proxmox_virtual_environment_vm" "example" {
   #   memory = 768
   # }
 
+  agent {
+    enabled = true
+    wait_for_ip {
+      ipv4 = true
+    }
+  }
+
   connection {
     type        = "ssh"
     agent       = false

fwprovider/test/resource_vm_test.go

@@ -845,6 +845,75 @@ func TestAccResourceVMNetwork(t *testing.T) {
 				}),
 			),
 		}}},
+		{"wait for IPv4 address", []resource.TestStep{{
+			Config: te.RenderConfig(`
+				resource "proxmox_virtual_environment_file" "cloud_config" {
+					content_type = "snippets"
+					datastore_id = "local"
+					node_name = "{{.NodeName}}"
+					source_raw {
+						data = <<-EOF
+						#cloud-config
+						runcmd:
+						  - apt update
+						  - apt install -y qemu-guest-agent
+						  - systemctl enable qemu-guest-agent
+						  - systemctl start qemu-guest-agent
+						EOF
+						file_name = "cloud-config.yaml"
+					}
+				}
+				
+				resource "proxmox_virtual_environment_vm" "test_vm_wait_ipv4" {
+					node_name = "{{.NodeName}}"
+					started   = true
+					agent {
+						enabled = true
+						wait_for_ip {
+							ipv4 = true
+						}
+					}
+					cpu {
+						cores = 2
+					}
+					memory {
+						dedicated = 2048
+					}
+					disk {
+						datastore_id = "local-lvm"
+						file_id      = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id
+						interface    = "virtio0"
+						iothread     = true
+						discard      = "on"
+						size         = 20
+					}
+					initialization {
+						ip_config {
+							ipv4 {
+								address = "dhcp"
+							}
+						}
+						user_data_file_id = proxmox_virtual_environment_file.cloud_config.id
+					}
+					network_device {
+						bridge = "vmbr0"
+					}
+				}
+
+				resource "proxmox_virtual_environment_download_file" "ubuntu_cloud_image" {
+					content_type = "iso"
+					datastore_id = "local"
+					node_name    = "{{.NodeName}}"
+					url = "{{.CloudImagesServer}}/minimal/releases/noble/release/ubuntu-24.04-minimal-cloudimg-amd64.img"
+					overwrite_unmanaged = true
+				}`),
+			Check: resource.ComposeTestCheckFunc(
+				ResourceAttributes("proxmox_virtual_environment_vm.test_vm_wait_ipv4", map[string]string{
+					"ipv4_addresses.#":           "2",
+					"agent.0.wait_for_ip.0.ipv4": "true",
+				}),
+			),
+		}}},
 		{"network device disconnected", []resource.TestStep{
 			{
 				Config: te.RenderConfig(`

proxmox/nodes/containers/containers.go

@@ -162,6 +162,7 @@ func (c *Client) ListContainers(ctx context.Context) ([]*ListResponseData, error
 func (c *Client) WaitForContainerNetworkInterfaces(
 	ctx context.Context,
 	timeout time.Duration,
+	waitForIPConfig *WaitForIPConfig, // configuration for which IP types to wait for (nil = wait for any global unicast)
 ) ([]GetNetworkInterfacesData, error) {
 	errNoIPsYet := errors.New("no ips yet")
 
@@ -175,17 +176,36 @@ func (c *Client) WaitForContainerNetworkInterfaces(
 				return nil, err
 			}
 
-			for _, iface := range ifaces {
-				if iface.Name != "lo" && iface.IPAddresses != nil && len(*iface.IPAddresses) > 0 {
-					for _, ipAddr := range *iface.IPAddresses {
-						if ip.IsValidGlobalUnicast(ipAddr.Address) {
-							return ifaces, nil
-						}
-					}
+			hasIPv4, hasIPv6 := c.checkIPAddresses(ifaces)
+
+			if waitForIPConfig == nil {
+				// backward compatibility: wait for any valid global unicast address
+				if !hasIPv4 && !hasIPv6 {
+					return nil, errNoIPsYet
+				}
+
+				return ifaces, nil
+			}
+
+			requiredIPv4 := waitForIPConfig.IPv4
+			requiredIPv6 := waitForIPConfig.IPv6
+
+			// if no specific requirements, wait for any IP (backward compatibility)
+			if !requiredIPv4 && !requiredIPv6 {
+				if !hasIPv4 && !hasIPv6 {
+					return nil, errNoIPsYet
 				}
+
+				return ifaces, nil
 			}
 
-			return nil, errNoIPsYet
+			// check if all required IP types are available
+			if (requiredIPv4 && !hasIPv4) || (requiredIPv6 && !hasIPv6) {
+				return nil, errNoIPsYet
+			}
+
+			// all required IP types are available
+			return ifaces, nil
 		},
 		retry.Context(ctxWithTimeout),
 		retry.RetryIf(func(err error) bool {
@@ -217,6 +237,34 @@ func (c *Client) WaitForContainerNetworkInterfaces(
 	return ifaces, nil
 }
 
+// checkIPAddresses checks network interfaces for valid IP addresses and returns whether IPv4 and IPv6 are present.
+func (c *Client) checkIPAddresses(
+	ifaces []GetNetworkInterfacesData,
+) (bool, bool) {
+	hasIPv4 := false
+	hasIPv6 := false
+
+	for _, iface := range ifaces {
+		if iface.Name == "lo" || iface.IPAddresses == nil || len(*iface.IPAddresses) == 0 {
+			continue
+		}
+
+		for _, ipAddr := range *iface.IPAddresses {
+			if !ip.IsValidGlobalUnicast(ipAddr.Address) {
+				continue
+			}
+
+			if ip.IsIPv4(ipAddr.Address) {
+				hasIPv4 = true
+			} else if ip.IsIPv6(ipAddr.Address) {
+				hasIPv6 = true
+			}
+		}
+	}
+
+	return hasIPv4, hasIPv6
+}
+
 // RebootContainer reboots a container.
 func (c *Client) RebootContainer(ctx context.Context, d *RebootRequestBody) error {
 	taskID, err := c.RebootContainerAsync(ctx, d)

proxmox/nodes/containers/containers_types.go

@@ -27,6 +27,12 @@ var (
 	regexMountPointKey = regexp.MustCompile(`^mp\d+$`)
 )
 
+// WaitForIPConfig specifies which IP address types to wait for when waiting for network interfaces.
+type WaitForIPConfig struct {
+	IPv4 bool // Wait for at least one IPv4 address (non-loopback, non-link-local)
+	IPv6 bool // Wait for at least one IPv6 address (non-loopback, non-link-local)
+}
+
 // CloneRequestBody contains the data for an container clone request.
 type CloneRequestBody struct {
 	BandwidthLimit *int              `json:"bwlimit,omitempty"     url:"bwlimit,omitempty"`