{"record":{"id":"470c6b1366ed8cbe","repo":"kubernetes/kops","slug":"error-reading-local-hostname-from-aws-metadata-v","errorCode":null,"errorMessage":"error reading local-hostname from AWS metadata: %v","messagePattern":"error reading local-hostname from AWS metadata: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upup/pkg/fi/nodeup/command.go","lineNumber":503,"sourceCode":"\t\t\treturn \"\", fmt.Errorf(\"error reading instance-id from AWS metadata: %v\", err)\n\t\t}\n\t\tinstanceID := string(instanceIDBytes)\n\n\t\tif !useIPBasedNodeNames {\n\t\t\treturn instanceID, nil\n\t\t}\n\n\t\t// The node name is the DNS name that EC2 generates for IP-named instances, built from the\n\t\t// primary private IPv4 address. kops-controller derives it with the same formula when\n\t\t// issuing certificates, so the two always agree. IMDS local-hostname is not usable for\n\t\t// this: with a custom DHCP domain it differs from the generated name.\n\t\t//\n\t\t// An instance launched with a resource-based hostname keeps a resource-based name (it can\n\t\t// only change while the instance is stopped), so an IP-based node name would not match its\n\t\t// EC2 hostname; fail rather than join a misconfigured instance.\n\t\thostnameBytes, err := vfs.Context.ReadFile(\"metadata://aws/meta-data/local-hostname\")\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"error reading local-hostname from AWS metadata: %v\", err)\n\t\t}\n\t\tif strings.HasPrefix(string(hostnameBytes), instanceID) {\n\t\t\treturn \"\", fmt.Errorf(\"instance %s was launched with a resource-based hostname; useIPBasedNodeNames requires subnets that assign IP-based hostnames\", instanceID)\n\t\t}\n\n\t\tlocalIPv4Bytes, err := vfs.Context.ReadFile(\"metadata://aws/meta-data/local-ipv4\")\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"error reading local-ipv4 from AWS metadata: %v\", err)\n\t\t}\n\t\tlocalIPv4 := string(localIPv4Bytes)\n\t\tif net.ParseIP(localIPv4).To4() == nil {\n\t\t\treturn \"\", fmt.Errorf(\"local-ipv4 from AWS metadata is not a valid IPv4 address: %q\", localIPv4)\n\t\t}\n\n\t\treturn awsbootstrap.PrivateDNSName(localIPv4, region), nil\n\n\tcase api.CloudProviderGCE:\n\t\t// This lets us tolerate broken hostnames (i.e. systemd)","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/upup/pkg/fi/nodeup/command.go#L485-L521","documentation":"When useIPBasedNodeNames is enabled on AWS, nodeup reads 'metadata://aws/meta-data/local-hostname' to verify the instance has an IP-based (DHCP-set) hostname. A read failure is wrapped with this message, since nodeup cannot decide whether the node name would be valid.","triggerScenarios":"vfs.Context.ReadFile(\"metadata://aws/meta-data/local-hostname\") errors while evaluateHostnameOverride runs with useIPBasedNodeNames=true: IMDS unreachable, metadata endpoint disabled, or hop-limit/token issues for IMDSv2.","commonSituations":"Cluster spec sets useIPBasedNodeNames but the node's metadata access is broken (network policy blocking link-local); nodeup running in a containerized context with hop limit 1; instance launched with metadata HttpEndpoint disabled.","solutions":["Restore IMDS connectivity (test with curl against /latest/meta-data/local-hostname).","Re-enable the metadata endpoint if disabled: aws ec2 modify-instance-metadata-options --http-endpoint enabled.","Set hop limit >=2 for containerized nodeup.","If IP-based names are not required, disable useIPBasedNodeNames in the cluster spec."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"H=$(curl -sf http://169.254.169.254/latest/meta-data/local-hostname) || { echo 'local-hostname metadata unavailable'; exit 1; }\necho \"local-hostname=$H\"","typeGuard":null,"tryCatchPattern":"override, err := evaluateHostnameOverride(provider, true /*useIPBasedNodeNames*/, region)\nif err != nil && strings.Contains(err.Error(), \"error reading local-hostname\") {\n    return fmt.Errorf(\"useIPBasedNodeNames requires readable local-hostname metadata: %w\", err)\n}","preventionTips":["Validate metadata reachability before enabling useIPBasedNodeNames.","Keep the metadata endpoint enabled and hop-limit >=2.","Test node naming on one instance before rolling the setting cluster-wide.","Fall back to instance-id node names if IP-based naming is not a hard requirement."],"tags":["aws","imds","metadata","dns"],"backgroundTag":"imds-unreachable","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T07:17:12.445Z"}