data-plane-api/api/lds.proto

// This is heavily derived from
// https://lyft.github.io/envoy/docs/configuration/listeners/listeners.html
// The v2 gRPC API differences are tagged with [V2-API-DIFF].

syntax = "proto3";

package envoy.api.v2;

import "api/address.proto";
import "api/base.proto";
import "api/discovery.proto";
import "api/sds.proto";

import "google/api/annotations.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

// The Envoy instance initiates an RPC at startup to discover a list of
// listeners. Updates are delivered via streaming from the LDS server and
// consist of a complete update of all listeners. Existing connections will be
// allowed to drain from listeners that are no longer present.
service ListenerDiscoveryService {
  rpc StreamListeners(stream DiscoveryRequest)
      returns (stream DiscoveryResponse) {
  }

  rpc FetchListeners(DiscoveryRequest)
      returns (DiscoveryResponse) {
    option (google.api.http) = {
      post: "/v2/discovery:listeners"
      body: "*"
    };
  }
}

message Filter {
  // The name of the filter to instantiate. The name must match a supported
  // filter.
  string name = 1;
  // Filter specific configuration which depends on the filter being
  // instantiated. See the supported filters for further documentation.
  google.protobuf.Struct config = 2;

  message DeprecatedV1 {
    string type = 1;
  }
  DeprecatedV1 deprecated_v1 = 3;
}

// Specifies the match criteria for selecting a specific filter chain for a
// listener [V2-API-DIFF].
message FilterChainMatch {
  // If non-empty, the SNI domains to consider. May contain a wildcard prefix,
  // e.g. *.example.com.
  repeated string sni_domains = 1;

  // If non-empty, an IP address and prefix length to match addresses when the
  // listener is bound to 0.0.0.0/:: or when use_original_dst is specified.
  repeated CidrRange prefix_ranges = 3;

  // If non-empty, an IP address and suffix length to match addresses when the
  // listener is bound to 0.0.0.0/:: or when use_original_dst is specified.
  string address_suffix = 4;
  google.protobuf.UInt32Value suffix_len = 5;

  // The criteria is satisfied if the source IP address of the downstream
  // connection is contained in at least one of the specified subnets. If the
  // parameter is not specified or the list is empty, the source IP address is
  // ignored.
  repeated CidrRange source_prefix_ranges = 6;

  // The criteria is satisfied if the source port of the downstream connection
  // is contained in at least one of the specified ports. If the parameter is
  // not specified, the source port is ignored.
  repeated google.protobuf.UInt32Value source_ports = 7;

  // Optional destination port to consider when use_original_dst is set on the
  // listener in determining a filter chain match.
  google.protobuf.UInt32Value destination_port = 8;
}

// Grouping of FilterChainMatch criteria, DownstreamTlsContext, the actual filter chain
// and related parameters.
message FilterChain {
  FilterChainMatch filter_chain_match = 1;
  DownstreamTlsContext tls_context = 2;
  // A list of individual network filters that make up the filter chain for
  // connections established with the listener. Order matters as the filters are
  // processed sequentially as connection events happen.  Note: If the filter
  // list is empty, the connection will close by default.
  repeated Filter filters = 3;

  // Whether the listener should expect a PROXY protocol V1 header on new
  // connections. If this option is enabled, the listener will assume that that
  // remote address of the connection is the one specified in the header. Some
  // load balancers including the AWS ELB support this option. If the option is
  // absent or set to false, Envoy will use the physical peer address of the
  // connection as the remote address.
  google.protobuf.BoolValue use_proxy_proto = 4;

  // See base.Metadata description.
  Metadata metadata = 5;

  // See base.TransportSocket description.
  TransportSocket transport_socket = 6;
}

message Listener {
  // The unique name of the listener. If no name is provided, Envoy will generate a
  // UUID for internal use. The name is used for dynamic listener update and removal
  // via the LDS APIs.
  string name = 1;

  // The address that the listener should listen on.
  Address address = 2;

  // A list of filter chains to consider for this listener. The FilterChain with
  // the most specific FilterChainMatch criteria is used on a connection. The
  // algorithm works as follows:
  // 1. If SNI information is presented at connection time, only the
  //    FilterChains matching the SNI are considered. Otherwise, only
  //    FilterChains with no SNI domains are considered.
  // 2. Of the FilterChains from step 1, the longest prefix match on the
  //    bound destination address is used to select the next set of
  //    FilterChains. This may be one FilterChain or multiple if there is
  //    a tie.
  // 3. The longest suffix match on the bound destination address is used to
  //    select the FilterChain from step 2 that is used.
  repeated FilterChain filter_chains = 3;

  // If a connection is redirected using iptables, the port on which the proxy
  // receives it might be different from the original destination port. When
  // this flag is set to true, the listener uses the original destination
  // address and port during FilterChain matching. Default is false.
  google.protobuf.BoolValue use_original_dst = 4;

  // Soft limit on size of the listener’s new connection read and write buffers.
  // If unspecified, an implementation defined default is applied (1MiB).
  google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5;

  // See base.Metadata description.
  Metadata metadata = 6;

  message DeprecatedV1 {
    // Whether the listener should bind to the port. A listener that doesn’t
    // bind can only receive connections redirected from other listeners that
    // set use_original_dst parameter to true. Default is true.
    //
    // [V2-API-DIFF] This is deprecated in v2, all Listeners will bind to their
    // port. An additional filter chain must be created for every original
    // destination port this listener may redirect to in v2, with the original
    // port specified in the FilterChainMatch destination_port field.
    google.protobuf.BoolValue bind_to_port = 1;
  }
  DeprecatedV1 deprecated_v1 = 7;

  enum DrainType {
    // Drain in response to calling /healthcheck/fail admin endpoint (along with the health check
    // filter), listener removal/modification, and hot restart.
    DEFAULT = 0;
    // Drain in response to listener removal/modification and hot restart. This setting does not
    // include /healthcheck/fail. This setting may be desirable if Envoy is hosting both ingress
    // and egress listeners.
    MODIFY_ONLY = 1;
  }

  // The type of draining to perform at a listener-wide level.
  DrainType drain_type = 8;
}