kubernetes/kops · error

getting primary MAC address from ec2 metadata: %w

Error message

getting primary MAC address from ec2 metadata: %w

What it means

Thrown when the IMDS GetMetadata call for the 'mac' item fails. nodeup queries EC2 instance metadata for the primary ENI's MAC address (device-index 0); any IMDS failure — unreachable endpoint, throttling, IMDSv2 token issues, hop-limit, or the key missing — surfaces here.

Source

Thrown at nodeup/pkg/model/networking/eni_networking.go:196

		Type:            nodetasks.FileType_File,
		AfterPackages:   true,
		OnChangeExecute: [][]string{{"systemctl", "restart", "systemd-networkd"}},
	})
	return nil
}

// primaryInterfaceName gives the name of the primary network interface. It gets the MAC address
// of the primary ENI (device-number 0) from the IMDS item "mac". Then it compares this MAC
// address with the physical network interfaces in sysfs.
func primaryInterfaceName(ctx context.Context) (string, error) {
	config, err := awsconfig.LoadDefaultConfig(ctx)
	if err != nil {
		return "", fmt.Errorf("loading AWS config: %w", err)
	}
	metadata := imds.NewFromConfig(config)
	resp, err := metadata.GetMetadata(ctx, &imds.GetMetadataInput{Path: "mac"})
	if err != nil {
		return "", fmt.Errorf("getting primary MAC address from ec2 metadata: %w", err)
	}
	defer resp.Content.Close()
	mac, err := io.ReadAll(resp.Content)
	if err != nil {
		return "", fmt.Errorf("reading primary MAC address from ec2 metadata: %w", err)
	}

	return findPhysicalInterfaceByMAC("/sys/class/net", strings.TrimSpace(string(mac)))
}

// findPhysicalInterfaceByMAC gives the name of the physical network interface that has the
// specified MAC address. The function ignores the virtual interfaces (veths, bridges, VLANs),
// because a virtual interface can have the same MAC address as a physical interface. The
// function gives an error if it does not find exactly one physical interface with this MAC
// address.
func findPhysicalInterfaceByMAC(sysClassNet string, mac string) (string, error) {
	entries, err := os.ReadDir(sysClassNet)
	if err != nil {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Verify IMDS reachability: curl -H 'X-aws-ec2-metadata-token: <token>' -v http://169.254.169.254/latest/meta-data/mac
2. Check EC2 instance metadata options: IMDS must be enabled (not 'Disabled') and hop limit >= 2 if running nodeup in a container
3. Confirm no host firewall/NAT rules block traffic to 169.254.169.254
4. Retry after transient failure — re-run nodeup; IMDS throttling/5xx is typically temporary

Example fix

// before: IMDS disabled
aws ec2 modify-instance-metadata-options --instance-id i-... --http-endpoint disabled
// after
aws ec2 modify-instance-metadata-options --instance-id i-... --http-endpoint enabled --http-put-response-hop-limit 2

token := curl PUT http://169.254.169.254/latest/api/token  # verify IMDS reachable before nodeup
// in Go: probe imds.GetMetadata(ctx, &imds.GetMetadataInput{Path: "instance-id"}) first

var resp *imds.GetMetadataOutput
err := retry.Do(func() error {
    r, err := metadata.GetMetadata(ctx, &imds.GetMetadataInput{Path: "mac"})
    resp = r
    return err
}, retry.Attempts(3), retry.Delay(time.Second))

When it happens

Trigger: imds.NewFromConfig(config).GetMetadata(ctx, &imds.GetMetadataInput{Path: "mac"}) returns an error: metadata endpoint unreachable (169.254.169.254), IMDS disabled via instance metadata options (http-tokens required but token fetch fails, or metadata disabled), hop limit too low inside containers, or transient 5xx/throttle.

Common situations: Instance launched with MetadataOptions HttpTokens=required but IMDSv2 token acquisition broken; IMDS put-response hop-limit 1 while nodeup runs in a container (need 2); firewall/iptables blocking link-local 169.254.169.254; bare-metal/non-EC2 environment without IMDS.

Related errors

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

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