kubernetes/kops · error

cluster is required

Error message

cluster is required

What it means

RunGenerateMachineDeployment validates options before doing any work and returns 'cluster is required' when options.ClusterName is empty. The toolbox clusterapi generator needs to know which cluster's subnets/zones/instance types to mirror into the MachineDeployment.

Source

Thrown at pkg/commands/toolbox/clusterapi/generate_machinedeployment.go:98

		},
	}

	cmd.Flags().StringVar(&options.ClusterName, "cluster", options.ClusterName, "Name of cluster to join")
	cmd.Flags().StringVar(&options.Name, "name", options.Name, "Name of MachineDeployment (and other objects) to create")
	cmd.Flags().StringVar(&options.Namespace, "namespace", options.Namespace, "Namespace for objects")
	cmd.Flags().IntVar(&options.Replicas, "replicas", options.Replicas, "Number of replicas for MachineDeployment")
	cmd.Flags().StringArrayVar(&options.Zones, "zones", options.Zones, "Zones for the MachineDeployment (if not specified, will be deployed to all discovered zones in the cluster)")
	cmd.Flags().StringVar(&options.InstanceType, "instance-type", options.InstanceType, "Instance type for the MachineDeployment (if not specified, an arbitrary instance type from the instance groups will be used)")
	cmd.Flags().StringVar(&options.Subnet, "subnet", options.Subnet, "Subnet for the MachineDeployment (if not specified, an arbitrary subnet from the instance groups will be used)")
	cmd.Flags().StringVar(&options.Image, "image", options.Image, "Image for the MachineDeployment (if not specified, an arbitrary image from the instance groups will be used)")
	return cmd
}

func RunGenerateMachineDeployment(ctx context.Context, f commandutils.Factory, out io.Writer, options *GenerateMachineDeploymentOptions) error {
	log := klog.FromContext(ctx)

	if options.ClusterName == "" {
		return fmt.Errorf("cluster is required")
	}
	if options.Name == "" {
		return fmt.Errorf("name is required")
	}

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

	cluster, err := clientset.GetCluster(ctx, options.ClusterName)
	if err != nil {
		return err
	}

	// TODO: Sync with LinkToSubnet and support ID
	subnet := options.Subnet
	if subnet == "" {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Pass --cluster <name> (e.g. --cluster mycluster.k8s.local) to the generate machinedeployment command.
2. Verify the option value is non-empty in scripts before invoking (echo "$CLUSTER").
3. When calling programmatically, set options.ClusterName before RunGenerateMachineDeployment.

Example fix

// before
opts := &GenerateMachineDeploymentOptions{Name: "workers"}
RunGenerateMachineDeployment(ctx, f, out, opts) // cluster is required
// after
opts := &GenerateMachineDeploymentOptions{Name: "workers", ClusterName: "mycluster.k8s.local"}
RunGenerateMachineDeployment(ctx, f, out, opts)

if options == nil || options.ClusterName == "" {
	return fmt.Errorf("cluster is required: pass --cluster <name>")
}

func optsReady(o *GenerateMachineDeploymentOptions) bool {
	return o != nil && o.ClusterName != "" && o.Name != ""
}

if err := RunGenerateMachineDeployment(ctx, f, out, options); err != nil {
	switch err.Error() {
	case "cluster is required":
		return flag.ErrHelp // trigger usage output
	default:
		return err
	}
}

When it happens

Trigger: Running `kops toolbox cluster-events`/clusterapi generate machinedeployment without --cluster (or programmatically passing GenerateMachineDeploymentOptions with ClusterName unset).

Common situations: Forgetting the --cluster flag on the CLI; scripting the command with an empty variable; calling the exported function directly in tests/tools without initializing options.

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

• name is required
• error creating kops config template: %w
• error creating gcp machine template: %w
• error building machine deployments: %w
• no subnets found in cluster %q

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