expected exactly one subnet for InstanceGroup %q; subnets wa

Error message

expected exactly one subnet for InstanceGroup %q; subnets was %s

What it means

During kOps cluster spec building for Akamai (Linode), InstanceModelBuilder.Build() maps each InstanceGroup to exactly one Linode VPC subnet. GatherSubnets resolves the instance group's subnet names to subnet specs, and if the group resolves to zero or more than one subnet, build fails with this error because a Linode instance must live in a single subnet/region.

Source

Thrown at pkg/model/linodemodel/instances.go:54

	SSHKeyLifecycle        fi.Lifecycle
	BootstrapScriptBuilder *model.BootstrapScriptBuilder
}

var _ fi.CloudupModelBuilder = &InstanceModelBuilder{}

func (b *InstanceModelBuilder) Build(c *fi.CloudupModelBuilderContext) error {
	sshKeyTask, err := b.buildSSHKeyTask(c)
	if err != nil {
		return err
	}

	for _, ig := range b.InstanceGroups {
		subnets, err := b.GatherSubnets(ig)
		if err != nil {
			return err
		}
		if len(subnets) != 1 {
			return fmt.Errorf("expected exactly one subnet for InstanceGroup %q; subnets was %s", ig.Name, ig.Spec.Subnets)
		}
		subnetSpec := subnets[0]
		subnetTaskName := linode.NormalizeLinodeLabel(b.ClusterName() + "-" + subnetSpec.Name)
		subnetTask, err := findSubnetTask(c, subnetTaskName, ig)
		if err != nil {
			return err
		}

		userData, err := b.BootstrapScriptBuilder.ResourceNodeUp(c, ig)
		if err != nil {
			return err
		}

		tagsMap, err := b.CloudTagsForInstanceGroup(ig)
		if err != nil {
			return err
		}
		tags := make([]string, 0, len(tagsMap))

View on GitHub (pinned to 4c8573c808)

Solutions

Edit the InstanceGroup manifest so spec.subnets contains exactly one subnet name (e.g. subnets: ["us-east-1a"]).
If multi-AZ is needed on Linode, create a separate InstanceGroup per subnet/region instead of one group with many subnets.
Run kops get instancegroup <name> -o yaml to confirm the current subnets list, then kops replace -f after fixing.
Check the cluster spec for duplicate subnet names that cause GatherSubnets to resolve more than one entry.

Example fix

// before
metadata:
  name: nodes
spec:
  subnets:
  - us-east-1a
  - us-east-1b
// after
metadata:
  name: nodes
spec:
  subnets:
  - us-east-1a

Defensive patterns

Strategy: validation

Validate before calling

ig, _ := kops.GetInstanceGroup(cluster, "nodes")
if len(ig.Spec.Subnets) != 1 {
    return fmt.Errorf("instance group %s must reference exactly one subnet, got %d", ig.Name, len(ig.Spec.Subnets))
}

Prevention

On Linode, always give each InstanceGroup exactly one subnet.
Create one InstanceGroup per region/subnet for multi-AZ designs.
Validate manifests with kops toolbox template or kops create --dry-run before applying.
Avoid copying AWS multi-subnet instance group specs to Linode.

When it happens

Trigger: Running kops update/create cluster on a Linode cluster where an InstanceGroup's spec.subnets lists multiple subnet names, or the subnet list is empty, or GatherSubnets silently yields multiple matches (e.g. duplicate subnet names in cluster.spec.networking.subnets).

Common situations: Copying an AWS cluster manifest (which allows multi-subnet instance groups across AZs) to Linode; adding a second subnet to an instance group intending multi-AZ support; typos merging subnet lists via kops toolbox or cluster template merges.

Related errors

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