kubernetes/kops · error

unexpected name for etcd cluster (must start with etcd): %q

Error message

unexpected name for etcd cluster (must start with etcd): %q

What it means

etcd-manager derives log paths, directories, and DNS names from the cluster name, so buildPod enforces that clusterName starts with 'etcd' to prevent directory/DNS collisions and keep naming sane. Names like 'events' or 'main' fail this prefix check.

Source

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

		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,
		DNSSuffix:     dnsInternalSuffix,
	}

	// Rewrite to the legacy URL shape for the pinned etcd-manager image; see
	// resolveAzureBackupStore.
	legacyBackupStore, azureStorageAccount, err := resolveAzureBackupStore(b.Cluster.Spec.ConfigStore.Base, backupStore)
	if err != nil {
		return nil, err
	}
	config.BackupStore = legacyBackupStore

View on GitHub (pinned to 4c8573c808)

Solutions

1. Rename the etcdClusters entries to the canonical 'etcd' and 'etcd-events'.
2. Fix upstream spec generators to always prefix names with 'etcd'.
3. If migrating an old cluster, rename via `kops replace` with a corrected spec.

Example fix

// before
- name: events
  ...
// after
- name: etcd-events
  ...

for _, c := range spec.EtcdClusters {
	if !strings.HasPrefix(c.Name, "etcd") {
		return fmt.Errorf("etcd cluster %q must start with 'etcd'", c.Name)
	}
}

When it happens

Trigger: buildManifest -> buildPod with an etcdCluster whose name (after normalization) does not begin with 'etcd', e.g. Name: 'events' or 'mainetcd'.

Common situations: Users abbreviating cluster names ('etcd' -> 'db', 'events' -> 'ev'); specs generated by tooling that dropped the prefix; typos like 'etc-main'.

Related errors

• InstanceGroup #%d did not have a Name
• expected exactly one object in manifest %s, found %d
• unknown etcd cluster key %q
• invalid InstanceGroup name: %v
• spec.PublicKey is required

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