kubernetes/kops · error

must configure at least one InstanceGroup

Error message

must configure at least one InstanceGroup

What it means

DeepValidate enforces that a cluster configuration includes at least one InstanceGroup before validating groups individually. kOps clusters cannot run without instance groups since they define the machines running Kubernetes. This error is returned immediately after cluster spec validation passes but the group list is empty.

Source

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

	if said.EnableAWSOIDCProvider {
		enableOIDCField := fieldSpec.Child("serviceAccountIssuerDiscovery", "enableAWSOIDCProvider")
		if discoveryStore == "" && discoveryService == nil {
			allErrs = append(allErrs, field.Forbidden(enableOIDCField, "AWS OIDC Provider requires a discoveryStore or discoveryService to be set"))
		}
	}

	return allErrs
}

// DeepValidate is responsible for validating the instancegroups within the cluster spec
func DeepValidate(c *kops.Cluster, groups []*kops.InstanceGroup, strict bool, vfsContext *vfs.VFSContext, cloud fi.Cloud) error {
	if errs := ValidateCluster(c, strict, vfsContext); len(errs) != 0 {
		return errs.ToAggregate()
	}

	if len(groups) == 0 {
		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")

View on GitHub (pinned to 4c8573c808)

Solutions

1. Add InstanceGroup manifests to the cluster YAML or run kops create ig to define control-plane and node groups
2. Use 'kops create cluster ...' without suppressing instance-group generation so defaults are created
3. When using -f, include both Cluster and InstanceGroup documents in the file (or apply them all together)
4. In code, ensure the groups slice passed to DeepValidate is populated from the parsed manifests

Example fix

// before (cluster.yaml)
apiVersion: kops.k8s.io/v1alpha2
kind: Cluster
metadata:
  name: mycluster.example.com
# no InstanceGroup documents
// after
apiVersion: kops.k8s.io/v1alpha2
kind: InstanceGroup
metadata:
  name: control-plane-us-east-1a
  cluster: mycluster.example.com
spec:
  role: ControlPlane
  machineType: m5.large
  minSize: 1
  maxSize: 1

groups, err := configstore.ReadInstanceGroups(vfs.Context, path)
if err != nil { return err }
if len(groups) == 0 {
    return errors.New("no InstanceGroups found; run 'kops create ig' or include InstanceGroup docs in your manifest")
}
if err := validation.DeepValidate(cluster, groups, true, vfs.Context, cloud); err != nil { return err }

func hasInstanceGroups(groups []*kops.InstanceGroup) bool {
    return len(groups) > 0
}

if err := validation.DeepValidate(cluster, groups, strict, vfsContext, cloud); err != nil {
    if strings.Contains(err.Error(), "at least one InstanceGroup") {
        return fmt.Errorf("cluster %s has no instance groups; add control-plane and node groups before updating", cluster.Name)
    }
    return err
}

When it happens

Trigger: kops create cluster / kops update cluster / kops create -f cluster.yaml invoked with a Cluster manifest that has zero InstanceGroups, or programmatic use of DeepValidate with an empty groups slice.

Common situations: Creating a cluster from a YAML manifest containing only the Cluster object without InstanceGroup documents; a partial file split losing InstanceGroup definitions; CLI flag omission that skips default group creation; API-driven provisioning that forgot to append groups.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• InstanceGroup #%d did not have a Name
• duplicate InstanceGroup Name found: %q
• must configure at least one ControlPlane InstanceGroup
• error building node labels: %w
• invalid InstanceGroup name: %v

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