etcd nodes requires the ExperimentalRoles feature flag to be

Error message

etcd nodes requires the ExperimentalRoles feature flag to be enabled

What it means

Experimental split roles (dedicated etcd instance groups) are gated behind the ExperimentalRoles feature flag. NewCluster rejects any instance group whose role includes etcd when the flag is disabled.

Source

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

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

		}

		if ig.Spec.Tenancy != "" && ig.Spec.Tenancy != "default" {
			switch cluster.GetCloudProvider() {
			case api.CloudProviderAWS:

View on GitHub (pinned to 4c8573c808)

Solutions

Enable the flag: `export KOPS_FEATURE_FLAGS=ExperimentalRoles` and retry.
Upgrade kops if a newer release graduated the desired role layout out of experimental.
Remove the dedicated etcd instance group and let control-plane groups host etcd (the default).

Example fix

// before
kops create cluster --name=example.com   # dedicated etcd IG, flag unset
// after
export KOPS_FEATURE_FLAGS=ExperimentalRoles
kops create cluster --name=example.com

Defensive patterns

Strategy: validation

Validate before calling

if hasRole(igGroups, "etcd") && !strings.Contains(os.Getenv("KOPS_FEATURE_FLAGS"), "ExperimentalRoles") {
    return errors.New("ExperimentalRoles flag required for dedicated etcd IGs")
}

Try / catch

_, err := NewCluster(opt, cluster, zoneMap)
if err != nil {
    if strings.Contains(err.Error(), "ExperimentalRoles feature flag") {
        return fmt.Errorf("enable KOPS_FEATURE_FLAGS=ExperimentalRoles or drop the dedicated etcd IG: %w", err)
    }
    return err
}

Prevention

Keep feature-flag exports in provisioning scripts/env manifests
Prefer standard control-plane etcd unless you truly need the split
Document flag requirements in cluster spec repos

When it happens

Trigger: Defining an instance group with an etcd-bearing role (e.g. role Master or a dedicated etcd group) without `KOPS_FEATURE_FLAGS=ExperimentalRoles`, during `kops create cluster`.

Common situations: Operators attempting external/etcd-only nodes for large clusters; tutorials requiring the flag that readers skipped; CI env missing the feature-flag export.

Related errors

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