kubernetes/kops · error

backupStore must be set for use with etcd-manager

Error message

backupStore must be set for use with etcd-manager

What it means

During etcd-manager model building, kOps iterates over every etcdCluster in the cluster spec and requires a non-empty EtcdCluster.Backups.BackupStore. etcd-manager manages its own backup lifecycle, so kOps must know where backups are stored; an empty backupStore makes the resulting manifest ambiguous, so Build aborts with this error. It is a cluster spec validation error, not a runtime failure.

Source

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

// EtcdManagerBuilder builds the manifest for the etcd-manager
type EtcdManagerBuilder struct {
	*model.KopsModelContext
	Lifecycle    fi.Lifecycle
	AssetBuilder *assets.AssetBuilder
}

var _ fi.CloudupModelBuilder = &EtcdManagerBuilder{}

// Build creates the tasks
func (b *EtcdManagerBuilder) Build(c *fi.CloudupModelBuilderContext) error {
	for _, etcdCluster := range b.Cluster.Spec.EtcdClusters {
		backupStore := ""
		if etcdCluster.Backups != nil {
			backupStore = etcdCluster.Backups.BackupStore
		}
		if backupStore == "" {
			return fmt.Errorf("backupStore must be set for use with etcd-manager")
		}

		for _, member := range etcdCluster.Members {
			instanceGroupName := fi.ValueOf(member.InstanceGroup)
			manifest, err := b.buildManifest(etcdCluster, instanceGroupName)
			if err != nil {
				return err
			}

			manifestYAML, err := k8scodecs.ToVersionedYaml(manifest)
			if err != nil {
				return fmt.Errorf("error marshaling manifest to yaml: %v", err)
			}

			name := fmt.Sprintf("%s-%s", etcdCluster.Name, instanceGroupName)
			c.AddTask(&fitasks.ManagedFile{
				Contents:  fi.NewBytesResource(manifestYAML),
				Lifecycle: b.Lifecycle,

View on GitHub (pinned to 4c8573c808)

Solutions

1. Add `backups: {backupStore: <state-store path, e.g. s3://bucket/cluster/backups/etcd-main>}` to each etcdCluster in the cluster spec.
2. Re-create the spec via `kops create cluster` (which populates backupStore automatically) and re-apply your customizations.
3. If you did not intend etcd-manager, check for leftover etcdClusters entries from a legacy (non-manager) cluster and remove or migrate them.

Example fix

// before
etcdClusters:
- name: main
  members:
  - instanceGroup: master-a
// after
etcdClusters:
- name: main
  backups:
    backupStore: s3://my-kops-state/mycluster/backups/etcd-main
  members:
  - instanceGroup: master-a

for _, c := range cluster.Spec.EtcdClusters {
	if c.Backups == nil || c.Backups.BackupStore == "" {
		return fmt.Errorf("etcd cluster %q missing backups.backupStore", c.Name)
	}
}

if err := validateBackupStores(cluster); err != nil { return fmt.Errorf("cluster spec invalid: %w", err) }

When it happens

Trigger: Running `kops update cluster` (or any target that triggers model building) when a spec EtcdClusters entry has no `backups.backupStore` set (Backups nil, or Backups.BackupStore empty string).

Common situations: Hand-written or migrated cluster manifests that omit the backups block; older cluster specs predating etcd-manager defaults; templating tools that strip empty fields from the spec.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• unknown etcd cluster key %q
• must configure at least one Node InstanceGroup
• no subnets found in cluster %q
• unhandled LoadBalancer type %q
• subnet %q had unknown type %q

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