What causes "must set Family when using SourceRanges" in kubernetes/kops?

Set family: ipv4 or family: ipv6 on the FirewallRule to match its ranges

must set Family when using SourceRanges

Error message

must set Family when using SourceRanges

What it means

kOps requires FirewallRule.Family to be set whenever SourceRanges is used, so it can consistently split rules into IPv4 and IPv6 variants. An empty Family with any SourceRanges entry is a spec validation error.

Source

Thrown at upup/pkg/fi/cloudup/gcetasks/firewallrule.go:126

	// this is interpreted as OR, not AND, which is likely not what was intended.
	if len(e.SourceRanges) != 0 && len(e.SourceTags) != 0 {
		return fmt.Errorf("SourceRanges and SourceTags should not both be specified")
	}

	name := fi.ValueOf(e.Name)

	// Make sure we've split the ipv4 / ipv6 addresses.
	// A single firewall rule can't mix ipv4 and ipv6 addresses, so we split them into two rules.
	for _, sourceRange := range e.SourceRanges {
		_, cidr, err := net.ParseCIDR(sourceRange)
		if err != nil {
			return fmt.Errorf("sourceRange %q is not valid: %w", sourceRange, err)
		}

		if e.Family == "" {
			// This is our own requirement, just for consistency checking.
			// Previous we used the name, but that was confused when the cluster name was ipv6.example.com
			return fmt.Errorf("must set Family when using SourceRanges")
		}

		if cidr.IP.To4() != nil {
			// IPv4
			if e.Family != AddressFamilyIPv4 {
				return fmt.Errorf("ipv4 ranges should not be in a ipv6-named rule (found %s in %s)", sourceRange, name)
			}
		} else {
			// IPv6
			if e.Family != AddressFamilyIPv6 {
				return fmt.Errorf("ipv6 ranges should be in a ipv6-named rule (found %s in %s)", sourceRange, name)
			}
		}
	}

	return nil
}

View on GitHub (pinned to 4c8573c808)

Solutions

Set family: ipv4 or family: ipv6 on the FirewallRule to match its ranges
Split IPv4 and IPv6 ranges into two rules with distinct families if mixed
Upgrade/adjust manifest tooling to emit the family field
Re-run kops update

Example fix

// before
sourceRanges: ["10.0.0.0/8"]
// after
family: ipv4
sourceRanges: ["10.0.0.0/8"]

Defensive patterns

Strategy: validation

Validate before calling

if len(rule.SourceRanges) > 0 && rule.Family == "" {
  return fmt.Errorf("rule %s: must set family (ipv4|ipv6) when using sourceRanges", rule.Name)
}

Prevention

Set family on every rule that declares sourceRanges
Update stored manifests/kustomizations when upgrading kOps
Derive family from CIDR version in generators

When it happens

Trigger: A firewallRule specifies sourceRanges but leaves the family field empty; Normalize checks e.Family == "" right after parsing each CIDR.

Common situations: Older cluster manifests written before the Family field existed; hand-written rules omitting the new required field; template generation that never sets family.

Related errors

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