kubernetes/kops · error

unknown etcd cluster key %q

Error message

unknown etcd cluster key %q

What it means

buildPod switches on etcdCluster.Name and only accepts the known etcd cluster keys ('etcd', 'etcd-events', and 'leases' as a no-op). Any other cluster name is rejected, since etcd-manager only provisions the standard main/events pairs.

Source

Thrown at pkg/model/components/etcdmanager/model.go:376

	}

	switch etcdCluster.Name {
	case "main":
		clusterName = "etcd"

	case "events":
		// ok

	case "cilium":
		if !featureflag.APIServerNodes.Enabled() {
			clientHost = b.Cluster.APIInternalName()
		}

	case "leases":
		// ok

	default:
		return nil, fmt.Errorf("unknown etcd cluster key %q", etcdCluster.Name)
	}

	if backupStore == "" {
		return nil, fmt.Errorf("backupStore must be set for use with etcd-manager")
	}

	name := clusterName
	if !strings.HasPrefix(name, "etcd") {
		// For sanity, and to avoid collisions in directories / dns
		return nil, fmt.Errorf("unexpected name for etcd cluster (must start with etcd): %q", name)
	}
	logFile := "/var/log/" + name + ".log"

	config := &config{
		Containerized: true,
		ClusterName:   clusterName,
		BackupStore:   backupStore,
		GrpcPort:      ports.GRPCPort,

View on GitHub (pinned to 4c8573c808)

Solutions

1. Rename the cluster to 'etcd' or 'etcd-events', or remove the extra etcdClusters entry.
2. Run additional etcd clusters outside kOps management if you truly need a third one.
3. Fix spec-generation tooling that emits custom etcd cluster names.

Example fix

// before
etcdClusters:
- name: etcd-metrics
  ...
// after (remove it, or rename to a supported key)
etcdClusters:
- name: etcd
  ...

allowed := map[string]bool{"etcd": true, "etcd-events": true, "leases": true}
for _, c := range spec.EtcdClusters {
	if !allowed[c.Name] {
		return fmt.Errorf("etcd cluster name %q not supported by etcd-manager", c.Name)
	}
}

When it happens

Trigger: A spec EtcdClusters entry whose Name is not etcd/etcd-events/leases (e.g. 'etcd-metering', 'my-etcd', or a missing 'etcd' prefix) reaches model building during `kops update cluster`.

Common situations: Attempts to add a third custom etcd cluster; typo in cluster name; copied spec fragments renamed for another purpose; legacy specs from clusters with extra etcd clusters.

Related errors

• backupStore must be set for use with etcd-manager
• unexpected name for etcd cluster (must start with etcd): %q
• InstanceGroup #%d did not have a Name
• must configure at least one Node InstanceGroup
• no subnets found in cluster %q

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