A visible guest IP address does not necessarily satisfy the vSphere Terraform provider's network waiter. In provider v2.12.0, the default waiter also considers gateway-related information, and configured exclusions can reject an otherwise visible address. Diagnose those predicates before extending the timeout or disabling the gate. A28-S1
This article reads the version-pinned resource documentation. All examples are synthetic and unexecuted. No Terraform plan, apply, refresh, import or guest command was run.
What the provider is waiting for
The network waiter runs near the end of VM creation and update. It consumes guest-network information associated with VMware Tools so the provider can expose a suitable address for later provisioning work.
For v2.12.0, the relevant settings are:
| Setting | Documented behaviour |
|---|---|
wait_for_guest_net_timeout |
Minutes to wait; default 5; below 1 disables it |
wait_for_guest_net_routable |
Default true; false skips default-gateway waiting and address/gateway matching |
wait_for_guest_ip_timeout |
Alternative IP waiter; default 0; intended for older Tools reporting limitations |
ignored_guest_ips |
Address/CIDR exclusions used by either waiter; default empty |
The routable setting is ignored when the alternative IP waiter is used. These are distinct mechanisms; changing one field without identifying the active waiter can have no intended effect. A28-S1
The provider's word “routable” should not be mistaken for a completed application transaction from the Terraform runner. Its documented success criteria involve reported addresses and gateways. An application port, firewall or authentication service can still fail after those criteria are satisfied.
Read the failed run's inputs
Prerequisites are the provider version recorded for that run, the existing resource configuration, the waiter error and timestamp, and authorised existing guest-network/Tools evidence. Read the saved material rather than rerunning an apply to reproduce the timeout.
Identify which waiter was active and whether any exclusions were configured. Compare the exact error stage with the resource's other timeouts. A clone or customisation timeout is not automatically a network-waiter timeout.
Then compare the reported IP addresses and gateway information for the same VM and period. A later screenshot showing an address does not prove it was reported before the waiter expired. Likewise, an address inside the guest does not prove that VMware Tools had supplied the metadata the provider needed at that time.
For an IPv6-exclusive network without DHCP, the v2.12.0 resource document specifically warns that the network waiter may need to cover the guest’s DHCP timeout. Separately, customisation default routes are global rather than per-interface gateway settings. Compare the failed run’s timeout and actual default-route metadata, especially on isolated or multi-NIC designs; this is diagnostic context, not a recommendation to change the route or extend a timeout blindly. Version v2.12.0 is the exact document assessed, not a claim to be the newest release. Publication must retain that scope or independently check a newer release.
Work through the visible-IP cases
Suppose a synthetic VM has an address on an isolated provisioning network but no intended default gateway. The active configuration retains wait_for_guest_net_routable = true. The address can be visible while the default network waiter's criteria remain unsatisfied.
The diagnosis is a mismatch between the expected network design and the selected readiness predicate. It is not proof that adding a gateway is the correct fix. The provisioning owner must decide what readiness means for that isolated VM.
In another example, ignored_guest_ips includes 192.0.2.0/24, and the only reported address is 192.0.2.25. The documentation says excluded addresses are ignored while waiting for a valid address. Increasing the timeout does not make that address stop matching the exclusion. The example range is illustrative and is not a deployment recommendation.
For a multi-NIC VM, record every reported address and the applicable exclusions. Do not assume the first address visible in a UI is the one the provider selects for downstream use.
Interpret the selected default address
The v2.12.0 documentation describes default_ip_address selection in terms of an IPv4 address associated with the default-gateway path, then IPv6, then a general discovered address if neither is available. It also states that the value is blank when Tools is not running or the VM is powered off. A28-S1
This makes Tools state and reporting part of the explanation. It does not justify upgrading Tools blindly or replacing the VM. First establish whether metadata was absent, delayed, excluded or unsuitable for the chosen waiter.
Disabling a waiter changes what Terraform waits to establish. It does not repair the network. The documentation warns that disabling the network wait can leave addresses unavailable to provisioners, so a faster apparent completion can simply move the failure downstream.
Acceptance and reversal limits
A completed diagnosis names the provider version, active waiter, timeout, exclusions and the missing or rejected network evidence. It distinguishes the time of the failed run from later observations.
For a future approved configuration change, acceptance must include both the intended waiter result and separately defined downstream readiness. An application check remains necessary where the deployment promises an application, rather than merely an address. No such check was executed here.
Inspection needs no rollback. Preserve the previous configuration for a later reviewed change and inspect its planned effects before applying anything. Do not destroy, recreate or import a VM merely because the network waiter timed out; the resource may already exist.
Learning notes
- A reported address and a satisfied network waiter are different facts.
- Exclusions and gateway metadata can explain a timeout without a missing VM.
- Removing a readiness gate does not create readiness.