kubernetes/kops · error

cluster is required

Error message

cluster is required

What it means

RunToolboxEnroll requires the target cluster name to resolve state-store configuration and PKI. When `options.ClusterName` is empty, it fails immediately with this validation error before contacting any infrastructure.

Source

Thrown at pkg/commands/toolbox_enroll.go:93

	BuildHost bool

	// PodCIDRs is the list of IP Address ranges to use for pods that run on this node
	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

View on GitHub (pinned to 4c8573c808)

Solutions

1. Pass `--cluster <cluster-name>` explicitly on the command line
2. Set `export KOPS_CLUSTER_NAME=<cluster-name>` for the shell/CI job
3. Verify with `kops get clusters` that the name you pass matches an existing cluster in the state store

Example fix

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

CLUSTER="${KOPS_CLUSTER_NAME:-}"
[ -n "$CLUSTER" ] || { echo "cluster is required: pass --cluster or set KOPS_CLUSTER_NAME"; exit 1; }

When it happens

Trigger: Invoking `kops toolbox enroll` without `--cluster` (or `--name`) and with no `KOPS_CLUSTER_NAME` set in the environment.

Common situations: Scripted enroll calls missing the flag; relying on `--cluster` short-hand that isn't supported; KOPS_CLUSTER_NAME unset in CI or new shell.

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
• instance-group is required
• host is required
• name is required

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