kubernetes/kops · error

expected exactly one subnet with GCE IP Aliases

Error message

expected exactly one subnet with GCE IP Aliases

What it means

performNetworkAssignmentsIPAliases implements kops GCE IP-alias networking under the assumption that the cluster uses exactly one subnet. If c.Spec.Networking.Subnets has a count other than 1, this error is thrown before any GCE API call. It is a hard design constraint of the GCE IP Aliases networking mode, not a cloud failure.

Source

Thrown at upup/pkg/fi/cloudup/gce/network.go:156

			continue
		}
		if err := used.MarkInUse(subnet.IpCidrRange); err != nil {
			return nil, err
		}

		for _, s := range subnet.SecondaryIpRanges {
			if err := used.MarkInUse(s.IpCidrRange); err != nil {
				return nil, err
			}
		}
	}

	return used, nil
}

func performNetworkAssignmentsIPAliases(ctx context.Context, c *kops.Cluster, cloudObj fi.Cloud) error {
	if len(c.Spec.Networking.Subnets) != 1 {
		return fmt.Errorf("expected exactly one subnet with GCE IP Aliases")
	}
	nodeSubnet := &c.Spec.Networking.Subnets[0]

	if c.Spec.Networking.PodCIDR != "" && c.Spec.Networking.ServiceClusterIPRange != "" && nodeSubnet.CIDR != "" {
		return nil
	}

	used, err := buildUsed(ctx, c, cloudObj)
	if err != nil {
		return err
	}

	// CIDRs should be in the RFC1918 range, but otherwise we have no constraints
	networkCIDR := "10.0.0.0/8"

	podCIDR, err := used.Allocate(networkCIDR, net.CIDRMask(14, 32))
	if err != nil {
		return err

View on GitHub (pinned to 4c8573c808)

Solutions

1. Reduce spec.networking.subnets to exactly one subnet in the cluster spec
2. If multiple subnets are needed, switch to a networking mode that supports them (e.g. calico with multiple subnets where supported) or use GCE route-based networking
3. Check UsesIPAliases conditions: if you do not intend IP aliases, adjust networking config so classic mode is selected

Example fix

// before
networking:
  subnets:
    - name: us-central1
    - name: us-east1
// after
networking:
  subnets:
    - name: us-central1

if UsesIPAliases(cluster) && len(cluster.Spec.Networking.Subnets) != 1 {
	return fmt.Errorf("GCE IP alias networking requires exactly one subnet, found %d", len(cluster.Spec.Networking.Subnets))
}

err := gcecloud.PerformNetworkAssignments(ctx, cluster, cloud)
if err != nil && strings.Contains(err.Error(), "expected exactly one subnet") {
	return fmt.Errorf("cluster spec unsupported for GCE IP aliases: %w", err)
}

When it happens

Trigger: Declaring GCE IP-alias networking (non-classic, UsesIPAliases true) in a cluster spec with zero subnets or with two or more subnets, during PerformNetworkAssignments at cluster creation/update.

Common situations: Multi-zone cluster specs where users add a subnet per region/zone; copying a multi-subnet AWS-style spec to GCE with ipalias networking enabled.

Related errors

• providerID %q did not match our project %q
• failed to parse subnet CIDR %q: %w
• unable to determine zones in region %q
• found multiple instance groups matching MIG %q
• cannot parse network name %q as either project/network or ne

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