kubernetes/kops · error

instance-group is required

Error message

instance-group is required

What it means

Enrolling a host requires knowing which InstanceGroup it will join (for roles, spec inheritance, etc.). When `options.InstanceGroup` is empty, RunToolboxEnroll returns this validation error before doing any SSH work.

Source

Thrown at pkg/commands/toolbox_enroll.go:96

	PodCIDRs []string

	kubeconfig.CreateKubecfgOptions
}

func (o *ToolboxEnrollOptions) InitDefaults() {
	o.SSHUser = "root"
	o.SSHPort = 22
}

func RunToolboxEnroll(ctx context.Context, f commandutils.Factory, out io.Writer, options *ToolboxEnrollOptions) error {
	if !featureflag.Metal.Enabled() {
		return fmt.Errorf("bare-metal support requires the Metal feature flag to be enabled")
	}
	if options.ClusterName == "" {
		return fmt.Errorf("cluster is required")
	}
	if options.InstanceGroup == "" {
		return fmt.Errorf("instance-group is required")
	}
	if options.Host == "" {
		// Technically we could build the host resource without the PKI, but this isn't the case we are targeting right now.
		return fmt.Errorf("host is required")
	}

	// Resolve KOPS_BASE_URL early so that kops.Version is overridden
	// before the version downgrade check in ApplyClusterCmd.Run.
	if _, err := wellknownassets.BaseURL(); err != nil {
		return err
	}

	clientset, err := f.KopsClient()
	if err != nil {
		return err
	}

	configBuilder := &ConfigBuilder{

View on GitHub (pinned to 4c8573c808)

Solutions

1. Add `--instance-group <ig-name>` matching an existing InstanceGroup in the cluster
2. List candidate groups with `kops get instancegroups --name <cluster>` and pick the right one
3. Fix variable interpolation in scripts so the IG name isn't empty

Example fix

// before
kops toolbox enroll --cluster c.example.com --host 10.0.0.5
// after
kops toolbox enroll --cluster c.example.com --instance-group metal --host 10.0.0.5

IG="${IG:?instance-group is required}"
kops get instancegroup --name "$CLUSTER" "$IG" >/dev/null || { echo "instance group $IG not found"; exit 1; }

When it happens

Trigger: Running `kops toolbox enroll` with --cluster and --host but without `--instance-group`.

Common situations: Typos in the flag name (e.g. `--instancegroup`); scripts parameterized for other kops commands that use different flag spellings; forgetting that enroll does not infer the IG from the host.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• must specify ID of instance or name of node to delete
• must specify the name of the instance group to delete
• cluster is required
• host is required
• name is required

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