kubernetes/kops · error

invalid InstanceGroup name: %v

Error message

invalid InstanceGroup name: %v

What it means

When the verified identity provides an InstanceGroup name, getNodeConfig validates it with kopsvalidation.ValidateInstanceGroupName before using it in configBase paths. If the name violates kops InstanceGroup naming rules (e.g. invalid DNS-label characters, wrong length), the request is rejected with the aggregated validation errors. CAPI-synthesized names skip this validation intentionally, since they never reach configBase paths.

Source

Thrown at cmd/kops-controller/pkg/server/node_config.go:51

func (s *Server) getNodeConfig(ctx context.Context, req *nodeup.BootstrapRequest, identity *bootstrap.VerifyResult) (*nodeup.NodeConfig, error) {
	log := klog.FromContext(ctx)

	if identity == nil {
		return nil, fmt.Errorf("node identity is required")
	}

	log.Info("getting node config", "req", req, "identity", identity)

	instanceGroupName := identity.InstanceGroupName
	if instanceGroupName == "" {
		if identity.CAPIMachine == nil {
			return nil, fmt.Errorf("did not find owner for node %q", identity.NodeName)
		}
		// CAPI path: the InstanceGroup is synthesized from the Machine and
		// the name never reaches the configBase path, so we don't validate it.
	} else if errs := kopsvalidation.ValidateInstanceGroupName(instanceGroupName, field.NewPath("instanceGroupName")); len(errs) > 0 {
		return nil, fmt.Errorf("invalid InstanceGroup name: %v", errs.ToAggregate())
	}

	var nodeConfig *nodeup.NodeConfig

	configBuilder := &commands.ConfigBuilder{
		Clientset:   s.clientset,
		ClusterName: s.opt.ClusterName,
	}

	if identity.CAPIMachine != nil && instanceGroupName == "" {
		// We have a CAPI Machine (but no instance group)
		instanceGroup, err := s.buildInstanceGroupFromCAPI(ctx, identity.CAPIMachine)
		if err != nil {
			return nil, fmt.Errorf("error building InstanceGroup from CAPI Machine: %w", err)
		}
		log.Info("built InstanceGroup from CAPI Machine", "instanceGroup", instanceGroup)
		configBuilder.InstanceGroup = instanceGroup
	} else if s.opt.Cloud == "metal" {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Rename the InstanceGroup to a valid DNS label: lowercase letters, numbers, and hyphens only, max 63 chars, no leading/trailing hyphen (e.g. via `kops replace` + `kops update cluster --yes`)
2. Fix the cloud tag or machine metadata that carries the bad InstanceGroup name so nodes report the corrected name
3. Check `kops get ig -oyaml` and your cluster spec for manually edited names that fail validation
4. If the name comes from CAPI, verify the CAPI path is active (identity.CAPIMachine set) so the name is synthesized instead of validated

Example fix

// before
kind: InstanceGroup
metadata:
  name: Workers_EU1
// after
kind: InstanceGroup
metadata:
  name: workers-eu1

if errs := kopsvalidation.ValidateInstanceGroupName(name, field.NewPath("instanceGroupName")); len(errs) > 0 {
	return errs.ToAggregate()
}

func validIGName(name string) bool {
	return len(name) <= 63 && regexp.MustCompile(`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`).MatchString(name)
}

if strings.Contains(err.Error(), "invalid InstanceGroup name") {
	// fix the IG name in the cluster spec and re-run kops update
}

When it happens

Trigger: identity.InstanceGroupName is non-empty but fails ValidateInstanceGroupName — typically a name containing characters other than lowercase alphanumeric and '-', starting/ending with '-', or exceeding DNS label length limits.

Common situations: Creating an InstanceGroup with an uppercase or underscore name (older kops versions or manual YAML edits); renaming instance groups in cloud tags so a non-conforming name is propagated to nodes; copying an IG name with a trailing space or domain suffix.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• did not find owner for node %q
• error building InstanceGroup from CAPI Machine: %w
• unexpected error creating validatior: %v
• cluster not yet healthy
• must configure at least one Node InstanceGroup

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