kubernetes/kops · error

must specify at least one zone for the cluster (use --zones)

Error message

must specify at least one zone for the cluster (use --zones)

What it means

NewCluster validation guard: fires when opt.Zones is empty, i.e. kops create cluster was run without --zones. At least one zone is required to derive regions/subnets and place the cluster, so creation is aborted before any cloud calls.

Source

Thrown at upup/pkg/fi/cloudup/new_cluster.go:321

			cluster.Spec.KubeAPIServer.FeatureGates[featureGate] = value
			cluster.Spec.KubeControllerManager.FeatureGates[featureGate] = value
			cluster.Spec.KubeProxy.FeatureGates[featureGate] = value
			cluster.Spec.KubeScheduler.FeatureGates[featureGate] = value
		}
	}

	if len(opt.AdminAccess) == 0 {
		opt.AdminAccess = []string{"0.0.0.0/0", "::/0"}
	}
	cluster.Spec.API.Access = opt.AdminAccess
	if len(opt.SSHAccess) != 0 {
		cluster.Spec.SSHAccess = opt.SSHAccess
	} else {
		cluster.Spec.SSHAccess = opt.AdminAccess
	}

	if len(opt.Zones) == 0 {
		return nil, fmt.Errorf("must specify at least one zone for the cluster (use --zones)")
	}
	allZones := sets.NewString()
	allZones.Insert(opt.Zones...)
	allZones.Insert(opt.ControlPlaneZones...)

	if opt.CloudProvider == "" {
		cloud, err := clouds.GuessCloudForPath(cluster.Spec.ConfigStore.Base)
		if err != nil {
			return nil, fmt.Errorf("pass in the cloud provider explicitly using --cloud: %w", err)
		}
		klog.V(2).Infof("Inferred %q cloud provider from state store %q", cloud, cluster.Spec.ConfigStore.Base)
		opt.CloudProvider = string(cloud)
	}

	var cloud fi.Cloud

	switch api.CloudProviderID(opt.CloudProvider) {
	case api.CloudProviderAWS:

View on GitHub (pinned to 4c8573c808)

Solutions

1. Add --zones, e.g. `kops create cluster --zones us-east-1a,us-east-1b`
2. Set opt.Zones in NewClusterOptions to at least one zone
3. Ensure the flag-parsing code actually populates Zones (check for cobra flag name mismatches)

Example fix

// before
kops create cluster --name c.example.com --cloud aws
// after
kops create cluster --name c.example.com --cloud aws --zones us-east-1a

if len(opt.Zones) == 0 {
    return fmt.Errorf("--zones is required, e.g. --zones us-east-1a")
}

func hasZones(opt *NewClusterOptions) bool {
    return len(opt.Zones) > 0
}

When it happens

Trigger: `kops create cluster` without --zones (or with --zones=""), or NewClusterOptions constructed with Zones: nil. Note ControlPlaneZones alone do not satisfy this check — opt.Zones specifically must be non-empty.

Common situations: Interactive usage that assumes zones are inferred from the cloud provider; scripts that build flags dynamically and produce an empty --zones; forgetting that even single-zone clusters need an explicit zone.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• at least one channel URL is required
• spec.PublicKey is required
• unable to execute --dry-run without setting --output
• --name is required
• --azure-subscription-id is required

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