{"record":{"id":"21c60b88cf7f667a","repo":"kubernetes/kops","slug":"etcd-version-q-is-not-supported-with-etcd-manager","errorCode":null,"errorMessage":"etcd version %q is not supported with etcd-manager, please specify a supported version, remove the value to use the recommended version, or also set the image field to run a custom version","messagePattern":"etcd version %q is not supported with etcd-manager, please specify a supported version, remove the value to use the recommended version, or also set the image field to run a custom version","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/model/components/etcdmanager/options.go","lineNumber":76,"sourceCode":"\t\tif etcdCluster.Backups == nil {\n\t\t\tetcdCluster.Backups = &kops.EtcdBackupSpec{}\n\t\t}\n\t\tif etcdCluster.Backups.BackupStore == \"\" {\n\t\t\tbase := clusterSpec.ConfigStore.Base\n\t\t\tetcdCluster.Backups.BackupStore = join(base, \"backups\", \"etcd\", etcdCluster.Name)\n\t\t}\n\n\t\tif !etcdVersionIsSupported(etcdCluster.Version) {\n\t\t\tif etcdCluster.Image != \"\" {\n\t\t\t\tklog.Warningf(\"etcd version %q is not bundled by kOps and has not been tested; using binaries from custom image %q\", etcdCluster.Version, etcdCluster.Image)\n\t\t\t} else {\n\t\t\t\tklog.Warningf(\"Unsupported etcd version %q detected; please update etcd version.\", etcdCluster.Version)\n\t\t\t\tvar versions []string\n\t\t\t\tfor _, v := range etcdSupportedVersions() {\n\t\t\t\t\tversions = append(versions, v.Version)\n\t\t\t\t}\n\t\t\t\tklog.Warningf(\"Supported etcd versions: %s\", strings.Join(versions, \", \"))\n\t\t\t\treturn fmt.Errorf(\"etcd version %q is not supported with etcd-manager, please specify a supported version, remove the value to use the recommended version, or also set the image field to run a custom version\", etcdCluster.Version)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// etcdVersion describes how we want to support each etcd version.\ntype etcdVersion struct {\n\tVersion          string\n\tImage            string\n\tSymlinkToVersion string\n}\n\n// etcdLatestImages lists the latest etcd patch image bundled by kops for each\n// supported minor. All earlier patch versions within the same minor are\n// generated as SymlinkToVersion entries by etcdSupportedVersions.\nvar etcdLatestImages = []etcdVersion{","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/pkg/model/components/etcdmanager/options.go#L58-L94","documentation":"BuildOptions validates every etcd cluster's version against kOps' bundled etcd version list (currently 3.5.x/3.6.x/3.7.x minors). If the version is unsupported AND no custom image is set on the cluster, the build fails with this message, because etcd-manager has no bundled binaries for that version. Setting spec.etcdClusters[].image bypasses the check since the custom image supplies the binaries.","triggerScenarios":"`kops update cluster` (or create cluster) where an etcdCluster has spec.etcdClusters[].version set to an unsupported string (e.g. \"3.4.13\", \"3.8.0\", or a typo like \"3.5.1\" misspelled) and etcdClusters[].image is empty.","commonSituations":"Clusters pinned to old etcd versions from pre-etcd-manager days, users trying to jump to a brand-new etcd release not yet bundled by kOps, or version typos in the cluster spec.","solutions":["Remove the version field from the etcdCluster spec so kOps uses its recommended etcd version","Set version to a supported version listed in the accompanying klog warning (3.5.x/3.6.x/3.7.x)","Keep the unsupported version but set etcdClusters[].image to a container image containing those binaries (custom image path)","Run `kops upgrade cluster` / update kOps to get newer bundled etcd versions"],"exampleFix":"// before (cluster.yaml)\netcdClusters:\n- name: main\n  version: 3.4.13\n  members: [...]\n// after\netcdClusters:\n- name: main\n  members: [...]","handlingStrategy":"validation","validationCode":"// Check etcd version against supported list before update\nsupported := []string{\"3.5.x\", \"3.6.x\", \"3.7.x\"} // see kops components.LatestEtcd*Version\nfor _, ec := range cluster.Spec.EtcdClusters {\n    if ec.Version != \"\" && !versionIn(ec.Version, supported) && ec.Image == \"\" {\n        return fmt.Errorf(\"etcd version %q unsupported and no image set\", ec.Version)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := applyClusterSpec(cluster); err != nil {\n    if strings.Contains(err.Error(), \"is not supported with etcd-manager\") {\n        return fmt.Errorf(\"pin a supported etcd version or set the image field: %w\", err)\n    }\n    return err\n}","preventionTips":["Omit the version field to let kOps pick the recommended etcd version","When pinning, choose versions from the klog \"Supported etcd versions\" list in the error output","For unlisted versions, always set etcdClusters[].image alongside version","Re-check etcd support matrix after every kOps upgrade"],"tags":["etcd-manager","etcd-version","cluster-spec"],"backgroundTag":"unsupported-etcd-version","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}