Skip to content

GEP-735: TCP and UDP addresses matching

  • Issue: #735
  • Status: Provisional


Spec for matching source and destination addresses on L4 APIs.


  • add matching rules for address to TCPRoute
  • add matching rules for address to UDPRoute
  • intentionally avoid type definitions that would make it hard to expand later


  • define rules for port matching


While TCPRoute and UDPRoute currently support custom matching extensions, there is desire among the community to include some "fundamental" matching options in the spec that cover the most common requirements. In this GEP we request address matching for these APIs in order to support a standard for some of the commonplace setups of gateway implementations. Matching is intended to be covered for both source and destination to enable a finer level of tuning options for L4 traffic routing at a level below the Gateway.


The API changes include the following new types:

  • AddressMatch to indicate the IP for address matching
  • AddressRouteMatches to configure matching according to network address

These types enable the address matching required, with some active considerations about how to leave these open ended for later expansion.

AddressMatch Type

A new AddressMatch type provides the targeting mechanism for match inclusion of a given network address:

type AddressMatch struct {
    // Type of the address, either IPAddress or NamedAddress.
    // If NamedAddress is used this is a custom and specific value for each
    // implementation to handle (and add validation for) according to their
    // own needs.
    // For IPAddress the implementor may expect either IPv4 or IPv6.
    // Support: Core (IPAddress)
    // Support: Custom (NamedAddress)
    // +optional
    // +kubebuilder:validation:Enum=IPAddress;NamedAddress
    // +kubebuilder:default=IPAddress
    Type *AddressType `json:"type,omitempty"`

    // Value of the address. The validity of the values will depend
    // on the type and support by the controller.
    // If implementations support proxy-protocol (see:
    // they
    // must respect the connection metadata from proxy-protocol
    // in the match logic implemented for these address values.
    // Examples: ``, `128::1`, `my-named-address`.
    // Support: Core
    // +kubebuilder:validation:MinLength=1
    // +kubebuilder:validation:MaxLength=253
    Value string `json:"value"`

AddressRouteMatches Type

Using the new AddressMatch type matches can be expressed in topical lists on TCPRoute and UDPRoute using the new AddressRouteMatches type:

type AddressRouteMatches struct {
    // SourceAddresses indicates the originating (source) network
    // addresses which are valid for routing traffic.
    // Support: Core
    SourceAddresses []AddressMatch `json:"sourceAddresses"`

    // DestinationAddresses indicates the destination network addresses
    // which are valid for routing traffic.
    // Support: Core
    DestinationAddresses []AddressMatch `json:"destinationAddresses"`

This type becomes an optional field and shared by both TCPRouteRule and UDPRouteRule as a list:

type TCPRouteRule struct {
    // Matches add rules for filtering traffic to backends based on addresses.
    // +optional
    Matches []AddressRouteMatches `json:"matches,omitempty"`

Each element in []AddressRouteMatches should be implemented as an OR style match (e.g. the inbound traffic matches as long as at least one of the separate AddressRouteMatches rules is matched).

The above would make the following YAML examples possible:

kind: TCPRoute
  name: matching
  - matches:
    - sourceAddresses:
      - value: ""
      - value: "FE80::0202:B3FF:FE1E:8329"
      - type: NamedAddress
        value: "my-custom-name"
      - value: ""
    - name: my-service
      port: 8080


Pure Gateway Mode

Technically the existing specification supported this kind of matching through Gateway object Listeners and it was considered to simply document that further and expand upon it, but in a desire to better support more complex setups that are becoming commonplace in the ecosystem (e.g. service mesh) there was sufficient cause to add this functionality at the route level.

Copying NetworkPolicy

After the first draft of this document we consulted the NetworkPolicy API to determine if there were enough similarities to copy some of the semantics there to here. Both the existing API and (at the time of writing) the upcoming API were reviewed. Ultimately some influence was taken from NetworkPolicyPort to define the PolicyMatch structure here, but some ideas such as binding ports and network addresses together in a single struct did not seem necessary as the RuleAction present in policy did not seem applicable for this work at the time. We may want to revisit this as the new policy work merges and matures.

Port Matching

While we were able to think of some cases for port matching, the constraints of listeners for the Gateway make it much harder to understand the value at this stage. We're deferring port matching to focus on address matching for this iteration so that we can come back around to it separately once we've gathered more use case information.

CIDR AddressType

When using AddressType as a component to AddressMatch it was considered to add a new type CIDRAddress which would allow matching against an entire subnet. This sounds good, but given a lack of concrete feedback on an immediate need for this in the original issue #727 it was decided that this could wait for now and just as easily be added later in a backwards compatible manner.


A related conversation in #727 ultimately instigated these new requirements and may be helpful to review.

Back to top