{"record":{"id":"99e817d2b0c16927","repo":"kubernetes/kops","slug":"etcd-nodes-requires-the-experimentalroles-feature","errorCode":null,"errorMessage":"etcd nodes requires the ExperimentalRoles feature flag to be enabled","messagePattern":"etcd nodes requires the ExperimentalRoles feature flag to be enabled","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upup/pkg/fi/cloudup/new_cluster.go","lineNumber":546,"sourceCode":"\t\t\t\t\treturn nil, fmt.Errorf(\"error assigning default machine type for control plane: %v\", err)\n\t\t\t\t}\n\n\t\t\t}\n\t\t} else if g.Spec.Role.HasBastion() {\n\t\t\tif g.Spec.MachineType == \"\" {\n\t\t\t\tg.Spec.MachineType, err = defaultMachineType(cloud, cluster, g)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn nil, fmt.Errorf(\"error assigning default machine type for bastions: %v\", err)\n\t\t\t\t}\n\t\t\t}\n\t\t} else {\n\t\t\tif g.IsAPIServerOnly() && !featureflag.APIServerNodes.Enabled() {\n\t\t\t\treturn nil, fmt.Errorf(\"apiserver nodes requires the APIServerNodes feature flag to be enabled\")\n\t\t\t}\n\t\t\tif !featureflag.ExperimentalRoles.Enabled() {\n\t\t\t\tswitch {\n\t\t\t\tcase g.Spec.Role.HasEtcd():\n\t\t\t\t\treturn nil, fmt.Errorf(\"etcd nodes requires the ExperimentalRoles feature flag to be enabled\")\n\t\t\t\tcase g.Spec.Role.HasScheduler():\n\t\t\t\t\treturn nil, fmt.Errorf(\"scheduler nodes requires the ExperimentalRoles feature flag to be enabled\")\n\t\t\t\tcase g.Spec.Role.HasKubeControllerManager():\n\t\t\t\t\treturn nil, fmt.Errorf(\"kube-controller-manager nodes requires the ExperimentalRoles feature flag to be enabled\")\n\t\t\t\t}\n\t\t\t}\n\t\t\tif g.Spec.MachineType == \"\" {\n\t\t\t\tg.Spec.MachineType, err = defaultMachineType(cloud, cluster, g)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn nil, fmt.Errorf(\"error assigning default machine type for nodes: %v\", err)\n\t\t\t\t}\n\t\t\t}\n\n\t\t}\n\n\t\tif ig.Spec.Tenancy != \"\" && ig.Spec.Tenancy != \"default\" {\n\t\t\tswitch cluster.GetCloudProvider() {\n\t\t\tcase api.CloudProviderAWS:","sourceCodeStart":528,"sourceCodeEnd":564,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/upup/pkg/fi/cloudup/new_cluster.go#L528-L564","documentation":"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.","triggerScenarios":"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`.","commonSituations":"Operators attempting external/etcd-only nodes for large clusters; tutorials requiring the flag that readers skipped; CI env missing the feature-flag export.","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)."],"exampleFix":"// before\nkops create cluster --name=example.com   # dedicated etcd IG, flag unset\n// after\nexport KOPS_FEATURE_FLAGS=ExperimentalRoles\nkops create cluster --name=example.com","handlingStrategy":"validation","validationCode":"if hasRole(igGroups, \"etcd\") && !strings.Contains(os.Getenv(\"KOPS_FEATURE_FLAGS\"), \"ExperimentalRoles\") {\n    return errors.New(\"ExperimentalRoles flag required for dedicated etcd IGs\")\n}","typeGuard":null,"tryCatchPattern":"_, err := NewCluster(opt, cluster, zoneMap)\nif err != nil {\n    if strings.Contains(err.Error(), \"ExperimentalRoles feature flag\") {\n        return fmt.Errorf(\"enable KOPS_FEATURE_FLAGS=ExperimentalRoles or drop the dedicated etcd IG: %w\", err)\n    }\n    return err\n}","preventionTips":["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"],"tags":["feature-flag","etcd","instance-group","kops"],"backgroundTag":"feature-flag-not-enabled","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T07:17:12.445Z"}