kubernetes/kops · error

must specify %q label with cluster name to replace instanceG

Error message

must specify %q label with cluster name to replace instanceGroup

What it means

When replacing an InstanceGroup manifest, kops derives the owning cluster from the metadata label kopsapi.LabelClusterName (kops.k8s.io/cluster). If the label is absent or empty, it cannot know which cluster the instance group belongs to and fails with this error.

Source

Thrown at cmd/kops/replace.go:163

							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
				ig, err := clientset.InstanceGroupsFor(cluster).Get(ctx, igName, metav1.GetOptions{})
				if err != nil {
					if errors.IsNotFound(err) {
						if !c.Force {
							return fmt.Errorf("instanceGroup: %v does not exist (try adding --force flag)", igName)
						}
					} else {
						return fmt.Errorf("unable to check for instanceGroup: %v", err)

View on GitHub (pinned to 4c8573c808)

Solutions

1. Add metadata.labels.kops.k8s.io/cluster: <cluster-name> to the instancegroup manifest
2. Regenerate the manifest with `kops get instancegroup <name> -o yaml` which includes the label
3. If copying between clusters, update the label to the target cluster name
4. Use `kops create instancegroup` / `kops replace -f` with a properly labeled manifest

Example fix

// before
kind: InstanceGroup
metadata:
  name: nodes
// after
kind: InstanceGroup
metadata:
  name: nodes
  labels:
    kops.k8s.io/cluster: mycluster.example.com

func validateInstanceGroup(manifest []byte) error {
    var ig kopsapi.InstanceGroup
    if err := yaml.Unmarshal(manifest, &ig); err != nil {
        return err
    }
    if ig.ObjectMeta.Labels[kopsapi.LabelClusterName] == "" {
        return fmt.Errorf("missing required label %q", kopsapi.LabelClusterName)
    }
    return nil
}

func hasClusterLabel(labels map[string]string) bool {
    return labels[kopsapi.LabelClusterName] != ""
}

if err != nil {
    if strings.Contains(err.Error(), "must specify") {
        // add kops.k8s.io/cluster label and retry
    }
    return err
}

When it happens

Trigger: Hand-written or exported instancegroup YAML missing metadata.labels['kops.k8s.io/cluster']; manifests generated by tools that strip labels; copying an instancegroup from one cluster and forgetting to set the label.

Common situations: Authoring instancegroup manifests manually instead of `kops get instancegroups -o yaml`; label removed during templating/templating engines (helm/kustomize stripping labels); older exported manifests predating the label convention.

Related errors

• must specify %q label with cluster name to replace SSHCreden
• failed to annotate %q: %w
• unhandled instanceGroup role %q
• error parsing addons or manifest: %v
• failed to parse objects: %w

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