kubernetes/kops · error

error reading local-ipv4 from AWS metadata: %v

Error message

error reading local-ipv4 from AWS metadata: %v

What it means

With useIPBasedNodeNames on AWS, nodeup reads 'metadata://aws/meta-data/local-ipv4' to build the IP-based node name. If the metadata read fails, it wraps the error with this message and aborts hostname evaluation.

Source

Thrown at upup/pkg/fi/nodeup/command.go:511

		// The node name is the DNS name that EC2 generates for IP-named instances, built from the
		// primary private IPv4 address. kops-controller derives it with the same formula when
		// issuing certificates, so the two always agree. IMDS local-hostname is not usable for
		// this: with a custom DHCP domain it differs from the generated name.
		//
		// An instance launched with a resource-based hostname keeps a resource-based name (it can
		// only change while the instance is stopped), so an IP-based node name would not match its
		// EC2 hostname; fail rather than join a misconfigured instance.
		hostnameBytes, err := vfs.Context.ReadFile("metadata://aws/meta-data/local-hostname")
		if err != nil {
			return "", fmt.Errorf("error reading local-hostname from AWS metadata: %v", err)
		}
		if strings.HasPrefix(string(hostnameBytes), instanceID) {
			return "", fmt.Errorf("instance %s was launched with a resource-based hostname; useIPBasedNodeNames requires subnets that assign IP-based hostnames", instanceID)
		}

		localIPv4Bytes, err := vfs.Context.ReadFile("metadata://aws/meta-data/local-ipv4")
		if err != nil {
			return "", fmt.Errorf("error reading local-ipv4 from AWS metadata: %v", err)
		}
		localIPv4 := string(localIPv4Bytes)
		if net.ParseIP(localIPv4).To4() == nil {
			return "", fmt.Errorf("local-ipv4 from AWS metadata is not a valid IPv4 address: %q", localIPv4)
		}

		return awsbootstrap.PrivateDNSName(localIPv4, region), nil

	case api.CloudProviderGCE:
		// This lets us tolerate broken hostnames (i.e. systemd)
		b, err := vfs.Context.ReadFile("metadata://gce/instance/hostname")
		if err != nil {
			return "", fmt.Errorf("error reading hostname from GCE metadata: %v", err)
		}

		// We only want to use the first portion of the fully-qualified name
		// e.g. foo.c.project.internal => foo
		fullyQualified := string(b)

View on GitHub (pinned to 4c8573c808)

Solutions

1. Retry nodeup — transient IMDS failures during boot are common.
2. Verify local-ipv4 is readable: curl http://169.254.169.254/latest/meta-data/local-ipv4.
3. Raise hop limit to >=2 and confirm metadata endpoint enabled if containerized.
4. Check for host-level firewalls (iptables/nftables) blocking 169.254.169.254.

curl -sf http://169.254.169.254/latest/meta-data/local-ipv4 | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$'

override, err := evaluateHostnameOverride(api.CloudProviderAWS, true, region)
if err != nil && strings.Contains(err.Error(), "error reading local-ipv4") {
    // transient IMDS failure: retry once before giving up
    time.Sleep(2 * time.Second)
    override, err = evaluateHostnameOverride(api.CloudProviderAWS, true, region)
}

When it happens

Trigger: vfs.Context.ReadFile("metadata://aws/meta-data/local-ipv4") errors after the local-hostname check passed: IMDS became unreachable, token expiry/network reset, or metadata endpoint disabled mid-run.

Common situations: Flaky IMDS access during boot (throttling when many metadata keys fetched concurrently); link-local blocked by host firewall; containerized nodeup with hop limit 1.

Related errors

• failed to load AWS config: %w
• failed to get local-ipv4 address from ec2 metadata: %w
• error reading from AWS metadata service: %v
• error querying ec2 metadata service (for region): %v
• getting primary MAC address from ec2 metadata: %w

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/4575fefdcb20474b. Report an issue: GitHub.