kubernetes/kops · error

resolving root device for %q: %w

Error message

resolving root device for %q: %w

What it means

Returned by buildKarpenterEC2NodeClass when tf.karpenterRootDeviceName(ig.Spec.Image) cannot determine the root device name for the instance group's image (e.g. an unknown distro/AMI). EC2NodeClass requires blockDeviceMappings anchored to the correct root device name, so failure aborts rendering.

Source

Thrown at upup/pkg/fi/cloudup/template_functions_karpenter.go:240

		return nil, fmt.Errorf("building instance profile for %q: %w", ig.Name, err)
	}

	tags, err := tf.CloudTagsForInstanceGroup(ig)
	if err != nil {
		return nil, fmt.Errorf("building tags for %q: %w", ig.Name, err)
	}
	tags = karpenterEC2NodeClassTags(tags)
	associatePublicIP, err := tf.karpenterAssociatePublicIP(ig)
	if err != nil {
		return nil, err
	}
	userData, err := tf.managedFileContents("nodeupscript-" + ig.Name)
	if err != nil {
		return nil, fmt.Errorf("reading userData for %q: %w", ig.Name, err)
	}
	rootDeviceName, err := tf.karpenterRootDeviceName(ig.Spec.Image)
	if err != nil {
		return nil, fmt.Errorf("resolving root device for %q: %w", ig.Name, err)
	}
	blockDeviceMappings, err := buildKarpenterBlockDeviceMappings(ig, rootDeviceName)
	if err != nil {
		return nil, fmt.Errorf("building blockDeviceMappings for %q: %w", ig.Name, err)
	}

	subnetTerms := []karpenterSelectorTerm{
		{
			Tags: map[string]string{
				"KubernetesCluster":                     tf.ClusterName(),
				"kops.k8s.io/instance-group/" + ig.Name: "true",
			},
		},
	}

	securityGroupTerms := []karpenterSelectorTerm{}
	if ig.Spec.SecurityGroupOverride != nil {
		securityGroupTerms = append(securityGroupTerms, karpenterSelectorTerm{ID: fi.ValueOf(ig.Spec.SecurityGroupOverride)})

View on GitHub (pinned to 4c8573c808)

Solutions

1. Use a supported image (known alias or AMI from a supported distro) for the instance group
2. Check the wrapped error from karpenterRootDeviceName to see the unmapped image
3. Extend the root-device mapping table if a new distro must be supported
4. Pin the image to an AMI based on a supported base

Example fix

// before
image: custom-linux-v3
// after
image: ubuntu22.04  # supported alias with known root device (/dev/sda1)

// verify the image maps to a known root device before rendering
if _, err := tf.karpenterRootDeviceName(ig.Spec.Image); err != nil {
	return fmt.Errorf("image %q on %q has no known root device", ig.Spec.Image, ig.Name)
}

nc, err := tf.KarpenterEC2NodeClass(ig)
if err != nil {
	return fmt.Errorf("root device resolution for %q failed: %w", ig.Name, err)
}

When it happens

Trigger: ig.Spec.Image resolves to a distro or AMI that karpenterRootDeviceName has no mapping for — unsupported OS, unknown AMI ID, or alias not in the lookup table.

Common situations: Using an OS variant (e.g. an unusual flatcar/debian image) whose root device name is not hardcoded; custom AMIs built from unsupported bases; kops upgrade where image aliases changed.

Related errors

• building amiSelectorTerms for %q: %w
• marshaling Karpenter resource for %q: %w
• building instance profile for %q: %w
• building tags for %q: %w
• reading userData for %q: %w

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