{"record":{"id":"fa34291935e9d390","repo":"kubernetes/kops","slug":"resolving-root-device-for-q-w","errorCode":null,"errorMessage":"resolving root device for %q: %w","messagePattern":"resolving root device for %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upup/pkg/fi/cloudup/template_functions_karpenter.go","lineNumber":240,"sourceCode":"\t\treturn nil, fmt.Errorf(\"building instance profile for %q: %w\", ig.Name, err)\n\t}\n\n\ttags, err := tf.CloudTagsForInstanceGroup(ig)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"building tags for %q: %w\", ig.Name, err)\n\t}\n\ttags = karpenterEC2NodeClassTags(tags)\n\tassociatePublicIP, err := tf.karpenterAssociatePublicIP(ig)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tuserData, err := tf.managedFileContents(\"nodeupscript-\" + ig.Name)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"reading userData for %q: %w\", ig.Name, err)\n\t}\n\trootDeviceName, err := tf.karpenterRootDeviceName(ig.Spec.Image)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"resolving root device for %q: %w\", ig.Name, err)\n\t}\n\tblockDeviceMappings, err := buildKarpenterBlockDeviceMappings(ig, rootDeviceName)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"building blockDeviceMappings for %q: %w\", ig.Name, err)\n\t}\n\n\tsubnetTerms := []karpenterSelectorTerm{\n\t\t{\n\t\t\tTags: map[string]string{\n\t\t\t\t\"KubernetesCluster\":                     tf.ClusterName(),\n\t\t\t\t\"kops.k8s.io/instance-group/\" + ig.Name: \"true\",\n\t\t\t},\n\t\t},\n\t}\n\n\tsecurityGroupTerms := []karpenterSelectorTerm{}\n\tif ig.Spec.SecurityGroupOverride != nil {\n\t\tsecurityGroupTerms = append(securityGroupTerms, karpenterSelectorTerm{ID: fi.ValueOf(ig.Spec.SecurityGroupOverride)})","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/upup/pkg/fi/cloudup/template_functions_karpenter.go#L222-L258","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a supported image (known alias or AMI from a supported distro) for the instance group","Check the wrapped error from karpenterRootDeviceName to see the unmapped image","Extend the root-device mapping table if a new distro must be supported","Pin the image to an AMI based on a supported base"],"exampleFix":"// before\nimage: custom-linux-v3\n// after\nimage: ubuntu22.04  # supported alias with known root device (/dev/sda1)","handlingStrategy":"validation","validationCode":"// verify the image maps to a known root device before rendering\nif _, err := tf.karpenterRootDeviceName(ig.Spec.Image); err != nil {\n\treturn fmt.Errorf(\"image %q on %q has no known root device\", ig.Spec.Image, ig.Name)\n}","typeGuard":null,"tryCatchPattern":"nc, err := tf.KarpenterEC2NodeClass(ig)\nif err != nil {\n\treturn fmt.Errorf(\"root device resolution for %q failed: %w\", ig.Name, err)\n}","preventionTips":["Restrict Karpenter instance groups to distros with known root device mappings","Extend rootDeviceName mapping when adding new OS support","Pin images to supported bases when using custom AMIs","Test karpenterRootDeviceName across all supported image aliases"],"tags":["karpenter","root-device","ami","kops"],"backgroundTag":"unknown-root-device-name","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"}