Troubleshoot VM Metadata Service Connectivity Failures

Problem

A Virtual Machine (VM) cannot reach the OpenStack metadata service at boot, so cloud-init cannot fetch its configuration (SSH keys, hostname, network config, and so on). The VM falls back to a default configuration instead. Symptoms include:

• The VM's cloud-init-output.log shows repeated warnings such as:

  url_helper.py[WARNING]: Exception(s) [UrlError("HTTPConnectionPool(host='169.254.169.254', port=80): Max retries exceeded ...")] during request to http://169.254.169.254/openstack, raising last exception
  util.py[WARNING]: No active metadata service found

• Manually curling the metadata endpoint from inside the VM fails:

  $ curl http://169.254.169.254/openstack
  curl: (7) Failed to connect to 169.254.169.254 port 80 after 3087 ms: Couldn't connect to server

• cloud-init eventually reports Used fallback datasource and generates new SSH host keys instead of applying the expected configuration.

Environment

• Private Cloud Director Virtualization - All Versions
• Self-Hosted Private Cloud Director Virtualization - All Versions
• Component - Networking Service

Prerequisites: Executing OVN Commands

Refer to the existing guide for SaaS Alias setup or Self-Hosted kubectl exec instructions to run ovn-nbctl commands.

Procedure

1. Confirm the Network and Compute Node

# 1. Get the network ID of the affected VM's port
$ openstack port show <VM_PORT_ID> -c network_id -f value

# 2. Confirm which compute node the VM is running on
$ openstack server show <VM_ID> -c "OS-EXT-SRV-ATTR:host" -f value

2. Check Whether the Metadata Namespace Exists

Log into the compute node identified above and check for the network's metadata namespace.

$ ip netns list | grep ovnmeta-<NETWORK_ID>
# No output means the namespace was never created for this network.

• Success: The namespace is listed. The issue described in this guide is not the cause; continue with general connectivity troubleshooting.
• Failure: No output. The neutron-ovn-metadata-agent never created the namespace for this network, which matches the symptom in this guide.

3. Identify the Network's Metadata Port

Every network has one dedicated metadata port, distinct from the VM and router ports on the same network.

$ openstack port list --network <NETWORK_ID> --device-owner network:distributed -c ID -f value
# Returns exactly one port ID: the network's metadata port.

4. Check the Metadata Port's OVN Type

$ ovn-nbctl lsp-get-type <METADATA_PORT_ID>
localport

• Expected: localport.
• Failure: The command returns nothing (an empty type). This is the root cause: without type=localport, neutron-ovn-metadata-agent does not create the ovnmeta-<NETWORK_ID> namespace, so no VM on that network can reach 169.254.169.254.

5. Restore the Port Type

$ ovn-nbctl lsp-set-type <METADATA_PORT_ID> localport
# No output on success.

neutron-ovn-metadata-agent creates the ovnmeta-<NETWORK_ID> namespace within a few seconds of this change, and metadata access is restored for all VMs on the network without a restart.

6. Recover Cloud-Init on Affected VMs

If a VM already fell back to a default configuration during boot (visible as Used fallback datasource in its cloud-init-output.log), reboot the VM once metadata access is restored so cloud-init can retry against the metadata service. Rebooting alone is sufficient; the VM does not need to be recreated.

If these steps prove insufficient to resolve the issue, reach out to the Platform9 Support Team for additional assistance. Because the trigger for the port type change is still being investigated, include the network ID and approximate time of occurrence when you contact Support so the case can be tracked.

Most Common Causes

• The network's OVN metadata logical switch port has its type unexpectedly reset from localport to empty, which stops neutron-ovn-metadata-agent from creating the network's metadata namespace. This has been observed rarely, and the exact trigger is not yet fully understood.