apiserver nodes requires the APIServerNodes feature flag to

Error message

apiserver nodes requires the APIServerNodes feature flag to be enabled

What it means

kops refuses to create dedicated API-server-only node groups unless the APIServerNodes feature flag is explicitly enabled. During instance-group validation in NewCluster, an APIServerOnly group encountered without the flag aborts creation.

Source

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

		// TODO: Clean up
		if g.IsControlPlane() {
			if g.Spec.MachineType == "" {
				g.Spec.MachineType, err = defaultMachineType(cloud, cluster, ig)
				if err != nil {
					return nil, fmt.Errorf("error assigning default machine type for control plane: %v", err)
				}

			}
		} 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)
				}
			}

View on GitHub (pinned to 4c8573c808)

Solutions

Enable the feature flag: `export KOPS_FEATURE_FLAGS=APIServerNodes` before running the command.
Upgrade kops to a release where dedicated API server nodes are GA (no flag needed).
If not intentionally using API-server-only nodes, set the instance group role to Node/Bastion instead.

Example fix

// before
kops create cluster --name=example.com   # IG role=APIServer, flag unset
// after
export KOPS_FEATURE_FLAGS=APIServerNodes
kops create cluster --name=example.com

Defensive patterns

Strategy: validation

Validate before calling

func preflight(role string) error {
    if role == "APIServer" && os.Getenv("KOPS_FEATURE_FLAGS") != "APIServerNodes" {
        return errors.New("APIServerNodes feature flag required for apiserver-only IGs")
    }
    return nil
}

Try / catch

_, err := NewCluster(opt, cluster, zoneMap)
if err != nil {
    if strings.Contains(err.Error(), "APIServerNodes feature flag") {
        os.Setenv("KOPS_FEATURE_FLAGS", "APIServerNodes")
        // retry once
    }
    return err
}

Prevention

Export KOPS_FEATURE_FLAGS in CI before kops commands
Check kops release notes for feature graduation
Use fallback: run the component on control-plane nodes instead

When it happens

Trigger: Adding an instance group with role APIServer or passing `--api-server-nodes` style configs without `export KOPS_FEATURE_FLAGS=APIServerNodes`, then running `kops create cluster`.

Common situations: Operators trying the dedicated API server nodes feature; CI pipelines where the feature flag env var is not exported; kops versions where APIServerNodes is not yet default-on.

Related errors

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