kubernetes/kops · error

instance %s was launched with a resource-based hostname; use

Error message

instance %s was launched with a resource-based hostname; useIPBasedNodeNames requires subnets that assign IP-based hostnames

What it means

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.

Source

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

		if !useIPBasedNodeNames {
			return instanceID, nil
		}

		// 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)

View on GitHub (pinned to 4c8573c808)

Solutions

1. Change the subnet's hostname type: aws ec2 modify-subnet-attribute --subnet-id subnet-xxx --private-dns-hostname-type ip-name.
2. Alternatively disable useIPBasedNodeNames in the kops cluster spec so instance-id-based node names are used.
3. Recreate/replace instances in that subnet after fixing the subnet attribute (existing instances keep their resource-based name).
4. Verify with: curl http://169.254.169.254/latest/meta-data/local-hostname — it must not start with 'i-'.

Example fix

// before
aws ec2 modify-subnet-attribute --subnet-id subnet-1 --private-dns-hostname-type resource-name
// after
aws ec2 modify-subnet-attribute --subnet-id subnet-1 --private-dns-hostname-type ip-name

IID=$(curl -sf http://169.254.169.254/latest/meta-data/instance-id)
H=$(curl -sf http://169.254.169.254/latest/meta-data/local-hostname)
case "$H" in "$IID"*) echo 'resource-based hostname: useIPBasedNodeNames will fail';; *) echo OK;; esac

func hasResourceBasedHostname(instanceID, localHostname string) bool {
    return strings.HasPrefix(localHostname, instanceID)
}
// call before enabling useIPBasedNodeNames:
// if hasResourceBasedHostname(iid, hostname) { fix subnet attribute first }

override, err := evaluateHostnameOverride(api.CloudProviderAWS, true, region)
if err != nil && strings.Contains(err.Error(), "resource-based hostname") {
    return fmt.Errorf("fix subnet private-dns-hostname-type to ip-name or disable useIPBasedNodeNames: %w", err)
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• DeviceName not set for volume
• error populating configuration: %v
• error initializing AWS client: %v
• error populating configuration: %w
• error initializing AWS client: %v

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