kubernetes/kops · error

must configure at least one Node InstanceGroup

Error message

must configure at least one Node InstanceGroup

What it means

DeepValidate in pkg/apis/kops/validation/legacy.go rejects a cluster spec whose InstanceGroups do not include at least one group with role Node. A kOps cluster must have worker (Node) InstanceGroups in addition to (or besides) control-plane groups so workloads can be scheduled. The count is computed from the groups passed in, after counting control-plane groups.

Source

Thrown at pkg/apis/kops/validation/legacy.go:295

		return fmt.Errorf("must configure at least one InstanceGroup")
	}

	controlPlaneGroupCount := 0
	nodeGroupCount := 0
	for _, g := range groups {
		if g.IsControlPlane() {
			controlPlaneGroupCount++
		} else {
			nodeGroupCount++
		}
	}

	if controlPlaneGroupCount == 0 {
		return fmt.Errorf("must configure at least one ControlPlane InstanceGroup")
	}

	if nodeGroupCount == 0 {
		return fmt.Errorf("must configure at least one Node InstanceGroup")
	}

	for _, g := range groups {
		errs := CrossValidateInstanceGroup(g, c, cloud, strict)

		// Additional cloud-specific validation rules
		if c.GetCloudProvider() != kops.CloudProviderAWS && len(g.Spec.Volumes) > 0 {
			errs = append(errs, field.Forbidden(field.NewPath("spec", "volumes"), "instancegroup volumes are only available with aws at present"))
		}

		if len(errs) != 0 {
			return errs.ToAggregate()
		}
	}

	return nil
}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Add a Node InstanceGroup (role: Node) to the cluster, e.g. `kops create instancegroup nodes --role Node` then `kops update cluster`.
2. If regenerating from scratch, re-run `kops create cluster` with --node-count/--node-size (defaults create a `nodes` group).
3. If you intentionally want no worker nodes, confirm your kOps version supports it via a different mechanism; otherwise keep at least one Node group.

Example fix

# before (instancegroups: only one, role ControlPlane)
# after
apiVersion: kops.k8s.io/v1alpha2
kind: InstanceGroup
metadata:
  name: nodes
spec:
  role: Node
  machineType: t3.medium
  minSize: 2
  maxSize: 4

nodeGroups := 0
for _, g := range groups {
    if g.Spec.Role == kops.InstanceGroupRoleNode {
        nodeGroups++
    }
}
if nodeGroups == 0 {
    return fmt.Errorf("cluster has no Node InstanceGroup; add one before validation")
}

When it happens

Trigger: Calling DeepValidate (directly or via `kops create cluster` / `kops update cluster` / `kops update --yes`) with a cluster whose InstanceGroup list contains zero groups whose Spec.Role is RoleNode — e.g. only control-plane groups, or the groups were filtered out before validation.

Common situations: Hand-editing the cluster spec and deleting all node groups; creating a cluster with only --control-plane-count and no --node-count/--node-size; a tooling script that removes node InstanceGroups when scaling to zero but forgets the cluster still needs one for validation.

Related errors

• invalid InstanceGroup name: %v
• unable to infer any Subnets for InstanceGroup %s
• did not find owner for node %q
• error building InstanceGroup from CAPI Machine: %w
• must specify %q label with cluster name to create instanceGr

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