data-plane-api/api/rds.proto

// This is heavily derived from
// https://lyft.github.io/envoy/docs/configuration/http_conn_man/route_config/route_config.html#config-http-conn-man-route-table.
// The v2 gRPC API differences are tagged with [V2-API-DIFF].

syntax = "proto3";

package envoy.api.v2;

import "api/base.proto";

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

// The resource_names field in DiscoveryRequest specifies a route configuration.
// This allows an Envoy configuration with multiple HTTP listeners (and
// associated HTTP connection manager filters) to use different route
// configurations. Each listener will bind its HTTP connection manager filter to
// a route table via this identifier.
service RouteDiscoveryService {
  rpc StreamRoutes(stream DiscoveryRequest)
      returns (stream DiscoveryResponse) {
  }

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

// Compared to the cluster field that specifies a single upstream cluster as the
// target of a request, the weighted_clusters option allows for specification of
// multiple upstream clusters along with weights that indicate the percentage of
// traffic to be forwarded to each cluster. The router selects an upstream
// cluster based on the weights.
message WeightedCluster {
  message ClusterWeight {
    // Name of the upstream cluster. The cluster must exist in the cluster
    // manager configuration.
    string name = 1;
    // An integer between 0-100. When a request matches the route, the choice of
    // an upstream cluster is determined by its weight. The sum of weights
    // across all entries in the clusters array must add up to 100.
    google.protobuf.UInt32Value weight = 2;
    // Optional endpoint metadata match criteria. Only endpoints in the upstream
    // cluster with metadata matching that set in metadata_match will be
    // considered. The filter name should be specified as "envoy.lb".
    Metadata metadata_match = 3;
  }
  // Specifies one or more upstream clusters associated with the route.
  repeated ClusterWeight clusters = 1;
  // Specifies the runtime key prefix that should be used to construct the
  // runtime keys associated with each cluster. When the runtime_key_prefix is
  // specified, the router will look for weights associated with each upstream
  // cluster under the key runtime_key_prefix + "." + cluster[i].name where
  // cluster[i] denotes an entry in the clusters array field. If the runtime
  // key for the cluster does not exist, the value specified in the
  // configuration file will be used as the default weight. See the runtime
  // documentation for how key names map to the underlying implementation.
  string runtime_key_prefix = 2;
}

message RouteMatch {
  // A path specifier must be present.
  oneof path_specifier {
    // If specified, the route is a prefix rule meaning that the prefix must
    // match the beginning of the :path header.
    string prefix = 1;

    // If specified, the route is an exact path rule meaning that the path must
    // exactly match the :path header once the query string is removed.
    string path = 2;

    // If specified, the route is a regular expression match on the :path header
    // once the query string is removed [V2-API-DIFF].
    string regex = 3;
  }
  // Indicates that prefix/path matching should be case insensitive. The default
  // is true.
  google.protobuf.BoolValue case_sensitive = 4;

  // Indicates that the route should additionally match on a runtime key. An
  // integer between 0-100. Every time the route is considered for a match, a
  // random number between 0-99 is selected. If the number is <= the value found
  // in the key (checked first) or, if the key is not present, the default
  // value, the route is a match (assuming everything also about the route
  // matches).
  // A runtime route configuration can be used to roll out route changes in a
  // gradual manner without full code/config deploys. Refer to traffic shifting
  // docs for additional documentation.
  RuntimeUInt32 runtime = 5;

  // Specifies a set of headers that the route should match on. The router will
  // check the request’s headers against all the specified headers in the route
  // config. A match will happen if all the headers in the route are present in
  // the request with the same values (or based on presence if the value field
  // is not in the config).
  repeated HeaderMatcher headers = 6;
}

message RouteAction {
  oneof cluster_specifier {
    // Indicates the upstream cluster to which the request should be routed
    // to.
    string cluster = 1;
    // Envoy will determine the cluster to route to by reading the value of the
    // HTTP header named by cluster_header from the request headers. If the
    // header is not found or the referenced cluster does not exist, Envoy will
    // return a 404 response.
    string cluster_header = 2;
    // Multiple upstream clusters can be specified for a given route. The
    // request is routed to one of the upstream clusters based on weights
    // assigned to each cluster. See traffic splitting for additional
    // documentation.
    WeightedCluster weighted_clusters = 3;
  }

  // Optional endpoint metadata match criteria. Only endpoints in the upstream
  // cluster with metadata matching that set in metadata_match will be
  // considered. The filter name should be specified as "envoy.lb".
  Metadata metadata_match = 4;

  // Indicates that during forwarding, the matched prefix (or path) should be
  // swapped with this value. This option allows application URLs to be rooted
  // at a different path from those exposed at the reverse proxy layer.
  string prefix_rewrite = 5;
  oneof host_rewrite_specifier {
    // Indicates that during forwarding, the host header will be swapped with
    // this value.
    string host_rewrite = 6;
    // Indicates that during forwarding, the host header will be swapped with
    // the hostname of the upstream host chosen by the cluster manager. This
    // option is applicable only when the destination cluster for a route is of
    // type strict_dns or logical_dns. Setting this to true with other cluster
    // types has no effect.
    google.protobuf.BoolValue auto_host_rewrite = 7;
  }

  // Specifies the timeout for the route. If not specified, the default is 15s.
  // Note that this timeout includes all retries. See also
  // x-envoy-upstream-rq-timeout-ms, x-envoy-upstream-rq-per-try-timeout-ms, and
  // the retry overview.
  google.protobuf.Duration timeout = 8;

  message RetryPolicy {
    // Specifies the conditions under which retry takes place. These are the
    // same conditions documented for x-envoy-retry-on.
    string retry_on = 1;
    // Specifies the allowed number of retries. This parameter is optional and
    // defaults to 1. These are the same conditions documented for
    // x-envoy-max-retries.
    google.protobuf.UInt32Value num_retries = 2;
    // Specifies a non-zero timeout per retry attempt. This parameter is
    // optional. The same conditions documented for
    // x-envoy-upstream-rq-per-try-timeout-ms apply.
    google.protobuf.Duration per_try_timeout = 3;
  }
  // Indicates that the route has a retry policy.
  RetryPolicy retry_policy = 9;

  // Indicates that the route has a request mirroring policy.
  message RequestMirrorPolicy {
    // Specifies the cluster that requests will be mirrored to. The cluster must
    // exist in the cluster manager configuration.
    string cluster = 1;
    // If not specified, all requests to the target cluster will be mirrored. If
    // specified, Envoy will lookup the runtime key to get the % of requests to
    // mirror. Valid values are from 0 to 10000, allowing for increments of
    // 0.01% of requests to be mirrored. If the runtime key is specified in the
    // configuration but not present in runtime, 0 is the default and thus 0% of
    // requests will be mirrored.
    string runtime_key = 2;
  }
  RequestMirrorPolicy request_mirror_policy = 10;

  RoutingPriority priority = 11;

  // Specifies a set of headers that will be added to requests matching this
  // route.
  repeated HeaderValueOption request_headers_to_add = 12;

  // Specifies a set of rate limit configurations that could be applied to the
  // route.
  repeated RateLimit rate_limits = 13;

  // Specifies if the rate limit filter should include the virtual host rate
  // limits. By default, if the route configured rate limits, the virtual host
  // rate_limits are not applied to the request.
  google.protobuf.BoolValue include_vh_rate_limits = 14;

  message HashPolicy {
    // [V2-API-DIFF] We expect additional hash policies in the future, e.g.
    // cookie based, originating IP, etc.
    message Header {
      // The name of the request header that will be used to obtain the hash
      // key. If the request header is not present, the load balancer will use a
      // random number as the hash, effectively making the load balancing policy
      // random.
      string header_name = 1;
    }
    // Envoy supports two types of cookie affinity:
    //
    // 1. Passive. Envoy takes a cookie that's present in the cookies header and
    //    hashes on its value.
    //
    // 2. Generated. Envoy generates and sets a cookie with an expiration (TTL)
    //    on the first request from the client in its response to the client,
    //    based on the endpoint the request gets sent to. The client then
    //    presents this on the next and all subsequent requests, the hash of
    //    this is sufficient to ensure these requests get sent to the same
    //    endpoint.
    message Cookie {
      // The name of the cookie that will be used to obtain the hash key. If the
      // cookie is not present and ttl below is not set, the load balancer will
      // use a random number as the hash, effectively making the load balancing
      // policy random.
      string name = 1;
      // If specified, a cookie with the TTL will be generated if the cookie is
      // not present.
      google.protobuf.Duration ttl = 2;
    }
    message ConnectionProperties {
      // Hash on source IP address.
      bool source_ip = 1;
    }
    oneof policy_specifier {
      Header header = 1;
      Cookie cookie = 2;
      ConnectionProperties connection_properties = 3;
    }
  }
  repeated HashPolicy hash_policy = 15;

  // Indicates that a HTTP/1.1 client connection to this particular route
  // should be allowed (and expected) to upgrade to a WebSocket connection. The
  // default is false.
  //
  // Attention
  //
  // If set to true, Envoy will expect the first request matching this route to
  // contain WebSocket upgrade headers. If the headers are not present, the
  // connection will be rejected. If set to true, Envoy will setup plain TCP
  // proxying between the client and the upstream server. Hence, an upstream
  // server that rejects the WebSocket upgrade request is also responsible for
  // closing the associated connection. Until then, Envoy will continue to
  // proxy data from the client to the upstream server.
  //
  // Redirects, timeouts and retries are not supported on routes where
  // websocket upgrades are allowed.
  google.protobuf.BoolValue use_websocket = 16;
}

message RedirectAction {
  // A 302 redirect response will be sent which swaps the host portion of the
  // URL with this value.
  string host_redirect = 1;
  // A 302 redirect response will be sent which swaps the path portion of the
  // URL with this value.
  string path_redirect = 2;
}

// The match/action distinction in Route is surfaced explicitly in the v2 API
// [V2-API-DIFF].
message Route {
  RouteMatch match = 1;

  oneof action {
    // Route request to some upstream cluster.
    RouteAction route = 2;
    // Return a 302 redirect.
    RedirectAction redirect = 3;
  }

  // See base.Metadata description.
  Metadata metadata = 4;
}

// A virtual cluster is a way of specifying a regex matching rule against
// certain important endpoints such that statistics are generated explicitly for
// the matched requests. The reason this is useful is that when doing
// prefix/path matching Envoy does not always know what the application
// considers to be an endpoint. Thus, it’s impossible for Envoy to generically
// emit per endpoint statistics. However, often systems have highly critical
// endpoints that they wish to get “perfect” statistics on. Virtual cluster
// statistics are perfect in the sense that they are emitted on the downstream
// side such that they include network level failures.
message VirtualCluster {
  // Specifies a regex pattern to use for matching requests.
  string pattern = 1;

  // Specifies the name of the virtual cluster. The virtual cluster name as well
  // as the virtual host name are used when emitting statistics.
  string name = 2;

  // Optionally specifies the HTTP method to match on. For example GET, PUT,
  // etc.
  RequestMethod method = 3;
}

// See
// https://lyft.github.io/envoy/docs/configuration/http_conn_man/route_config/rate_limits.html
message RateLimit {
  // Refers to the stage set in the filter. The rate limit configuration only
  // applies to filters with the same stage number. The default stage number is
  // 0.
  // NOTE: The filter supports a range of 0 - 10 inclusively for stage numbers.
  google.protobuf.UInt32Value stage = 1;

  // The key to be set in runtime to disable this rate limit configuration.
  string disable_key = 2;

  message Action {
    // The following descriptor entry is appended to the descriptor:
    // ("source_cluster", "<local service cluster>")
    message SourceCluster {
    }

    // The following descriptor entry is appended to the descriptor:
    // ("destination_cluster", "<routed target cluster>")
    message DestinationCluster {
    }

    // The following descriptor entry is appended when a header contains a key
    // that matches the header_name:
    // ("<descriptor_key>", "<header_value_queried_from_header>")
    message RequestHeaders {
      // The header name to be queried from the request headers. The header’s
      // value is used to populate the value of the descriptor entry for the
      // descriptor_key.
      string header_name = 1;
      // The key to use in the descriptor entry.
      string descriptor_key = 2;
    }

    // The following descriptor entry is appended to the descriptor and is
    // populated using the trusted address from x-forwarded-for:
    // ("remote_address", "<trusted address from x-forwarded-for>")
    message RemoteAddress {
    }

    // The following descriptor entry is appended to the descriptor:
    // ("generic_key", "<descriptor_value>")
    message GenericKey {
      // The value to use in the descriptor entry.
      string descriptor_value = 1;
    }

    // The following descriptor entry is appended to the descriptor:
    // (“header_match”, “<descriptor_value>”)
    message HeaderValueMatch {
      // The value to use in the descriptor entry.
      string descriptor_value = 1;
      // If set to true, the action will append a descriptor entry when the
      // request matches the headers. If set to false, the action will append a
      // descriptor entry when the request does not match the headers. The
      // default value is true.
      google.protobuf.BoolValue expect_match = 2;
      // Specifies a set of headers that the rate limit action should match
      // on. The action will check the request’s headers against all the
      // specified headers in the config. A match will happen if all the
      // headers in the config are present in the request with the same values
      // (or based on presence if the value field is not in the config).
      repeated HeaderMatcher headers = 3;
    }

    oneof action_specifier {
      SourceCluster source_cluster = 1;
      DestinationCluster destination_cluster = 2;
      RequestHeaders request_headers = 3;
      RemoteAddress remote_address = 4;
      GenericKey generic_key = 5;
      HeaderValueMatch header_value_match = 6;
    }
  }
  // A list of actions that are to be applied for this rate limit configuration.
  // Order matters as the actions are processed sequentially and the descriptor
  // is composed by appending descriptor entries in that sequence. If an action
  // cannot append a descriptor entry, no descriptor is generated for the
  // configuration. See composing actions for additional documentation.
  repeated Action actions = 3;
}

message HeaderMatcher {
  // Specifies the name of the header in the request.
  string name = 1;
  // Specifies the value of the header. If the value is absent a request that
  // has the name header will match, regardless of the header’s value.
  string value = 2;
  // Specifies whether the header value is a regular expression or not.
  // Defaults to false.
  google.protobuf.BoolValue regex = 3;
}

message VirtualHost {
  // The logical name of the virtual host. This is used when emitting certain
  // statistics but is not relevant for routing.
  string name = 1;

  // A list of domains (host/authority header) that will be matched to this
  // virtual host. Wildcard hosts are supported in the form of “*.foo.com” or
  // “*-bar.foo.com”. Note that the wildcard will not match the empty string.
  // e.g. “*-bar.foo.com” will match “baz-bar.foo.com” but not “-bar.foo.com”.
  // Additionally, a special entry “*” is allowed which will match any
  // host/authority header. Only a single virtual host in the entire route
  // configuration can match on “*”. A domain must be unique across all virtual
  // hosts or the config will fail to load.
  repeated string domains = 2;

  // The list of routes that will be matched, in order, for incoming requests.
  // The first route that matches will be used.
  repeated Route routes = 3;

  enum TlsRequirementType {
    // No TLS requirement for the virtual host.
    NONE = 0;
    // External requests must use TLS. If a request is external and it is not
    // using TLS, a 302 redirect will be sent telling the client to use HTTPS.
    EXTERNAL_ONLY = 1;
    // All requests must use TLS. If a request is not using TLS, a 302 redirect
    // will be sent telling the client to use HTTPS.
    ALL = 2;
  }
  // Specifies the type of TLS enforcement the virtual host expects.
  TlsRequirementType require_tls = 4;

  // A list of virtual clusters defined for this virtual host. Virtual clusters
  // are used for additional statistics gathering.
  repeated VirtualCluster virtual_clusters = 5;

  // Specifies a set of rate limit configurations that will be applied to the
  // virtual host.
  repeated RateLimit rate_limits = 6;

  // Specifies a list of HTTP headers that should be added to each request
  // handled by this virtual host. In the presence of duplicate header keys,
  // precedence rules apply.
  repeated HeaderValueOption request_headers_to_add = 7;
}

message RouteConfiguration {
  // The name of the route configuration. For example, it might match the
  // router_config_name in the HttpConnectionManager > route_specifier > rds
  // message.
  string name = 1;

  // An array of virtual hosts that make up the route table.
  repeated VirtualHost virtual_hosts = 2;

  // Specifies a list of HTTP headers that the connection manager will consider
  // to be internal only. If they are found on external requests they will be
  // cleaned prior to filter invocation. See x-envoy-internal for more
  // information.
  repeated string internal_only_headers = 3;

  // Specifies a list of HTTP headers that should be added to each response that
  // the connection manager encodes.
  repeated HeaderValueOption response_headers_to_add = 4;

  // Specifies a list of HTTP headers that should be removed from each response
  // that the connection manager encodes.
  repeated string response_headers_to_remove = 5;

  // Specifies a list of HTTP headers that should be added to each request
  // routed by the HTTP connection manager. In the presence of duplicate
  // header keys, precendence rules apply.
  repeated HeaderValueOption request_headers_to_add = 6;

  // An optional boolean that specifies whether the clusters that the route
  // table refers to will be validated by the cluster manager. If set to true
  // and a route refers to a non-existent cluster, the route table will not
  // load. If set to false and a route refers to a non-existent cluster, the
  // route table will load and the router filter will return a 404 if the route
  // is selected at runtime. This setting defaults to true if the route table
  // is statically defined via the route_config option. This setting default to
  // false if the route table is loaded dynamically via the rds option. Users
  // may which to override the default behavior in certain cases (for example
  // when using CDS with a static route table).
  google.protobuf.BoolValue validate_clusters = 7;
}