kubernetes/kops · error

error replacing cluster: %v

Error message

error replacing cluster: %v

What it means

RunReplace wraps the failure of clientset.UpdateCluster when the replaced manifest is an existing cluster (cluster != nil). It fires when the state store rejects or errors on updating the cluster spec during `kops replace -f`; the underlying API/storage error is appended.

Source

Thrown at cmd/kops/replace.go:155

					}
					if cluster == nil {
						if !c.Force {
							return fmt.Errorf("cluster %v does not exist (try adding --force flag)", clusterName)
						}

						err = cloudup.PerformAssignments(v, vfsContext, cloud)
						if err != nil {
							return fmt.Errorf("error populating configuration: %w", err)
						}

						_, err = clientset.CreateCluster(ctx, v)
						if err != nil {
							return fmt.Errorf("error creating cluster: %v", err)
						}
					} else {
						_, err = clientset.UpdateCluster(ctx, v, status)
						if err != nil {
							return fmt.Errorf("error replacing cluster: %v", err)
						}
					}
				}

			case *kopsapi.InstanceGroup:
				clusterName := v.ObjectMeta.Labels[kopsapi.LabelClusterName]
				if clusterName == "" {
					return fmt.Errorf("must specify %q label with cluster name to replace instanceGroup", kopsapi.LabelClusterName)
				}
				cluster, err := clientset.GetCluster(ctx, clusterName)
				if err != nil {
					if errors.IsNotFound(err) {
						return fmt.Errorf("cluster %q not found", clusterName)
					}
					return fmt.Errorf("error fetching cluster %q: %v", clusterName, err)
				}
				// check if the instancegroup exists already
				igName := v.ObjectMeta.Name

View on GitHub (pinned to 4c8573c808)

Solutions

1. Avoid changing immutable fields; use `kops edit cluster` + `kops update cluster` workflow or create a new cluster for incompatible changes
2. Re-run and check for a concurrent-modification conflict; serialize cluster changes within your team/tooling
3. Verify state store write access and health
4. Compare the manifest against the stored cluster (`kops get cluster <name> -o yaml`) and diff to find the rejected field
5. Read the wrapped error for the precise cause

Example fix

// before
spec:
  networking:
    calico: {}   # changing from weave on an existing cluster via replace
// after
# keep existing networking or migrate via documented procedure
kops replace -f cluster.yaml

// diff manifest against stored cluster to catch immutable changes early
stored, err := clientset.GetCluster(ctx, v.Name)
if err == nil && immutableFieldsChanged(stored, v) {
    return fmt.Errorf("immutable fields changed (e.g. networking/zones); recreate cluster instead")
}

_, err := clientset.UpdateCluster(ctx, v, status)
if err != nil {
    if isConflict(err) { /* serialize with other operators, retry */ }
    return fmt.Errorf("update rejected: %w", err)
}

When it happens

Trigger: UpdateCluster rejecting the change: spec field mutated that is immutable (e.g. changing zone/networking type on an existing cluster), state store write failure, concurrent modification conflict, or status fetch producing an incompatible object.

Common situations: Trying to change immutable fields (networking plugin, cluster name semantics) via replace; two operators running replace simultaneously; state-store permission/availability problems; apiVersion drift between manifest and stored cluster.

Related errors

• error creating cluster: %v
• cannot update configuration file %s: does not exist
• cluster not found %q
• reading file %v: %w
• error loading NodeupConfig %q: %v

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