kubernetes/kops · error

invalid instance group role %q

Error message

invalid instance group role %q

What it means

When --role (options.InstanceGroupRoles) is supplied, each role string is parsed with kopsapi.ParseInstanceGroupRole(role, true). If parsing fails — the string is not a valid InstanceGroupRole value — the command returns "invalid instance group role %q". Only canonical role names (control-plane/master, node, bastion, apiserver...) are accepted.

Source

Thrown at cmd/kops/rolling-update_cluster.go:331

				return fmt.Errorf("InstanceGroup %q not found", instanceGroupName)
			}

			filtered = append(filtered, found)
		}

		instanceGroups = filtered

		// Don't warn if we find more ASGs than IGs
		warnUnmatched = false
	}

	if len(options.InstanceGroupRoles) != 0 {
		var filtered []*kopsapi.InstanceGroup

		for _, role := range options.InstanceGroupRoles {
			s, f := kopsapi.ParseInstanceGroupRole(role, true)
			if !f {
				return fmt.Errorf("invalid instance group role %q", role)
			}
			for _, ig := range instanceGroups {
				if ig.Spec.Role == s {
					filtered = append(filtered, ig)
				}
			}
		}

		instanceGroups = filtered

		// Don't warn if we find more ASGs than IGs
		warnUnmatched = false
	}

	cloud, err := cloudup.BuildCloud(cluster)
	if err != nil {
		return err
	}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Use one of the valid values printed by kops help rolling-update cluster (e.g. control-plane, node, bastion)
2. Check kopsapi.ParseInstanceGroupRole / InstanceGroupRole constants in k8s.io/kops/pkg/apis/kops for the exact accepted strings for your kops version
3. Drop the --role flag to consider all instance groups

Example fix

// before
kops rolling-update cluster mycluster.k8s.local --role worker
// error: invalid instance group role "worker"
// after
kops rolling-update cluster mycluster.k8s.local --role node

// validate role string against kopsapi roles before invoking
valid := map[string]bool{"control-plane": true, "master": true, "node": true, "bastion": true, "apiserver": true}
if !valid[role] {
    return fmt.Errorf("role %q invalid; use one of: control-plane, node, bastion, apiserver", role)
}

When it happens

Trigger: options.InstanceGroupRoles contains a string that kopsapi.ParseInstanceGroupRole does not recognize, e.g. --role worker, --role Node (case sensitivity), or --role control_plane.

Common situations: Using pre-1.24 terminology like "master" after role renames, or vice versa; guessing role names like "worker" or "etcd"; shell completing a truncated value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• InstanceGroup %q not found
• invalid InstanceGroup name: %v
• GroupName is required
• --name is required
• unsupported output type %q

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