scheduler nodes requires the ExperimentalRoles feature flag

Error message

scheduler nodes requires the ExperimentalRoles feature flag to be enabled

What it means

Dedicated scheduler node groups are part of the experimental role split and are rejected unless the ExperimentalRoles feature flag is enabled. The check occurs while validating instance-group roles in NewCluster.

Source

Thrown at upup/pkg/fi/cloudup/new_cluster.go:548

			}
		} else if g.Spec.Role.HasBastion() {
			if g.Spec.MachineType == "" {
				g.Spec.MachineType, err = defaultMachineType(cloud, cluster, g)
				if err != nil {
					return nil, fmt.Errorf("error assigning default machine type for bastions: %v", err)
				}
			}
		} else {
			if g.IsAPIServerOnly() && !featureflag.APIServerNodes.Enabled() {
				return nil, fmt.Errorf("apiserver nodes requires the APIServerNodes feature flag to be enabled")
			}
			if !featureflag.ExperimentalRoles.Enabled() {
				switch {
				case g.Spec.Role.HasEtcd():
					return nil, fmt.Errorf("etcd nodes requires the ExperimentalRoles feature flag to be enabled")
				case g.Spec.Role.HasScheduler():
					return nil, fmt.Errorf("scheduler nodes requires the ExperimentalRoles feature flag to be enabled")
				case g.Spec.Role.HasKubeControllerManager():
					return nil, fmt.Errorf("kube-controller-manager nodes requires the ExperimentalRoles feature flag to be enabled")
				}
			}
			if g.Spec.MachineType == "" {
				g.Spec.MachineType, err = defaultMachineType(cloud, cluster, g)
				if err != nil {
					return nil, fmt.Errorf("error assigning default machine type for nodes: %v", err)
				}
			}

		}

		if ig.Spec.Tenancy != "" && ig.Spec.Tenancy != "default" {
			switch cluster.GetCloudProvider() {
			case api.CloudProviderAWS:
				if _, ok := awsDedicatedInstanceExceptions[g.Spec.MachineType]; ok {
					return nil, fmt.Errorf("invalid dedicated instance type: %s", g.Spec.MachineType)

View on GitHub (pinned to 4c8573c808)

Solutions

Enable the flag: `export KOPS_FEATURE_FLAGS=ExperimentalRoles`.
Merge the scheduler role back into a standard control-plane instance group.
Upgrade kops if the role split is supported natively in newer versions.

Example fix

// before
export KOPS_FEATURE_FLAGS=""
kops create cluster --name=example.com   # scheduler-only IG
// after
export KOPS_FEATURE_FLAGS=ExperimentalRoles
kops create cluster --name=example.com

Defensive patterns

Strategy: validation

Validate before calling

if hasRole(igGroups, "scheduler") && !featureFlagEnabled("ExperimentalRoles") {
    return errors.New("ExperimentalRoles flag required for dedicated scheduler IGs")
}

Try / catch

_, err := NewCluster(opt, cluster, zoneMap)
if err != nil {
    if strings.Contains(err.Error(), "scheduler nodes requires") {
        return fmt.Errorf("enable ExperimentalRoles or merge scheduler role into control-plane IG: %w", err)
    }
    return err
}

Prevention

Audit IG role specs against enabled feature flags before create
Set KOPS_FEATURE_FLAGS consistently across environments
Pin cluster templates to supported, non-experimental topologies

When it happens

Trigger: An instance group whose role includes the scheduler component is present at `kops create cluster` time without ExperimentalRoles enabled.

Common situations: Custom cluster specs splitting control-plane components onto separate machines; inherited specs from teams that ran with the flag; flag lost when moving between environments/CI.

Related errors

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