{"record":{"id":"14f9f1647d4e30e2","repo":"kubernetes/kops","slug":"instance-s-was-launched-with-a-resource-based-hos","errorCode":null,"errorMessage":"instance %s was launched with a resource-based hostname; useIPBasedNodeNames requires subnets that assign IP-based hostnames","messagePattern":"instance (.+?) was launched with a resource-based hostname; useIPBasedNodeNames requires subnets that assign IP-based hostnames","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upup/pkg/fi/nodeup/command.go","lineNumber":506,"sourceCode":"\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)\n\t\tb, err := vfs.Context.ReadFile(\"metadata://gce/instance/hostname\")\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"error reading hostname from GCE metadata: %v\", err)","sourceCodeStart":488,"sourceCodeEnd":524,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/upup/pkg/fi/nodeup/command.go#L488-L524","documentation":"Not an AWS failure — nodeup deliberately refuses to start: with useIPBasedNodeNames, the local-hostname must be IP/DHCP-based, but it starts with the instance ID (i-...), which indicates a resource-based hostname. Such a name survives stop/start, so an IP-based node name would never match the EC2 hostname; nodeup fails fast to prevent joining a misconfigured instance.","triggerScenarios":"useIPBasedNodeNames=true AND the local-hostname metadata value has prefix equal to the instance's instance-id (e.g. hostname 'i-0abc123...' because the subnet/DHCP set uses-resource-based hostnames).","commonSituations":"Subnets with 'Resource-based DNS hostname' set (or AMI/launch-template hostname options set to resource-name) combined with useIPBasedNodeNames in the cluster spec; clusters migrated to IP-based naming without updating subnet hostname options.","solutions":["Change the subnet's hostname type: aws ec2 modify-subnet-attribute --subnet-id subnet-xxx --private-dns-hostname-type ip-name.","Alternatively disable useIPBasedNodeNames in the kops cluster spec so instance-id-based node names are used.","Recreate/replace instances in that subnet after fixing the subnet attribute (existing instances keep their resource-based name).","Verify with: curl http://169.254.169.254/latest/meta-data/local-hostname — it must not start with 'i-'."],"exampleFix":"// before\naws ec2 modify-subnet-attribute --subnet-id subnet-1 --private-dns-hostname-type resource-name\n// after\naws ec2 modify-subnet-attribute --subnet-id subnet-1 --private-dns-hostname-type ip-name","handlingStrategy":"validation","validationCode":"IID=$(curl -sf http://169.254.169.254/latest/meta-data/instance-id)\nH=$(curl -sf http://169.254.169.254/latest/meta-data/local-hostname)\ncase \"$H\" in \"$IID\"*) echo 'resource-based hostname: useIPBasedNodeNames will fail';; *) echo OK;; esac","typeGuard":"func hasResourceBasedHostname(instanceID, localHostname string) bool {\n    return strings.HasPrefix(localHostname, instanceID)\n}\n// call before enabling useIPBasedNodeNames:\n// if hasResourceBasedHostname(iid, hostname) { fix subnet attribute first }","tryCatchPattern":"override, err := evaluateHostnameOverride(api.CloudProviderAWS, true, region)\nif err != nil && strings.Contains(err.Error(), \"resource-based hostname\") {\n    return fmt.Errorf(\"fix subnet private-dns-hostname-type to ip-name or disable useIPBasedNodeNames: %w\", err)\n}","preventionTips":["Set subnet attribute --private-dns-hostname-type ip-name before enabling useIPBasedNodeNames.","Check the launch template/AMI doesn't override hostname options to resource-based naming.","Replace existing instances after changing subnet attributes (names persist on old instances).","Verify with IMDS local-hostname that it does not start with 'i-'."],"tags":["aws","hostname","configuration","nodeup"],"backgroundTag":"resource-based-hostname-conflict","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"}