IP matcher (proto)

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

.xds.type.matcher.v3.IPMatcher

[.xds.type.matcher.v3.IPMatcher proto]

Matches a specific IP address against a set of possibly overlapping subnets using a trie.

{
  "range_matchers": []
}

range_matchers: (repeated .xds.type.matcher.v3.IPMatcher.IPRangeMatcher) Match IP address by CIDR ranges.

.xds.type.matcher.v3.IPMatcher.IPRangeMatcher

[.xds.type.matcher.v3.IPMatcher.IPRangeMatcher proto]

Specifies a list of IP address ranges and a match action.

{
  "ranges": [],
  "on_match": {...},
  "exclusive": ...
}

ranges: (repeated .xds.core.v3.CidrRange, REQUIRED) A non-empty set of CIDR ranges.

on_match: (.xds.type.matcher.v3.Matcher.OnMatch) Match action to apply when the IP address is within one of the CIDR ranges.

exclusive

(bool) Indicates whether this match option should be considered if there is a more specific matcher. Exclusive matchers are not selected whenever a more specific matcher exists (e.g. matcher with a longer prefix) even when the more specific matcher fails its nested match condition. Non-exclusive matchers are considered if the more specific matcher exists but its nested match condition does not entirely match. Non-exclusive matchers are selected in the order of their specificity first (longest prefix first), then the order of declaration next.

For example, consider two range matchers: an exclusive matcher X on 0.0.0.0/0 and a matcher Y on 192.0.0.0/2 with a nested match condition Z. For the input IP 192.168.0.1 matcher Y is the most specific. If its nested match condition Z does not accept the input, then the less specific matcher X does not apply either despite the input being within the range, because matcher X is exclusive.

The opposite is true if matcher X is not marked as exclusive. In that case matcher X always matches whenever matcher “Y rejects the input.