diff --git a/BUILD b/BUILD index 265a70db..bbcd60b0 100644 --- a/BUILD +++ b/BUILD @@ -90,6 +90,7 @@ proto_library( "//envoy/config/resource_monitor/injected_resource/v2alpha:pkg", "//envoy/config/retry/previous_priorities:pkg", "//envoy/config/route/v3alpha:pkg", + "//envoy/config/tap/v3alpha:pkg", "//envoy/config/trace/v2:pkg", "//envoy/config/trace/v2alpha:pkg", "//envoy/config/trace/v3alpha:pkg", diff --git a/envoy/admin/v2alpha/config_dump.proto b/envoy/admin/v2alpha/config_dump.proto index c5d9aa7b..d1e7d4af 100644 --- a/envoy/admin/v2alpha/config_dump.proto +++ b/envoy/admin/v2alpha/config_dump.proto @@ -3,10 +3,10 @@ syntax = "proto3"; package envoy.admin.v2alpha; import "envoy/api/v2/auth/cert.proto"; -import "envoy/api/v2/cds.proto"; +import "envoy/api/v2/cluster.proto"; import "envoy/api/v2/listener.proto"; -import "envoy/api/v2/rds.proto"; -import "envoy/api/v2/srds.proto"; +import "envoy/api/v2/route.proto"; +import "envoy/api/v2/scoped_route.proto"; import "envoy/config/bootstrap/v2/bootstrap.proto"; import "google/protobuf/any.proto"; diff --git a/envoy/admin/v3alpha/BUILD b/envoy/admin/v3alpha/BUILD index e16c4914..5de70fa0 100644 --- a/envoy/admin/v3alpha/BUILD +++ b/envoy/admin/v3alpha/BUILD @@ -8,12 +8,12 @@ api_proto_package( deps = [ "//envoy/admin/v2alpha:pkg", "//envoy/config/bootstrap/v3alpha:pkg", + "//envoy/config/cluster/v3alpha:pkg", "//envoy/config/core/v3alpha:pkg", "//envoy/config/listener/v3alpha:pkg", + "//envoy/config/route/v3alpha:pkg", + "//envoy/config/tap/v3alpha:pkg", "//envoy/extensions/transport_sockets/tls/v3alpha:pkg", - "//envoy/service/cluster/v3alpha:pkg", - "//envoy/service/route/v3alpha:pkg", - "//envoy/service/tap/v3alpha:pkg", "//envoy/type/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], diff --git a/envoy/admin/v3alpha/config_dump.proto b/envoy/admin/v3alpha/config_dump.proto index 2688bab5..af801e8d 100644 --- a/envoy/admin/v3alpha/config_dump.proto +++ b/envoy/admin/v3alpha/config_dump.proto @@ -3,11 +3,11 @@ syntax = "proto3"; package envoy.admin.v3alpha; import "envoy/config/bootstrap/v3alpha/bootstrap.proto"; +import "envoy/config/cluster/v3alpha/cluster.proto"; import "envoy/config/listener/v3alpha/listener.proto"; +import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/scoped_route.proto"; import "envoy/extensions/transport_sockets/tls/v3alpha/cert.proto"; -import "envoy/service/cluster/v3alpha/cds.proto"; -import "envoy/service/route/v3alpha/rds.proto"; -import "envoy/service/route/v3alpha/srds.proto"; import "google/protobuf/any.proto"; import "google/protobuf/timestamp.proto"; @@ -164,7 +164,7 @@ message ClustersConfigDump { "envoy.admin.v2alpha.ClustersConfigDump.StaticCluster"; // The cluster config. - service.cluster.v3alpha.Cluster cluster = 1; + config.cluster.v3alpha.Cluster cluster = 1; // The timestamp when the Cluster was last updated. google.protobuf.Timestamp last_updated = 2; @@ -183,7 +183,7 @@ message ClustersConfigDump { string version_info = 1; // The cluster config. - service.cluster.v3alpha.Cluster cluster = 2; + config.cluster.v3alpha.Cluster cluster = 2; // The timestamp when the Cluster was last updated. google.protobuf.Timestamp last_updated = 3; @@ -223,7 +223,7 @@ message RoutesConfigDump { "envoy.admin.v2alpha.RoutesConfigDump.StaticRouteConfig"; // The route config. - service.route.v3alpha.RouteConfiguration route_config = 1; + config.route.v3alpha.RouteConfiguration route_config = 1; // The timestamp when the Route was last updated. google.protobuf.Timestamp last_updated = 2; @@ -240,7 +240,7 @@ message RoutesConfigDump { string version_info = 1; // The route config. - service.route.v3alpha.RouteConfiguration route_config = 2; + config.route.v3alpha.RouteConfiguration route_config = 2; // The timestamp when the Route was last updated. google.protobuf.Timestamp last_updated = 3; @@ -269,7 +269,7 @@ message ScopedRoutesConfigDump { string name = 1; // The scoped route configurations. - repeated service.route.v3alpha.ScopedRouteConfiguration scoped_route_configs = 2; + repeated config.route.v3alpha.ScopedRouteConfiguration scoped_route_configs = 2; // The timestamp when the scoped route config set was last updated. google.protobuf.Timestamp last_updated = 3; @@ -289,7 +289,7 @@ message ScopedRoutesConfigDump { string version_info = 2; // The scoped route configurations. - repeated service.route.v3alpha.ScopedRouteConfiguration scoped_route_configs = 3; + repeated config.route.v3alpha.ScopedRouteConfiguration scoped_route_configs = 3; // The timestamp when the scoped route config set was last updated. google.protobuf.Timestamp last_updated = 4; diff --git a/envoy/admin/v3alpha/tap.proto b/envoy/admin/v3alpha/tap.proto index aaf23c56..5eda5e73 100644 --- a/envoy/admin/v3alpha/tap.proto +++ b/envoy/admin/v3alpha/tap.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.admin.v3alpha; -import "envoy/service/tap/v3alpha/common.proto"; +import "envoy/config/tap/v3alpha/common.proto"; import "udpa/annotations/versioning.proto"; @@ -21,5 +21,5 @@ message TapRequest { string config_id = 1 [(validate.rules).string = {min_bytes: 1}]; // The tap configuration to load. - service.tap.v3alpha.TapConfig tap_config = 2 [(validate.rules).message = {required: true}]; + config.tap.v3alpha.TapConfig tap_config = 2 [(validate.rules).message = {required: true}]; } diff --git a/envoy/api/v2/cds.proto b/envoy/api/v2/cds.proto index 8b044e80..622f6509 100644 --- a/envoy/api/v2/cds.proto +++ b/envoy/api/v2/cds.proto @@ -2,27 +2,13 @@ syntax = "proto3"; package envoy.api.v2; -import "envoy/api/v2/auth/cert.proto"; -import "envoy/api/v2/cluster/circuit_breaker.proto"; -import "envoy/api/v2/cluster/filter.proto"; -import "envoy/api/v2/cluster/outlier_detection.proto"; -import "envoy/api/v2/core/address.proto"; -import "envoy/api/v2/core/base.proto"; -import "envoy/api/v2/core/config_source.proto"; -import "envoy/api/v2/core/health_check.proto"; -import "envoy/api/v2/core/protocol.proto"; import "envoy/api/v2/discovery.proto"; -import "envoy/api/v2/eds.proto"; -import "envoy/type/percent.proto"; import "google/api/annotations.proto"; -import "google/protobuf/any.proto"; -import "google/protobuf/duration.proto"; -import "google/protobuf/struct.proto"; -import "google/protobuf/wrappers.proto"; import "udpa/annotations/migrate.proto"; -import "validate/validate.proto"; + +import public "envoy/api/v2/cluster.proto"; option java_package = "io.envoyproxy.envoy.api.v2"; option java_outer_classname = "CdsProto"; @@ -30,7 +16,7 @@ option java_multiple_files = true; option java_generic_services = true; option (udpa.annotations.file_migrate).move_to_package = "envoy.service.cluster.v3alpha"; -// [#protodoc-title: Clusters] +// [#protodoc-title: CDS] // Return list of all clusters this proxy will load balance to. service ClusterDiscoveryService { @@ -46,809 +32,7 @@ service ClusterDiscoveryService { } } -// Configuration for a single upstream cluster. -// [#next-free-field: 46] -message Cluster { - // Refer to :ref:`service discovery type ` - // for an explanation on each type. - enum DiscoveryType { - // Refer to the :ref:`static discovery type` - // for an explanation. - STATIC = 0; - - // Refer to the :ref:`strict DNS discovery - // type` - // for an explanation. - STRICT_DNS = 1; - - // Refer to the :ref:`logical DNS discovery - // type` - // for an explanation. - LOGICAL_DNS = 2; - - // Refer to the :ref:`service discovery type` - // for an explanation. - EDS = 3; - - // Refer to the :ref:`original destination discovery - // type` - // for an explanation. - ORIGINAL_DST = 4; - } - - // Refer to :ref:`load balancer type ` architecture - // overview section for information on each type. - enum LbPolicy { - // Refer to the :ref:`round robin load balancing - // policy` - // for an explanation. - ROUND_ROBIN = 0; - - // Refer to the :ref:`least request load balancing - // policy` - // for an explanation. - LEAST_REQUEST = 1; - - // Refer to the :ref:`ring hash load balancing - // policy` - // for an explanation. - RING_HASH = 2; - - // Refer to the :ref:`random load balancing - // policy` - // for an explanation. - RANDOM = 3; - - // Refer to the :ref:`original destination load balancing - // policy` - // for an explanation. - // - // .. attention:: - // - // **This load balancing policy is deprecated**. Use CLUSTER_PROVIDED instead. - // - ORIGINAL_DST_LB = 4 [deprecated = true]; - - // Refer to the :ref:`Maglev load balancing policy` - // for an explanation. - MAGLEV = 5; - - // This load balancer type must be specified if the configured cluster provides a cluster - // specific load balancer. Consult the configured cluster's documentation for whether to set - // this option or not. - CLUSTER_PROVIDED = 6; - - // [#not-implemented-hide:] Use the new :ref:`load_balancing_policy - // ` field to determine the LB policy. - // [#next-major-version: In the v3 API, we should consider deprecating the lb_policy field - // and instead using the new load_balancing_policy field as the one and only mechanism for - // configuring this.] - LOAD_BALANCING_POLICY_CONFIG = 7; - } - - // When V4_ONLY is selected, the DNS resolver will only perform a lookup for - // addresses in the IPv4 family. If V6_ONLY is selected, the DNS resolver will - // only perform a lookup for addresses in the IPv6 family. If AUTO is - // specified, the DNS resolver will first perform a lookup for addresses in - // the IPv6 family and fallback to a lookup for addresses in the IPv4 family. - // For cluster types other than - // :ref:`STRICT_DNS` and - // :ref:`LOGICAL_DNS`, - // this setting is - // ignored. - enum DnsLookupFamily { - AUTO = 0; - V4_ONLY = 1; - V6_ONLY = 2; - } - - enum ClusterProtocolSelection { - // Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2). - // If :ref:`http2_protocol_options ` are - // present, HTTP2 will be used, otherwise HTTP1.1 will be used. - USE_CONFIGURED_PROTOCOL = 0; - - // Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection. - USE_DOWNSTREAM_PROTOCOL = 1; - } - - // TransportSocketMatch specifies what transport socket config will be used - // when the match conditions are satisfied. - message TransportSocketMatch { - // The name of the match, used in stats generation. - string name = 1 [(validate.rules).string = {min_len: 1}]; - - // Optional endpoint metadata match criteria. - // The connection to the endpoint with metadata matching what is set in this field - // will use the transport socket configuration specified here. - // The endpoint's metadata entry in *envoy.transport_socket_match* is used to match - // against the values specified in this field. - google.protobuf.Struct match = 2; - - // The configuration of the transport socket. - core.TransportSocket transport_socket = 3; - } - - // Extended cluster type. - message CustomClusterType { - // The type of the cluster to instantiate. The name must match a supported cluster type. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // Cluster specific configuration which depends on the cluster being instantiated. - // See the supported cluster for further documentation. - google.protobuf.Any typed_config = 2; - } - - // Only valid when discovery type is EDS. - message EdsClusterConfig { - // Configuration for the source of EDS updates for this Cluster. - core.ConfigSource eds_config = 1; - - // Optional alternative to cluster name to present to EDS. This does not - // have the same restrictions as cluster name, i.e. it may be arbitrary - // length. - string service_name = 2; - } - - // Optionally divide the endpoints in this cluster into subsets defined by - // endpoint metadata and selected by route and weighted cluster metadata. - // [#next-free-field: 8] - message LbSubsetConfig { - // If NO_FALLBACK is selected, a result - // equivalent to no healthy hosts is reported. If ANY_ENDPOINT is selected, - // any cluster endpoint may be returned (subject to policy, health checks, - // etc). If DEFAULT_SUBSET is selected, load balancing is performed over the - // endpoints matching the values from the default_subset field. - enum LbSubsetFallbackPolicy { - NO_FALLBACK = 0; - ANY_ENDPOINT = 1; - DEFAULT_SUBSET = 2; - } - - // Specifications for subsets. - message LbSubsetSelector { - // Allows to override top level fallback policy per selector. - enum LbSubsetSelectorFallbackPolicy { - // If NOT_DEFINED top level config fallback policy is used instead. - NOT_DEFINED = 0; - - // If NO_FALLBACK is selected, a result equivalent to no healthy hosts is reported. - NO_FALLBACK = 1; - - // If ANY_ENDPOINT is selected, any cluster endpoint may be returned - // (subject to policy, health checks, etc). - ANY_ENDPOINT = 2; - - // If DEFAULT_SUBSET is selected, load balancing is performed over the - // endpoints matching the values from the default_subset field. - DEFAULT_SUBSET = 3; - - // If KEYS_SUBSET is selected, subset selector matching is performed again with metadata - // keys reduced to - // :ref:`fallback_keys_subset`. - // It allows for a fallback to a different, less specific selector if some of the keys of - // the selector are considered optional. - KEYS_SUBSET = 4; - } - - // List of keys to match with the weighted cluster metadata. - repeated string keys = 1; - - // The behavior used when no endpoint subset matches the selected route's - // metadata. - LbSubsetSelectorFallbackPolicy fallback_policy = 2 - [(validate.rules).enum = {defined_only: true}]; - - // Subset of - // :ref:`keys` used by - // :ref:`KEYS_SUBSET` - // fallback policy. - // It has to be a non empty list if KEYS_SUBSET fallback policy is selected. - // For any other fallback policy the parameter is not used and should not be set. - // Only values also present in - // :ref:`keys` are allowed, but - // `fallback_keys_subset` cannot be equal to `keys`. - repeated string fallback_keys_subset = 3; - } - - // The behavior used when no endpoint subset matches the selected route's - // metadata. The value defaults to - // :ref:`NO_FALLBACK`. - LbSubsetFallbackPolicy fallback_policy = 1 [(validate.rules).enum = {defined_only: true}]; - - // Specifies the default subset of endpoints used during fallback if - // fallback_policy is - // :ref:`DEFAULT_SUBSET`. - // Each field in default_subset is - // compared to the matching LbEndpoint.Metadata under the *envoy.lb* - // namespace. It is valid for no hosts to match, in which case the behavior - // is the same as a fallback_policy of - // :ref:`NO_FALLBACK`. - google.protobuf.Struct default_subset = 2; - - // For each entry, LbEndpoint.Metadata's - // *envoy.lb* namespace is traversed and a subset is created for each unique - // combination of key and value. For example: - // - // .. code-block:: json - // - // { "subset_selectors": [ - // { "keys": [ "version" ] }, - // { "keys": [ "stage", "hardware_type" ] } - // ]} - // - // A subset is matched when the metadata from the selected route and - // weighted cluster contains the same keys and values as the subset's - // metadata. The same host may appear in multiple subsets. - repeated LbSubsetSelector subset_selectors = 3; - - // If true, routing to subsets will take into account the localities and locality weights of the - // endpoints when making the routing decision. - // - // There are some potential pitfalls associated with enabling this feature, as the resulting - // traffic split after applying both a subset match and locality weights might be undesirable. - // - // Consider for example a situation in which you have 50/50 split across two localities X/Y - // which have 100 hosts each without subsetting. If the subset LB results in X having only 1 - // host selected but Y having 100, then a lot more load is being dumped on the single host in X - // than originally anticipated in the load balancing assignment delivered via EDS. - bool locality_weight_aware = 4; - - // When used with locality_weight_aware, scales the weight of each locality by the ratio - // of hosts in the subset vs hosts in the original subset. This aims to even out the load - // going to an individual locality if said locality is disproportionately affected by the - // subset predicate. - bool scale_locality_weight = 5; - - // If true, when a fallback policy is configured and its corresponding subset fails to find - // a host this will cause any host to be selected instead. - // - // This is useful when using the default subset as the fallback policy, given the default - // subset might become empty. With this option enabled, if that happens the LB will attempt - // to select a host from the entire cluster. - bool panic_mode_any = 6; - - // If true, metadata specified for a metadata key will be matched against the corresponding - // endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value - // and any of the elements in the list matches the criteria. - bool list_as_any = 7; - } - - // Specific configuration for the LeastRequest load balancing policy. - message LeastRequestLbConfig { - // The number of random healthy hosts from which the host with the fewest active requests will - // be chosen. Defaults to 2 so that we perform two-choice selection if the field is not set. - google.protobuf.UInt32Value choice_count = 1 [(validate.rules).uint32 = {gte: 2}]; - } - - // Specific configuration for the :ref:`RingHash` - // load balancing policy. - message RingHashLbConfig { - // The hash function used to hash hosts onto the ketama ring. - enum HashFunction { - // Use `xxHash `_, this is the default hash function. - XX_HASH = 0; - - // Use `MurmurHash2 `_, this is compatible with - // std:hash in GNU libstdc++ 3.4.20 or above. This is typically the case when compiled - // on Linux and not macOS. - MURMUR_HASH_2 = 1; - } - - reserved 2; - - // Minimum hash ring size. The larger the ring is (that is, the more hashes there are for each - // provided host) the better the request distribution will reflect the desired weights. Defaults - // to 1024 entries, and limited to 8M entries. See also - // :ref:`maximum_ring_size`. - google.protobuf.UInt64Value minimum_ring_size = 1 [(validate.rules).uint64 = {lte: 8388608}]; - - // The hash function used to hash hosts onto the ketama ring. The value defaults to - // :ref:`XX_HASH`. - HashFunction hash_function = 3 [(validate.rules).enum = {defined_only: true}]; - - // Maximum hash ring size. Defaults to 8M entries, and limited to 8M entries, but can be lowered - // to further constrain resource use. See also - // :ref:`minimum_ring_size`. - google.protobuf.UInt64Value maximum_ring_size = 4 [(validate.rules).uint64 = {lte: 8388608}]; - } - - // Specific configuration for the - // :ref:`Original Destination ` - // load balancing policy. - message OriginalDstLbConfig { - // When true, :ref:`x-envoy-original-dst-host - // ` can be used to override destination - // address. - // - // .. attention:: - // - // This header isn't sanitized by default, so enabling this feature allows HTTP clients to - // route traffic to arbitrary hosts and/or ports, which may have serious security - // consequences. - bool use_http_header = 1; - } - - // Common configuration for all load balancer implementations. - // [#next-free-field: 7] - message CommonLbConfig { - // Configuration for :ref:`zone aware routing - // `. - message ZoneAwareLbConfig { - // Configures percentage of requests that will be considered for zone aware routing - // if zone aware routing is configured. If not specified, the default is 100%. - // * :ref:`runtime values `. - // * :ref:`Zone aware routing support `. - type.Percent routing_enabled = 1; - - // Configures minimum upstream cluster size required for zone aware routing - // If upstream cluster size is less than specified, zone aware routing is not performed - // even if zone aware routing is configured. If not specified, the default is 6. - // * :ref:`runtime values `. - // * :ref:`Zone aware routing support `. - google.protobuf.UInt64Value min_cluster_size = 2; - - // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic - // mode`. Instead, the cluster will fail all - // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a - // failing service. - bool fail_traffic_on_panic = 3; - } - - // Configuration for :ref:`locality weighted load balancing - // ` - message LocalityWeightedLbConfig { - } - - // Configures the :ref:`healthy panic threshold `. - // If not specified, the default is 50%. - // To disable panic mode, set to 0%. - // - // .. note:: - // The specified percent will be truncated to the nearest 1%. - type.Percent healthy_panic_threshold = 1; - - oneof locality_config_specifier { - ZoneAwareLbConfig zone_aware_lb_config = 2; - - LocalityWeightedLbConfig locality_weighted_lb_config = 3; - } - - // If set, all health check/weight/metadata updates that happen within this duration will be - // merged and delivered in one shot when the duration expires. The start of the duration is when - // the first update happens. This is useful for big clusters, with potentially noisy deploys - // that might trigger excessive CPU usage due to a constant stream of healthcheck state changes - // or metadata updates. The first set of updates to be seen apply immediately (e.g.: a new - // cluster). Please always keep in mind that the use of sandbox technologies may change this - // behavior. - // - // If this is not set, we default to a merge window of 1000ms. To disable it, set the merge - // window to 0. - // - // Note: merging does not apply to cluster membership changes (e.g.: adds/removes); this is - // because merging those updates isn't currently safe. See - // https://github.com/envoyproxy/envoy/pull/3941. - google.protobuf.Duration update_merge_window = 4; - - // If set to true, Envoy will not consider new hosts when computing load balancing weights until - // they have been health checked for the first time. This will have no effect unless - // active health checking is also configured. - // - // Ignoring a host means that for any load balancing calculations that adjust weights based - // on the ratio of eligible hosts and total hosts (priority spillover, locality weighting and - // panic mode) Envoy will exclude these hosts in the denominator. - // - // For example, with hosts in two priorities P0 and P1, where P0 looks like - // {healthy, unhealthy (new), unhealthy (new)} - // and where P1 looks like - // {healthy, healthy} - // all traffic will still hit P0, as 1 / (3 - 2) = 1. - // - // Enabling this will allow scaling up the number of hosts for a given cluster without entering - // panic mode or triggering priority spillover, assuming the hosts pass the first health check. - // - // If panic mode is triggered, new hosts are still eligible for traffic; they simply do not - // contribute to the calculation when deciding whether panic mode is enabled or not. - bool ignore_new_hosts_until_first_hc = 5; - - // If set to `true`, the cluster manager will drain all existing - // connections to upstream hosts whenever hosts are added or removed from the cluster. - bool close_connections_on_host_set_change = 6; - } - - message RefreshRate { - // Specifies the base interval between refreshes. This parameter is required and must be greater - // than zero and less than - // :ref:`max_interval `. - google.protobuf.Duration base_interval = 1 [(validate.rules).duration = { - required: true - gt {nanos: 1000000} - }]; - - // Specifies the maximum interval between refreshes. This parameter is optional, but must be - // greater than or equal to the - // :ref:`base_interval ` if set. The default - // is 10 times the :ref:`base_interval `. - google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {nanos: 1000000}}]; - } - - reserved 12, 15; - - // Configuration to use different transport sockets for different endpoints. - // The entry of *envoy.transport_socket* in the - // :ref:`LbEndpoint.Metadata ` - // is used to match against the transport sockets as they appear in the list. The first - // :ref:`match ` is used. - // For example, with the following match - // - // .. code-block:: yaml - // - // transport_socket_matches: - // - name: "enableMTLS" - // match: - // acceptMTLS: true - // transport_socket: - // name: envoy.transport_sockets.tls - // config: { ... } # tls socket configuration - // - name: "defaultToPlaintext" - // match: {} - // transport_socket: - // name: envoy.transport_sockets.raw_buffer - // - // Connections to the endpoints whose metadata value under *envoy.transport_socket* - // having "acceptMTLS"/"true" key/value pair use the "enableMTLS" socket configuration. - // - // If a :ref:`socket match ` with empty match - // criteria is provided, that always match any endpoint. For example, the "defaultToPlaintext" - // socket match in case above. - // - // If an endpoint metadata's value under *envoy.transport_socket* does not match any - // *TransportSocketMatch*, socket configuration fallbacks to use the *tls_context* or - // *transport_socket* specified in this cluster. - // - // This field allows gradual and flexible transport socket configuration changes. - // - // The metadata of endpoints in EDS can indicate transport socket capabilities. For example, - // an endpoint's metadata can have two key value pairs as "acceptMTLS": "true", - // "acceptPlaintext": "true". While some other endpoints, only accepting plaintext traffic - // has "acceptPlaintext": "true" metadata information. - // - // Then the xDS server can configure the CDS to a client, Envoy A, to send mutual TLS - // traffic for endpoints with "acceptMTLS": "true", by adding a corresponding - // *TransportSocketMatch* in this field. Other client Envoys receive CDS without - // *transport_socket_match* set, and still send plain text traffic to the same cluster. - // - // [#comment:TODO(incfly): add a detailed architecture doc on intended usage.] - repeated TransportSocketMatch transport_socket_matches = 43; - - // Supplies the name of the cluster which must be unique across all clusters. - // The cluster name is used when emitting - // :ref:`statistics ` if :ref:`alt_stat_name - // ` is not provided. - // Any ``:`` in the cluster name will be converted to ``_`` when emitting statistics. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // An optional alternative to the cluster name to be used while emitting stats. - // Any ``:`` in the name will be converted to ``_`` when emitting statistics. This should not be - // confused with :ref:`Router Filter Header - // `. - string alt_stat_name = 28; - - oneof cluster_discovery_type { - // The :ref:`service discovery type ` - // to use for resolving the cluster. - DiscoveryType type = 2 [(validate.rules).enum = {defined_only: true}]; - - // The custom cluster type. - CustomClusterType cluster_type = 38; - } - - // Configuration to use for EDS updates for the Cluster. - EdsClusterConfig eds_cluster_config = 3; - - // The timeout for new network connections to hosts in the cluster. - google.protobuf.Duration connect_timeout = 4 [(validate.rules).duration = {gt {}}]; - - // Soft limit on size of the cluster’s connections read and write buffers. If - // unspecified, an implementation defined default is applied (1MiB). - google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5; - - // The :ref:`load balancer type ` to use - // when picking a host in the cluster. - LbPolicy lb_policy = 6 [(validate.rules).enum = {defined_only: true}]; - - // If the service discovery type is - // :ref:`STATIC`, - // :ref:`STRICT_DNS` - // or :ref:`LOGICAL_DNS`, - // then hosts is required. - // - // .. attention:: - // - // **This field is deprecated**. Set the - // :ref:`load_assignment` field instead. - // - repeated core.Address hosts = 7; - - // Setting this is required for specifying members of - // :ref:`STATIC`, - // :ref:`STRICT_DNS` - // or :ref:`LOGICAL_DNS` clusters. - // This field supersedes :ref:`hosts` field. - // [#comment:TODO(dio): Deprecate the hosts field and add it to :ref:`deprecated log` - // once load_assignment is implemented.] - // - // .. attention:: - // - // Setting this allows non-EDS cluster types to contain embedded EDS equivalent - // :ref:`endpoint assignments`. - // Setting this overrides :ref:`hosts` values. - // - ClusterLoadAssignment load_assignment = 33; - - // Optional :ref:`active health checking ` - // configuration for the cluster. If no - // configuration is specified no health checking will be done and all cluster - // members will be considered healthy at all times. - repeated core.HealthCheck health_checks = 8; - - // Optional maximum requests for a single upstream connection. This parameter - // is respected by both the HTTP/1.1 and HTTP/2 connection pool - // implementations. If not specified, there is no limit. Setting this - // parameter to 1 will effectively disable keep alive. - google.protobuf.UInt32Value max_requests_per_connection = 9; - - // Optional :ref:`circuit breaking ` for the cluster. - cluster.CircuitBreakers circuit_breakers = 10; - - // The TLS configuration for connections to the upstream cluster. - // - // .. attention:: - // - // **This field is deprecated**. Use `transport_socket` with name `tls` instead. If both are - // set, `transport_socket` takes priority. - auth.UpstreamTlsContext tls_context = 11 [deprecated = true]; - - // Additional options when handling HTTP requests upstream. These options will be applicable to - // both HTTP1 and HTTP2 requests. - core.HttpProtocolOptions common_http_protocol_options = 29; - - // Additional options when handling HTTP1 requests. - core.Http1ProtocolOptions http_protocol_options = 13; - - // Even if default HTTP2 protocol options are desired, this field must be - // set so that Envoy will assume that the upstream supports HTTP/2 when - // making new HTTP connection pool connections. Currently, Envoy only - // supports prior knowledge for upstream connections. Even if TLS is used - // with ALPN, `http2_protocol_options` must be specified. As an aside this allows HTTP/2 - // connections to happen over plain text. - core.Http2ProtocolOptions http2_protocol_options = 14; - - // The extension_protocol_options field is used to provide extension-specific protocol options - // for upstream connections. The key should match the extension filter name, such as - // "envoy.filters.network.thrift_proxy". See the extension's documentation for details on - // specific options. - map extension_protocol_options = 35 [deprecated = true]; - - // The extension_protocol_options field is used to provide extension-specific protocol options - // for upstream connections. The key should match the extension filter name, such as - // "envoy.filters.network.thrift_proxy". See the extension's documentation for details on - // specific options. - map typed_extension_protocol_options = 36; - - // If the DNS refresh rate is specified and the cluster type is either - // :ref:`STRICT_DNS`, - // or :ref:`LOGICAL_DNS`, - // this value is used as the cluster’s DNS refresh - // rate. The value configured must be at least 1ms. If this setting is not specified, the - // value defaults to 5000ms. For cluster types other than - // :ref:`STRICT_DNS` - // and :ref:`LOGICAL_DNS` - // this setting is ignored. - google.protobuf.Duration dns_refresh_rate = 16 - [(validate.rules).duration = {gt {nanos: 1000000}}]; - - // If the DNS failure refresh rate is specified and the cluster type is either - // :ref:`STRICT_DNS`, - // or :ref:`LOGICAL_DNS`, - // this is used as the cluster’s DNS refresh rate when requests are failing. If this setting is - // not specified, the failure refresh rate defaults to the DNS refresh rate. For cluster types - // other than :ref:`STRICT_DNS` and - // :ref:`LOGICAL_DNS` this setting is - // ignored. - // - // Note: Currently, DNS failures and empty DNS responses are not treated differently and this - // configuration is applied in both situations. - RefreshRate dns_failure_refresh_rate = 44; - - // Optional configuration for setting cluster's DNS refresh rate. If the value is set to true, - // cluster's DNS refresh rate will be set to resource record's TTL which comes from DNS - // resolution. - bool respect_dns_ttl = 39; - - // The DNS IP address resolution policy. If this setting is not specified, the - // value defaults to - // :ref:`AUTO`. - DnsLookupFamily dns_lookup_family = 17 [(validate.rules).enum = {defined_only: true}]; - - // If DNS resolvers are specified and the cluster type is either - // :ref:`STRICT_DNS`, - // or :ref:`LOGICAL_DNS`, - // this value is used to specify the cluster’s dns resolvers. - // If this setting is not specified, the value defaults to the default - // resolver, which uses /etc/resolv.conf for configuration. For cluster types - // other than - // :ref:`STRICT_DNS` - // and :ref:`LOGICAL_DNS` - // this setting is ignored. - repeated core.Address dns_resolvers = 18; - - // [#next-major-version: Reconcile DNS options in a single message.] - // Always use TCP queries instead of UDP queries for DNS lookups. - bool use_tcp_for_dns_lookups = 45; - - // If specified, outlier detection will be enabled for this upstream cluster. - // Each of the configuration values can be overridden via - // :ref:`runtime values `. - cluster.OutlierDetection outlier_detection = 19; - - // The interval for removing stale hosts from a cluster type - // :ref:`ORIGINAL_DST`. - // Hosts are considered stale if they have not been used - // as upstream destinations during this interval. New hosts are added - // to original destination clusters on demand as new connections are - // redirected to Envoy, causing the number of hosts in the cluster to - // grow over time. Hosts that are not stale (they are actively used as - // destinations) are kept in the cluster, which allows connections to - // them remain open, saving the latency that would otherwise be spent - // on opening new connections. If this setting is not specified, the - // value defaults to 5000ms. For cluster types other than - // :ref:`ORIGINAL_DST` - // this setting is ignored. - google.protobuf.Duration cleanup_interval = 20 [(validate.rules).duration = {gt {}}]; - - // Optional configuration used to bind newly established upstream connections. - // This overrides any bind_config specified in the bootstrap proto. - // If the address and port are empty, no bind will be performed. - core.BindConfig upstream_bind_config = 21; - - // Configuration for load balancing subsetting. - LbSubsetConfig lb_subset_config = 22; - - // Optional configuration for the load balancing algorithm selected by - // LbPolicy. Currently only - // :ref:`RING_HASH` and - // :ref:`LEAST_REQUEST` - // has additional configuration options. - // Specifying ring_hash_lb_config or least_request_lb_config without setting the corresponding - // LbPolicy will generate an error at runtime. - oneof lb_config { - // Optional configuration for the Ring Hash load balancing policy. - RingHashLbConfig ring_hash_lb_config = 23; - - // Optional configuration for the Original Destination load balancing policy. - OriginalDstLbConfig original_dst_lb_config = 34; - - // Optional configuration for the LeastRequest load balancing policy. - LeastRequestLbConfig least_request_lb_config = 37; - } - - // Common configuration for all load balancer implementations. - CommonLbConfig common_lb_config = 27; - - // Optional custom transport socket implementation to use for upstream connections. - // To setup TLS, set a transport socket with name `tls` and - // :ref:`UpstreamTlsContexts ` in the `typed_config`. - // If no transport socket configuration is specified, new connections - // will be set up with plaintext. - core.TransportSocket transport_socket = 24; - - // The Metadata field can be used to provide additional information about the - // cluster. It can be used for stats, logging, and varying filter behavior. - // Fields should use reverse DNS notation to denote which entity within Envoy - // will need the information. For instance, if the metadata is intended for - // the Router filter, the filter name should be specified as *envoy.router*. - core.Metadata metadata = 25; - - // Determines how Envoy selects the protocol used to speak to upstream hosts. - ClusterProtocolSelection protocol_selection = 26; - - // Optional options for upstream connections. - UpstreamConnectionOptions upstream_connection_options = 30; - - // If an upstream host becomes unhealthy (as determined by the configured health checks - // or outlier detection), immediately close all connections to the failed host. - // - // .. note:: - // - // This is currently only supported for connections created by tcp_proxy. - // - // .. note:: - // - // The current implementation of this feature closes all connections immediately when - // the unhealthy status is detected. If there are a large number of connections open - // to an upstream host that becomes unhealthy, Envoy may spend a substantial amount of - // time exclusively closing these connections, and not processing any other traffic. - bool close_connections_on_host_health_failure = 31; - - // If set to true, Envoy will ignore the health value of a host when processing its removal - // from service discovery. This means that if active health checking is used, Envoy will *not* - // wait for the endpoint to go unhealthy before removing it. - bool drain_connections_on_host_removal = 32 - [(udpa.annotations.field_migrate).rename = "ignore_health_on_host_removal"]; - - // An (optional) network filter chain, listed in the order the filters should be applied. - // The chain will be applied to all outgoing connections that Envoy makes to the upstream - // servers of this cluster. - repeated cluster.Filter filters = 40; - - // [#not-implemented-hide:] New mechanism for LB policy configuration. Used only if the - // :ref:`lb_policy` field has the value - // :ref:`LOAD_BALANCING_POLICY_CONFIG`. - LoadBalancingPolicy load_balancing_policy = 41; - - // [#not-implemented-hide:] - // If present, tells the client where to send load reports via LRS. If not present, the - // client will fall back to a client-side default, which may be either (a) don't send any - // load reports or (b) send load reports for all clusters to a single default server - // (which may be configured in the bootstrap file). - // - // Note that if multiple clusters point to the same LRS server, the client may choose to - // create a separate stream for each cluster or it may choose to coalesce the data for - // multiple clusters onto a single stream. Either way, the client must make sure to send - // the data for any given cluster on no more than one stream. - // - // [#next-major-version: In the v3 API, we should consider restructuring this somehow, - // maybe by allowing LRS to go on the ADS stream, or maybe by moving some of the negotiation - // from the LRS stream here.] - core.ConfigSource lrs_server = 42; -} - -// [#not-implemented-hide:] Extensible load balancing policy configuration. -// -// Every LB policy defined via this mechanism will be identified via a unique name using reverse -// DNS notation. If the policy needs configuration parameters, it must define a message for its -// own configuration, which will be stored in the config field. The name of the policy will tell -// clients which type of message they should expect to see in the config field. -// -// Note that there are cases where it is useful to be able to independently select LB policies -// for choosing a locality and for choosing an endpoint within that locality. For example, a -// given deployment may always use the same policy to choose the locality, but for choosing the -// endpoint within the locality, some clusters may use weighted-round-robin, while others may -// use some sort of session-based balancing. -// -// This can be accomplished via hierarchical LB policies, where the parent LB policy creates a -// child LB policy for each locality. For each request, the parent chooses the locality and then -// delegates to the child policy for that locality to choose the endpoint within the locality. -// -// To facilitate this, the config message for the top-level LB policy may include a field of -// type LoadBalancingPolicy that specifies the child policy. -message LoadBalancingPolicy { - message Policy { - // Required. The name of the LB policy. - string name = 1; - - // Optional config for the LB policy. - // No more than one of these two fields may be populated. - google.protobuf.Struct config = 2 [deprecated = true]; - - google.protobuf.Any typed_config = 3; - } - - // Each client will iterate over the list in order and stop at the first policy that it - // supports. This provides a mechanism for starting to use new LB policies that are not yet - // supported by all clients. - repeated Policy policies = 1; -} - -// An extensible structure containing the address Envoy should bind to when -// establishing upstream connections. -message UpstreamBindConfig { - // The address Envoy should bind to when establishing upstream connections. - core.Address source_address = 1; -} - -message UpstreamConnectionOptions { - // If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives. - core.TcpKeepalive tcp_keepalive = 1; +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 and protoxform to upgrade the file. +message CdsDummy { } diff --git a/envoy/api/v2/cluster.proto b/envoy/api/v2/cluster.proto new file mode 100644 index 00000000..e7fdd97f --- /dev/null +++ b/envoy/api/v2/cluster.proto @@ -0,0 +1,837 @@ +syntax = "proto3"; + +package envoy.api.v2; + +import "envoy/api/v2/auth/cert.proto"; +import "envoy/api/v2/cluster/circuit_breaker.proto"; +import "envoy/api/v2/cluster/filter.proto"; +import "envoy/api/v2/cluster/outlier_detection.proto"; +import "envoy/api/v2/core/address.proto"; +import "envoy/api/v2/core/base.proto"; +import "envoy/api/v2/core/config_source.proto"; +import "envoy/api/v2/core/health_check.proto"; +import "envoy/api/v2/core/protocol.proto"; +import "envoy/api/v2/endpoint.proto"; +import "envoy/type/percent.proto"; + +import "google/protobuf/any.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/migrate.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.api.v2"; +option java_outer_classname = "ClusterProto"; +option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.config.cluster.v3alpha"; + +// [#protodoc-title: Cluster configuration] + +// Configuration for a single upstream cluster. +// [#next-free-field: 46] +message Cluster { + // Refer to :ref:`service discovery type ` + // for an explanation on each type. + enum DiscoveryType { + // Refer to the :ref:`static discovery type` + // for an explanation. + STATIC = 0; + + // Refer to the :ref:`strict DNS discovery + // type` + // for an explanation. + STRICT_DNS = 1; + + // Refer to the :ref:`logical DNS discovery + // type` + // for an explanation. + LOGICAL_DNS = 2; + + // Refer to the :ref:`service discovery type` + // for an explanation. + EDS = 3; + + // Refer to the :ref:`original destination discovery + // type` + // for an explanation. + ORIGINAL_DST = 4; + } + + // Refer to :ref:`load balancer type ` architecture + // overview section for information on each type. + enum LbPolicy { + // Refer to the :ref:`round robin load balancing + // policy` + // for an explanation. + ROUND_ROBIN = 0; + + // Refer to the :ref:`least request load balancing + // policy` + // for an explanation. + LEAST_REQUEST = 1; + + // Refer to the :ref:`ring hash load balancing + // policy` + // for an explanation. + RING_HASH = 2; + + // Refer to the :ref:`random load balancing + // policy` + // for an explanation. + RANDOM = 3; + + // Refer to the :ref:`original destination load balancing + // policy` + // for an explanation. + // + // .. attention:: + // + // **This load balancing policy is deprecated**. Use CLUSTER_PROVIDED instead. + // + ORIGINAL_DST_LB = 4 [deprecated = true]; + + // Refer to the :ref:`Maglev load balancing policy` + // for an explanation. + MAGLEV = 5; + + // This load balancer type must be specified if the configured cluster provides a cluster + // specific load balancer. Consult the configured cluster's documentation for whether to set + // this option or not. + CLUSTER_PROVIDED = 6; + + // [#not-implemented-hide:] Use the new :ref:`load_balancing_policy + // ` field to determine the LB policy. + // [#next-major-version: In the v3 API, we should consider deprecating the lb_policy field + // and instead using the new load_balancing_policy field as the one and only mechanism for + // configuring this.] + LOAD_BALANCING_POLICY_CONFIG = 7; + } + + // When V4_ONLY is selected, the DNS resolver will only perform a lookup for + // addresses in the IPv4 family. If V6_ONLY is selected, the DNS resolver will + // only perform a lookup for addresses in the IPv6 family. If AUTO is + // specified, the DNS resolver will first perform a lookup for addresses in + // the IPv6 family and fallback to a lookup for addresses in the IPv4 family. + // For cluster types other than + // :ref:`STRICT_DNS` and + // :ref:`LOGICAL_DNS`, + // this setting is + // ignored. + enum DnsLookupFamily { + AUTO = 0; + V4_ONLY = 1; + V6_ONLY = 2; + } + + enum ClusterProtocolSelection { + // Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2). + // If :ref:`http2_protocol_options ` are + // present, HTTP2 will be used, otherwise HTTP1.1 will be used. + USE_CONFIGURED_PROTOCOL = 0; + + // Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection. + USE_DOWNSTREAM_PROTOCOL = 1; + } + + // TransportSocketMatch specifies what transport socket config will be used + // when the match conditions are satisfied. + message TransportSocketMatch { + // The name of the match, used in stats generation. + string name = 1 [(validate.rules).string = {min_len: 1}]; + + // Optional endpoint metadata match criteria. + // The connection to the endpoint with metadata matching what is set in this field + // will use the transport socket configuration specified here. + // The endpoint's metadata entry in *envoy.transport_socket_match* is used to match + // against the values specified in this field. + google.protobuf.Struct match = 2; + + // The configuration of the transport socket. + core.TransportSocket transport_socket = 3; + } + + // Extended cluster type. + message CustomClusterType { + // The type of the cluster to instantiate. The name must match a supported cluster type. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // Cluster specific configuration which depends on the cluster being instantiated. + // See the supported cluster for further documentation. + google.protobuf.Any typed_config = 2; + } + + // Only valid when discovery type is EDS. + message EdsClusterConfig { + // Configuration for the source of EDS updates for this Cluster. + core.ConfigSource eds_config = 1; + + // Optional alternative to cluster name to present to EDS. This does not + // have the same restrictions as cluster name, i.e. it may be arbitrary + // length. + string service_name = 2; + } + + // Optionally divide the endpoints in this cluster into subsets defined by + // endpoint metadata and selected by route and weighted cluster metadata. + // [#next-free-field: 8] + message LbSubsetConfig { + // If NO_FALLBACK is selected, a result + // equivalent to no healthy hosts is reported. If ANY_ENDPOINT is selected, + // any cluster endpoint may be returned (subject to policy, health checks, + // etc). If DEFAULT_SUBSET is selected, load balancing is performed over the + // endpoints matching the values from the default_subset field. + enum LbSubsetFallbackPolicy { + NO_FALLBACK = 0; + ANY_ENDPOINT = 1; + DEFAULT_SUBSET = 2; + } + + // Specifications for subsets. + message LbSubsetSelector { + // Allows to override top level fallback policy per selector. + enum LbSubsetSelectorFallbackPolicy { + // If NOT_DEFINED top level config fallback policy is used instead. + NOT_DEFINED = 0; + + // If NO_FALLBACK is selected, a result equivalent to no healthy hosts is reported. + NO_FALLBACK = 1; + + // If ANY_ENDPOINT is selected, any cluster endpoint may be returned + // (subject to policy, health checks, etc). + ANY_ENDPOINT = 2; + + // If DEFAULT_SUBSET is selected, load balancing is performed over the + // endpoints matching the values from the default_subset field. + DEFAULT_SUBSET = 3; + + // If KEYS_SUBSET is selected, subset selector matching is performed again with metadata + // keys reduced to + // :ref:`fallback_keys_subset`. + // It allows for a fallback to a different, less specific selector if some of the keys of + // the selector are considered optional. + KEYS_SUBSET = 4; + } + + // List of keys to match with the weighted cluster metadata. + repeated string keys = 1; + + // The behavior used when no endpoint subset matches the selected route's + // metadata. + LbSubsetSelectorFallbackPolicy fallback_policy = 2 + [(validate.rules).enum = {defined_only: true}]; + + // Subset of + // :ref:`keys` used by + // :ref:`KEYS_SUBSET` + // fallback policy. + // It has to be a non empty list if KEYS_SUBSET fallback policy is selected. + // For any other fallback policy the parameter is not used and should not be set. + // Only values also present in + // :ref:`keys` are allowed, but + // `fallback_keys_subset` cannot be equal to `keys`. + repeated string fallback_keys_subset = 3; + } + + // The behavior used when no endpoint subset matches the selected route's + // metadata. The value defaults to + // :ref:`NO_FALLBACK`. + LbSubsetFallbackPolicy fallback_policy = 1 [(validate.rules).enum = {defined_only: true}]; + + // Specifies the default subset of endpoints used during fallback if + // fallback_policy is + // :ref:`DEFAULT_SUBSET`. + // Each field in default_subset is + // compared to the matching LbEndpoint.Metadata under the *envoy.lb* + // namespace. It is valid for no hosts to match, in which case the behavior + // is the same as a fallback_policy of + // :ref:`NO_FALLBACK`. + google.protobuf.Struct default_subset = 2; + + // For each entry, LbEndpoint.Metadata's + // *envoy.lb* namespace is traversed and a subset is created for each unique + // combination of key and value. For example: + // + // .. code-block:: json + // + // { "subset_selectors": [ + // { "keys": [ "version" ] }, + // { "keys": [ "stage", "hardware_type" ] } + // ]} + // + // A subset is matched when the metadata from the selected route and + // weighted cluster contains the same keys and values as the subset's + // metadata. The same host may appear in multiple subsets. + repeated LbSubsetSelector subset_selectors = 3; + + // If true, routing to subsets will take into account the localities and locality weights of the + // endpoints when making the routing decision. + // + // There are some potential pitfalls associated with enabling this feature, as the resulting + // traffic split after applying both a subset match and locality weights might be undesirable. + // + // Consider for example a situation in which you have 50/50 split across two localities X/Y + // which have 100 hosts each without subsetting. If the subset LB results in X having only 1 + // host selected but Y having 100, then a lot more load is being dumped on the single host in X + // than originally anticipated in the load balancing assignment delivered via EDS. + bool locality_weight_aware = 4; + + // When used with locality_weight_aware, scales the weight of each locality by the ratio + // of hosts in the subset vs hosts in the original subset. This aims to even out the load + // going to an individual locality if said locality is disproportionately affected by the + // subset predicate. + bool scale_locality_weight = 5; + + // If true, when a fallback policy is configured and its corresponding subset fails to find + // a host this will cause any host to be selected instead. + // + // This is useful when using the default subset as the fallback policy, given the default + // subset might become empty. With this option enabled, if that happens the LB will attempt + // to select a host from the entire cluster. + bool panic_mode_any = 6; + + // If true, metadata specified for a metadata key will be matched against the corresponding + // endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value + // and any of the elements in the list matches the criteria. + bool list_as_any = 7; + } + + // Specific configuration for the LeastRequest load balancing policy. + message LeastRequestLbConfig { + // The number of random healthy hosts from which the host with the fewest active requests will + // be chosen. Defaults to 2 so that we perform two-choice selection if the field is not set. + google.protobuf.UInt32Value choice_count = 1 [(validate.rules).uint32 = {gte: 2}]; + } + + // Specific configuration for the :ref:`RingHash` + // load balancing policy. + message RingHashLbConfig { + // The hash function used to hash hosts onto the ketama ring. + enum HashFunction { + // Use `xxHash `_, this is the default hash function. + XX_HASH = 0; + + // Use `MurmurHash2 `_, this is compatible with + // std:hash in GNU libstdc++ 3.4.20 or above. This is typically the case when compiled + // on Linux and not macOS. + MURMUR_HASH_2 = 1; + } + + reserved 2; + + // Minimum hash ring size. The larger the ring is (that is, the more hashes there are for each + // provided host) the better the request distribution will reflect the desired weights. Defaults + // to 1024 entries, and limited to 8M entries. See also + // :ref:`maximum_ring_size`. + google.protobuf.UInt64Value minimum_ring_size = 1 [(validate.rules).uint64 = {lte: 8388608}]; + + // The hash function used to hash hosts onto the ketama ring. The value defaults to + // :ref:`XX_HASH`. + HashFunction hash_function = 3 [(validate.rules).enum = {defined_only: true}]; + + // Maximum hash ring size. Defaults to 8M entries, and limited to 8M entries, but can be lowered + // to further constrain resource use. See also + // :ref:`minimum_ring_size`. + google.protobuf.UInt64Value maximum_ring_size = 4 [(validate.rules).uint64 = {lte: 8388608}]; + } + + // Specific configuration for the + // :ref:`Original Destination ` + // load balancing policy. + message OriginalDstLbConfig { + // When true, :ref:`x-envoy-original-dst-host + // ` can be used to override destination + // address. + // + // .. attention:: + // + // This header isn't sanitized by default, so enabling this feature allows HTTP clients to + // route traffic to arbitrary hosts and/or ports, which may have serious security + // consequences. + bool use_http_header = 1; + } + + // Common configuration for all load balancer implementations. + // [#next-free-field: 7] + message CommonLbConfig { + // Configuration for :ref:`zone aware routing + // `. + message ZoneAwareLbConfig { + // Configures percentage of requests that will be considered for zone aware routing + // if zone aware routing is configured. If not specified, the default is 100%. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + type.Percent routing_enabled = 1; + + // Configures minimum upstream cluster size required for zone aware routing + // If upstream cluster size is less than specified, zone aware routing is not performed + // even if zone aware routing is configured. If not specified, the default is 6. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + google.protobuf.UInt64Value min_cluster_size = 2; + + // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic + // mode`. Instead, the cluster will fail all + // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a + // failing service. + bool fail_traffic_on_panic = 3; + } + + // Configuration for :ref:`locality weighted load balancing + // ` + message LocalityWeightedLbConfig { + } + + // Configures the :ref:`healthy panic threshold `. + // If not specified, the default is 50%. + // To disable panic mode, set to 0%. + // + // .. note:: + // The specified percent will be truncated to the nearest 1%. + type.Percent healthy_panic_threshold = 1; + + oneof locality_config_specifier { + ZoneAwareLbConfig zone_aware_lb_config = 2; + + LocalityWeightedLbConfig locality_weighted_lb_config = 3; + } + + // If set, all health check/weight/metadata updates that happen within this duration will be + // merged and delivered in one shot when the duration expires. The start of the duration is when + // the first update happens. This is useful for big clusters, with potentially noisy deploys + // that might trigger excessive CPU usage due to a constant stream of healthcheck state changes + // or metadata updates. The first set of updates to be seen apply immediately (e.g.: a new + // cluster). Please always keep in mind that the use of sandbox technologies may change this + // behavior. + // + // If this is not set, we default to a merge window of 1000ms. To disable it, set the merge + // window to 0. + // + // Note: merging does not apply to cluster membership changes (e.g.: adds/removes); this is + // because merging those updates isn't currently safe. See + // https://github.com/envoyproxy/envoy/pull/3941. + google.protobuf.Duration update_merge_window = 4; + + // If set to true, Envoy will not consider new hosts when computing load balancing weights until + // they have been health checked for the first time. This will have no effect unless + // active health checking is also configured. + // + // Ignoring a host means that for any load balancing calculations that adjust weights based + // on the ratio of eligible hosts and total hosts (priority spillover, locality weighting and + // panic mode) Envoy will exclude these hosts in the denominator. + // + // For example, with hosts in two priorities P0 and P1, where P0 looks like + // {healthy, unhealthy (new), unhealthy (new)} + // and where P1 looks like + // {healthy, healthy} + // all traffic will still hit P0, as 1 / (3 - 2) = 1. + // + // Enabling this will allow scaling up the number of hosts for a given cluster without entering + // panic mode or triggering priority spillover, assuming the hosts pass the first health check. + // + // If panic mode is triggered, new hosts are still eligible for traffic; they simply do not + // contribute to the calculation when deciding whether panic mode is enabled or not. + bool ignore_new_hosts_until_first_hc = 5; + + // If set to `true`, the cluster manager will drain all existing + // connections to upstream hosts whenever hosts are added or removed from the cluster. + bool close_connections_on_host_set_change = 6; + } + + message RefreshRate { + // Specifies the base interval between refreshes. This parameter is required and must be greater + // than zero and less than + // :ref:`max_interval `. + google.protobuf.Duration base_interval = 1 [(validate.rules).duration = { + required: true + gt {nanos: 1000000} + }]; + + // Specifies the maximum interval between refreshes. This parameter is optional, but must be + // greater than or equal to the + // :ref:`base_interval ` if set. The default + // is 10 times the :ref:`base_interval `. + google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {nanos: 1000000}}]; + } + + reserved 12, 15; + + // Configuration to use different transport sockets for different endpoints. + // The entry of *envoy.transport_socket* in the + // :ref:`LbEndpoint.Metadata ` + // is used to match against the transport sockets as they appear in the list. The first + // :ref:`match ` is used. + // For example, with the following match + // + // .. code-block:: yaml + // + // transport_socket_matches: + // - name: "enableMTLS" + // match: + // acceptMTLS: true + // transport_socket: + // name: envoy.transport_sockets.tls + // config: { ... } # tls socket configuration + // - name: "defaultToPlaintext" + // match: {} + // transport_socket: + // name: envoy.transport_sockets.raw_buffer + // + // Connections to the endpoints whose metadata value under *envoy.transport_socket* + // having "acceptMTLS"/"true" key/value pair use the "enableMTLS" socket configuration. + // + // If a :ref:`socket match ` with empty match + // criteria is provided, that always match any endpoint. For example, the "defaultToPlaintext" + // socket match in case above. + // + // If an endpoint metadata's value under *envoy.transport_socket* does not match any + // *TransportSocketMatch*, socket configuration fallbacks to use the *tls_context* or + // *transport_socket* specified in this cluster. + // + // This field allows gradual and flexible transport socket configuration changes. + // + // The metadata of endpoints in EDS can indicate transport socket capabilities. For example, + // an endpoint's metadata can have two key value pairs as "acceptMTLS": "true", + // "acceptPlaintext": "true". While some other endpoints, only accepting plaintext traffic + // has "acceptPlaintext": "true" metadata information. + // + // Then the xDS server can configure the CDS to a client, Envoy A, to send mutual TLS + // traffic for endpoints with "acceptMTLS": "true", by adding a corresponding + // *TransportSocketMatch* in this field. Other client Envoys receive CDS without + // *transport_socket_match* set, and still send plain text traffic to the same cluster. + // + // [#comment:TODO(incfly): add a detailed architecture doc on intended usage.] + repeated TransportSocketMatch transport_socket_matches = 43; + + // Supplies the name of the cluster which must be unique across all clusters. + // The cluster name is used when emitting + // :ref:`statistics ` if :ref:`alt_stat_name + // ` is not provided. + // Any ``:`` in the cluster name will be converted to ``_`` when emitting statistics. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // An optional alternative to the cluster name to be used while emitting stats. + // Any ``:`` in the name will be converted to ``_`` when emitting statistics. This should not be + // confused with :ref:`Router Filter Header + // `. + string alt_stat_name = 28; + + oneof cluster_discovery_type { + // The :ref:`service discovery type ` + // to use for resolving the cluster. + DiscoveryType type = 2 [(validate.rules).enum = {defined_only: true}]; + + // The custom cluster type. + CustomClusterType cluster_type = 38; + } + + // Configuration to use for EDS updates for the Cluster. + EdsClusterConfig eds_cluster_config = 3; + + // The timeout for new network connections to hosts in the cluster. + google.protobuf.Duration connect_timeout = 4 [(validate.rules).duration = {gt {}}]; + + // Soft limit on size of the cluster’s connections read and write buffers. If + // unspecified, an implementation defined default is applied (1MiB). + google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5; + + // The :ref:`load balancer type ` to use + // when picking a host in the cluster. + LbPolicy lb_policy = 6 [(validate.rules).enum = {defined_only: true}]; + + // If the service discovery type is + // :ref:`STATIC`, + // :ref:`STRICT_DNS` + // or :ref:`LOGICAL_DNS`, + // then hosts is required. + // + // .. attention:: + // + // **This field is deprecated**. Set the + // :ref:`load_assignment` field instead. + // + repeated core.Address hosts = 7; + + // Setting this is required for specifying members of + // :ref:`STATIC`, + // :ref:`STRICT_DNS` + // or :ref:`LOGICAL_DNS` clusters. + // This field supersedes :ref:`hosts` field. + // [#comment:TODO(dio): Deprecate the hosts field and add it to :ref:`deprecated log` + // once load_assignment is implemented.] + // + // .. attention:: + // + // Setting this allows non-EDS cluster types to contain embedded EDS equivalent + // :ref:`endpoint assignments`. + // Setting this overrides :ref:`hosts` values. + // + ClusterLoadAssignment load_assignment = 33; + + // Optional :ref:`active health checking ` + // configuration for the cluster. If no + // configuration is specified no health checking will be done and all cluster + // members will be considered healthy at all times. + repeated core.HealthCheck health_checks = 8; + + // Optional maximum requests for a single upstream connection. This parameter + // is respected by both the HTTP/1.1 and HTTP/2 connection pool + // implementations. If not specified, there is no limit. Setting this + // parameter to 1 will effectively disable keep alive. + google.protobuf.UInt32Value max_requests_per_connection = 9; + + // Optional :ref:`circuit breaking ` for the cluster. + cluster.CircuitBreakers circuit_breakers = 10; + + // The TLS configuration for connections to the upstream cluster. + // + // .. attention:: + // + // **This field is deprecated**. Use `transport_socket` with name `tls` instead. If both are + // set, `transport_socket` takes priority. + auth.UpstreamTlsContext tls_context = 11 [deprecated = true]; + + // Additional options when handling HTTP requests upstream. These options will be applicable to + // both HTTP1 and HTTP2 requests. + core.HttpProtocolOptions common_http_protocol_options = 29; + + // Additional options when handling HTTP1 requests. + core.Http1ProtocolOptions http_protocol_options = 13; + + // Even if default HTTP2 protocol options are desired, this field must be + // set so that Envoy will assume that the upstream supports HTTP/2 when + // making new HTTP connection pool connections. Currently, Envoy only + // supports prior knowledge for upstream connections. Even if TLS is used + // with ALPN, `http2_protocol_options` must be specified. As an aside this allows HTTP/2 + // connections to happen over plain text. + core.Http2ProtocolOptions http2_protocol_options = 14; + + // The extension_protocol_options field is used to provide extension-specific protocol options + // for upstream connections. The key should match the extension filter name, such as + // "envoy.filters.network.thrift_proxy". See the extension's documentation for details on + // specific options. + map extension_protocol_options = 35 [deprecated = true]; + + // The extension_protocol_options field is used to provide extension-specific protocol options + // for upstream connections. The key should match the extension filter name, such as + // "envoy.filters.network.thrift_proxy". See the extension's documentation for details on + // specific options. + map typed_extension_protocol_options = 36; + + // If the DNS refresh rate is specified and the cluster type is either + // :ref:`STRICT_DNS`, + // or :ref:`LOGICAL_DNS`, + // this value is used as the cluster’s DNS refresh + // rate. The value configured must be at least 1ms. If this setting is not specified, the + // value defaults to 5000ms. For cluster types other than + // :ref:`STRICT_DNS` + // and :ref:`LOGICAL_DNS` + // this setting is ignored. + google.protobuf.Duration dns_refresh_rate = 16 + [(validate.rules).duration = {gt {nanos: 1000000}}]; + + // If the DNS failure refresh rate is specified and the cluster type is either + // :ref:`STRICT_DNS`, + // or :ref:`LOGICAL_DNS`, + // this is used as the cluster’s DNS refresh rate when requests are failing. If this setting is + // not specified, the failure refresh rate defaults to the DNS refresh rate. For cluster types + // other than :ref:`STRICT_DNS` and + // :ref:`LOGICAL_DNS` this setting is + // ignored. + // + // Note: Currently, DNS failures and empty DNS responses are not treated differently and this + // configuration is applied in both situations. + RefreshRate dns_failure_refresh_rate = 44; + + // Optional configuration for setting cluster's DNS refresh rate. If the value is set to true, + // cluster's DNS refresh rate will be set to resource record's TTL which comes from DNS + // resolution. + bool respect_dns_ttl = 39; + + // The DNS IP address resolution policy. If this setting is not specified, the + // value defaults to + // :ref:`AUTO`. + DnsLookupFamily dns_lookup_family = 17 [(validate.rules).enum = {defined_only: true}]; + + // If DNS resolvers are specified and the cluster type is either + // :ref:`STRICT_DNS`, + // or :ref:`LOGICAL_DNS`, + // this value is used to specify the cluster’s dns resolvers. + // If this setting is not specified, the value defaults to the default + // resolver, which uses /etc/resolv.conf for configuration. For cluster types + // other than + // :ref:`STRICT_DNS` + // and :ref:`LOGICAL_DNS` + // this setting is ignored. + repeated core.Address dns_resolvers = 18; + + // [#next-major-version: Reconcile DNS options in a single message.] + // Always use TCP queries instead of UDP queries for DNS lookups. + bool use_tcp_for_dns_lookups = 45; + + // If specified, outlier detection will be enabled for this upstream cluster. + // Each of the configuration values can be overridden via + // :ref:`runtime values `. + cluster.OutlierDetection outlier_detection = 19; + + // The interval for removing stale hosts from a cluster type + // :ref:`ORIGINAL_DST`. + // Hosts are considered stale if they have not been used + // as upstream destinations during this interval. New hosts are added + // to original destination clusters on demand as new connections are + // redirected to Envoy, causing the number of hosts in the cluster to + // grow over time. Hosts that are not stale (they are actively used as + // destinations) are kept in the cluster, which allows connections to + // them remain open, saving the latency that would otherwise be spent + // on opening new connections. If this setting is not specified, the + // value defaults to 5000ms. For cluster types other than + // :ref:`ORIGINAL_DST` + // this setting is ignored. + google.protobuf.Duration cleanup_interval = 20 [(validate.rules).duration = {gt {}}]; + + // Optional configuration used to bind newly established upstream connections. + // This overrides any bind_config specified in the bootstrap proto. + // If the address and port are empty, no bind will be performed. + core.BindConfig upstream_bind_config = 21; + + // Configuration for load balancing subsetting. + LbSubsetConfig lb_subset_config = 22; + + // Optional configuration for the load balancing algorithm selected by + // LbPolicy. Currently only + // :ref:`RING_HASH` and + // :ref:`LEAST_REQUEST` + // has additional configuration options. + // Specifying ring_hash_lb_config or least_request_lb_config without setting the corresponding + // LbPolicy will generate an error at runtime. + oneof lb_config { + // Optional configuration for the Ring Hash load balancing policy. + RingHashLbConfig ring_hash_lb_config = 23; + + // Optional configuration for the Original Destination load balancing policy. + OriginalDstLbConfig original_dst_lb_config = 34; + + // Optional configuration for the LeastRequest load balancing policy. + LeastRequestLbConfig least_request_lb_config = 37; + } + + // Common configuration for all load balancer implementations. + CommonLbConfig common_lb_config = 27; + + // Optional custom transport socket implementation to use for upstream connections. + // To setup TLS, set a transport socket with name `tls` and + // :ref:`UpstreamTlsContexts ` in the `typed_config`. + // If no transport socket configuration is specified, new connections + // will be set up with plaintext. + core.TransportSocket transport_socket = 24; + + // The Metadata field can be used to provide additional information about the + // cluster. It can be used for stats, logging, and varying filter behavior. + // Fields should use reverse DNS notation to denote which entity within Envoy + // will need the information. For instance, if the metadata is intended for + // the Router filter, the filter name should be specified as *envoy.router*. + core.Metadata metadata = 25; + + // Determines how Envoy selects the protocol used to speak to upstream hosts. + ClusterProtocolSelection protocol_selection = 26; + + // Optional options for upstream connections. + UpstreamConnectionOptions upstream_connection_options = 30; + + // If an upstream host becomes unhealthy (as determined by the configured health checks + // or outlier detection), immediately close all connections to the failed host. + // + // .. note:: + // + // This is currently only supported for connections created by tcp_proxy. + // + // .. note:: + // + // The current implementation of this feature closes all connections immediately when + // the unhealthy status is detected. If there are a large number of connections open + // to an upstream host that becomes unhealthy, Envoy may spend a substantial amount of + // time exclusively closing these connections, and not processing any other traffic. + bool close_connections_on_host_health_failure = 31; + + // If set to true, Envoy will ignore the health value of a host when processing its removal + // from service discovery. This means that if active health checking is used, Envoy will *not* + // wait for the endpoint to go unhealthy before removing it. + bool drain_connections_on_host_removal = 32 + [(udpa.annotations.field_migrate).rename = "ignore_health_on_host_removal"]; + + // An (optional) network filter chain, listed in the order the filters should be applied. + // The chain will be applied to all outgoing connections that Envoy makes to the upstream + // servers of this cluster. + repeated cluster.Filter filters = 40; + + // [#not-implemented-hide:] New mechanism for LB policy configuration. Used only if the + // :ref:`lb_policy` field has the value + // :ref:`LOAD_BALANCING_POLICY_CONFIG`. + LoadBalancingPolicy load_balancing_policy = 41; + + // [#not-implemented-hide:] + // If present, tells the client where to send load reports via LRS. If not present, the + // client will fall back to a client-side default, which may be either (a) don't send any + // load reports or (b) send load reports for all clusters to a single default server + // (which may be configured in the bootstrap file). + // + // Note that if multiple clusters point to the same LRS server, the client may choose to + // create a separate stream for each cluster or it may choose to coalesce the data for + // multiple clusters onto a single stream. Either way, the client must make sure to send + // the data for any given cluster on no more than one stream. + // + // [#next-major-version: In the v3 API, we should consider restructuring this somehow, + // maybe by allowing LRS to go on the ADS stream, or maybe by moving some of the negotiation + // from the LRS stream here.] + core.ConfigSource lrs_server = 42; +} + +// [#not-implemented-hide:] Extensible load balancing policy configuration. +// +// Every LB policy defined via this mechanism will be identified via a unique name using reverse +// DNS notation. If the policy needs configuration parameters, it must define a message for its +// own configuration, which will be stored in the config field. The name of the policy will tell +// clients which type of message they should expect to see in the config field. +// +// Note that there are cases where it is useful to be able to independently select LB policies +// for choosing a locality and for choosing an endpoint within that locality. For example, a +// given deployment may always use the same policy to choose the locality, but for choosing the +// endpoint within the locality, some clusters may use weighted-round-robin, while others may +// use some sort of session-based balancing. +// +// This can be accomplished via hierarchical LB policies, where the parent LB policy creates a +// child LB policy for each locality. For each request, the parent chooses the locality and then +// delegates to the child policy for that locality to choose the endpoint within the locality. +// +// To facilitate this, the config message for the top-level LB policy may include a field of +// type LoadBalancingPolicy that specifies the child policy. +message LoadBalancingPolicy { + message Policy { + // Required. The name of the LB policy. + string name = 1; + + // Optional config for the LB policy. + // No more than one of these two fields may be populated. + google.protobuf.Struct config = 2 [deprecated = true]; + + google.protobuf.Any typed_config = 3; + } + + // Each client will iterate over the list in order and stop at the first policy that it + // supports. This provides a mechanism for starting to use new LB policies that are not yet + // supported by all clients. + repeated Policy policies = 1; +} + +// An extensible structure containing the address Envoy should bind to when +// establishing upstream connections. +message UpstreamBindConfig { + // The address Envoy should bind to when establishing upstream connections. + core.Address source_address = 1; +} + +message UpstreamConnectionOptions { + // If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives. + core.TcpKeepalive tcp_keepalive = 1; +} diff --git a/envoy/api/v2/eds.proto b/envoy/api/v2/eds.proto index 1ca1c6a0..e5a77dba 100644 --- a/envoy/api/v2/eds.proto +++ b/envoy/api/v2/eds.proto @@ -3,8 +3,6 @@ syntax = "proto3"; package envoy.api.v2; import "envoy/api/v2/discovery.proto"; -import "envoy/api/v2/endpoint/endpoint.proto"; -import "envoy/type/percent.proto"; import "google/api/annotations.proto"; import "google/protobuf/duration.proto"; @@ -13,6 +11,8 @@ import "google/protobuf/wrappers.proto"; import "udpa/annotations/migrate.proto"; import "validate/validate.proto"; +import public "envoy/api/v2/endpoint.proto"; + option java_package = "io.envoyproxy.envoy.api.v2"; option java_outer_classname = "EdsProto"; option java_multiple_files = true; @@ -37,98 +37,7 @@ service EndpointDiscoveryService { } } -// Each route from RDS will map to a single cluster or traffic split across -// clusters using weights expressed in the RDS WeightedCluster. -// -// With EDS, each cluster is treated independently from a LB perspective, with -// LB taking place between the Localities within a cluster and at a finer -// granularity between the hosts within a locality. The percentage of traffic -// for each endpoint is determined by both its load_balancing_weight, and the -// load_balancing_weight of its locality. First, a locality will be selected, -// then an endpoint within that locality will be chose based on its weight. -// [#next-free-field: 6] -message ClusterLoadAssignment { - // Load balancing policy settings. - // [#next-free-field: 6] - message Policy { - message DropOverload { - // Identifier for the policy specifying the drop. - string category = 1 [(validate.rules).string = {min_bytes: 1}]; - - // Percentage of traffic that should be dropped for the category. - type.FractionalPercent drop_percentage = 2; - } - - reserved 1; - - // Action to trim the overall incoming traffic to protect the upstream - // hosts. This action allows protection in case the hosts are unable to - // recover from an outage, or unable to autoscale or unable to handle - // incoming traffic volume for any reason. - // - // At the client each category is applied one after the other to generate - // the 'actual' drop percentage on all outgoing traffic. For example: - // - // .. code-block:: json - // - // { "drop_overloads": [ - // { "category": "throttle", "drop_percentage": 60 } - // { "category": "lb", "drop_percentage": 50 } - // ]} - // - // The actual drop percentages applied to the traffic at the clients will be - // "throttle"_drop = 60% - // "lb"_drop = 20% // 50% of the remaining 'actual' load, which is 40%. - // actual_outgoing_load = 20% // remaining after applying all categories. - repeated DropOverload drop_overloads = 2; - - // Priority levels and localities are considered overprovisioned with this - // factor (in percentage). This means that we don't consider a priority - // level or locality unhealthy until the percentage of healthy hosts - // multiplied by the overprovisioning factor drops below 100. - // With the default value 140(1.4), Envoy doesn't consider a priority level - // or a locality unhealthy until their percentage of healthy hosts drops - // below 72%. For example: - // - // .. code-block:: json - // - // { "overprovisioning_factor": 100 } - // - // Read more at :ref:`priority levels ` and - // :ref:`localities `. - google.protobuf.UInt32Value overprovisioning_factor = 3 [(validate.rules).uint32 = {gt: 0}]; - - // The max time until which the endpoints from this assignment can be used. - // If no new assignments are received before this time expires the endpoints - // are considered stale and should be marked unhealthy. - // Defaults to 0 which means endpoints never go stale. - google.protobuf.Duration endpoint_stale_after = 4 [(validate.rules).duration = {gt {}}]; - - // The flag to disable overprovisioning. If it is set to true, - // :ref:`overprovisioning factor - // ` will be ignored - // and Envoy will not perform graceful failover between priority levels or - // localities as endpoints become unhealthy. Otherwise Envoy will perform - // graceful failover as :ref:`overprovisioning factor - // ` suggests. - // [#next-major-version: Unify with overprovisioning config as a single message.] - // [#not-implemented-hide:] - bool disable_overprovisioning = 5; - } - - // Name of the cluster. This will be the :ref:`service_name - // ` value if specified - // in the cluster :ref:`EdsClusterConfig - // `. - string cluster_name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // List of endpoints to load balance to. - repeated endpoint.LocalityLbEndpoints endpoints = 2; - - // Map of named endpoints that can be referenced in LocalityLbEndpoints. - // [#not-implemented-hide:] - map named_endpoints = 5; - - // Load balancing policy settings. - Policy policy = 4; +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 and protoxform to upgrade the file. +message EdsDummy { } diff --git a/envoy/api/v2/endpoint.proto b/envoy/api/v2/endpoint.proto new file mode 100644 index 00000000..979fe8fd --- /dev/null +++ b/envoy/api/v2/endpoint.proto @@ -0,0 +1,117 @@ +syntax = "proto3"; + +package envoy.api.v2; + +import "envoy/api/v2/endpoint/endpoint_components.proto"; +import "envoy/type/percent.proto"; + +import "google/api/annotations.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/migrate.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.api.v2"; +option java_outer_classname = "EndpointProto"; +option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.config.endpoint.v3alpha"; + +// [#protodoc-title: Endpoint configuration] +// Endpoint discovery :ref:`architecture overview ` + +// Each route from RDS will map to a single cluster or traffic split across +// clusters using weights expressed in the RDS WeightedCluster. +// +// With EDS, each cluster is treated independently from a LB perspective, with +// LB taking place between the Localities within a cluster and at a finer +// granularity between the hosts within a locality. The percentage of traffic +// for each endpoint is determined by both its load_balancing_weight, and the +// load_balancing_weight of its locality. First, a locality will be selected, +// then an endpoint within that locality will be chose based on its weight. +// [#next-free-field: 6] +message ClusterLoadAssignment { + // Load balancing policy settings. + // [#next-free-field: 6] + message Policy { + message DropOverload { + // Identifier for the policy specifying the drop. + string category = 1 [(validate.rules).string = {min_bytes: 1}]; + + // Percentage of traffic that should be dropped for the category. + type.FractionalPercent drop_percentage = 2; + } + + reserved 1; + + // Action to trim the overall incoming traffic to protect the upstream + // hosts. This action allows protection in case the hosts are unable to + // recover from an outage, or unable to autoscale or unable to handle + // incoming traffic volume for any reason. + // + // At the client each category is applied one after the other to generate + // the 'actual' drop percentage on all outgoing traffic. For example: + // + // .. code-block:: json + // + // { "drop_overloads": [ + // { "category": "throttle", "drop_percentage": 60 } + // { "category": "lb", "drop_percentage": 50 } + // ]} + // + // The actual drop percentages applied to the traffic at the clients will be + // "throttle"_drop = 60% + // "lb"_drop = 20% // 50% of the remaining 'actual' load, which is 40%. + // actual_outgoing_load = 20% // remaining after applying all categories. + repeated DropOverload drop_overloads = 2; + + // Priority levels and localities are considered overprovisioned with this + // factor (in percentage). This means that we don't consider a priority + // level or locality unhealthy until the percentage of healthy hosts + // multiplied by the overprovisioning factor drops below 100. + // With the default value 140(1.4), Envoy doesn't consider a priority level + // or a locality unhealthy until their percentage of healthy hosts drops + // below 72%. For example: + // + // .. code-block:: json + // + // { "overprovisioning_factor": 100 } + // + // Read more at :ref:`priority levels ` and + // :ref:`localities `. + google.protobuf.UInt32Value overprovisioning_factor = 3 [(validate.rules).uint32 = {gt: 0}]; + + // The max time until which the endpoints from this assignment can be used. + // If no new assignments are received before this time expires the endpoints + // are considered stale and should be marked unhealthy. + // Defaults to 0 which means endpoints never go stale. + google.protobuf.Duration endpoint_stale_after = 4 [(validate.rules).duration = {gt {}}]; + + // The flag to disable overprovisioning. If it is set to true, + // :ref:`overprovisioning factor + // ` will be ignored + // and Envoy will not perform graceful failover between priority levels or + // localities as endpoints become unhealthy. Otherwise Envoy will perform + // graceful failover as :ref:`overprovisioning factor + // ` suggests. + // [#next-major-version: Unify with overprovisioning config as a single message.] + // [#not-implemented-hide:] + bool disable_overprovisioning = 5; + } + + // Name of the cluster. This will be the :ref:`service_name + // ` value if specified + // in the cluster :ref:`EdsClusterConfig + // `. + string cluster_name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // List of endpoints to load balance to. + repeated endpoint.LocalityLbEndpoints endpoints = 2; + + // Map of named endpoints that can be referenced in LocalityLbEndpoints. + // [#not-implemented-hide:] + map named_endpoints = 5; + + // Load balancing policy settings. + Policy policy = 4; +} diff --git a/envoy/api/v2/endpoint/endpoint.proto b/envoy/api/v2/endpoint/endpoint.proto index a8a13e2c..247c9ae2 100644 --- a/envoy/api/v2/endpoint/endpoint.proto +++ b/envoy/api/v2/endpoint/endpoint.proto @@ -2,130 +2,8 @@ syntax = "proto3"; package envoy.api.v2.endpoint; -import "envoy/api/v2/core/address.proto"; -import "envoy/api/v2/core/base.proto"; -import "envoy/api/v2/core/health_check.proto"; - -import "google/protobuf/wrappers.proto"; - -import "udpa/annotations/migrate.proto"; -import "validate/validate.proto"; +import public "envoy/api/v2/endpoint/endpoint_components.proto"; option java_package = "io.envoyproxy.envoy.api.v2.endpoint"; option java_outer_classname = "EndpointProto"; option java_multiple_files = true; -option (udpa.annotations.file_migrate).move_to_package = "envoy.config.endpoint.v3alpha"; - -// [#protodoc-title: Endpoints] - -// Upstream host identifier. -message Endpoint { - // The optional health check configuration. - message HealthCheckConfig { - // Optional alternative health check port value. - // - // By default the health check address port of an upstream host is the same - // as the host's serving address port. This provides an alternative health - // check port. Setting this with a non-zero value allows an upstream host - // to have different health check address port. - uint32 port_value = 1 [(validate.rules).uint32 = {lte: 65535}]; - } - - // The upstream host address. - // - // .. attention:: - // - // The form of host address depends on the given cluster type. For STATIC or EDS, - // it is expected to be a direct IP address (or something resolvable by the - // specified :ref:`resolver ` - // in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname, - // and will be resolved via DNS. - core.Address address = 1; - - // The optional health check configuration is used as configuration for the - // health checker to contact the health checked host. - // - // .. attention:: - // - // This takes into effect only for upstream clusters with - // :ref:`active health checking ` enabled. - HealthCheckConfig health_check_config = 2; -} - -// An Endpoint that Envoy can route traffic to. -// [#next-free-field: 6] -message LbEndpoint { - // Upstream host identifier or a named reference. - oneof host_identifier { - Endpoint endpoint = 1; - - // [#not-implemented-hide:] - string endpoint_name = 5; - } - - // Optional health status when known and supplied by EDS server. - core.HealthStatus health_status = 2; - - // The endpoint metadata specifies values that may be used by the load - // balancer to select endpoints in a cluster for a given request. The filter - // name should be specified as *envoy.lb*. An example boolean key-value pair - // is *canary*, providing the optional canary status of the upstream host. - // This may be matched against in a route's - // :ref:`RouteAction ` metadata_match field - // to subset the endpoints considered in cluster load balancing. - core.Metadata metadata = 3; - - // The optional load balancing weight of the upstream host; at least 1. - // Envoy uses the load balancing weight in some of the built in load - // balancers. The load balancing weight for an endpoint is divided by the sum - // of the weights of all endpoints in the endpoint's locality to produce a - // percentage of traffic for the endpoint. This percentage is then further - // weighted by the endpoint's locality's load balancing weight from - // LocalityLbEndpoints. If unspecified, each host is presumed to have equal - // weight in a locality. - google.protobuf.UInt32Value load_balancing_weight = 4 [(validate.rules).uint32 = {gte: 1}]; -} - -// A group of endpoints belonging to a Locality. -// One can have multiple LocalityLbEndpoints for a locality, but this is -// generally only done if the different groups need to have different load -// balancing weights or different priorities. -// [#next-free-field: 7] -message LocalityLbEndpoints { - // Identifies location of where the upstream hosts run. - core.Locality locality = 1; - - // The group of endpoints belonging to the locality specified. - repeated LbEndpoint lb_endpoints = 2; - - // Optional: Per priority/region/zone/sub_zone weight; at least 1. The load - // balancing weight for a locality is divided by the sum of the weights of all - // localities at the same priority level to produce the effective percentage - // of traffic for the locality. - // - // Locality weights are only considered when :ref:`locality weighted load - // balancing ` is - // configured. These weights are ignored otherwise. If no weights are - // specified when locality weighted load balancing is enabled, the locality is - // assigned no load. - google.protobuf.UInt32Value load_balancing_weight = 3 [(validate.rules).uint32 = {gte: 1}]; - - // Optional: the priority for this LocalityLbEndpoints. If unspecified this will - // default to the highest priority (0). - // - // Under usual circumstances, Envoy will only select endpoints for the highest - // priority (0). In the event all endpoints for a particular priority are - // unavailable/unhealthy, Envoy will fail over to selecting endpoints for the - // next highest priority group. - // - // Priorities should range from 0 (highest) to N (lowest) without skipping. - uint32 priority = 5 [(validate.rules).uint32 = {lte: 128}]; - - // Optional: Per locality proximity value which indicates how close this - // locality is from the source locality. This value only provides ordering - // information (lower the value, closer it is to the source locality). - // This will be consumed by load balancing schemes that need proximity order - // to determine where to route the requests. - // [#not-implemented-hide:] - google.protobuf.UInt32Value proximity = 6; -} diff --git a/envoy/api/v2/endpoint/endpoint_components.proto b/envoy/api/v2/endpoint/endpoint_components.proto new file mode 100644 index 00000000..20c163b3 --- /dev/null +++ b/envoy/api/v2/endpoint/endpoint_components.proto @@ -0,0 +1,131 @@ +syntax = "proto3"; + +package envoy.api.v2.endpoint; + +import "envoy/api/v2/core/address.proto"; +import "envoy/api/v2/core/base.proto"; +import "envoy/api/v2/core/health_check.proto"; + +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/migrate.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.api.v2.endpoint"; +option java_outer_classname = "EndpointComponentsProto"; +option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.config.endpoint.v3alpha"; + +// [#protodoc-title: Endpoints] + +// Upstream host identifier. +message Endpoint { + // The optional health check configuration. + message HealthCheckConfig { + // Optional alternative health check port value. + // + // By default the health check address port of an upstream host is the same + // as the host's serving address port. This provides an alternative health + // check port. Setting this with a non-zero value allows an upstream host + // to have different health check address port. + uint32 port_value = 1 [(validate.rules).uint32 = {lte: 65535}]; + } + + // The upstream host address. + // + // .. attention:: + // + // The form of host address depends on the given cluster type. For STATIC or EDS, + // it is expected to be a direct IP address (or something resolvable by the + // specified :ref:`resolver ` + // in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname, + // and will be resolved via DNS. + core.Address address = 1; + + // The optional health check configuration is used as configuration for the + // health checker to contact the health checked host. + // + // .. attention:: + // + // This takes into effect only for upstream clusters with + // :ref:`active health checking ` enabled. + HealthCheckConfig health_check_config = 2; +} + +// An Endpoint that Envoy can route traffic to. +// [#next-free-field: 6] +message LbEndpoint { + // Upstream host identifier or a named reference. + oneof host_identifier { + Endpoint endpoint = 1; + + // [#not-implemented-hide:] + string endpoint_name = 5; + } + + // Optional health status when known and supplied by EDS server. + core.HealthStatus health_status = 2; + + // The endpoint metadata specifies values that may be used by the load + // balancer to select endpoints in a cluster for a given request. The filter + // name should be specified as *envoy.lb*. An example boolean key-value pair + // is *canary*, providing the optional canary status of the upstream host. + // This may be matched against in a route's + // :ref:`RouteAction ` metadata_match field + // to subset the endpoints considered in cluster load balancing. + core.Metadata metadata = 3; + + // The optional load balancing weight of the upstream host; at least 1. + // Envoy uses the load balancing weight in some of the built in load + // balancers. The load balancing weight for an endpoint is divided by the sum + // of the weights of all endpoints in the endpoint's locality to produce a + // percentage of traffic for the endpoint. This percentage is then further + // weighted by the endpoint's locality's load balancing weight from + // LocalityLbEndpoints. If unspecified, each host is presumed to have equal + // weight in a locality. + google.protobuf.UInt32Value load_balancing_weight = 4 [(validate.rules).uint32 = {gte: 1}]; +} + +// A group of endpoints belonging to a Locality. +// One can have multiple LocalityLbEndpoints for a locality, but this is +// generally only done if the different groups need to have different load +// balancing weights or different priorities. +// [#next-free-field: 7] +message LocalityLbEndpoints { + // Identifies location of where the upstream hosts run. + core.Locality locality = 1; + + // The group of endpoints belonging to the locality specified. + repeated LbEndpoint lb_endpoints = 2; + + // Optional: Per priority/region/zone/sub_zone weight; at least 1. The load + // balancing weight for a locality is divided by the sum of the weights of all + // localities at the same priority level to produce the effective percentage + // of traffic for the locality. + // + // Locality weights are only considered when :ref:`locality weighted load + // balancing ` is + // configured. These weights are ignored otherwise. If no weights are + // specified when locality weighted load balancing is enabled, the locality is + // assigned no load. + google.protobuf.UInt32Value load_balancing_weight = 3 [(validate.rules).uint32 = {gte: 1}]; + + // Optional: the priority for this LocalityLbEndpoints. If unspecified this will + // default to the highest priority (0). + // + // Under usual circumstances, Envoy will only select endpoints for the highest + // priority (0). In the event all endpoints for a particular priority are + // unavailable/unhealthy, Envoy will fail over to selecting endpoints for the + // next highest priority group. + // + // Priorities should range from 0 (highest) to N (lowest) without skipping. + uint32 priority = 5 [(validate.rules).uint32 = {lte: 128}]; + + // Optional: Per locality proximity value which indicates how close this + // locality is from the source locality. This value only provides ordering + // information (lower the value, closer it is to the source locality). + // This will be consumed by load balancing schemes that need proximity order + // to determine where to route the requests. + // [#not-implemented-hide:] + google.protobuf.UInt32Value proximity = 6; +} diff --git a/envoy/api/v2/rds.proto b/envoy/api/v2/rds.proto index c2754592..75f2e4cf 100644 --- a/envoy/api/v2/rds.proto +++ b/envoy/api/v2/rds.proto @@ -2,10 +2,7 @@ syntax = "proto3"; package envoy.api.v2; -import "envoy/api/v2/core/base.proto"; -import "envoy/api/v2/core/config_source.proto"; import "envoy/api/v2/discovery.proto"; -import "envoy/api/v2/route/route.proto"; import "google/api/annotations.proto"; import "google/protobuf/wrappers.proto"; @@ -13,15 +10,15 @@ import "google/protobuf/wrappers.proto"; import "udpa/annotations/migrate.proto"; import "validate/validate.proto"; +import public "envoy/api/v2/route.proto"; + option java_package = "io.envoyproxy.envoy.api.v2"; option java_outer_classname = "RdsProto"; option java_multiple_files = true; option java_generic_services = true; option (udpa.annotations.file_migrate).move_to_package = "envoy.service.route.v3alpha"; -// [#protodoc-title: HTTP route configuration] -// * Routing :ref:`architecture overview ` -// * HTTP :ref:`router filter ` +// [#protodoc-title: RDS] // The resource_names field in DiscoveryRequest specifies a route configuration. // This allows an Envoy configuration with multiple HTTP listeners (and @@ -56,86 +53,7 @@ service VirtualHostDiscoveryService { } } -// [#next-free-field: 11] -message RouteConfiguration { - // The name of the route configuration. For example, it might match - // :ref:`route_config_name - // ` in - // :ref:`envoy_api_msg_config.filter.network.http_connection_manager.v2.Rds`. - string name = 1; - - // An array of virtual hosts that make up the route table. - repeated route.VirtualHost virtual_hosts = 2; - - // An array of virtual hosts will be dynamically loaded via the VHDS API. - // Both *virtual_hosts* and *vhds* fields will be used when present. *virtual_hosts* can be used - // for a base routing table or for infrequently changing virtual hosts. *vhds* is used for - // on-demand discovery of virtual hosts. The contents of these two fields will be merged to - // generate a routing table for a given RouteConfiguration, with *vhds* derived configuration - // taking precedence. - Vhds vhds = 9; - - // Optionally 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 :ref:`config_http_conn_man_headers_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. Headers specified at this level are applied - // after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or - // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.HeaderValueOption response_headers_to_add = 4 - [(validate.rules).repeated = {max_items: 1000}]; - - // 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. Headers specified at this level are - // applied after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or - // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.HeaderValueOption request_headers_to_add = 6 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each request - // routed by the HTTP connection manager. - repeated string request_headers_to_remove = 8; - - // By default, headers that should be added/removed are evaluated from most to least specific: - // - // * route level - // * virtual host level - // * connection manager level - // - // To allow setting overrides at the route or virtual host level, this order can be reversed - // by setting this option to true. Defaults to false. - // - // [#next-major-version: In the v3 API, this will default to true.] - bool most_specific_header_mutations_wins = 10; - - // 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 :ref:`route_config - // ` - // option. This setting default to false if the route table is loaded dynamically via the - // :ref:`rds - // ` - // option. Users may wish to override the default behavior in certain cases (for example when - // using CDS with a static route table). - google.protobuf.BoolValue validate_clusters = 7; -} - -message Vhds { - // Configuration source specifier for VHDS. - core.ConfigSource config_source = 1 [(validate.rules).message = {required: true}]; +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 and protoxform to upgrade the file. +message RdsDummy { } diff --git a/envoy/api/v2/route.proto b/envoy/api/v2/route.proto new file mode 100644 index 00000000..b68a73e5 --- /dev/null +++ b/envoy/api/v2/route.proto @@ -0,0 +1,105 @@ +syntax = "proto3"; + +package envoy.api.v2; + +import "envoy/api/v2/core/base.proto"; +import "envoy/api/v2/core/config_source.proto"; +import "envoy/api/v2/route/route_components.proto"; + +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/migrate.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.api.v2"; +option java_outer_classname = "RouteProto"; +option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.config.route.v3alpha"; + +// [#protodoc-title: HTTP route configuration] +// * Routing :ref:`architecture overview ` +// * HTTP :ref:`router filter ` + +// [#next-free-field: 11] +message RouteConfiguration { + // The name of the route configuration. For example, it might match + // :ref:`route_config_name + // ` in + // :ref:`envoy_api_msg_config.filter.network.http_connection_manager.v2.Rds`. + string name = 1; + + // An array of virtual hosts that make up the route table. + repeated route.VirtualHost virtual_hosts = 2; + + // An array of virtual hosts will be dynamically loaded via the VHDS API. + // Both *virtual_hosts* and *vhds* fields will be used when present. *virtual_hosts* can be used + // for a base routing table or for infrequently changing virtual hosts. *vhds* is used for + // on-demand discovery of virtual hosts. The contents of these two fields will be merged to + // generate a routing table for a given RouteConfiguration, with *vhds* derived configuration + // taking precedence. + Vhds vhds = 9; + + // Optionally 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 :ref:`config_http_conn_man_headers_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. Headers specified at this level are applied + // after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or + // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.HeaderValueOption response_headers_to_add = 4 + [(validate.rules).repeated = {max_items: 1000}]; + + // 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. Headers specified at this level are + // applied after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or + // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.HeaderValueOption request_headers_to_add = 6 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each request + // routed by the HTTP connection manager. + repeated string request_headers_to_remove = 8; + + // By default, headers that should be added/removed are evaluated from most to least specific: + // + // * route level + // * virtual host level + // * connection manager level + // + // To allow setting overrides at the route or virtual host level, this order can be reversed + // by setting this option to true. Defaults to false. + // + // [#next-major-version: In the v3 API, this will default to true.] + bool most_specific_header_mutations_wins = 10; + + // 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 :ref:`route_config + // ` + // option. This setting default to false if the route table is loaded dynamically via the + // :ref:`rds + // ` + // option. Users may wish to override the default behavior in certain cases (for example when + // using CDS with a static route table). + google.protobuf.BoolValue validate_clusters = 7; +} + +message Vhds { + // Configuration source specifier for VHDS. + core.ConfigSource config_source = 1 [(validate.rules).message = {required: true}]; +} diff --git a/envoy/api/v2/route/route.proto b/envoy/api/v2/route/route.proto index 63fc301c..ec13e9e5 100644 --- a/envoy/api/v2/route/route.proto +++ b/envoy/api/v2/route/route.proto @@ -2,1448 +2,8 @@ syntax = "proto3"; package envoy.api.v2.route; -import "envoy/api/v2/core/base.proto"; -import "envoy/type/matcher/regex.proto"; -import "envoy/type/matcher/string.proto"; -import "envoy/type/percent.proto"; -import "envoy/type/range.proto"; -import "envoy/type/tracing/v2/custom_tag.proto"; - -import "google/protobuf/any.proto"; -import "google/protobuf/duration.proto"; -import "google/protobuf/struct.proto"; -import "google/protobuf/wrappers.proto"; - -import "udpa/annotations/migrate.proto"; -import "validate/validate.proto"; +import public "envoy/api/v2/route/route_components.proto"; option java_package = "io.envoyproxy.envoy.api.v2.route"; option java_outer_classname = "RouteProto"; option java_multiple_files = true; -option (udpa.annotations.file_migrate).move_to_package = "envoy.config.route.v3alpha"; - -// [#protodoc-title: HTTP route] -// * Routing :ref:`architecture overview ` -// * HTTP :ref:`router filter ` - -// The top level element in the routing configuration is a virtual host. Each virtual host has -// a logical name as well as a set of domains that get routed to it based on the incoming request's -// host header. This allows a single listener to service multiple top level domain path trees. Once -// a virtual host is selected based on the domain, the routes are processed in order to see which -// upstream cluster to route to or whether to perform a redirect. -// [#next-free-field: 19] -message VirtualHost { - 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 301 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 301 redirect - // will be sent telling the client to use HTTPS. - ALL = 2; - } - - reserved 9; - - // The logical name of the virtual host. This is used when emitting certain - // statistics but is not relevant for routing. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // A list of domains (host/authority header) that will be matched to this - // virtual host. Wildcard hosts are supported in the suffix or prefix form. - // - // Domain search order: - // 1. Exact domain names: ``www.foo.com``. - // 2. Suffix domain wildcards: ``*.foo.com`` or ``*-bar.foo.com``. - // 3. Prefix domain wildcards: ``foo.*`` or ``foo-*``. - // 4. Special wildcard ``*`` matching any domain. - // - // .. note:: - // - // The wildcard will not match the empty string. - // e.g. ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``. - // The longest wildcards match first. - // 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 [(validate.rules).repeated = {min_items: 1}]; - - // 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; - - // Specifies the type of TLS enforcement the virtual host expects. If this option is not - // specified, there is no TLS requirement for the virtual host. - 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. Headers specified at this level are applied - // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the - // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including - // details on header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.HeaderValueOption request_headers_to_add = 7 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each request - // handled by this virtual host. - repeated string request_headers_to_remove = 13; - - // Specifies a list of HTTP headers that should be added to each response - // handled by this virtual host. Headers specified at this level are applied - // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the - // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including - // details on header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.HeaderValueOption response_headers_to_add = 10 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each response - // handled by this virtual host. - repeated string response_headers_to_remove = 11; - - // Indicates that the virtual host has a CORS policy. - CorsPolicy cors = 8; - - // The per_filter_config field can be used to provide virtual host-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` - // for if and how it is utilized. - map per_filter_config = 12 [deprecated = true]; - - // The per_filter_config field can be used to provide virtual host-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` - // for if and how it is utilized. - map typed_per_filter_config = 15; - - // Decides whether the :ref:`x-envoy-attempt-count - // ` header should be included - // in the upstream request. Setting this option will cause it to override any existing header - // value, so in the case of two Envoys on the request path with this option enabled, the upstream - // will see the attempt count as perceived by the second Envoy. Defaults to false. - // This header is unaffected by the - // :ref:`suppress_envoy_headers - // ` flag. - bool include_request_attempt_count = 14; - - // Indicates the retry policy for all routes in this virtual host. Note that setting a - // route level entry will take precedence over this config and it'll be treated - // independently (e.g.: values are not inherited). - RetryPolicy retry_policy = 16; - - // Indicates the hedge policy for all routes in this virtual host. Note that setting a - // route level entry will take precedence over this config and it'll be treated - // independently (e.g.: values are not inherited). - HedgePolicy hedge_policy = 17; - - // The maximum bytes which will be buffered for retries and shadowing. - // If set and a route-specific limit is not set, the bytes actually buffered will be the minimum - // value of this and the listener per_connection_buffer_limit_bytes. - google.protobuf.UInt32Value per_request_buffer_limit_bytes = 18; -} - -// A filter-defined action type. -message FilterAction { - google.protobuf.Any action = 1; -} - -// A route is both a specification of how to match a request as well as an indication of what to do -// next (e.g., redirect, forward, rewrite, etc.). -// -// .. attention:: -// -// Envoy supports routing on HTTP method via :ref:`header matching -// `. -// [#next-free-field: 18] -message Route { - reserved 6; - - // Name for the route. - string name = 14; - - // Route matching parameters. - RouteMatch match = 1 [(validate.rules).message = {required: true}]; - - oneof action { - option (validate.required) = true; - - // Route request to some upstream cluster. - RouteAction route = 2; - - // Return a redirect. - RedirectAction redirect = 3; - - // Return an arbitrary HTTP response directly, without proxying. - DirectResponseAction direct_response = 7; - - // [#not-implemented-hide:] - // If true, a filter will define the action (e.g., it could dynamically generate the - // RouteAction). - FilterAction filter_action = 17; - } - - // The Metadata field can be used to provide additional information - // about the route. It can be used for configuration, stats, and logging. - // The metadata should go under the filter namespace that will need it. - // For instance, if the metadata is intended for the Router filter, - // the filter name should be specified as *envoy.router*. - core.Metadata metadata = 4; - - // Decorator for the matched route. - Decorator decorator = 5; - - // The per_filter_config field can be used to provide route-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` for - // if and how it is utilized. - map per_filter_config = 8 [deprecated = true]; - - // The per_filter_config field can be used to provide route-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` for - // if and how it is utilized. - map typed_per_filter_config = 13; - - // Specifies a set of headers that will be added to requests matching this - // route. Headers specified at this level are applied before headers from the - // enclosing :ref:`envoy_api_msg_route.VirtualHost` and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.HeaderValueOption request_headers_to_add = 9 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each request - // matching this route. - repeated string request_headers_to_remove = 12; - - // Specifies a set of headers that will be added to responses to requests - // matching this route. Headers specified at this level are applied before - // headers from the enclosing :ref:`envoy_api_msg_route.VirtualHost` and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including - // details on header value syntax, see the documentation on - // :ref:`custom request headers `. - repeated core.HeaderValueOption response_headers_to_add = 10 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each response - // to requests matching this route. - repeated string response_headers_to_remove = 11; - - // Presence of the object defines whether the connection manager's tracing configuration - // is overridden by this route specific instance. - Tracing tracing = 15; - - // The maximum bytes which will be buffered for retries and shadowing. - // If set, the bytes actually buffered will be the minimum value of this and the - // listener per_connection_buffer_limit_bytes. - google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16; -} - -// Compared to the :ref:`cluster ` field that specifies a -// single upstream cluster as the target of a request, the :ref:`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 { - // [#next-free-field: 11] - message ClusterWeight { - reserved 7; - - // Name of the upstream cluster. The cluster must exist in the - // :ref:`cluster manager configuration `. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // An integer between 0 and :ref:`total_weight - // `. 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 the total_weight, which defaults to 100. - google.protobuf.UInt32Value weight = 2; - - // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in - // the upstream cluster with metadata matching what is set in this field will be considered for - // load balancing. Note that this will be merged with what's provided in - // :ref:`RouteAction.metadata_match `, with - // values here taking precedence. The filter name should be specified as *envoy.lb*. - core.Metadata metadata_match = 3; - - // Specifies a list of headers to be added to requests when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. - // Headers specified at this level are applied before headers from the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.HeaderValueOption request_headers_to_add = 4 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each request when - // this cluster is selected through the enclosing :ref:`envoy_api_msg_route.RouteAction`. - repeated string request_headers_to_remove = 9; - - // Specifies a list of headers to be added to responses when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. - // Headers specified at this level are applied before headers from the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.HeaderValueOption response_headers_to_add = 5 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of headers to be removed from responses when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. - repeated string response_headers_to_remove = 6; - - // The per_filter_config field can be used to provide weighted cluster-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` - // for if and how it is utilized. - map per_filter_config = 8 [deprecated = true]; - - // The per_filter_config field can be used to provide weighted cluster-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` - // for if and how it is utilized. - map typed_per_filter_config = 10; - } - - // Specifies one or more upstream clusters associated with the route. - repeated ClusterWeight clusters = 1 [(validate.rules).repeated = {min_items: 1}]; - - // Specifies the total weight across all clusters. The sum of all cluster weights must equal this - // value, which must be greater than 0. Defaults to 100. - google.protobuf.UInt32Value total_weight = 3 [(validate.rules).uint32 = {gte: 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 :ref:`runtime documentation - // ` for how key names map to the underlying implementation. - string runtime_key_prefix = 2; -} - -// [#next-free-field: 12] -message RouteMatch { - message GrpcRouteMatchOptions { - } - - message TlsContextMatchOptions { - // If specified, the route will match against whether or not a certificate is presented. - google.protobuf.BoolValue presented = 1; - } - - reserved 5; - - oneof path_specifier { - option (validate.required) = true; - - // 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 rule meaning that the - // regex must match the *:path* header once the query string is removed. The entire path - // (without the query string) must match the regex. The rule will not match if only a - // subsequence of the *:path* header matches the regex. The regex grammar is defined `here - // `_. - // - // Examples: - // - // * The regex ``/b[io]t`` matches the path */bit* - // * The regex ``/b[io]t`` matches the path */bot* - // * The regex ``/b[io]t`` does not match the path */bite* - // * The regex ``/b[io]t`` does not match the path */bit/bot* - // - // .. attention:: - // This field has been deprecated in favor of `safe_regex` as it is not safe for use with - // untrusted input in all cases. - string regex = 3 [deprecated = true, (validate.rules).string = {max_bytes: 1024}]; - - // If specified, the route is a regular expression rule meaning that the - // regex must match the *:path* header once the query string is removed. The entire path - // (without the query string) must match the regex. The rule will not match if only a - // subsequence of the *:path* header matches the regex. - // - // [#next-major-version: In the v3 API we should redo how path specification works such - // that we utilize StringMatcher, and additionally have consistent options around whether we - // strip query strings, do a case sensitive match, etc. In the interim it will be too disruptive - // to deprecate the existing options. We should even consider whether we want to do away with - // path_specifier entirely and just rely on a set of header matchers which can already match - // on :path, etc. The issue with that is it is unclear how to generically deal with query string - // stripping. This needs more thought.] - type.matcher.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}]; - } - - // 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. Every time the route - // is considered for a match, it must also fall under the percentage of matches indicated by - // this field. For some fraction N/D, a random number in the range [0,D) is selected. If the - // number is <= the value of the numerator N, or if the key is not present, the default - // value, the router continues to evaluate the remaining match criteria. A runtime_fraction - // route configuration can be used to roll out route changes in a gradual manner without full - // code/config deploys. Refer to the :ref:`traffic shifting - // ` docs for additional documentation. - // - // .. note:: - // - // Parsing this field is implemented such that the runtime key's data may be represented - // as a FractionalPercent proto represented as JSON/YAML and may also be represented as an - // integer with the assumption that the value is an integral percentage out of 100. For - // instance, a runtime key lookup returning the value "42" would parse as a FractionalPercent - // whose numerator is 42 and denominator is HUNDRED. This preserves legacy semantics. - core.RuntimeFractionalPercent runtime_fraction = 9; - - // 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; - - // Specifies a set of URL query parameters on which the route should - // match. The router will check the query string from the *path* header - // against all the specified query parameters. If the number of specified - // query parameters is nonzero, they all must match the *path* header's - // query string for a match to occur. - repeated QueryParameterMatcher query_parameters = 7; - - // If specified, only gRPC requests will be matched. The router will check - // that the content-type header has a application/grpc or one of the various - // application/grpc+ values. - GrpcRouteMatchOptions grpc = 8; - - // If specified, the client tls context will be matched against the defined - // match options. - // - // [#next-major-version: unify with RBAC] - TlsContextMatchOptions tls_context = 11; -} - -// [#next-free-field: 12] -message CorsPolicy { - // Specifies the origins that will be allowed to do CORS requests. - // - // An origin is allowed if either allow_origin or allow_origin_regex match. - // - // .. attention:: - // This field has been deprecated in favor of `allow_origin_string_match`. - repeated string allow_origin = 1 [deprecated = true]; - - // Specifies regex patterns that match allowed origins. - // - // An origin is allowed if either allow_origin or allow_origin_regex match. - // - // .. attention:: - // This field has been deprecated in favor of `allow_origin_string_match` as it is not safe for - // use with untrusted input in all cases. - repeated string allow_origin_regex = 8 - [deprecated = true, (validate.rules).repeated = {items {string {max_bytes: 1024}}}]; - - // Specifies string patterns that match allowed origins. An origin is allowed if any of the - // string matchers match. - repeated type.matcher.StringMatcher allow_origin_string_match = 11; - - // Specifies the content for the *access-control-allow-methods* header. - string allow_methods = 2; - - // Specifies the content for the *access-control-allow-headers* header. - string allow_headers = 3; - - // Specifies the content for the *access-control-expose-headers* header. - string expose_headers = 4; - - // Specifies the content for the *access-control-max-age* header. - string max_age = 5; - - // Specifies whether the resource allows credentials. - google.protobuf.BoolValue allow_credentials = 6; - - oneof enabled_specifier { - // Specifies if the CORS filter is enabled. Defaults to true. Only effective on route. - // - // .. attention:: - // - // **This field is deprecated**. Set the - // :ref:`filter_enabled` field instead. - google.protobuf.BoolValue enabled = 7 [deprecated = true]; - - // Specifies the % of requests for which the CORS filter is enabled. - // - // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS - // filter will be enabled for 100% of the requests. - // - // If :ref:`runtime_key ` is - // specified, Envoy will lookup the runtime key to get the percentage of requests to filter. - core.RuntimeFractionalPercent filter_enabled = 9; - } - - // Specifies the % of requests for which the CORS policies will be evaluated and tracked, but not - // enforced. - // - // This field is intended to be used when ``filter_enabled`` and ``enabled`` are off. One of those - // fields have to explicitly disable the filter in order for this setting to take effect. - // - // If :ref:`runtime_key ` is specified, - // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate - // and track the request's *Origin* to determine if it's valid but will not enforce any policies. - core.RuntimeFractionalPercent shadow_enabled = 10; -} - -// [#next-free-field: 31] -message RouteAction { - enum ClusterNotFoundResponseCode { - // HTTP status code - 503 Service Unavailable. - SERVICE_UNAVAILABLE = 0; - - // HTTP status code - 404 Not Found. - NOT_FOUND = 1; - } - - // Configures :ref:`internal redirect ` behavior. - enum InternalRedirectAction { - PASS_THROUGH_INTERNAL_REDIRECT = 0; - HANDLE_INTERNAL_REDIRECT = 1; - } - - // The router is capable of shadowing traffic from one cluster to another. The current - // implementation is "fire and forget," meaning Envoy will not wait for the shadow cluster to - // respond before returning the response from the primary cluster. All normal statistics are - // collected for the shadow cluster making this feature useful for testing. - // - // During shadowing, the host/authority header is altered such that *-shadow* is appended. This is - // useful for logging. For example, *cluster1* becomes *cluster1-shadow*. - message RequestMirrorPolicy { - // Specifies the cluster that requests will be mirrored to. The cluster must - // exist in the cluster manager configuration. - string cluster = 1 [(validate.rules).string = {min_bytes: 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. - // - // .. attention:: - // - // **This field is deprecated**. Set the - // :ref:`runtime_fraction - // ` field instead. - string runtime_key = 2 [deprecated = true]; - - // If both :ref:`runtime_key - // ` and this field are not - // specified, all requests to the target cluster will be mirrored. - // - // If specified, this field takes precedence over the `runtime_key` field and requests must also - // fall under the percentage of matches indicated by this field. - // - // For some fraction N/D, a random number in the range [0,D) is selected. If the - // number is <= the value of the numerator N, or if the key is not present, the default - // value, the request will be mirrored. - core.RuntimeFractionalPercent runtime_fraction = 3; - } - - // Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer - // `. - // [#next-free-field: 6] - message HashPolicy { - message Header { - // The name of the request header that will be used to obtain the hash - // key. If the request header is not present, no hash will be produced. - string header_name = 1 [(validate.rules).string = {min_bytes: 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. The cookie is generated by hashing the source and - // destination ports and addresses so that multiple independent HTTP2 - // streams on the same connection will independently receive the same - // cookie, even if they arrive at the Envoy simultaneously. - 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, no hash will be - // produced. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // If specified, a cookie with the TTL will be generated if the cookie is - // not present. If the TTL is present and zero, the generated cookie will - // be a session cookie. - google.protobuf.Duration ttl = 2; - - // The name of the path for the cookie. If no path is specified here, no path - // will be set for the cookie. - string path = 3; - } - - message ConnectionProperties { - // Hash on source IP address. - bool source_ip = 1; - } - - message QueryParameter { - // The name of the URL query parameter that will be used to obtain the hash - // key. If the parameter is not present, no hash will be produced. Query - // parameter names are case-sensitive. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - } - - oneof policy_specifier { - option (validate.required) = true; - - // Header hash policy. - Header header = 1; - - // Cookie hash policy. - Cookie cookie = 2; - - // Connection properties hash policy. - ConnectionProperties connection_properties = 3; - - // Query parameter hash policy. - QueryParameter query_parameter = 5; - } - - // The flag that short-circuits the hash computing. This field provides a - // 'fallback' style of configuration: "if a terminal policy doesn't work, - // fallback to rest of the policy list", it saves time when the terminal - // policy works. - // - // If true, and there is already a hash computed, ignore rest of the - // list of hash polices. - // For example, if the following hash methods are configured: - // - // ========= ======== - // specifier terminal - // ========= ======== - // Header A true - // Header B false - // Header C false - // ========= ======== - // - // The generateHash process ends if policy "header A" generates a hash, as - // it's a terminal policy. - bool terminal = 4; - } - - // Allows enabling and disabling upgrades on a per-route basis. - // This overrides any enabled/disabled upgrade filter chain specified in the - // HttpConnectionManager - // :ref:`upgrade_configs - // ` - // but does not affect any custom filter chain specified there. - message UpgradeConfig { - // The case-insensitive name of this upgrade, e.g. "websocket". - // For each upgrade type present in upgrade_configs, requests with - // Upgrade: [upgrade_type] will be proxied upstream. - string upgrade_type = 1; - - // Determines if upgrades are available on this route. Defaults to true. - google.protobuf.BoolValue enabled = 2; - } - - reserved 12, 18, 19, 16, 22, 21; - - oneof cluster_specifier { - option (validate.required) = true; - - // Indicates the upstream cluster to which the request should be routed - // to. - string cluster = 1 [(validate.rules).string = {min_bytes: 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. - // - // .. attention:: - // - // Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 - // *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead. - string cluster_header = 2 [(validate.rules).string = {min_bytes: 1}]; - - // 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 - // :ref:`traffic splitting ` - // for additional documentation. - WeightedCluster weighted_clusters = 3; - } - - // The HTTP status code to use when configured cluster is not found. - // The default response code is 503 Service Unavailable. - ClusterNotFoundResponseCode cluster_not_found_response_code = 20 - [(validate.rules).enum = {defined_only: true}]; - - // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints - // in the upstream cluster with metadata matching what's set in this field will be considered - // for load balancing. If using :ref:`weighted_clusters - // `, metadata will be merged, with values - // provided there taking precedence. The filter name should be specified as *envoy.lb*. - core.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. The router filter will - // place the original path before rewrite into the :ref:`x-envoy-original-path - // ` header. - // - // .. attention:: - // - // Pay careful attention to the use of trailing slashes in the - // :ref:`route's match ` prefix value. - // Stripping a prefix from a path requires multiple Routes to handle all cases. For example, - // rewriting */prefix* to */* and */prefix/etc* to */etc* cannot be done in a single - // :ref:`Route `, as shown by the below config entries: - // - // .. code-block:: yaml - // - // - match: - // prefix: "/prefix/" - // route: - // prefix_rewrite: "/" - // - match: - // prefix: "/prefix" - // route: - // prefix_rewrite: "/" - // - // Having above entries in the config, requests to */prefix* will be stripped to */*, while - // requests to */prefix/etc* will be stripped to */etc*. - 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 [(udpa.annotations.field_migrate).rename = "host_rewrite_literal"]; - - // 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; - - // Indicates that during forwarding, the host header will be swapped with the content of given - // downstream or :ref:`custom ` header. - // If header value is empty, host header is left intact. - // - // .. attention:: - // - // Pay attention to the potential security implications of using this option. Provided header - // must come from trusted source. - string auto_host_rewrite_header = 29 - [(udpa.annotations.field_migrate).rename = "host_rewrite_header"]; - } - - // Specifies the upstream timeout for the route. If not specified, the default is 15s. This - // spans between the point at which the entire downstream request (i.e. end-of-stream) has been - // processed and when the upstream response has been completely processed. A value of 0 will - // disable the route's timeout. - // - // .. note:: - // - // This timeout includes all retries. See also - // :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`, - // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the - // :ref:`retry overview `. - google.protobuf.Duration timeout = 8; - - // Specifies the idle timeout for the route. If not specified, there is no per-route idle timeout, - // although the connection manager wide :ref:`stream_idle_timeout - // ` - // will still apply. A value of 0 will completely disable the route's idle timeout, even if a - // connection manager stream idle timeout is configured. - // - // The idle timeout is distinct to :ref:`timeout - // `, which provides an upper bound - // on the upstream response time; :ref:`idle_timeout - // ` instead bounds the amount - // of time the request's stream may be idle. - // - // After header decoding, the idle timeout will apply on downstream and - // upstream request events. Each time an encode/decode event for headers or - // data is processed for the stream, the timer will be reset. If the timeout - // fires, the stream is terminated with a 408 Request Timeout error code if no - // upstream response header has been received, otherwise a stream reset - // occurs. - google.protobuf.Duration idle_timeout = 24; - - // Indicates that the route has a retry policy. Note that if this is set, - // it'll take precedence over the virtual host level retry policy entirely - // (e.g.: policies are not merged, most internal one becomes the enforced policy). - RetryPolicy retry_policy = 9; - - // Indicates that the route has a request mirroring policy. - // - // .. attention:: - // This field has been deprecated in favor of `request_mirror_policies` which supports one or - // more mirroring policies. - RequestMirrorPolicy request_mirror_policy = 10 [deprecated = true]; - - // Indicates that the route has request mirroring policies. - repeated RequestMirrorPolicy request_mirror_policies = 30; - - // Optionally specifies the :ref:`routing priority `. - core.RoutingPriority priority = 11 [(validate.rules).enum = {defined_only: true}]; - - // 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 - // :ref:`rate_limits ` are not applied to the - // request. - google.protobuf.BoolValue include_vh_rate_limits = 14; - - // Specifies a list of hash policies to use for ring hash load balancing. Each - // hash policy is evaluated individually and the combined result is used to - // route the request. The method of combination is deterministic such that - // identical lists of hash policies will produce the same hash. Since a hash - // policy examines specific parts of a request, it can fail to produce a hash - // (i.e. if the hashed header is not present). If (and only if) all configured - // hash policies fail to generate a hash, no hash will be produced for - // the route. In this case, the behavior is the same as if no hash policies - // were specified (i.e. the ring hash load balancer will choose a random - // backend). If a hash policy has the "terminal" attribute set to true, and - // there is already a hash generated, the hash is returned immediately, - // ignoring the rest of the hash policy list. - repeated HashPolicy hash_policy = 15; - - // Indicates that the route has a CORS policy. - CorsPolicy cors = 17; - - // If present, and the request is a gRPC request, use the - // `grpc-timeout header `_, - // or its default value (infinity) instead of - // :ref:`timeout `, but limit the applied timeout - // to the maximum value specified here. If configured as 0, the maximum allowed timeout for - // gRPC requests is infinity. If not configured at all, the `grpc-timeout` header is not used - // and gRPC requests time out like any other requests using - // :ref:`timeout ` or its default. - // This can be used to prevent unexpected upstream request timeouts due to potentially long - // time gaps between gRPC request and response in gRPC streaming mode. - google.protobuf.Duration max_grpc_timeout = 23; - - // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by subtracting - // the provided duration from the header. This is useful in allowing Envoy to set its global - // timeout to be less than that of the deadline imposed by the calling client, which makes it more - // likely that Envoy will handle the timeout instead of having the call canceled by the client. - // The offset will only be applied if the provided grpc_timeout is greater than the offset. This - // ensures that the offset will only ever decrease the timeout and never set it to 0 (meaning - // infinity). - google.protobuf.Duration grpc_timeout_offset = 28; - - repeated UpgradeConfig upgrade_configs = 25; - - InternalRedirectAction internal_redirect_action = 26; - - // Indicates that the route has a hedge policy. Note that if this is set, - // it'll take precedence over the virtual host level hedge policy entirely - // (e.g.: policies are not merged, most internal one becomes the enforced policy). - HedgePolicy hedge_policy = 27; -} - -// HTTP retry :ref:`architecture overview `. -// [#next-free-field: 11] -message RetryPolicy { - message RetryPriority { - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - oneof config_type { - google.protobuf.Struct config = 2 [deprecated = true]; - - google.protobuf.Any typed_config = 3; - } - } - - message RetryHostPredicate { - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - oneof config_type { - google.protobuf.Struct config = 2 [deprecated = true]; - - google.protobuf.Any typed_config = 3; - } - } - - message RetryBackOff { - // Specifies the base interval between retries. This parameter is required and must be greater - // than zero. Values less than 1 ms are rounded up to 1 ms. - // See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion of Envoy's - // back-off algorithm. - google.protobuf.Duration base_interval = 1 [(validate.rules).duration = { - required: true - gt {} - }]; - - // Specifies the maximum interval between retries. This parameter is optional, but must be - // greater than or equal to the `base_interval` if set. The default is 10 times the - // `base_interval`. See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion - // of Envoy's back-off algorithm. - google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}]; - } - - // Specifies the conditions under which retry takes place. These are the same - // conditions documented for :ref:`config_http_filters_router_x-envoy-retry-on` and - // :ref:`config_http_filters_router_x-envoy-retry-grpc-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 - // :ref:`config_http_filters_router_x-envoy-max-retries`. - google.protobuf.UInt32Value num_retries = 2; - - // Specifies a non-zero upstream timeout per retry attempt. This parameter is optional. The - // same conditions documented for - // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms` apply. - // - // .. note:: - // - // If left unspecified, Envoy will use the global - // :ref:`route timeout ` for the request. - // Consequently, when using a :ref:`5xx ` based - // retry policy, a request that times out will not be retried as the total timeout budget - // would have been exhausted. - google.protobuf.Duration per_try_timeout = 3; - - // Specifies an implementation of a RetryPriority which is used to determine the - // distribution of load across priorities used for retries. Refer to - // :ref:`retry plugin configuration ` for more details. - RetryPriority retry_priority = 4; - - // Specifies a collection of RetryHostPredicates that will be consulted when selecting a host - // for retries. If any of the predicates reject the host, host selection will be reattempted. - // Refer to :ref:`retry plugin configuration ` for more - // details. - repeated RetryHostPredicate retry_host_predicate = 5; - - // The maximum number of times host selection will be reattempted before giving up, at which - // point the host that was last selected will be routed to. If unspecified, this will default to - // retrying once. - int64 host_selection_retry_max_attempts = 6; - - // HTTP status codes that should trigger a retry in addition to those specified by retry_on. - repeated uint32 retriable_status_codes = 7; - - // Specifies parameters that control retry back off. This parameter is optional, in which case the - // default base interval is 25 milliseconds or, if set, the current value of the - // `upstream.base_retry_backoff_ms` runtime parameter. The default maximum interval is 10 times - // the base interval. The documentation for :ref:`config_http_filters_router_x-envoy-max-retries` - // describes Envoy's back-off algorithm. - RetryBackOff retry_back_off = 8; - - // HTTP response headers that trigger a retry if present in the response. A retry will be - // triggered if any of the header matches match the upstream response headers. - // The field is only consulted if 'retriable-headers' retry policy is active. - repeated HeaderMatcher retriable_headers = 9; - - // HTTP headers which must be present in the request for retries to be attempted. - repeated HeaderMatcher retriable_request_headers = 10; -} - -// HTTP request hedging :ref:`architecture overview `. -message HedgePolicy { - // Specifies the number of initial requests that should be sent upstream. - // Must be at least 1. - // Defaults to 1. - // [#not-implemented-hide:] - google.protobuf.UInt32Value initial_requests = 1 [(validate.rules).uint32 = {gte: 1}]; - - // Specifies a probability that an additional upstream request should be sent - // on top of what is specified by initial_requests. - // Defaults to 0. - // [#not-implemented-hide:] - type.FractionalPercent additional_request_chance = 2; - - // Indicates that a hedged request should be sent when the per-try timeout - // is hit. This will only occur if the retry policy also indicates that a - // timed out request should be retried. - // Once a timed out request is retried due to per try timeout, the router - // filter will ensure that it is not retried again even if the returned - // response headers would otherwise be retried according the specified - // :ref:`RetryPolicy `. - // Defaults to false. - bool hedge_on_per_try_timeout = 3; -} - -// [#next-free-field: 9] -message RedirectAction { - enum RedirectResponseCode { - // Moved Permanently HTTP Status Code - 301. - MOVED_PERMANENTLY = 0; - - // Found HTTP Status Code - 302. - FOUND = 1; - - // See Other HTTP Status Code - 303. - SEE_OTHER = 2; - - // Temporary Redirect HTTP Status Code - 307. - TEMPORARY_REDIRECT = 3; - - // Permanent Redirect HTTP Status Code - 308. - PERMANENT_REDIRECT = 4; - } - - // When the scheme redirection take place, the following rules apply: - // 1. If the source URI scheme is `http` and the port is explicitly - // set to `:80`, the port will be removed after the redirection - // 2. If the source URI scheme is `https` and the port is explicitly - // set to `:443`, the port will be removed after the redirection - oneof scheme_rewrite_specifier { - // The scheme portion of the URL will be swapped with "https". - bool https_redirect = 4; - - // The scheme portion of the URL will be swapped with this value. - string scheme_redirect = 7; - } - - // The host portion of the URL will be swapped with this value. - string host_redirect = 1; - - // The port value of the URL will be swapped with this value. - uint32 port_redirect = 8; - - oneof path_rewrite_specifier { - // The path portion of the URL will be swapped with this value. - string path_redirect = 2; - - // Indicates that during redirection, the matched prefix (or path) - // should be swapped with this value. This option allows redirect URLs be dynamically created - // based on the request. - // - // .. attention:: - // - // Pay attention to the use of trailing slashes as mentioned in - // :ref:`RouteAction's prefix_rewrite `. - string prefix_rewrite = 5; - } - - // The HTTP status code to use in the redirect response. The default response - // code is MOVED_PERMANENTLY (301). - RedirectResponseCode response_code = 3 [(validate.rules).enum = {defined_only: true}]; - - // Indicates that during redirection, the query portion of the URL will - // be removed. Default value is false. - bool strip_query = 6; -} - -message DirectResponseAction { - // Specifies the HTTP response status to be returned. - uint32 status = 1 [(validate.rules).uint32 = {lt: 600 gte: 100}]; - - // Specifies the content of the response body. If this setting is omitted, - // no body is included in the generated response. - // - // .. note:: - // - // Headers can be specified using *response_headers_to_add* in the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_RouteConfiguration` or - // :ref:`envoy_api_msg_route.VirtualHost`. - core.DataSource body = 2; -} - -message Decorator { - // The operation name associated with the request matched to this route. If tracing is - // enabled, this information will be used as the span name reported for this request. - // - // .. note:: - // - // For ingress (inbound) requests, or egress (outbound) responses, this value may be overridden - // by the :ref:`x-envoy-decorator-operation - // ` header. - string operation = 1 [(validate.rules).string = {min_bytes: 1}]; -} - -message Tracing { - // Target percentage of requests managed by this HTTP connection manager that will be force - // traced if the :ref:`x-client-trace-id ` - // header is set. This field is a direct analog for the runtime variable - // 'tracing.client_sampling' in the :ref:`HTTP Connection Manager - // `. - // Default: 100% - type.FractionalPercent client_sampling = 1; - - // Target percentage of requests managed by this HTTP connection manager that will be randomly - // selected for trace generation, if not requested by the client or not forced. This field is - // a direct analog for the runtime variable 'tracing.random_sampling' in the - // :ref:`HTTP Connection Manager `. - // Default: 100% - type.FractionalPercent random_sampling = 2; - - // Target percentage of requests managed by this HTTP connection manager that will be traced - // after all other sampling checks have been applied (client-directed, force tracing, random - // sampling). This field functions as an upper limit on the total configured sampling rate. For - // instance, setting client_sampling to 100% but overall_sampling to 1% will result in only 1% - // of client requests with the appropriate headers to be force traced. This field is a direct - // analog for the runtime variable 'tracing.global_enabled' in the - // :ref:`HTTP Connection Manager `. - // Default: 100% - type.FractionalPercent overall_sampling = 3; - - // A list of custom tags with unique tag name to create tags for the active span. - // It will take effect after merging with the :ref:`corresponding configuration - // ` - // configured in the HTTP connection manager. If two tags with the same name are configured - // each in the HTTP connection manager and the route level, the one configured here takes - // priority. - repeated type.tracing.v2.CustomTag custom_tags = 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. -// -// Documentation for :ref:`virtual cluster statistics `. -// -// .. note:: -// -// Virtual clusters are a useful tool, but we do not recommend setting up a virtual cluster for -// every application endpoint. This is both not easily maintainable and as well the matching and -// statistics output are not free. -message VirtualCluster { - // Specifies a regex pattern to use for matching requests. The entire path of the request - // must match the regex. The regex grammar used is defined `here - // `_. - // - // Examples: - // - // * The regex ``/rides/\d+`` matches the path */rides/0* - // * The regex ``/rides/\d+`` matches the path */rides/123* - // * The regex ``/rides/\d+`` does not match the path */rides/123/456* - // - // .. attention:: - // This field has been deprecated in favor of `headers` as it is not safe for use with - // untrusted input in all cases. - string pattern = 1 [deprecated = true, (validate.rules).string = {max_bytes: 1024}]; - - // Specifies a list of header matchers to use for matching requests. Each specified header must - // match. The pseudo-headers `:path` and `:method` can be used to match the request path and - // method, respectively. - repeated HeaderMatcher headers = 4; - - // Specifies the name of the virtual cluster. The virtual cluster name as well - // as the virtual host name are used when emitting statistics. The statistics are emitted by the - // router filter and are documented :ref:`here `. - string name = 2 [(validate.rules).string = {min_bytes: 1}]; - - // Optionally specifies the HTTP method to match on. For example GET, PUT, - // etc. - // - // .. attention:: - // This field has been deprecated in favor of `headers`. - core.RequestMethod method = 3 [deprecated = true]; -} - -// Global rate limiting :ref:`architecture overview `. -message RateLimit { - // [#next-free-field: 7] - message Action { - // The following descriptor entry is appended to the descriptor: - // - // .. code-block:: cpp - // - // ("source_cluster", "") - // - // is derived from the :option:`--service-cluster` option. - message SourceCluster { - } - - // The following descriptor entry is appended to the descriptor: - // - // .. code-block:: cpp - // - // ("destination_cluster", "") - // - // Once a request matches against a route table rule, a routed cluster is determined by one of - // the following :ref:`route table configuration ` - // settings: - // - // * :ref:`cluster ` indicates the upstream cluster - // to route to. - // * :ref:`weighted_clusters ` - // chooses a cluster randomly from a set of clusters with attributed weight. - // * :ref:`cluster_header ` indicates which - // header in the request contains the target cluster. - message DestinationCluster { - } - - // The following descriptor entry is appended when a header contains a key that matches the - // *header_name*: - // - // .. code-block:: cpp - // - // ("", "") - 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 [(validate.rules).string = {min_bytes: 1}]; - - // The key to use in the descriptor entry. - string descriptor_key = 2 [(validate.rules).string = {min_bytes: 1}]; - } - - // The following descriptor entry is appended to the descriptor and is populated using the - // trusted address from :ref:`x-forwarded-for `: - // - // .. code-block:: cpp - // - // ("remote_address", "") - message RemoteAddress { - } - - // The following descriptor entry is appended to the descriptor: - // - // .. code-block:: cpp - // - // ("generic_key", "") - message GenericKey { - // The value to use in the descriptor entry. - string descriptor_value = 1 [(validate.rules).string = {min_bytes: 1}]; - } - - // The following descriptor entry is appended to the descriptor: - // - // .. code-block:: cpp - // - // ("header_match", "") - message HeaderValueMatch { - // The value to use in the descriptor entry. - string descriptor_value = 1 [(validate.rules).string = {min_bytes: 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 [(validate.rules).repeated = {min_items: 1}]; - } - - oneof action_specifier { - option (validate.required) = true; - - // Rate limit on source cluster. - SourceCluster source_cluster = 1; - - // Rate limit on destination cluster. - DestinationCluster destination_cluster = 2; - - // Rate limit on request headers. - RequestHeaders request_headers = 3; - - // Rate limit on remote address. - RemoteAddress remote_address = 4; - - // Rate limit on a generic key. - GenericKey generic_key = 5; - - // Rate limit on the existence of request headers. - HeaderValueMatch header_value_match = 6; - } - } - - // 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 [(validate.rules).uint32 = {lte: 10}]; - - // The key to be set in runtime to disable this rate limit configuration. - string disable_key = 2; - - // 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 :ref:`composing actions - // ` for additional documentation. - repeated Action actions = 3 [(validate.rules).repeated = {min_items: 1}]; -} - -// .. attention:: -// -// Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host* -// header. Thus, if attempting to match on *Host*, match on *:authority* instead. -// -// .. attention:: -// -// To route on HTTP method, use the special HTTP/2 *:method* header. This works for both -// HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g., -// -// .. code-block:: json -// -// { -// "name": ":method", -// "exact_match": "POST" -// } -// -// .. attention:: -// In the absence of any header match specifier, match will default to :ref:`present_match -// `. i.e, a request that has the :ref:`name -// ` header will match, regardless of the header's -// value. -// -// [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.] -// [#next-free-field: 12] -message HeaderMatcher { - reserved 2, 3; - - // Specifies the name of the header in the request. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // Specifies how the header match will be performed to route the request. - oneof header_match_specifier { - // If specified, header match will be performed based on the value of the header. - string exact_match = 4; - - // If specified, this regex string is a regular expression rule which implies the entire request - // header value must match the regex. The rule will not match if only a subsequence of the - // request header value matches the regex. The regex grammar used in the value field is defined - // `here `_. - // - // Examples: - // - // * The regex ``\d{3}`` matches the value *123* - // * The regex ``\d{3}`` does not match the value *1234* - // * The regex ``\d{3}`` does not match the value *123.456* - // - // .. attention:: - // This field has been deprecated in favor of `safe_regex_match` as it is not safe for use - // with untrusted input in all cases. - string regex_match = 5 [deprecated = true, (validate.rules).string = {max_bytes: 1024}]; - - // If specified, this regex string is a regular expression rule which implies the entire request - // header value must match the regex. The rule will not match if only a subsequence of the - // request header value matches the regex. - type.matcher.RegexMatcher safe_regex_match = 11; - - // If specified, header match will be performed based on range. - // The rule will match if the request header value is within this range. - // The entire request header value must represent an integer in base 10 notation: consisting of - // an optional plus or minus sign followed by a sequence of digits. The rule will not match if - // the header value does not represent an integer. Match will fail for empty values, floating - // point numbers or if only a subsequence of the header value is an integer. - // - // Examples: - // - // * For range [-10,0), route will match for header value -1, but not for 0, "somestring", 10.9, - // "-1somestring" - type.Int64Range range_match = 6; - - // If specified, header match will be performed based on whether the header is in the - // request. - bool present_match = 7; - - // If specified, header match will be performed based on the prefix of the header value. - // Note: empty prefix is not allowed, please use present_match instead. - // - // Examples: - // - // * The prefix *abcd* matches the value *abcdxyz*, but not for *abcxyz*. - string prefix_match = 9 [(validate.rules).string = {min_bytes: 1}]; - - // If specified, header match will be performed based on the suffix of the header value. - // Note: empty suffix is not allowed, please use present_match instead. - // - // Examples: - // - // * The suffix *abcd* matches the value *xyzabcd*, but not for *xyzbcd*. - string suffix_match = 10 [(validate.rules).string = {min_bytes: 1}]; - } - - // If specified, the match result will be inverted before checking. Defaults to false. - // - // Examples: - // - // * The regex ``\d{3}`` does not match the value *1234*, so it will match when inverted. - // * The range [-10,0) will match the value -1, so it will not match when inverted. - bool invert_match = 8; -} - -// Query parameter matching treats the query string of a request's :path header -// as an ampersand-separated list of keys and/or key=value elements. -// [#next-free-field: 7] -message QueryParameterMatcher { - // Specifies the name of a key that must be present in the requested - // *path*'s query string. - string name = 1 [(validate.rules).string = {min_bytes: 1 max_bytes: 1024}]; - - // Specifies the value of the key. If the value is absent, a request - // that contains the key in its query string will match, whether the - // key appears with a value (e.g., "?debug=true") or not (e.g., "?debug") - // - // ..attention:: - // This field is deprecated. Use an `exact` match inside the `string_match` field. - string value = 3 [deprecated = true]; - - // Specifies whether the query parameter value is a regular expression. - // Defaults to false. The entire query parameter value (i.e., the part to - // the right of the equals sign in "key=value") must match the regex. - // E.g., the regex ``\d+$`` will match *123* but not *a123* or *123a*. - // - // ..attention:: - // This field is deprecated. Use a `safe_regex` match inside the `string_match` field. - google.protobuf.BoolValue regex = 4 [deprecated = true]; - - oneof query_parameter_match_specifier { - // Specifies whether a query parameter value should match against a string. - type.matcher.StringMatcher string_match = 5 [(validate.rules).message = {required: true}]; - - // Specifies whether a query parameter should be present. - bool present_match = 6; - } -} diff --git a/envoy/api/v2/route/route_components.proto b/envoy/api/v2/route/route_components.proto new file mode 100644 index 00000000..0df0407d --- /dev/null +++ b/envoy/api/v2/route/route_components.proto @@ -0,0 +1,1449 @@ +syntax = "proto3"; + +package envoy.api.v2.route; + +import "envoy/api/v2/core/base.proto"; +import "envoy/type/matcher/regex.proto"; +import "envoy/type/matcher/string.proto"; +import "envoy/type/percent.proto"; +import "envoy/type/range.proto"; +import "envoy/type/tracing/v2/custom_tag.proto"; + +import "google/protobuf/any.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/migrate.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.api.v2.route"; +option java_outer_classname = "RouteComponentsProto"; +option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.config.route.v3alpha"; + +// [#protodoc-title: HTTP route components] +// * Routing :ref:`architecture overview ` +// * HTTP :ref:`router filter ` + +// The top level element in the routing configuration is a virtual host. Each virtual host has +// a logical name as well as a set of domains that get routed to it based on the incoming request's +// host header. This allows a single listener to service multiple top level domain path trees. Once +// a virtual host is selected based on the domain, the routes are processed in order to see which +// upstream cluster to route to or whether to perform a redirect. +// [#next-free-field: 19] +message VirtualHost { + 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 301 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 301 redirect + // will be sent telling the client to use HTTPS. + ALL = 2; + } + + reserved 9; + + // The logical name of the virtual host. This is used when emitting certain + // statistics but is not relevant for routing. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // A list of domains (host/authority header) that will be matched to this + // virtual host. Wildcard hosts are supported in the suffix or prefix form. + // + // Domain search order: + // 1. Exact domain names: ``www.foo.com``. + // 2. Suffix domain wildcards: ``*.foo.com`` or ``*-bar.foo.com``. + // 3. Prefix domain wildcards: ``foo.*`` or ``foo-*``. + // 4. Special wildcard ``*`` matching any domain. + // + // .. note:: + // + // The wildcard will not match the empty string. + // e.g. ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``. + // The longest wildcards match first. + // 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 [(validate.rules).repeated = {min_items: 1}]; + + // 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; + + // Specifies the type of TLS enforcement the virtual host expects. If this option is not + // specified, there is no TLS requirement for the virtual host. + 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. Headers specified at this level are applied + // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the + // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // details on header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.HeaderValueOption request_headers_to_add = 7 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each request + // handled by this virtual host. + repeated string request_headers_to_remove = 13; + + // Specifies a list of HTTP headers that should be added to each response + // handled by this virtual host. Headers specified at this level are applied + // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the + // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // details on header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.HeaderValueOption response_headers_to_add = 10 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each response + // handled by this virtual host. + repeated string response_headers_to_remove = 11; + + // Indicates that the virtual host has a CORS policy. + CorsPolicy cors = 8; + + // The per_filter_config field can be used to provide virtual host-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` + // for if and how it is utilized. + map per_filter_config = 12 [deprecated = true]; + + // The per_filter_config field can be used to provide virtual host-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` + // for if and how it is utilized. + map typed_per_filter_config = 15; + + // Decides whether the :ref:`x-envoy-attempt-count + // ` header should be included + // in the upstream request. Setting this option will cause it to override any existing header + // value, so in the case of two Envoys on the request path with this option enabled, the upstream + // will see the attempt count as perceived by the second Envoy. Defaults to false. + // This header is unaffected by the + // :ref:`suppress_envoy_headers + // ` flag. + bool include_request_attempt_count = 14; + + // Indicates the retry policy for all routes in this virtual host. Note that setting a + // route level entry will take precedence over this config and it'll be treated + // independently (e.g.: values are not inherited). + RetryPolicy retry_policy = 16; + + // Indicates the hedge policy for all routes in this virtual host. Note that setting a + // route level entry will take precedence over this config and it'll be treated + // independently (e.g.: values are not inherited). + HedgePolicy hedge_policy = 17; + + // The maximum bytes which will be buffered for retries and shadowing. + // If set and a route-specific limit is not set, the bytes actually buffered will be the minimum + // value of this and the listener per_connection_buffer_limit_bytes. + google.protobuf.UInt32Value per_request_buffer_limit_bytes = 18; +} + +// A filter-defined action type. +message FilterAction { + google.protobuf.Any action = 1; +} + +// A route is both a specification of how to match a request as well as an indication of what to do +// next (e.g., redirect, forward, rewrite, etc.). +// +// .. attention:: +// +// Envoy supports routing on HTTP method via :ref:`header matching +// `. +// [#next-free-field: 18] +message Route { + reserved 6; + + // Name for the route. + string name = 14; + + // Route matching parameters. + RouteMatch match = 1 [(validate.rules).message = {required: true}]; + + oneof action { + option (validate.required) = true; + + // Route request to some upstream cluster. + RouteAction route = 2; + + // Return a redirect. + RedirectAction redirect = 3; + + // Return an arbitrary HTTP response directly, without proxying. + DirectResponseAction direct_response = 7; + + // [#not-implemented-hide:] + // If true, a filter will define the action (e.g., it could dynamically generate the + // RouteAction). + FilterAction filter_action = 17; + } + + // The Metadata field can be used to provide additional information + // about the route. It can be used for configuration, stats, and logging. + // The metadata should go under the filter namespace that will need it. + // For instance, if the metadata is intended for the Router filter, + // the filter name should be specified as *envoy.router*. + core.Metadata metadata = 4; + + // Decorator for the matched route. + Decorator decorator = 5; + + // The per_filter_config field can be used to provide route-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` for + // if and how it is utilized. + map per_filter_config = 8 [deprecated = true]; + + // The per_filter_config field can be used to provide route-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` for + // if and how it is utilized. + map typed_per_filter_config = 13; + + // Specifies a set of headers that will be added to requests matching this + // route. Headers specified at this level are applied before headers from the + // enclosing :ref:`envoy_api_msg_route.VirtualHost` and + // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.HeaderValueOption request_headers_to_add = 9 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each request + // matching this route. + repeated string request_headers_to_remove = 12; + + // Specifies a set of headers that will be added to responses to requests + // matching this route. Headers specified at this level are applied before + // headers from the enclosing :ref:`envoy_api_msg_route.VirtualHost` and + // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // details on header value syntax, see the documentation on + // :ref:`custom request headers `. + repeated core.HeaderValueOption response_headers_to_add = 10 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each response + // to requests matching this route. + repeated string response_headers_to_remove = 11; + + // Presence of the object defines whether the connection manager's tracing configuration + // is overridden by this route specific instance. + Tracing tracing = 15; + + // The maximum bytes which will be buffered for retries and shadowing. + // If set, the bytes actually buffered will be the minimum value of this and the + // listener per_connection_buffer_limit_bytes. + google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16; +} + +// Compared to the :ref:`cluster ` field that specifies a +// single upstream cluster as the target of a request, the :ref:`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 { + // [#next-free-field: 11] + message ClusterWeight { + reserved 7; + + // Name of the upstream cluster. The cluster must exist in the + // :ref:`cluster manager configuration `. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // An integer between 0 and :ref:`total_weight + // `. 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 the total_weight, which defaults to 100. + google.protobuf.UInt32Value weight = 2; + + // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in + // the upstream cluster with metadata matching what is set in this field will be considered for + // load balancing. Note that this will be merged with what's provided in + // :ref:`RouteAction.metadata_match `, with + // values here taking precedence. The filter name should be specified as *envoy.lb*. + core.Metadata metadata_match = 3; + + // Specifies a list of headers to be added to requests when this cluster is selected + // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + // Headers specified at this level are applied before headers from the enclosing + // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and + // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.HeaderValueOption request_headers_to_add = 4 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each request when + // this cluster is selected through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + repeated string request_headers_to_remove = 9; + + // Specifies a list of headers to be added to responses when this cluster is selected + // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + // Headers specified at this level are applied before headers from the enclosing + // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and + // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.HeaderValueOption response_headers_to_add = 5 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of headers to be removed from responses when this cluster is selected + // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + repeated string response_headers_to_remove = 6; + + // The per_filter_config field can be used to provide weighted cluster-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` + // for if and how it is utilized. + map per_filter_config = 8 [deprecated = true]; + + // The per_filter_config field can be used to provide weighted cluster-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` + // for if and how it is utilized. + map typed_per_filter_config = 10; + } + + // Specifies one or more upstream clusters associated with the route. + repeated ClusterWeight clusters = 1 [(validate.rules).repeated = {min_items: 1}]; + + // Specifies the total weight across all clusters. The sum of all cluster weights must equal this + // value, which must be greater than 0. Defaults to 100. + google.protobuf.UInt32Value total_weight = 3 [(validate.rules).uint32 = {gte: 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 :ref:`runtime documentation + // ` for how key names map to the underlying implementation. + string runtime_key_prefix = 2; +} + +// [#next-free-field: 12] +message RouteMatch { + message GrpcRouteMatchOptions { + } + + message TlsContextMatchOptions { + // If specified, the route will match against whether or not a certificate is presented. + google.protobuf.BoolValue presented = 1; + } + + reserved 5; + + oneof path_specifier { + option (validate.required) = true; + + // 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 rule meaning that the + // regex must match the *:path* header once the query string is removed. The entire path + // (without the query string) must match the regex. The rule will not match if only a + // subsequence of the *:path* header matches the regex. The regex grammar is defined `here + // `_. + // + // Examples: + // + // * The regex ``/b[io]t`` matches the path */bit* + // * The regex ``/b[io]t`` matches the path */bot* + // * The regex ``/b[io]t`` does not match the path */bite* + // * The regex ``/b[io]t`` does not match the path */bit/bot* + // + // .. attention:: + // This field has been deprecated in favor of `safe_regex` as it is not safe for use with + // untrusted input in all cases. + string regex = 3 [deprecated = true, (validate.rules).string = {max_bytes: 1024}]; + + // If specified, the route is a regular expression rule meaning that the + // regex must match the *:path* header once the query string is removed. The entire path + // (without the query string) must match the regex. The rule will not match if only a + // subsequence of the *:path* header matches the regex. + // + // [#next-major-version: In the v3 API we should redo how path specification works such + // that we utilize StringMatcher, and additionally have consistent options around whether we + // strip query strings, do a case sensitive match, etc. In the interim it will be too disruptive + // to deprecate the existing options. We should even consider whether we want to do away with + // path_specifier entirely and just rely on a set of header matchers which can already match + // on :path, etc. The issue with that is it is unclear how to generically deal with query string + // stripping. This needs more thought.] + type.matcher.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}]; + } + + // 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. Every time the route + // is considered for a match, it must also fall under the percentage of matches indicated by + // this field. For some fraction N/D, a random number in the range [0,D) is selected. If the + // number is <= the value of the numerator N, or if the key is not present, the default + // value, the router continues to evaluate the remaining match criteria. A runtime_fraction + // route configuration can be used to roll out route changes in a gradual manner without full + // code/config deploys. Refer to the :ref:`traffic shifting + // ` docs for additional documentation. + // + // .. note:: + // + // Parsing this field is implemented such that the runtime key's data may be represented + // as a FractionalPercent proto represented as JSON/YAML and may also be represented as an + // integer with the assumption that the value is an integral percentage out of 100. For + // instance, a runtime key lookup returning the value "42" would parse as a FractionalPercent + // whose numerator is 42 and denominator is HUNDRED. This preserves legacy semantics. + core.RuntimeFractionalPercent runtime_fraction = 9; + + // 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; + + // Specifies a set of URL query parameters on which the route should + // match. The router will check the query string from the *path* header + // against all the specified query parameters. If the number of specified + // query parameters is nonzero, they all must match the *path* header's + // query string for a match to occur. + repeated QueryParameterMatcher query_parameters = 7; + + // If specified, only gRPC requests will be matched. The router will check + // that the content-type header has a application/grpc or one of the various + // application/grpc+ values. + GrpcRouteMatchOptions grpc = 8; + + // If specified, the client tls context will be matched against the defined + // match options. + // + // [#next-major-version: unify with RBAC] + TlsContextMatchOptions tls_context = 11; +} + +// [#next-free-field: 12] +message CorsPolicy { + // Specifies the origins that will be allowed to do CORS requests. + // + // An origin is allowed if either allow_origin or allow_origin_regex match. + // + // .. attention:: + // This field has been deprecated in favor of `allow_origin_string_match`. + repeated string allow_origin = 1 [deprecated = true]; + + // Specifies regex patterns that match allowed origins. + // + // An origin is allowed if either allow_origin or allow_origin_regex match. + // + // .. attention:: + // This field has been deprecated in favor of `allow_origin_string_match` as it is not safe for + // use with untrusted input in all cases. + repeated string allow_origin_regex = 8 + [deprecated = true, (validate.rules).repeated = {items {string {max_bytes: 1024}}}]; + + // Specifies string patterns that match allowed origins. An origin is allowed if any of the + // string matchers match. + repeated type.matcher.StringMatcher allow_origin_string_match = 11; + + // Specifies the content for the *access-control-allow-methods* header. + string allow_methods = 2; + + // Specifies the content for the *access-control-allow-headers* header. + string allow_headers = 3; + + // Specifies the content for the *access-control-expose-headers* header. + string expose_headers = 4; + + // Specifies the content for the *access-control-max-age* header. + string max_age = 5; + + // Specifies whether the resource allows credentials. + google.protobuf.BoolValue allow_credentials = 6; + + oneof enabled_specifier { + // Specifies if the CORS filter is enabled. Defaults to true. Only effective on route. + // + // .. attention:: + // + // **This field is deprecated**. Set the + // :ref:`filter_enabled` field instead. + google.protobuf.BoolValue enabled = 7 [deprecated = true]; + + // Specifies the % of requests for which the CORS filter is enabled. + // + // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS + // filter will be enabled for 100% of the requests. + // + // If :ref:`runtime_key ` is + // specified, Envoy will lookup the runtime key to get the percentage of requests to filter. + core.RuntimeFractionalPercent filter_enabled = 9; + } + + // Specifies the % of requests for which the CORS policies will be evaluated and tracked, but not + // enforced. + // + // This field is intended to be used when ``filter_enabled`` and ``enabled`` are off. One of those + // fields have to explicitly disable the filter in order for this setting to take effect. + // + // If :ref:`runtime_key ` is specified, + // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate + // and track the request's *Origin* to determine if it's valid but will not enforce any policies. + core.RuntimeFractionalPercent shadow_enabled = 10; +} + +// [#next-free-field: 31] +message RouteAction { + enum ClusterNotFoundResponseCode { + // HTTP status code - 503 Service Unavailable. + SERVICE_UNAVAILABLE = 0; + + // HTTP status code - 404 Not Found. + NOT_FOUND = 1; + } + + // Configures :ref:`internal redirect ` behavior. + enum InternalRedirectAction { + PASS_THROUGH_INTERNAL_REDIRECT = 0; + HANDLE_INTERNAL_REDIRECT = 1; + } + + // The router is capable of shadowing traffic from one cluster to another. The current + // implementation is "fire and forget," meaning Envoy will not wait for the shadow cluster to + // respond before returning the response from the primary cluster. All normal statistics are + // collected for the shadow cluster making this feature useful for testing. + // + // During shadowing, the host/authority header is altered such that *-shadow* is appended. This is + // useful for logging. For example, *cluster1* becomes *cluster1-shadow*. + message RequestMirrorPolicy { + // Specifies the cluster that requests will be mirrored to. The cluster must + // exist in the cluster manager configuration. + string cluster = 1 [(validate.rules).string = {min_bytes: 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. + // + // .. attention:: + // + // **This field is deprecated**. Set the + // :ref:`runtime_fraction + // ` field instead. + string runtime_key = 2 [deprecated = true]; + + // If both :ref:`runtime_key + // ` and this field are not + // specified, all requests to the target cluster will be mirrored. + // + // If specified, this field takes precedence over the `runtime_key` field and requests must also + // fall under the percentage of matches indicated by this field. + // + // For some fraction N/D, a random number in the range [0,D) is selected. If the + // number is <= the value of the numerator N, or if the key is not present, the default + // value, the request will be mirrored. + core.RuntimeFractionalPercent runtime_fraction = 3; + } + + // Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer + // `. + // [#next-free-field: 6] + message HashPolicy { + message Header { + // The name of the request header that will be used to obtain the hash + // key. If the request header is not present, no hash will be produced. + string header_name = 1 [(validate.rules).string = {min_bytes: 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. The cookie is generated by hashing the source and + // destination ports and addresses so that multiple independent HTTP2 + // streams on the same connection will independently receive the same + // cookie, even if they arrive at the Envoy simultaneously. + 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, no hash will be + // produced. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // If specified, a cookie with the TTL will be generated if the cookie is + // not present. If the TTL is present and zero, the generated cookie will + // be a session cookie. + google.protobuf.Duration ttl = 2; + + // The name of the path for the cookie. If no path is specified here, no path + // will be set for the cookie. + string path = 3; + } + + message ConnectionProperties { + // Hash on source IP address. + bool source_ip = 1; + } + + message QueryParameter { + // The name of the URL query parameter that will be used to obtain the hash + // key. If the parameter is not present, no hash will be produced. Query + // parameter names are case-sensitive. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + } + + oneof policy_specifier { + option (validate.required) = true; + + // Header hash policy. + Header header = 1; + + // Cookie hash policy. + Cookie cookie = 2; + + // Connection properties hash policy. + ConnectionProperties connection_properties = 3; + + // Query parameter hash policy. + QueryParameter query_parameter = 5; + } + + // The flag that short-circuits the hash computing. This field provides a + // 'fallback' style of configuration: "if a terminal policy doesn't work, + // fallback to rest of the policy list", it saves time when the terminal + // policy works. + // + // If true, and there is already a hash computed, ignore rest of the + // list of hash polices. + // For example, if the following hash methods are configured: + // + // ========= ======== + // specifier terminal + // ========= ======== + // Header A true + // Header B false + // Header C false + // ========= ======== + // + // The generateHash process ends if policy "header A" generates a hash, as + // it's a terminal policy. + bool terminal = 4; + } + + // Allows enabling and disabling upgrades on a per-route basis. + // This overrides any enabled/disabled upgrade filter chain specified in the + // HttpConnectionManager + // :ref:`upgrade_configs + // ` + // but does not affect any custom filter chain specified there. + message UpgradeConfig { + // The case-insensitive name of this upgrade, e.g. "websocket". + // For each upgrade type present in upgrade_configs, requests with + // Upgrade: [upgrade_type] will be proxied upstream. + string upgrade_type = 1; + + // Determines if upgrades are available on this route. Defaults to true. + google.protobuf.BoolValue enabled = 2; + } + + reserved 12, 18, 19, 16, 22, 21; + + oneof cluster_specifier { + option (validate.required) = true; + + // Indicates the upstream cluster to which the request should be routed + // to. + string cluster = 1 [(validate.rules).string = {min_bytes: 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. + // + // .. attention:: + // + // Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 + // *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead. + string cluster_header = 2 [(validate.rules).string = {min_bytes: 1}]; + + // 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 + // :ref:`traffic splitting ` + // for additional documentation. + WeightedCluster weighted_clusters = 3; + } + + // The HTTP status code to use when configured cluster is not found. + // The default response code is 503 Service Unavailable. + ClusterNotFoundResponseCode cluster_not_found_response_code = 20 + [(validate.rules).enum = {defined_only: true}]; + + // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints + // in the upstream cluster with metadata matching what's set in this field will be considered + // for load balancing. If using :ref:`weighted_clusters + // `, metadata will be merged, with values + // provided there taking precedence. The filter name should be specified as *envoy.lb*. + core.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. The router filter will + // place the original path before rewrite into the :ref:`x-envoy-original-path + // ` header. + // + // .. attention:: + // + // Pay careful attention to the use of trailing slashes in the + // :ref:`route's match ` prefix value. + // Stripping a prefix from a path requires multiple Routes to handle all cases. For example, + // rewriting */prefix* to */* and */prefix/etc* to */etc* cannot be done in a single + // :ref:`Route `, as shown by the below config entries: + // + // .. code-block:: yaml + // + // - match: + // prefix: "/prefix/" + // route: + // prefix_rewrite: "/" + // - match: + // prefix: "/prefix" + // route: + // prefix_rewrite: "/" + // + // Having above entries in the config, requests to */prefix* will be stripped to */*, while + // requests to */prefix/etc* will be stripped to */etc*. + 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 [(udpa.annotations.field_migrate).rename = "host_rewrite_literal"]; + + // 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; + + // Indicates that during forwarding, the host header will be swapped with the content of given + // downstream or :ref:`custom ` header. + // If header value is empty, host header is left intact. + // + // .. attention:: + // + // Pay attention to the potential security implications of using this option. Provided header + // must come from trusted source. + string auto_host_rewrite_header = 29 + [(udpa.annotations.field_migrate).rename = "host_rewrite_header"]; + } + + // Specifies the upstream timeout for the route. If not specified, the default is 15s. This + // spans between the point at which the entire downstream request (i.e. end-of-stream) has been + // processed and when the upstream response has been completely processed. A value of 0 will + // disable the route's timeout. + // + // .. note:: + // + // This timeout includes all retries. See also + // :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`, + // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the + // :ref:`retry overview `. + google.protobuf.Duration timeout = 8; + + // Specifies the idle timeout for the route. If not specified, there is no per-route idle timeout, + // although the connection manager wide :ref:`stream_idle_timeout + // ` + // will still apply. A value of 0 will completely disable the route's idle timeout, even if a + // connection manager stream idle timeout is configured. + // + // The idle timeout is distinct to :ref:`timeout + // `, which provides an upper bound + // on the upstream response time; :ref:`idle_timeout + // ` instead bounds the amount + // of time the request's stream may be idle. + // + // After header decoding, the idle timeout will apply on downstream and + // upstream request events. Each time an encode/decode event for headers or + // data is processed for the stream, the timer will be reset. If the timeout + // fires, the stream is terminated with a 408 Request Timeout error code if no + // upstream response header has been received, otherwise a stream reset + // occurs. + google.protobuf.Duration idle_timeout = 24; + + // Indicates that the route has a retry policy. Note that if this is set, + // it'll take precedence over the virtual host level retry policy entirely + // (e.g.: policies are not merged, most internal one becomes the enforced policy). + RetryPolicy retry_policy = 9; + + // Indicates that the route has a request mirroring policy. + // + // .. attention:: + // This field has been deprecated in favor of `request_mirror_policies` which supports one or + // more mirroring policies. + RequestMirrorPolicy request_mirror_policy = 10 [deprecated = true]; + + // Indicates that the route has request mirroring policies. + repeated RequestMirrorPolicy request_mirror_policies = 30; + + // Optionally specifies the :ref:`routing priority `. + core.RoutingPriority priority = 11 [(validate.rules).enum = {defined_only: true}]; + + // 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 + // :ref:`rate_limits ` are not applied to the + // request. + google.protobuf.BoolValue include_vh_rate_limits = 14; + + // Specifies a list of hash policies to use for ring hash load balancing. Each + // hash policy is evaluated individually and the combined result is used to + // route the request. The method of combination is deterministic such that + // identical lists of hash policies will produce the same hash. Since a hash + // policy examines specific parts of a request, it can fail to produce a hash + // (i.e. if the hashed header is not present). If (and only if) all configured + // hash policies fail to generate a hash, no hash will be produced for + // the route. In this case, the behavior is the same as if no hash policies + // were specified (i.e. the ring hash load balancer will choose a random + // backend). If a hash policy has the "terminal" attribute set to true, and + // there is already a hash generated, the hash is returned immediately, + // ignoring the rest of the hash policy list. + repeated HashPolicy hash_policy = 15; + + // Indicates that the route has a CORS policy. + CorsPolicy cors = 17; + + // If present, and the request is a gRPC request, use the + // `grpc-timeout header `_, + // or its default value (infinity) instead of + // :ref:`timeout `, but limit the applied timeout + // to the maximum value specified here. If configured as 0, the maximum allowed timeout for + // gRPC requests is infinity. If not configured at all, the `grpc-timeout` header is not used + // and gRPC requests time out like any other requests using + // :ref:`timeout ` or its default. + // This can be used to prevent unexpected upstream request timeouts due to potentially long + // time gaps between gRPC request and response in gRPC streaming mode. + google.protobuf.Duration max_grpc_timeout = 23; + + // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by subtracting + // the provided duration from the header. This is useful in allowing Envoy to set its global + // timeout to be less than that of the deadline imposed by the calling client, which makes it more + // likely that Envoy will handle the timeout instead of having the call canceled by the client. + // The offset will only be applied if the provided grpc_timeout is greater than the offset. This + // ensures that the offset will only ever decrease the timeout and never set it to 0 (meaning + // infinity). + google.protobuf.Duration grpc_timeout_offset = 28; + + repeated UpgradeConfig upgrade_configs = 25; + + InternalRedirectAction internal_redirect_action = 26; + + // Indicates that the route has a hedge policy. Note that if this is set, + // it'll take precedence over the virtual host level hedge policy entirely + // (e.g.: policies are not merged, most internal one becomes the enforced policy). + HedgePolicy hedge_policy = 27; +} + +// HTTP retry :ref:`architecture overview `. +// [#next-free-field: 11] +message RetryPolicy { + message RetryPriority { + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + oneof config_type { + google.protobuf.Struct config = 2 [deprecated = true]; + + google.protobuf.Any typed_config = 3; + } + } + + message RetryHostPredicate { + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + oneof config_type { + google.protobuf.Struct config = 2 [deprecated = true]; + + google.protobuf.Any typed_config = 3; + } + } + + message RetryBackOff { + // Specifies the base interval between retries. This parameter is required and must be greater + // than zero. Values less than 1 ms are rounded up to 1 ms. + // See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion of Envoy's + // back-off algorithm. + google.protobuf.Duration base_interval = 1 [(validate.rules).duration = { + required: true + gt {} + }]; + + // Specifies the maximum interval between retries. This parameter is optional, but must be + // greater than or equal to the `base_interval` if set. The default is 10 times the + // `base_interval`. See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion + // of Envoy's back-off algorithm. + google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}]; + } + + // Specifies the conditions under which retry takes place. These are the same + // conditions documented for :ref:`config_http_filters_router_x-envoy-retry-on` and + // :ref:`config_http_filters_router_x-envoy-retry-grpc-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 + // :ref:`config_http_filters_router_x-envoy-max-retries`. + google.protobuf.UInt32Value num_retries = 2; + + // Specifies a non-zero upstream timeout per retry attempt. This parameter is optional. The + // same conditions documented for + // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms` apply. + // + // .. note:: + // + // If left unspecified, Envoy will use the global + // :ref:`route timeout ` for the request. + // Consequently, when using a :ref:`5xx ` based + // retry policy, a request that times out will not be retried as the total timeout budget + // would have been exhausted. + google.protobuf.Duration per_try_timeout = 3; + + // Specifies an implementation of a RetryPriority which is used to determine the + // distribution of load across priorities used for retries. Refer to + // :ref:`retry plugin configuration ` for more details. + RetryPriority retry_priority = 4; + + // Specifies a collection of RetryHostPredicates that will be consulted when selecting a host + // for retries. If any of the predicates reject the host, host selection will be reattempted. + // Refer to :ref:`retry plugin configuration ` for more + // details. + repeated RetryHostPredicate retry_host_predicate = 5; + + // The maximum number of times host selection will be reattempted before giving up, at which + // point the host that was last selected will be routed to. If unspecified, this will default to + // retrying once. + int64 host_selection_retry_max_attempts = 6; + + // HTTP status codes that should trigger a retry in addition to those specified by retry_on. + repeated uint32 retriable_status_codes = 7; + + // Specifies parameters that control retry back off. This parameter is optional, in which case the + // default base interval is 25 milliseconds or, if set, the current value of the + // `upstream.base_retry_backoff_ms` runtime parameter. The default maximum interval is 10 times + // the base interval. The documentation for :ref:`config_http_filters_router_x-envoy-max-retries` + // describes Envoy's back-off algorithm. + RetryBackOff retry_back_off = 8; + + // HTTP response headers that trigger a retry if present in the response. A retry will be + // triggered if any of the header matches match the upstream response headers. + // The field is only consulted if 'retriable-headers' retry policy is active. + repeated HeaderMatcher retriable_headers = 9; + + // HTTP headers which must be present in the request for retries to be attempted. + repeated HeaderMatcher retriable_request_headers = 10; +} + +// HTTP request hedging :ref:`architecture overview `. +message HedgePolicy { + // Specifies the number of initial requests that should be sent upstream. + // Must be at least 1. + // Defaults to 1. + // [#not-implemented-hide:] + google.protobuf.UInt32Value initial_requests = 1 [(validate.rules).uint32 = {gte: 1}]; + + // Specifies a probability that an additional upstream request should be sent + // on top of what is specified by initial_requests. + // Defaults to 0. + // [#not-implemented-hide:] + type.FractionalPercent additional_request_chance = 2; + + // Indicates that a hedged request should be sent when the per-try timeout + // is hit. This will only occur if the retry policy also indicates that a + // timed out request should be retried. + // Once a timed out request is retried due to per try timeout, the router + // filter will ensure that it is not retried again even if the returned + // response headers would otherwise be retried according the specified + // :ref:`RetryPolicy `. + // Defaults to false. + bool hedge_on_per_try_timeout = 3; +} + +// [#next-free-field: 9] +message RedirectAction { + enum RedirectResponseCode { + // Moved Permanently HTTP Status Code - 301. + MOVED_PERMANENTLY = 0; + + // Found HTTP Status Code - 302. + FOUND = 1; + + // See Other HTTP Status Code - 303. + SEE_OTHER = 2; + + // Temporary Redirect HTTP Status Code - 307. + TEMPORARY_REDIRECT = 3; + + // Permanent Redirect HTTP Status Code - 308. + PERMANENT_REDIRECT = 4; + } + + // When the scheme redirection take place, the following rules apply: + // 1. If the source URI scheme is `http` and the port is explicitly + // set to `:80`, the port will be removed after the redirection + // 2. If the source URI scheme is `https` and the port is explicitly + // set to `:443`, the port will be removed after the redirection + oneof scheme_rewrite_specifier { + // The scheme portion of the URL will be swapped with "https". + bool https_redirect = 4; + + // The scheme portion of the URL will be swapped with this value. + string scheme_redirect = 7; + } + + // The host portion of the URL will be swapped with this value. + string host_redirect = 1; + + // The port value of the URL will be swapped with this value. + uint32 port_redirect = 8; + + oneof path_rewrite_specifier { + // The path portion of the URL will be swapped with this value. + string path_redirect = 2; + + // Indicates that during redirection, the matched prefix (or path) + // should be swapped with this value. This option allows redirect URLs be dynamically created + // based on the request. + // + // .. attention:: + // + // Pay attention to the use of trailing slashes as mentioned in + // :ref:`RouteAction's prefix_rewrite `. + string prefix_rewrite = 5; + } + + // The HTTP status code to use in the redirect response. The default response + // code is MOVED_PERMANENTLY (301). + RedirectResponseCode response_code = 3 [(validate.rules).enum = {defined_only: true}]; + + // Indicates that during redirection, the query portion of the URL will + // be removed. Default value is false. + bool strip_query = 6; +} + +message DirectResponseAction { + // Specifies the HTTP response status to be returned. + uint32 status = 1 [(validate.rules).uint32 = {lt: 600 gte: 100}]; + + // Specifies the content of the response body. If this setting is omitted, + // no body is included in the generated response. + // + // .. note:: + // + // Headers can be specified using *response_headers_to_add* in the enclosing + // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_RouteConfiguration` or + // :ref:`envoy_api_msg_route.VirtualHost`. + core.DataSource body = 2; +} + +message Decorator { + // The operation name associated with the request matched to this route. If tracing is + // enabled, this information will be used as the span name reported for this request. + // + // .. note:: + // + // For ingress (inbound) requests, or egress (outbound) responses, this value may be overridden + // by the :ref:`x-envoy-decorator-operation + // ` header. + string operation = 1 [(validate.rules).string = {min_bytes: 1}]; +} + +message Tracing { + // Target percentage of requests managed by this HTTP connection manager that will be force + // traced if the :ref:`x-client-trace-id ` + // header is set. This field is a direct analog for the runtime variable + // 'tracing.client_sampling' in the :ref:`HTTP Connection Manager + // `. + // Default: 100% + type.FractionalPercent client_sampling = 1; + + // Target percentage of requests managed by this HTTP connection manager that will be randomly + // selected for trace generation, if not requested by the client or not forced. This field is + // a direct analog for the runtime variable 'tracing.random_sampling' in the + // :ref:`HTTP Connection Manager `. + // Default: 100% + type.FractionalPercent random_sampling = 2; + + // Target percentage of requests managed by this HTTP connection manager that will be traced + // after all other sampling checks have been applied (client-directed, force tracing, random + // sampling). This field functions as an upper limit on the total configured sampling rate. For + // instance, setting client_sampling to 100% but overall_sampling to 1% will result in only 1% + // of client requests with the appropriate headers to be force traced. This field is a direct + // analog for the runtime variable 'tracing.global_enabled' in the + // :ref:`HTTP Connection Manager `. + // Default: 100% + type.FractionalPercent overall_sampling = 3; + + // A list of custom tags with unique tag name to create tags for the active span. + // It will take effect after merging with the :ref:`corresponding configuration + // ` + // configured in the HTTP connection manager. If two tags with the same name are configured + // each in the HTTP connection manager and the route level, the one configured here takes + // priority. + repeated type.tracing.v2.CustomTag custom_tags = 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. +// +// Documentation for :ref:`virtual cluster statistics `. +// +// .. note:: +// +// Virtual clusters are a useful tool, but we do not recommend setting up a virtual cluster for +// every application endpoint. This is both not easily maintainable and as well the matching and +// statistics output are not free. +message VirtualCluster { + // Specifies a regex pattern to use for matching requests. The entire path of the request + // must match the regex. The regex grammar used is defined `here + // `_. + // + // Examples: + // + // * The regex ``/rides/\d+`` matches the path */rides/0* + // * The regex ``/rides/\d+`` matches the path */rides/123* + // * The regex ``/rides/\d+`` does not match the path */rides/123/456* + // + // .. attention:: + // This field has been deprecated in favor of `headers` as it is not safe for use with + // untrusted input in all cases. + string pattern = 1 [deprecated = true, (validate.rules).string = {max_bytes: 1024}]; + + // Specifies a list of header matchers to use for matching requests. Each specified header must + // match. The pseudo-headers `:path` and `:method` can be used to match the request path and + // method, respectively. + repeated HeaderMatcher headers = 4; + + // Specifies the name of the virtual cluster. The virtual cluster name as well + // as the virtual host name are used when emitting statistics. The statistics are emitted by the + // router filter and are documented :ref:`here `. + string name = 2 [(validate.rules).string = {min_bytes: 1}]; + + // Optionally specifies the HTTP method to match on. For example GET, PUT, + // etc. + // + // .. attention:: + // This field has been deprecated in favor of `headers`. + core.RequestMethod method = 3 [deprecated = true]; +} + +// Global rate limiting :ref:`architecture overview `. +message RateLimit { + // [#next-free-field: 7] + message Action { + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("source_cluster", "") + // + // is derived from the :option:`--service-cluster` option. + message SourceCluster { + } + + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("destination_cluster", "") + // + // Once a request matches against a route table rule, a routed cluster is determined by one of + // the following :ref:`route table configuration ` + // settings: + // + // * :ref:`cluster ` indicates the upstream cluster + // to route to. + // * :ref:`weighted_clusters ` + // chooses a cluster randomly from a set of clusters with attributed weight. + // * :ref:`cluster_header ` indicates which + // header in the request contains the target cluster. + message DestinationCluster { + } + + // The following descriptor entry is appended when a header contains a key that matches the + // *header_name*: + // + // .. code-block:: cpp + // + // ("", "") + 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 [(validate.rules).string = {min_bytes: 1}]; + + // The key to use in the descriptor entry. + string descriptor_key = 2 [(validate.rules).string = {min_bytes: 1}]; + } + + // The following descriptor entry is appended to the descriptor and is populated using the + // trusted address from :ref:`x-forwarded-for `: + // + // .. code-block:: cpp + // + // ("remote_address", "") + message RemoteAddress { + } + + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("generic_key", "") + message GenericKey { + // The value to use in the descriptor entry. + string descriptor_value = 1 [(validate.rules).string = {min_bytes: 1}]; + } + + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("header_match", "") + message HeaderValueMatch { + // The value to use in the descriptor entry. + string descriptor_value = 1 [(validate.rules).string = {min_bytes: 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 [(validate.rules).repeated = {min_items: 1}]; + } + + oneof action_specifier { + option (validate.required) = true; + + // Rate limit on source cluster. + SourceCluster source_cluster = 1; + + // Rate limit on destination cluster. + DestinationCluster destination_cluster = 2; + + // Rate limit on request headers. + RequestHeaders request_headers = 3; + + // Rate limit on remote address. + RemoteAddress remote_address = 4; + + // Rate limit on a generic key. + GenericKey generic_key = 5; + + // Rate limit on the existence of request headers. + HeaderValueMatch header_value_match = 6; + } + } + + // 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 [(validate.rules).uint32 = {lte: 10}]; + + // The key to be set in runtime to disable this rate limit configuration. + string disable_key = 2; + + // 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 :ref:`composing actions + // ` for additional documentation. + repeated Action actions = 3 [(validate.rules).repeated = {min_items: 1}]; +} + +// .. attention:: +// +// Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host* +// header. Thus, if attempting to match on *Host*, match on *:authority* instead. +// +// .. attention:: +// +// To route on HTTP method, use the special HTTP/2 *:method* header. This works for both +// HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g., +// +// .. code-block:: json +// +// { +// "name": ":method", +// "exact_match": "POST" +// } +// +// .. attention:: +// In the absence of any header match specifier, match will default to :ref:`present_match +// `. i.e, a request that has the :ref:`name +// ` header will match, regardless of the header's +// value. +// +// [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.] +// [#next-free-field: 12] +message HeaderMatcher { + reserved 2, 3; + + // Specifies the name of the header in the request. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // Specifies how the header match will be performed to route the request. + oneof header_match_specifier { + // If specified, header match will be performed based on the value of the header. + string exact_match = 4; + + // If specified, this regex string is a regular expression rule which implies the entire request + // header value must match the regex. The rule will not match if only a subsequence of the + // request header value matches the regex. The regex grammar used in the value field is defined + // `here `_. + // + // Examples: + // + // * The regex ``\d{3}`` matches the value *123* + // * The regex ``\d{3}`` does not match the value *1234* + // * The regex ``\d{3}`` does not match the value *123.456* + // + // .. attention:: + // This field has been deprecated in favor of `safe_regex_match` as it is not safe for use + // with untrusted input in all cases. + string regex_match = 5 [deprecated = true, (validate.rules).string = {max_bytes: 1024}]; + + // If specified, this regex string is a regular expression rule which implies the entire request + // header value must match the regex. The rule will not match if only a subsequence of the + // request header value matches the regex. + type.matcher.RegexMatcher safe_regex_match = 11; + + // If specified, header match will be performed based on range. + // The rule will match if the request header value is within this range. + // The entire request header value must represent an integer in base 10 notation: consisting of + // an optional plus or minus sign followed by a sequence of digits. The rule will not match if + // the header value does not represent an integer. Match will fail for empty values, floating + // point numbers or if only a subsequence of the header value is an integer. + // + // Examples: + // + // * For range [-10,0), route will match for header value -1, but not for 0, "somestring", 10.9, + // "-1somestring" + type.Int64Range range_match = 6; + + // If specified, header match will be performed based on whether the header is in the + // request. + bool present_match = 7; + + // If specified, header match will be performed based on the prefix of the header value. + // Note: empty prefix is not allowed, please use present_match instead. + // + // Examples: + // + // * The prefix *abcd* matches the value *abcdxyz*, but not for *abcxyz*. + string prefix_match = 9 [(validate.rules).string = {min_bytes: 1}]; + + // If specified, header match will be performed based on the suffix of the header value. + // Note: empty suffix is not allowed, please use present_match instead. + // + // Examples: + // + // * The suffix *abcd* matches the value *xyzabcd*, but not for *xyzbcd*. + string suffix_match = 10 [(validate.rules).string = {min_bytes: 1}]; + } + + // If specified, the match result will be inverted before checking. Defaults to false. + // + // Examples: + // + // * The regex ``\d{3}`` does not match the value *1234*, so it will match when inverted. + // * The range [-10,0) will match the value -1, so it will not match when inverted. + bool invert_match = 8; +} + +// Query parameter matching treats the query string of a request's :path header +// as an ampersand-separated list of keys and/or key=value elements. +// [#next-free-field: 7] +message QueryParameterMatcher { + // Specifies the name of a key that must be present in the requested + // *path*'s query string. + string name = 1 [(validate.rules).string = {min_bytes: 1 max_bytes: 1024}]; + + // Specifies the value of the key. If the value is absent, a request + // that contains the key in its query string will match, whether the + // key appears with a value (e.g., "?debug=true") or not (e.g., "?debug") + // + // ..attention:: + // This field is deprecated. Use an `exact` match inside the `string_match` field. + string value = 3 [deprecated = true]; + + // Specifies whether the query parameter value is a regular expression. + // Defaults to false. The entire query parameter value (i.e., the part to + // the right of the equals sign in "key=value") must match the regex. + // E.g., the regex ``\d+$`` will match *123* but not *a123* or *123a*. + // + // ..attention:: + // This field is deprecated. Use a `safe_regex` match inside the `string_match` field. + google.protobuf.BoolValue regex = 4 [deprecated = true]; + + oneof query_parameter_match_specifier { + // Specifies whether a query parameter value should match against a string. + type.matcher.StringMatcher string_match = 5 [(validate.rules).message = {required: true}]; + + // Specifies whether a query parameter should be present. + bool present_match = 6; + } +} diff --git a/envoy/api/v2/scoped_route.proto b/envoy/api/v2/scoped_route.proto new file mode 100644 index 00000000..d73ddd07 --- /dev/null +++ b/envoy/api/v2/scoped_route.proto @@ -0,0 +1,107 @@ +syntax = "proto3"; + +package envoy.api.v2; + +import "udpa/annotations/migrate.proto"; +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.api.v2"; +option java_outer_classname = "ScopedRouteProto"; +option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.config.route.v3alpha"; + +// [#protodoc-title: HTTP scoped routing configuration] +// * Routing :ref:`architecture overview ` + +// Specifies a routing scope, which associates a +// :ref:`Key` to a +// :ref:`envoy_api_msg_RouteConfiguration` (identified by its resource name). +// +// The HTTP connection manager builds up a table consisting of these Key to +// RouteConfiguration mappings, and looks up the RouteConfiguration to use per +// request according to the algorithm specified in the +// :ref:`scope_key_builder` +// assigned to the HttpConnectionManager. +// +// For example, with the following configurations (in YAML): +// +// HttpConnectionManager config: +// +// .. code:: +// +// ... +// scoped_routes: +// name: foo-scoped-routes +// scope_key_builder: +// fragments: +// - header_value_extractor: +// name: X-Route-Selector +// element_separator: , +// element: +// separator: = +// key: vip +// +// ScopedRouteConfiguration resources (specified statically via +// :ref:`scoped_route_configurations_list` +// or obtained dynamically via SRDS): +// +// .. code:: +// +// (1) +// name: route-scope1 +// route_configuration_name: route-config1 +// key: +// fragments: +// - string_key: 172.10.10.20 +// +// (2) +// name: route-scope2 +// route_configuration_name: route-config2 +// key: +// fragments: +// - string_key: 172.20.20.30 +// +// A request from a client such as: +// +// .. code:: +// +// GET / HTTP/1.1 +// Host: foo.com +// X-Route-Selector: vip=172.10.10.20 +// +// would result in the routing table defined by the `route-config1` +// RouteConfiguration being assigned to the HTTP request/stream. +// +message ScopedRouteConfiguration { + // Specifies a key which is matched against the output of the + // :ref:`scope_key_builder` + // specified in the HttpConnectionManager. The matching is done per HTTP + // request and is dependent on the order of the fragments contained in the + // Key. + message Key { + message Fragment { + oneof type { + option (validate.required) = true; + + // A string to match against. + string string_key = 1; + } + } + + // The ordered set of fragments to match against. The order must match the + // fragments in the corresponding + // :ref:`scope_key_builder`. + repeated Fragment fragments = 1 [(validate.rules).repeated = {min_items: 1}]; + } + + // The name assigned to the routing scope. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // The resource name to use for a :ref:`envoy_api_msg_DiscoveryRequest` to an + // RDS server to fetch the :ref:`envoy_api_msg_RouteConfiguration` associated + // with this scope. + string route_configuration_name = 2 [(validate.rules).string = {min_bytes: 1}]; + + // The key to match against. + Key key = 3 [(validate.rules).message = {required: true}]; +} diff --git a/envoy/api/v2/srds.proto b/envoy/api/v2/srds.proto index 52593923..5bcb0dee 100644 --- a/envoy/api/v2/srds.proto +++ b/envoy/api/v2/srds.proto @@ -7,7 +7,8 @@ import "envoy/api/v2/discovery.proto"; import "google/api/annotations.proto"; import "udpa/annotations/migrate.proto"; -import "validate/validate.proto"; + +import public "envoy/api/v2/scoped_route.proto"; option java_package = "io.envoyproxy.envoy.api.v2"; option java_outer_classname = "SrdsProto"; @@ -15,7 +16,7 @@ option java_multiple_files = true; option java_generic_services = true; option (udpa.annotations.file_migrate).move_to_package = "envoy.service.route.v3alpha"; -// [#protodoc-title: HTTP scoped routing configuration] +// [#protodoc-title: SRDS] // * Routing :ref:`architecture overview ` // The Scoped Routes Discovery Service (SRDS) API distributes @@ -38,95 +39,7 @@ service ScopedRoutesDiscoveryService { } } -// Specifies a routing scope, which associates a -// :ref:`Key` to a -// :ref:`envoy_api_msg_RouteConfiguration` (identified by its resource name). -// -// The HTTP connection manager builds up a table consisting of these Key to -// RouteConfiguration mappings, and looks up the RouteConfiguration to use per -// request according to the algorithm specified in the -// :ref:`scope_key_builder` -// assigned to the HttpConnectionManager. -// -// For example, with the following configurations (in YAML): -// -// HttpConnectionManager config: -// -// .. code:: -// -// ... -// scoped_routes: -// name: foo-scoped-routes -// scope_key_builder: -// fragments: -// - header_value_extractor: -// name: X-Route-Selector -// element_separator: , -// element: -// separator: = -// key: vip -// -// ScopedRouteConfiguration resources (specified statically via -// :ref:`scoped_route_configurations_list` -// or obtained dynamically via SRDS): -// -// .. code:: -// -// (1) -// name: route-scope1 -// route_configuration_name: route-config1 -// key: -// fragments: -// - string_key: 172.10.10.20 -// -// (2) -// name: route-scope2 -// route_configuration_name: route-config2 -// key: -// fragments: -// - string_key: 172.20.20.30 -// -// A request from a client such as: -// -// .. code:: -// -// GET / HTTP/1.1 -// Host: foo.com -// X-Route-Selector: vip=172.10.10.20 -// -// would result in the routing table defined by the `route-config1` -// RouteConfiguration being assigned to the HTTP request/stream. -// -message ScopedRouteConfiguration { - // Specifies a key which is matched against the output of the - // :ref:`scope_key_builder` - // specified in the HttpConnectionManager. The matching is done per HTTP - // request and is dependent on the order of the fragments contained in the - // Key. - message Key { - message Fragment { - oneof type { - option (validate.required) = true; - - // A string to match against. - string string_key = 1; - } - } - - // The ordered set of fragments to match against. The order must match the - // fragments in the corresponding - // :ref:`scope_key_builder`. - repeated Fragment fragments = 1 [(validate.rules).repeated = {min_items: 1}]; - } - - // The name assigned to the routing scope. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // The resource name to use for a :ref:`envoy_api_msg_DiscoveryRequest` to an - // RDS server to fetch the :ref:`envoy_api_msg_RouteConfiguration` associated - // with this scope. - string route_configuration_name = 2 [(validate.rules).string = {min_bytes: 1}]; - - // The key to match against. - Key key = 3 [(validate.rules).message = {required: true}]; +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 and protoxform to upgrade the file. +message SrdsDummy { } diff --git a/envoy/config/bootstrap/v2/bootstrap.proto b/envoy/config/bootstrap/v2/bootstrap.proto index 5254bcc4..bd33e601 100644 --- a/envoy/config/bootstrap/v2/bootstrap.proto +++ b/envoy/config/bootstrap/v2/bootstrap.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package envoy.config.bootstrap.v2; import "envoy/api/v2/auth/cert.proto"; -import "envoy/api/v2/cds.proto"; +import "envoy/api/v2/cluster.proto"; import "envoy/api/v2/core/address.proto"; import "envoy/api/v2/core/base.proto"; import "envoy/api/v2/core/config_source.proto"; diff --git a/envoy/config/bootstrap/v3alpha/BUILD b/envoy/config/bootstrap/v3alpha/BUILD index 3cdf3875..30bb6946 100644 --- a/envoy/config/bootstrap/v3alpha/BUILD +++ b/envoy/config/bootstrap/v3alpha/BUILD @@ -7,13 +7,13 @@ licenses(["notice"]) # Apache 2 api_proto_package( deps = [ "//envoy/config/bootstrap/v2:pkg", + "//envoy/config/cluster/v3alpha:pkg", "//envoy/config/core/v3alpha:pkg", "//envoy/config/listener/v3alpha:pkg", "//envoy/config/metrics/v3alpha:pkg", "//envoy/config/overload/v3alpha:pkg", "//envoy/config/trace/v3alpha:pkg", "//envoy/extensions/transport_sockets/tls/v3alpha:pkg", - "//envoy/service/cluster/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/config/bootstrap/v3alpha/bootstrap.proto b/envoy/config/bootstrap/v3alpha/bootstrap.proto index 2c13e06b..372dc8d7 100644 --- a/envoy/config/bootstrap/v3alpha/bootstrap.proto +++ b/envoy/config/bootstrap/v3alpha/bootstrap.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.config.bootstrap.v3alpha; +import "envoy/config/cluster/v3alpha/cluster.proto"; import "envoy/config/core/v3alpha/address.proto"; import "envoy/config/core/v3alpha/base.proto"; import "envoy/config/core/v3alpha/config_source.proto"; @@ -10,7 +11,6 @@ import "envoy/config/metrics/v3alpha/stats.proto"; import "envoy/config/overload/v3alpha/overload.proto"; import "envoy/config/trace/v3alpha/trace.proto"; import "envoy/extensions/transport_sockets/tls/v3alpha/cert.proto"; -import "envoy/service/cluster/v3alpha/cds.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/struct.proto"; @@ -48,7 +48,7 @@ message Bootstrap { // necessary to have some initial cluster definitions available to allow Envoy to know how to // speak to the management server. These cluster definitions may not use :ref:`EDS // ` (i.e. they should be static IP or DNS-based). - repeated service.cluster.v3alpha.Cluster clusters = 2; + repeated cluster.v3alpha.Cluster clusters = 2; // These static secrets can be used by :ref:`SdsSecretConfig // ` @@ -65,7 +65,7 @@ message Bootstrap { // single :ref:`LDS ` configuration source. core.v3alpha.ConfigSource lds_config = 1; - // All post-bootstrap :ref:`Cluster ` definitions + // All post-bootstrap :ref:`Cluster ` definitions // are provided by a single :ref:`CDS ` configuration source. core.v3alpha.ConfigSource cds_config = 2; @@ -164,9 +164,9 @@ message Bootstrap { // Always use TCP queries instead of UDP queries for DNS lookups. // This may be overridden on a per-cluster basis in cds_config, - // when :ref:`dns_resolvers ` and + // when :ref:`dns_resolvers ` and // :ref:`use_tcp_for_dns_lookups - // ` are specified. + // ` are specified. bool use_tcp_for_dns_lookups = 20; } @@ -210,7 +210,7 @@ message ClusterManager { // this configuration). In order to enable :ref:`zone aware routing // ` this option must be set. // If *local_cluster_name* is defined then :ref:`clusters - // ` must be defined in the :ref:`Bootstrap + // ` must be defined in the :ref:`Bootstrap // static cluster resources // `. This is // unrelated to the :option:`--service-cluster` option which does not `affect zone aware routing diff --git a/envoy/config/cluster/v3alpha/BUILD b/envoy/config/cluster/v3alpha/BUILD index ebf7e499..d49bf184 100644 --- a/envoy/config/cluster/v3alpha/BUILD +++ b/envoy/config/cluster/v3alpha/BUILD @@ -6,8 +6,11 @@ licenses(["notice"]) # Apache 2 api_proto_package( deps = [ + "//envoy/api/v2:pkg", "//envoy/api/v2/cluster:pkg", "//envoy/config/core/v3alpha:pkg", + "//envoy/config/endpoint/v3alpha:pkg", + "//envoy/type/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/config/cluster/v3alpha/cluster.proto b/envoy/config/cluster/v3alpha/cluster.proto new file mode 100644 index 00000000..999378d6 --- /dev/null +++ b/envoy/config/cluster/v3alpha/cluster.proto @@ -0,0 +1,883 @@ +syntax = "proto3"; + +package envoy.config.cluster.v3alpha; + +import "envoy/config/cluster/v3alpha/circuit_breaker.proto"; +import "envoy/config/cluster/v3alpha/filter.proto"; +import "envoy/config/cluster/v3alpha/outlier_detection.proto"; +import "envoy/config/core/v3alpha/address.proto"; +import "envoy/config/core/v3alpha/base.proto"; +import "envoy/config/core/v3alpha/config_source.proto"; +import "envoy/config/core/v3alpha/health_check.proto"; +import "envoy/config/core/v3alpha/protocol.proto"; +import "envoy/config/endpoint/v3alpha/endpoint.proto"; +import "envoy/type/v3alpha/percent.proto"; + +import "google/protobuf/any.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/versioning.proto"; + +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.config.cluster.v3alpha"; +option java_outer_classname = "ClusterProto"; +option java_multiple_files = true; + +// [#protodoc-title: Cluster configuration] + +// Configuration for a single upstream cluster. +// [#next-free-field: 46] +message Cluster { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster"; + + // Refer to :ref:`service discovery type ` + // for an explanation on each type. + enum DiscoveryType { + // Refer to the :ref:`static discovery type` + // for an explanation. + STATIC = 0; + + // Refer to the :ref:`strict DNS discovery + // type` + // for an explanation. + STRICT_DNS = 1; + + // Refer to the :ref:`logical DNS discovery + // type` + // for an explanation. + LOGICAL_DNS = 2; + + // Refer to the :ref:`service discovery type` + // for an explanation. + EDS = 3; + + // Refer to the :ref:`original destination discovery + // type` + // for an explanation. + ORIGINAL_DST = 4; + } + + // Refer to :ref:`load balancer type ` architecture + // overview section for information on each type. + enum LbPolicy { + reserved 4; + + reserved "ORIGINAL_DST_LB"; + + // Refer to the :ref:`round robin load balancing + // policy` + // for an explanation. + ROUND_ROBIN = 0; + + // Refer to the :ref:`least request load balancing + // policy` + // for an explanation. + LEAST_REQUEST = 1; + + // Refer to the :ref:`ring hash load balancing + // policy` + // for an explanation. + RING_HASH = 2; + + // Refer to the :ref:`random load balancing + // policy` + // for an explanation. + RANDOM = 3; + + // Refer to the :ref:`Maglev load balancing policy` + // for an explanation. + MAGLEV = 5; + + // This load balancer type must be specified if the configured cluster provides a cluster + // specific load balancer. Consult the configured cluster's documentation for whether to set + // this option or not. + CLUSTER_PROVIDED = 6; + + // [#not-implemented-hide:] Use the new :ref:`load_balancing_policy + // ` field to determine + // the LB policy. + // [#next-major-version: In the v3 API, we should consider deprecating the lb_policy field + // and instead using the new load_balancing_policy field as the one and only mechanism for + // configuring this.] + LOAD_BALANCING_POLICY_CONFIG = 7; + } + + // When V4_ONLY is selected, the DNS resolver will only perform a lookup for + // addresses in the IPv4 family. If V6_ONLY is selected, the DNS resolver will + // only perform a lookup for addresses in the IPv6 family. If AUTO is + // specified, the DNS resolver will first perform a lookup for addresses in + // the IPv6 family and fallback to a lookup for addresses in the IPv4 family. + // For cluster types other than + // :ref:`STRICT_DNS` + // and + // :ref:`LOGICAL_DNS`, + // this setting is + // ignored. + enum DnsLookupFamily { + AUTO = 0; + V4_ONLY = 1; + V6_ONLY = 2; + } + + enum ClusterProtocolSelection { + // Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2). + // If :ref:`http2_protocol_options + // ` are present, HTTP2 + // will be used, otherwise HTTP1.1 will be used. + USE_CONFIGURED_PROTOCOL = 0; + + // Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection. + USE_DOWNSTREAM_PROTOCOL = 1; + } + + // TransportSocketMatch specifies what transport socket config will be used + // when the match conditions are satisfied. + message TransportSocketMatch { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.TransportSocketMatch"; + + // The name of the match, used in stats generation. + string name = 1 [(validate.rules).string = {min_len: 1}]; + + // Optional endpoint metadata match criteria. + // The connection to the endpoint with metadata matching what is set in this field + // will use the transport socket configuration specified here. + // The endpoint's metadata entry in *envoy.transport_socket_match* is used to match + // against the values specified in this field. + google.protobuf.Struct match = 2; + + // The configuration of the transport socket. + core.v3alpha.TransportSocket transport_socket = 3; + } + + // Extended cluster type. + message CustomClusterType { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.CustomClusterType"; + + // The type of the cluster to instantiate. The name must match a supported cluster type. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // Cluster specific configuration which depends on the cluster being instantiated. + // See the supported cluster for further documentation. + google.protobuf.Any typed_config = 2; + } + + // Only valid when discovery type is EDS. + message EdsClusterConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.EdsClusterConfig"; + + // Configuration for the source of EDS updates for this Cluster. + core.v3alpha.ConfigSource eds_config = 1; + + // Optional alternative to cluster name to present to EDS. This does not + // have the same restrictions as cluster name, i.e. it may be arbitrary + // length. + string service_name = 2; + } + + // Optionally divide the endpoints in this cluster into subsets defined by + // endpoint metadata and selected by route and weighted cluster metadata. + // [#next-free-field: 8] + message LbSubsetConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.LbSubsetConfig"; + + // If NO_FALLBACK is selected, a result + // equivalent to no healthy hosts is reported. If ANY_ENDPOINT is selected, + // any cluster endpoint may be returned (subject to policy, health checks, + // etc). If DEFAULT_SUBSET is selected, load balancing is performed over the + // endpoints matching the values from the default_subset field. + enum LbSubsetFallbackPolicy { + NO_FALLBACK = 0; + ANY_ENDPOINT = 1; + DEFAULT_SUBSET = 2; + } + + // Specifications for subsets. + message LbSubsetSelector { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.LbSubsetConfig.LbSubsetSelector"; + + // Allows to override top level fallback policy per selector. + enum LbSubsetSelectorFallbackPolicy { + // If NOT_DEFINED top level config fallback policy is used instead. + NOT_DEFINED = 0; + + // If NO_FALLBACK is selected, a result equivalent to no healthy hosts is reported. + NO_FALLBACK = 1; + + // If ANY_ENDPOINT is selected, any cluster endpoint may be returned + // (subject to policy, health checks, etc). + ANY_ENDPOINT = 2; + + // If DEFAULT_SUBSET is selected, load balancing is performed over the + // endpoints matching the values from the default_subset field. + DEFAULT_SUBSET = 3; + + // If KEYS_SUBSET is selected, subset selector matching is performed again with metadata + // keys reduced to + // :ref:`fallback_keys_subset`. + // It allows for a fallback to a different, less specific selector if some of the keys of + // the selector are considered optional. + KEYS_SUBSET = 4; + } + + // List of keys to match with the weighted cluster metadata. + repeated string keys = 1; + + // The behavior used when no endpoint subset matches the selected route's + // metadata. + LbSubsetSelectorFallbackPolicy fallback_policy = 2 + [(validate.rules).enum = {defined_only: true}]; + + // Subset of + // :ref:`keys` + // used by + // :ref:`KEYS_SUBSET` + // fallback policy. + // It has to be a non empty list if KEYS_SUBSET fallback policy is selected. + // For any other fallback policy the parameter is not used and should not be set. + // Only values also present in + // :ref:`keys` + // are allowed, but `fallback_keys_subset` cannot be equal to `keys`. + repeated string fallback_keys_subset = 3; + } + + // The behavior used when no endpoint subset matches the selected route's + // metadata. The value defaults to + // :ref:`NO_FALLBACK`. + LbSubsetFallbackPolicy fallback_policy = 1 [(validate.rules).enum = {defined_only: true}]; + + // Specifies the default subset of endpoints used during fallback if + // fallback_policy is + // :ref:`DEFAULT_SUBSET`. + // Each field in default_subset is + // compared to the matching LbEndpoint.Metadata under the *envoy.lb* + // namespace. It is valid for no hosts to match, in which case the behavior + // is the same as a fallback_policy of + // :ref:`NO_FALLBACK`. + google.protobuf.Struct default_subset = 2; + + // For each entry, LbEndpoint.Metadata's + // *envoy.lb* namespace is traversed and a subset is created for each unique + // combination of key and value. For example: + // + // .. code-block:: json + // + // { "subset_selectors": [ + // { "keys": [ "version" ] }, + // { "keys": [ "stage", "hardware_type" ] } + // ]} + // + // A subset is matched when the metadata from the selected route and + // weighted cluster contains the same keys and values as the subset's + // metadata. The same host may appear in multiple subsets. + repeated LbSubsetSelector subset_selectors = 3; + + // If true, routing to subsets will take into account the localities and locality weights of the + // endpoints when making the routing decision. + // + // There are some potential pitfalls associated with enabling this feature, as the resulting + // traffic split after applying both a subset match and locality weights might be undesirable. + // + // Consider for example a situation in which you have 50/50 split across two localities X/Y + // which have 100 hosts each without subsetting. If the subset LB results in X having only 1 + // host selected but Y having 100, then a lot more load is being dumped on the single host in X + // than originally anticipated in the load balancing assignment delivered via EDS. + bool locality_weight_aware = 4; + + // When used with locality_weight_aware, scales the weight of each locality by the ratio + // of hosts in the subset vs hosts in the original subset. This aims to even out the load + // going to an individual locality if said locality is disproportionately affected by the + // subset predicate. + bool scale_locality_weight = 5; + + // If true, when a fallback policy is configured and its corresponding subset fails to find + // a host this will cause any host to be selected instead. + // + // This is useful when using the default subset as the fallback policy, given the default + // subset might become empty. With this option enabled, if that happens the LB will attempt + // to select a host from the entire cluster. + bool panic_mode_any = 6; + + // If true, metadata specified for a metadata key will be matched against the corresponding + // endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value + // and any of the elements in the list matches the criteria. + bool list_as_any = 7; + } + + // Specific configuration for the LeastRequest load balancing policy. + message LeastRequestLbConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.LeastRequestLbConfig"; + + // The number of random healthy hosts from which the host with the fewest active requests will + // be chosen. Defaults to 2 so that we perform two-choice selection if the field is not set. + google.protobuf.UInt32Value choice_count = 1 [(validate.rules).uint32 = {gte: 2}]; + } + + // Specific configuration for the :ref:`RingHash` + // load balancing policy. + message RingHashLbConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.RingHashLbConfig"; + + // The hash function used to hash hosts onto the ketama ring. + enum HashFunction { + // Use `xxHash `_, this is the default hash function. + XX_HASH = 0; + + // Use `MurmurHash2 `_, this is compatible with + // std:hash in GNU libstdc++ 3.4.20 or above. This is typically the case when compiled + // on Linux and not macOS. + MURMUR_HASH_2 = 1; + } + + reserved 2; + + // Minimum hash ring size. The larger the ring is (that is, the more hashes there are for each + // provided host) the better the request distribution will reflect the desired weights. Defaults + // to 1024 entries, and limited to 8M entries. See also + // :ref:`maximum_ring_size`. + google.protobuf.UInt64Value minimum_ring_size = 1 [(validate.rules).uint64 = {lte: 8388608}]; + + // The hash function used to hash hosts onto the ketama ring. The value defaults to + // :ref:`XX_HASH`. + HashFunction hash_function = 3 [(validate.rules).enum = {defined_only: true}]; + + // Maximum hash ring size. Defaults to 8M entries, and limited to 8M entries, but can be lowered + // to further constrain resource use. See also + // :ref:`minimum_ring_size`. + google.protobuf.UInt64Value maximum_ring_size = 4 [(validate.rules).uint64 = {lte: 8388608}]; + } + + // Specific configuration for the + // :ref:`Original Destination ` + // load balancing policy. + message OriginalDstLbConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.OriginalDstLbConfig"; + + // When true, :ref:`x-envoy-original-dst-host + // ` can be used to override destination + // address. + // + // .. attention:: + // + // This header isn't sanitized by default, so enabling this feature allows HTTP clients to + // route traffic to arbitrary hosts and/or ports, which may have serious security + // consequences. + bool use_http_header = 1; + } + + // Common configuration for all load balancer implementations. + // [#next-free-field: 7] + message CommonLbConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.CommonLbConfig"; + + // Configuration for :ref:`zone aware routing + // `. + message ZoneAwareLbConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.CommonLbConfig.ZoneAwareLbConfig"; + + // Configures percentage of requests that will be considered for zone aware routing + // if zone aware routing is configured. If not specified, the default is 100%. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + type.v3alpha.Percent routing_enabled = 1; + + // Configures minimum upstream cluster size required for zone aware routing + // If upstream cluster size is less than specified, zone aware routing is not performed + // even if zone aware routing is configured. If not specified, the default is 6. + // * :ref:`runtime values `. + // * :ref:`Zone aware routing support `. + google.protobuf.UInt64Value min_cluster_size = 2; + + // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic + // mode`. Instead, the cluster will fail all + // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a + // failing service. + bool fail_traffic_on_panic = 3; + } + + // Configuration for :ref:`locality weighted load balancing + // ` + message LocalityWeightedLbConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.Cluster.CommonLbConfig.LocalityWeightedLbConfig"; + } + + // Configures the :ref:`healthy panic threshold `. + // If not specified, the default is 50%. + // To disable panic mode, set to 0%. + // + // .. note:: + // The specified percent will be truncated to the nearest 1%. + type.v3alpha.Percent healthy_panic_threshold = 1; + + oneof locality_config_specifier { + ZoneAwareLbConfig zone_aware_lb_config = 2; + + LocalityWeightedLbConfig locality_weighted_lb_config = 3; + } + + // If set, all health check/weight/metadata updates that happen within this duration will be + // merged and delivered in one shot when the duration expires. The start of the duration is when + // the first update happens. This is useful for big clusters, with potentially noisy deploys + // that might trigger excessive CPU usage due to a constant stream of healthcheck state changes + // or metadata updates. The first set of updates to be seen apply immediately (e.g.: a new + // cluster). Please always keep in mind that the use of sandbox technologies may change this + // behavior. + // + // If this is not set, we default to a merge window of 1000ms. To disable it, set the merge + // window to 0. + // + // Note: merging does not apply to cluster membership changes (e.g.: adds/removes); this is + // because merging those updates isn't currently safe. See + // https://github.com/envoyproxy/envoy/pull/3941. + google.protobuf.Duration update_merge_window = 4; + + // If set to true, Envoy will not consider new hosts when computing load balancing weights until + // they have been health checked for the first time. This will have no effect unless + // active health checking is also configured. + // + // Ignoring a host means that for any load balancing calculations that adjust weights based + // on the ratio of eligible hosts and total hosts (priority spillover, locality weighting and + // panic mode) Envoy will exclude these hosts in the denominator. + // + // For example, with hosts in two priorities P0 and P1, where P0 looks like + // {healthy, unhealthy (new), unhealthy (new)} + // and where P1 looks like + // {healthy, healthy} + // all traffic will still hit P0, as 1 / (3 - 2) = 1. + // + // Enabling this will allow scaling up the number of hosts for a given cluster without entering + // panic mode or triggering priority spillover, assuming the hosts pass the first health check. + // + // If panic mode is triggered, new hosts are still eligible for traffic; they simply do not + // contribute to the calculation when deciding whether panic mode is enabled or not. + bool ignore_new_hosts_until_first_hc = 5; + + // If set to `true`, the cluster manager will drain all existing + // connections to upstream hosts whenever hosts are added or removed from the cluster. + bool close_connections_on_host_set_change = 6; + } + + message RefreshRate { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster.RefreshRate"; + + // Specifies the base interval between refreshes. This parameter is required and must be greater + // than zero and less than + // :ref:`max_interval + // `. + google.protobuf.Duration base_interval = 1 [(validate.rules).duration = { + required: true + gt {nanos: 1000000} + }]; + + // Specifies the maximum interval between refreshes. This parameter is optional, but must be + // greater than or equal to the + // :ref:`base_interval + // ` if set. The + // default is 10 times the :ref:`base_interval + // `. + google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {nanos: 1000000}}]; + } + + reserved 12, 15, 11, 35; + + reserved "tls_context", "extension_protocol_options"; + + // Configuration to use different transport sockets for different endpoints. + // The entry of *envoy.transport_socket* in the + // :ref:`LbEndpoint.Metadata ` + // is used to match against the transport sockets as they appear in the list. The first + // :ref:`match ` is used. + // For example, with the following match + // + // .. code-block:: yaml + // + // transport_socket_matches: + // - name: "enableMTLS" + // match: + // acceptMTLS: true + // transport_socket: + // name: envoy.transport_sockets.tls + // config: { ... } # tls socket configuration + // - name: "defaultToPlaintext" + // match: {} + // transport_socket: + // name: envoy.transport_sockets.raw_buffer + // + // Connections to the endpoints whose metadata value under *envoy.transport_socket* + // having "acceptMTLS"/"true" key/value pair use the "enableMTLS" socket configuration. + // + // If a :ref:`socket match ` + // with empty match criteria is provided, that always match any endpoint. For example, the + // "defaultToPlaintext" socket match in case above. + // + // If an endpoint metadata's value under *envoy.transport_socket* does not match any + // *TransportSocketMatch*, socket configuration fallbacks to use the *tls_context* or + // *transport_socket* specified in this cluster. + // + // This field allows gradual and flexible transport socket configuration changes. + // + // The metadata of endpoints in EDS can indicate transport socket capabilities. For example, + // an endpoint's metadata can have two key value pairs as "acceptMTLS": "true", + // "acceptPlaintext": "true". While some other endpoints, only accepting plaintext traffic + // has "acceptPlaintext": "true" metadata information. + // + // Then the xDS server can configure the CDS to a client, Envoy A, to send mutual TLS + // traffic for endpoints with "acceptMTLS": "true", by adding a corresponding + // *TransportSocketMatch* in this field. Other client Envoys receive CDS without + // *transport_socket_match* set, and still send plain text traffic to the same cluster. + // + // [#comment:TODO(incfly): add a detailed architecture doc on intended usage.] + repeated TransportSocketMatch transport_socket_matches = 43; + + // Supplies the name of the cluster which must be unique across all clusters. + // The cluster name is used when emitting + // :ref:`statistics ` if :ref:`alt_stat_name + // ` is not provided. + // Any ``:`` in the cluster name will be converted to ``_`` when emitting statistics. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // An optional alternative to the cluster name to be used while emitting stats. + // Any ``:`` in the name will be converted to ``_`` when emitting statistics. This should not be + // confused with :ref:`Router Filter Header + // `. + string alt_stat_name = 28; + + oneof cluster_discovery_type { + // The :ref:`service discovery type ` + // to use for resolving the cluster. + DiscoveryType type = 2 [(validate.rules).enum = {defined_only: true}]; + + // The custom cluster type. + CustomClusterType cluster_type = 38; + } + + // Configuration to use for EDS updates for the Cluster. + EdsClusterConfig eds_cluster_config = 3; + + // The timeout for new network connections to hosts in the cluster. + google.protobuf.Duration connect_timeout = 4 [(validate.rules).duration = {gt {}}]; + + // Soft limit on size of the cluster’s connections read and write buffers. If + // unspecified, an implementation defined default is applied (1MiB). + google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5; + + // The :ref:`load balancer type ` to use + // when picking a host in the cluster. + LbPolicy lb_policy = 6 [(validate.rules).enum = {defined_only: true}]; + + // If the service discovery type is + // :ref:`STATIC`, + // :ref:`STRICT_DNS` + // or + // :ref:`LOGICAL_DNS`, + // then hosts is required. + // + // .. attention:: + // + // **This field is deprecated**. Set the + // :ref:`load_assignment` field + // instead. + // + repeated core.v3alpha.Address hosts = 7; + + // Setting this is required for specifying members of + // :ref:`STATIC`, + // :ref:`STRICT_DNS` + // or + // :ref:`LOGICAL_DNS` + // clusters. This field supersedes + // :ref:`hosts` field. + // [#comment:TODO(dio): Deprecate the hosts field and add it to :ref:`deprecated log` + // once load_assignment is implemented.] + // + // .. attention:: + // + // Setting this allows non-EDS cluster types to contain embedded EDS equivalent + // :ref:`endpoint assignments`. + // Setting this overrides :ref:`hosts` + // values. + // + endpoint.v3alpha.ClusterLoadAssignment load_assignment = 33; + + // Optional :ref:`active health checking ` + // configuration for the cluster. If no + // configuration is specified no health checking will be done and all cluster + // members will be considered healthy at all times. + repeated core.v3alpha.HealthCheck health_checks = 8; + + // Optional maximum requests for a single upstream connection. This parameter + // is respected by both the HTTP/1.1 and HTTP/2 connection pool + // implementations. If not specified, there is no limit. Setting this + // parameter to 1 will effectively disable keep alive. + google.protobuf.UInt32Value max_requests_per_connection = 9; + + // Optional :ref:`circuit breaking ` for the cluster. + CircuitBreakers circuit_breakers = 10; + + // Additional options when handling HTTP requests upstream. These options will be applicable to + // both HTTP1 and HTTP2 requests. + core.v3alpha.HttpProtocolOptions common_http_protocol_options = 29; + + // Additional options when handling HTTP1 requests. + core.v3alpha.Http1ProtocolOptions http_protocol_options = 13; + + // Even if default HTTP2 protocol options are desired, this field must be + // set so that Envoy will assume that the upstream supports HTTP/2 when + // making new HTTP connection pool connections. Currently, Envoy only + // supports prior knowledge for upstream connections. Even if TLS is used + // with ALPN, `http2_protocol_options` must be specified. As an aside this allows HTTP/2 + // connections to happen over plain text. + core.v3alpha.Http2ProtocolOptions http2_protocol_options = 14; + + // The extension_protocol_options field is used to provide extension-specific protocol options + // for upstream connections. The key should match the extension filter name, such as + // "envoy.filters.network.thrift_proxy". See the extension's documentation for details on + // specific options. + map typed_extension_protocol_options = 36; + + // If the DNS refresh rate is specified and the cluster type is either + // :ref:`STRICT_DNS`, + // or + // :ref:`LOGICAL_DNS`, + // this value is used as the cluster’s DNS refresh + // rate. The value configured must be at least 1ms. If this setting is not specified, the + // value defaults to 5000ms. For cluster types other than + // :ref:`STRICT_DNS` + // and + // :ref:`LOGICAL_DNS` + // this setting is ignored. + google.protobuf.Duration dns_refresh_rate = 16 + [(validate.rules).duration = {gt {nanos: 1000000}}]; + + // If the DNS failure refresh rate is specified and the cluster type is either + // :ref:`STRICT_DNS`, + // or + // :ref:`LOGICAL_DNS`, + // this is used as the cluster’s DNS refresh rate when requests are failing. If this setting is + // not specified, the failure refresh rate defaults to the DNS refresh rate. For cluster types + // other than + // :ref:`STRICT_DNS` + // and + // :ref:`LOGICAL_DNS` + // this setting is ignored. + // + // Note: Currently, DNS failures and empty DNS responses are not treated differently and this + // configuration is applied in both situations. + RefreshRate dns_failure_refresh_rate = 44; + + // Optional configuration for setting cluster's DNS refresh rate. If the value is set to true, + // cluster's DNS refresh rate will be set to resource record's TTL which comes from DNS + // resolution. + bool respect_dns_ttl = 39; + + // The DNS IP address resolution policy. If this setting is not specified, the + // value defaults to + // :ref:`AUTO`. + DnsLookupFamily dns_lookup_family = 17 [(validate.rules).enum = {defined_only: true}]; + + // If DNS resolvers are specified and the cluster type is either + // :ref:`STRICT_DNS`, + // or + // :ref:`LOGICAL_DNS`, + // this value is used to specify the cluster’s dns resolvers. + // If this setting is not specified, the value defaults to the default + // resolver, which uses /etc/resolv.conf for configuration. For cluster types + // other than + // :ref:`STRICT_DNS` + // and + // :ref:`LOGICAL_DNS` + // this setting is ignored. + repeated core.v3alpha.Address dns_resolvers = 18; + + // [#next-major-version: Reconcile DNS options in a single message.] + // Always use TCP queries instead of UDP queries for DNS lookups. + bool use_tcp_for_dns_lookups = 45; + + // If specified, outlier detection will be enabled for this upstream cluster. + // Each of the configuration values can be overridden via + // :ref:`runtime values `. + OutlierDetection outlier_detection = 19; + + // The interval for removing stale hosts from a cluster type + // :ref:`ORIGINAL_DST`. + // Hosts are considered stale if they have not been used + // as upstream destinations during this interval. New hosts are added + // to original destination clusters on demand as new connections are + // redirected to Envoy, causing the number of hosts in the cluster to + // grow over time. Hosts that are not stale (they are actively used as + // destinations) are kept in the cluster, which allows connections to + // them remain open, saving the latency that would otherwise be spent + // on opening new connections. If this setting is not specified, the + // value defaults to 5000ms. For cluster types other than + // :ref:`ORIGINAL_DST` + // this setting is ignored. + google.protobuf.Duration cleanup_interval = 20 [(validate.rules).duration = {gt {}}]; + + // Optional configuration used to bind newly established upstream connections. + // This overrides any bind_config specified in the bootstrap proto. + // If the address and port are empty, no bind will be performed. + core.v3alpha.BindConfig upstream_bind_config = 21; + + // Configuration for load balancing subsetting. + LbSubsetConfig lb_subset_config = 22; + + // Optional configuration for the load balancing algorithm selected by + // LbPolicy. Currently only + // :ref:`RING_HASH` and + // :ref:`LEAST_REQUEST` + // has additional configuration options. + // Specifying ring_hash_lb_config or least_request_lb_config without setting the corresponding + // LbPolicy will generate an error at runtime. + oneof lb_config { + // Optional configuration for the Ring Hash load balancing policy. + RingHashLbConfig ring_hash_lb_config = 23; + + // Optional configuration for the Original Destination load balancing policy. + OriginalDstLbConfig original_dst_lb_config = 34; + + // Optional configuration for the LeastRequest load balancing policy. + LeastRequestLbConfig least_request_lb_config = 37; + } + + // Common configuration for all load balancer implementations. + CommonLbConfig common_lb_config = 27; + + // Optional custom transport socket implementation to use for upstream connections. + // To setup TLS, set a transport socket with name `tls` and + // :ref:`UpstreamTlsContexts + // ` in the + // `typed_config`. If no transport socket configuration is specified, new connections will be set + // up with plaintext. + core.v3alpha.TransportSocket transport_socket = 24; + + // The Metadata field can be used to provide additional information about the + // cluster. It can be used for stats, logging, and varying filter behavior. + // Fields should use reverse DNS notation to denote which entity within Envoy + // will need the information. For instance, if the metadata is intended for + // the Router filter, the filter name should be specified as *envoy.router*. + core.v3alpha.Metadata metadata = 25; + + // Determines how Envoy selects the protocol used to speak to upstream hosts. + ClusterProtocolSelection protocol_selection = 26; + + // Optional options for upstream connections. + UpstreamConnectionOptions upstream_connection_options = 30; + + // If an upstream host becomes unhealthy (as determined by the configured health checks + // or outlier detection), immediately close all connections to the failed host. + // + // .. note:: + // + // This is currently only supported for connections created by tcp_proxy. + // + // .. note:: + // + // The current implementation of this feature closes all connections immediately when + // the unhealthy status is detected. If there are a large number of connections open + // to an upstream host that becomes unhealthy, Envoy may spend a substantial amount of + // time exclusively closing these connections, and not processing any other traffic. + bool close_connections_on_host_health_failure = 31; + + // If set to true, Envoy will ignore the health value of a host when processing its removal + // from service discovery. This means that if active health checking is used, Envoy will *not* + // wait for the endpoint to go unhealthy before removing it. + bool ignore_health_on_host_removal = 32; + + // An (optional) network filter chain, listed in the order the filters should be applied. + // The chain will be applied to all outgoing connections that Envoy makes to the upstream + // servers of this cluster. + repeated Filter filters = 40; + + // [#not-implemented-hide:] New mechanism for LB policy configuration. Used only if the + // :ref:`lb_policy` field has the value + // :ref:`LOAD_BALANCING_POLICY_CONFIG`. + LoadBalancingPolicy load_balancing_policy = 41; + + // [#not-implemented-hide:] + // If present, tells the client where to send load reports via LRS. If not present, the + // client will fall back to a client-side default, which may be either (a) don't send any + // load reports or (b) send load reports for all clusters to a single default server + // (which may be configured in the bootstrap file). + // + // Note that if multiple clusters point to the same LRS server, the client may choose to + // create a separate stream for each cluster or it may choose to coalesce the data for + // multiple clusters onto a single stream. Either way, the client must make sure to send + // the data for any given cluster on no more than one stream. + // + // [#next-major-version: In the v3 API, we should consider restructuring this somehow, + // maybe by allowing LRS to go on the ADS stream, or maybe by moving some of the negotiation + // from the LRS stream here.] + core.v3alpha.ConfigSource lrs_server = 42; +} + +// [#not-implemented-hide:] Extensible load balancing policy configuration. +// +// Every LB policy defined via this mechanism will be identified via a unique name using reverse +// DNS notation. If the policy needs configuration parameters, it must define a message for its +// own configuration, which will be stored in the config field. The name of the policy will tell +// clients which type of message they should expect to see in the config field. +// +// Note that there are cases where it is useful to be able to independently select LB policies +// for choosing a locality and for choosing an endpoint within that locality. For example, a +// given deployment may always use the same policy to choose the locality, but for choosing the +// endpoint within the locality, some clusters may use weighted-round-robin, while others may +// use some sort of session-based balancing. +// +// This can be accomplished via hierarchical LB policies, where the parent LB policy creates a +// child LB policy for each locality. For each request, the parent chooses the locality and then +// delegates to the child policy for that locality to choose the endpoint within the locality. +// +// To facilitate this, the config message for the top-level LB policy may include a field of +// type LoadBalancingPolicy that specifies the child policy. +message LoadBalancingPolicy { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.LoadBalancingPolicy"; + + message Policy { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.LoadBalancingPolicy.Policy"; + + reserved 2; + + reserved "config"; + + // Required. The name of the LB policy. + string name = 1; + + google.protobuf.Any typed_config = 3; + } + + // Each client will iterate over the list in order and stop at the first policy that it + // supports. This provides a mechanism for starting to use new LB policies that are not yet + // supported by all clients. + repeated Policy policies = 1; +} + +// An extensible structure containing the address Envoy should bind to when +// establishing upstream connections. +message UpstreamBindConfig { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.UpstreamBindConfig"; + + // The address Envoy should bind to when establishing upstream connections. + core.v3alpha.Address source_address = 1; +} + +message UpstreamConnectionOptions { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.UpstreamConnectionOptions"; + + // If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives. + core.v3alpha.TcpKeepalive tcp_keepalive = 1; +} diff --git a/envoy/config/common/dynamic_forward_proxy/v2alpha/dns_cache.proto b/envoy/config/common/dynamic_forward_proxy/v2alpha/dns_cache.proto index cf614c56..804a9dd5 100644 --- a/envoy/config/common/dynamic_forward_proxy/v2alpha/dns_cache.proto +++ b/envoy/config/common/dynamic_forward_proxy/v2alpha/dns_cache.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.config.common.dynamic_forward_proxy.v2alpha; -import "envoy/api/v2/cds.proto"; +import "envoy/api/v2/cluster.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; diff --git a/envoy/config/core/v3alpha/address.proto b/envoy/config/core/v3alpha/address.proto index 4d1c83e0..63d4d556 100644 --- a/envoy/config/core/v3alpha/address.proto +++ b/envoy/config/core/v3alpha/address.proto @@ -47,7 +47,7 @@ message SocketAddress { // in :ref:`FilterChainMatch `.] When used // within an upstream :ref:`BindConfig `, the // address controls the source address of outbound connections. For :ref:`clusters - // `, the cluster type determines whether the + // `, the cluster type determines whether the // address must be an IP (*STATIC* or *EDS* clusters) or a hostname resolved by DNS // (*STRICT_DNS* or *LOGICAL_DNS* clusters). Address resolution can be customized // via :ref:`resolver_name `. @@ -104,10 +104,11 @@ message BindConfig { // Whether to set the *IP_FREEBIND* option when creating the socket. When this // flag is set to true, allows the :ref:`source_address - // ` to be an IP - // address that is not configured on the system running Envoy. When this flag is set to false, the - // option *IP_FREEBIND* is disabled on the socket. When this flag is not set (default), the socket - // is not modified, i.e. the option is neither enabled nor disabled. + // ` to be an IP address + // that is not configured on the system running Envoy. When this flag is set + // to false, the option *IP_FREEBIND* is disabled on the socket. When this + // flag is not set (default), the socket is not modified, i.e. the option is + // neither enabled nor disabled. google.protobuf.BoolValue freebind = 2; // Additional socket options that may not be present in Envoy source code or diff --git a/envoy/config/core/v3alpha/base.proto b/envoy/config/core/v3alpha/base.proto index f9422d69..869e61ea 100644 --- a/envoy/config/core/v3alpha/base.proto +++ b/envoy/config/core/v3alpha/base.proto @@ -257,7 +257,7 @@ message AsyncDataSource { } // Configuration for transport socket in :ref:`listeners ` and -// :ref:`clusters `. If the configuration is +// :ref:`clusters `. If the configuration is // empty, a default transport socket implementation and configuration will be // chosen based on the platform and existence of tls_context. message TransportSocket { diff --git a/envoy/config/core/v3alpha/config_source.proto b/envoy/config/core/v3alpha/config_source.proto index 824c65b9..b2e4d555 100644 --- a/envoy/config/core/v3alpha/config_source.proto +++ b/envoy/config/core/v3alpha/config_source.proto @@ -109,7 +109,7 @@ message RateLimitSettings { // Configuration for :ref:`listeners `, :ref:`clusters // `, :ref:`routes -// `, :ref:`endpoints +// `, :ref:`endpoints // ` etc. may either be sourced from the // filesystem or from an xDS API source. Filesystem configs are watched with // inotify for updates. diff --git a/envoy/config/core/v3alpha/grpc_service.proto b/envoy/config/core/v3alpha/grpc_service.proto index 67490acc..31e4650e 100644 --- a/envoy/config/core/v3alpha/grpc_service.proto +++ b/envoy/config/core/v3alpha/grpc_service.proto @@ -30,8 +30,8 @@ message GrpcService { "envoy.api.v2.core.GrpcService.EnvoyGrpc"; // The name of the upstream gRPC cluster. SSL credentials will be supplied - // in the :ref:`Cluster ` :ref:`transport_socket - // `. + // in the :ref:`Cluster ` :ref:`transport_socket + // `. string cluster_name = 1 [(validate.rules).string = {min_bytes: 1}]; } diff --git a/envoy/config/endpoint/v3alpha/BUILD b/envoy/config/endpoint/v3alpha/BUILD index 0e220253..f2ff581d 100644 --- a/envoy/config/endpoint/v3alpha/BUILD +++ b/envoy/config/endpoint/v3alpha/BUILD @@ -6,8 +6,10 @@ licenses(["notice"]) # Apache 2 api_proto_package( deps = [ + "//envoy/api/v2:pkg", "//envoy/api/v2/endpoint:pkg", "//envoy/config/core/v3alpha:pkg", + "//envoy/type/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/config/endpoint/v3alpha/endpoint.proto b/envoy/config/endpoint/v3alpha/endpoint.proto index a39332cc..7999b31b 100644 --- a/envoy/config/endpoint/v3alpha/endpoint.proto +++ b/envoy/config/endpoint/v3alpha/endpoint.proto @@ -2,10 +2,11 @@ syntax = "proto3"; package envoy.config.endpoint.v3alpha; -import "envoy/config/core/v3alpha/address.proto"; -import "envoy/config/core/v3alpha/base.proto"; -import "envoy/config/core/v3alpha/health_check.proto"; +import "envoy/config/endpoint/v3alpha/endpoint_components.proto"; +import "envoy/type/v3alpha/percent.proto"; +import "google/api/annotations.proto"; +import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; import "udpa/annotations/versioning.proto"; @@ -16,126 +17,109 @@ option java_package = "io.envoyproxy.envoy.config.endpoint.v3alpha"; option java_outer_classname = "EndpointProto"; option java_multiple_files = true; -// [#protodoc-title: Endpoints] - -// Upstream host identifier. -message Endpoint { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.Endpoint"; +// [#protodoc-title: Endpoint configuration] +// Endpoint discovery :ref:`architecture overview ` + +// Each route from RDS will map to a single cluster or traffic split across +// clusters using weights expressed in the RDS WeightedCluster. +// +// With EDS, each cluster is treated independently from a LB perspective, with +// LB taking place between the Localities within a cluster and at a finer +// granularity between the hosts within a locality. The percentage of traffic +// for each endpoint is determined by both its load_balancing_weight, and the +// load_balancing_weight of its locality. First, a locality will be selected, +// then an endpoint within that locality will be chose based on its weight. +// [#next-free-field: 6] +message ClusterLoadAssignment { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.ClusterLoadAssignment"; - // The optional health check configuration. - message HealthCheckConfig { + // Load balancing policy settings. + // [#next-free-field: 6] + message Policy { option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.endpoint.Endpoint.HealthCheckConfig"; + "envoy.api.v2.ClusterLoadAssignment.Policy"; - // Optional alternative health check port value. - // - // By default the health check address port of an upstream host is the same - // as the host's serving address port. This provides an alternative health - // check port. Setting this with a non-zero value allows an upstream host - // to have different health check address port. - uint32 port_value = 1 [(validate.rules).uint32 = {lte: 65535}]; - } + message DropOverload { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.ClusterLoadAssignment.Policy.DropOverload"; - // The upstream host address. - // - // .. attention:: - // - // The form of host address depends on the given cluster type. For STATIC or EDS, - // it is expected to be a direct IP address (or something resolvable by the - // specified :ref:`resolver ` - // in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname, - // and will be resolved via DNS. - core.v3alpha.Address address = 1; - - // The optional health check configuration is used as configuration for the - // health checker to contact the health checked host. - // - // .. attention:: - // - // This takes into effect only for upstream clusters with - // :ref:`active health checking ` enabled. - HealthCheckConfig health_check_config = 2; -} + // Identifier for the policy specifying the drop. + string category = 1 [(validate.rules).string = {min_bytes: 1}]; -// An Endpoint that Envoy can route traffic to. -// [#next-free-field: 6] -message LbEndpoint { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.LbEndpoint"; + // Percentage of traffic that should be dropped for the category. + type.v3alpha.FractionalPercent drop_percentage = 2; + } - // Upstream host identifier or a named reference. - oneof host_identifier { - Endpoint endpoint = 1; + reserved 1; + // Action to trim the overall incoming traffic to protect the upstream + // hosts. This action allows protection in case the hosts are unable to + // recover from an outage, or unable to autoscale or unable to handle + // incoming traffic volume for any reason. + // + // At the client each category is applied one after the other to generate + // the 'actual' drop percentage on all outgoing traffic. For example: + // + // .. code-block:: json + // + // { "drop_overloads": [ + // { "category": "throttle", "drop_percentage": 60 } + // { "category": "lb", "drop_percentage": 50 } + // ]} + // + // The actual drop percentages applied to the traffic at the clients will be + // "throttle"_drop = 60% + // "lb"_drop = 20% // 50% of the remaining 'actual' load, which is 40%. + // actual_outgoing_load = 20% // remaining after applying all categories. + repeated DropOverload drop_overloads = 2; + + // Priority levels and localities are considered overprovisioned with this + // factor (in percentage). This means that we don't consider a priority + // level or locality unhealthy until the percentage of healthy hosts + // multiplied by the overprovisioning factor drops below 100. + // With the default value 140(1.4), Envoy doesn't consider a priority level + // or a locality unhealthy until their percentage of healthy hosts drops + // below 72%. For example: + // + // .. code-block:: json + // + // { "overprovisioning_factor": 100 } + // + // Read more at :ref:`priority levels ` and + // :ref:`localities `. + google.protobuf.UInt32Value overprovisioning_factor = 3 [(validate.rules).uint32 = {gt: 0}]; + + // The max time until which the endpoints from this assignment can be used. + // If no new assignments are received before this time expires the endpoints + // are considered stale and should be marked unhealthy. + // Defaults to 0 which means endpoints never go stale. + google.protobuf.Duration endpoint_stale_after = 4 [(validate.rules).duration = {gt {}}]; + + // The flag to disable overprovisioning. If it is set to true, + // :ref:`overprovisioning factor + // ` will be ignored + // and Envoy will not perform graceful failover between priority levels or + // localities as endpoints become unhealthy. Otherwise Envoy will perform + // graceful failover as :ref:`overprovisioning factor + // ` suggests. + // [#next-major-version: Unify with overprovisioning config as a single message.] // [#not-implemented-hide:] - string endpoint_name = 5; + bool disable_overprovisioning = 5; } - // Optional health status when known and supplied by EDS server. - core.v3alpha.HealthStatus health_status = 2; - - // The endpoint metadata specifies values that may be used by the load - // balancer to select endpoints in a cluster for a given request. The filter - // name should be specified as *envoy.lb*. An example boolean key-value pair - // is *canary*, providing the optional canary status of the upstream host. - // This may be matched against in a route's - // :ref:`RouteAction ` metadata_match field - // to subset the endpoints considered in cluster load balancing. - core.v3alpha.Metadata metadata = 3; - - // The optional load balancing weight of the upstream host; at least 1. - // Envoy uses the load balancing weight in some of the built in load - // balancers. The load balancing weight for an endpoint is divided by the sum - // of the weights of all endpoints in the endpoint's locality to produce a - // percentage of traffic for the endpoint. This percentage is then further - // weighted by the endpoint's locality's load balancing weight from - // LocalityLbEndpoints. If unspecified, each host is presumed to have equal - // weight in a locality. - google.protobuf.UInt32Value load_balancing_weight = 4 [(validate.rules).uint32 = {gte: 1}]; -} + // Name of the cluster. This will be the :ref:`service_name + // ` value if + // specified in the cluster :ref:`EdsClusterConfig + // `. + string cluster_name = 1 [(validate.rules).string = {min_bytes: 1}]; -// A group of endpoints belonging to a Locality. -// One can have multiple LocalityLbEndpoints for a locality, but this is -// generally only done if the different groups need to have different load -// balancing weights or different priorities. -// [#next-free-field: 7] -message LocalityLbEndpoints { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.endpoint.LocalityLbEndpoints"; - - // Identifies location of where the upstream hosts run. - core.v3alpha.Locality locality = 1; - - // The group of endpoints belonging to the locality specified. - repeated LbEndpoint lb_endpoints = 2; - - // Optional: Per priority/region/zone/sub_zone weight; at least 1. The load - // balancing weight for a locality is divided by the sum of the weights of all - // localities at the same priority level to produce the effective percentage - // of traffic for the locality. - // - // Locality weights are only considered when :ref:`locality weighted load - // balancing ` is - // configured. These weights are ignored otherwise. If no weights are - // specified when locality weighted load balancing is enabled, the locality is - // assigned no load. - google.protobuf.UInt32Value load_balancing_weight = 3 [(validate.rules).uint32 = {gte: 1}]; - - // Optional: the priority for this LocalityLbEndpoints. If unspecified this will - // default to the highest priority (0). - // - // Under usual circumstances, Envoy will only select endpoints for the highest - // priority (0). In the event all endpoints for a particular priority are - // unavailable/unhealthy, Envoy will fail over to selecting endpoints for the - // next highest priority group. - // - // Priorities should range from 0 (highest) to N (lowest) without skipping. - uint32 priority = 5 [(validate.rules).uint32 = {lte: 128}]; - - // Optional: Per locality proximity value which indicates how close this - // locality is from the source locality. This value only provides ordering - // information (lower the value, closer it is to the source locality). - // This will be consumed by load balancing schemes that need proximity order - // to determine where to route the requests. + // List of endpoints to load balance to. + repeated LocalityLbEndpoints endpoints = 2; + + // Map of named endpoints that can be referenced in LocalityLbEndpoints. // [#not-implemented-hide:] - google.protobuf.UInt32Value proximity = 6; + map named_endpoints = 5; + + // Load balancing policy settings. + Policy policy = 4; } diff --git a/envoy/config/endpoint/v3alpha/endpoint_components.proto b/envoy/config/endpoint/v3alpha/endpoint_components.proto new file mode 100644 index 00000000..a787876b --- /dev/null +++ b/envoy/config/endpoint/v3alpha/endpoint_components.proto @@ -0,0 +1,141 @@ +syntax = "proto3"; + +package envoy.config.endpoint.v3alpha; + +import "envoy/config/core/v3alpha/address.proto"; +import "envoy/config/core/v3alpha/base.proto"; +import "envoy/config/core/v3alpha/health_check.proto"; + +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/versioning.proto"; + +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.config.endpoint.v3alpha"; +option java_outer_classname = "EndpointComponentsProto"; +option java_multiple_files = true; + +// [#protodoc-title: Endpoints] + +// Upstream host identifier. +message Endpoint { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.Endpoint"; + + // The optional health check configuration. + message HealthCheckConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.endpoint.Endpoint.HealthCheckConfig"; + + // Optional alternative health check port value. + // + // By default the health check address port of an upstream host is the same + // as the host's serving address port. This provides an alternative health + // check port. Setting this with a non-zero value allows an upstream host + // to have different health check address port. + uint32 port_value = 1 [(validate.rules).uint32 = {lte: 65535}]; + } + + // The upstream host address. + // + // .. attention:: + // + // The form of host address depends on the given cluster type. For STATIC or EDS, + // it is expected to be a direct IP address (or something resolvable by the + // specified :ref:`resolver ` + // in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname, + // and will be resolved via DNS. + core.v3alpha.Address address = 1; + + // The optional health check configuration is used as configuration for the + // health checker to contact the health checked host. + // + // .. attention:: + // + // This takes into effect only for upstream clusters with + // :ref:`active health checking ` enabled. + HealthCheckConfig health_check_config = 2; +} + +// An Endpoint that Envoy can route traffic to. +// [#next-free-field: 6] +message LbEndpoint { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.LbEndpoint"; + + // Upstream host identifier or a named reference. + oneof host_identifier { + Endpoint endpoint = 1; + + // [#not-implemented-hide:] + string endpoint_name = 5; + } + + // Optional health status when known and supplied by EDS server. + core.v3alpha.HealthStatus health_status = 2; + + // The endpoint metadata specifies values that may be used by the load + // balancer to select endpoints in a cluster for a given request. The filter + // name should be specified as *envoy.lb*. An example boolean key-value pair + // is *canary*, providing the optional canary status of the upstream host. + // This may be matched against in a route's + // :ref:`RouteAction ` metadata_match field + // to subset the endpoints considered in cluster load balancing. + core.v3alpha.Metadata metadata = 3; + + // The optional load balancing weight of the upstream host; at least 1. + // Envoy uses the load balancing weight in some of the built in load + // balancers. The load balancing weight for an endpoint is divided by the sum + // of the weights of all endpoints in the endpoint's locality to produce a + // percentage of traffic for the endpoint. This percentage is then further + // weighted by the endpoint's locality's load balancing weight from + // LocalityLbEndpoints. If unspecified, each host is presumed to have equal + // weight in a locality. + google.protobuf.UInt32Value load_balancing_weight = 4 [(validate.rules).uint32 = {gte: 1}]; +} + +// A group of endpoints belonging to a Locality. +// One can have multiple LocalityLbEndpoints for a locality, but this is +// generally only done if the different groups need to have different load +// balancing weights or different priorities. +// [#next-free-field: 7] +message LocalityLbEndpoints { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.endpoint.LocalityLbEndpoints"; + + // Identifies location of where the upstream hosts run. + core.v3alpha.Locality locality = 1; + + // The group of endpoints belonging to the locality specified. + repeated LbEndpoint lb_endpoints = 2; + + // Optional: Per priority/region/zone/sub_zone weight; at least 1. The load + // balancing weight for a locality is divided by the sum of the weights of all + // localities at the same priority level to produce the effective percentage + // of traffic for the locality. + // + // Locality weights are only considered when :ref:`locality weighted load + // balancing ` is + // configured. These weights are ignored otherwise. If no weights are + // specified when locality weighted load balancing is enabled, the locality is + // assigned no load. + google.protobuf.UInt32Value load_balancing_weight = 3 [(validate.rules).uint32 = {gte: 1}]; + + // Optional: the priority for this LocalityLbEndpoints. If unspecified this will + // default to the highest priority (0). + // + // Under usual circumstances, Envoy will only select endpoints for the highest + // priority (0). In the event all endpoints for a particular priority are + // unavailable/unhealthy, Envoy will fail over to selecting endpoints for the + // next highest priority group. + // + // Priorities should range from 0 (highest) to N (lowest) without skipping. + uint32 priority = 5 [(validate.rules).uint32 = {lte: 128}]; + + // Optional: Per locality proximity value which indicates how close this + // locality is from the source locality. This value only provides ordering + // information (lower the value, closer it is to the source locality). + // This will be consumed by load balancing schemes that need proximity order + // to determine where to route the requests. + // [#not-implemented-hide:] + google.protobuf.UInt32Value proximity = 6; +} diff --git a/envoy/config/filter/accesslog/v2/accesslog.proto b/envoy/config/filter/accesslog/v2/accesslog.proto index e634f4c2..576e88c8 100644 --- a/envoy/config/filter/accesslog/v2/accesslog.proto +++ b/envoy/config/filter/accesslog/v2/accesslog.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package envoy.config.filter.accesslog.v2; import "envoy/api/v2/core/base.proto"; -import "envoy/api/v2/route/route.proto"; +import "envoy/api/v2/route/route_components.proto"; import "envoy/type/percent.proto"; import "google/protobuf/any.proto"; diff --git a/envoy/config/filter/accesslog/v3alpha/accesslog.proto b/envoy/config/filter/accesslog/v3alpha/accesslog.proto index 5fd426b7..a6b6aae2 100644 --- a/envoy/config/filter/accesslog/v3alpha/accesslog.proto +++ b/envoy/config/filter/accesslog/v3alpha/accesslog.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package envoy.config.filter.accesslog.v3alpha; import "envoy/config/core/v3alpha/base.proto"; -import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; import "envoy/type/v3alpha/percent.proto"; import "google/protobuf/any.proto"; diff --git a/envoy/config/filter/http/fault/v2/fault.proto b/envoy/config/filter/http/fault/v2/fault.proto index 61da8b1a..8b16b4f3 100644 --- a/envoy/config/filter/http/fault/v2/fault.proto +++ b/envoy/config/filter/http/fault/v2/fault.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.config.filter.http.fault.v2; -import "envoy/api/v2/route/route.proto"; +import "envoy/api/v2/route/route_components.proto"; import "envoy/config/filter/fault/v2/fault.proto"; import "envoy/type/percent.proto"; diff --git a/envoy/config/filter/http/health_check/v2/health_check.proto b/envoy/config/filter/http/health_check/v2/health_check.proto index dd42c106..478e28a5 100644 --- a/envoy/config/filter/http/health_check/v2/health_check.proto +++ b/envoy/config/filter/http/health_check/v2/health_check.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.config.filter.http.health_check.v2; -import "envoy/api/v2/route/route.proto"; +import "envoy/api/v2/route/route_components.proto"; import "envoy/type/percent.proto"; import "google/protobuf/duration.proto"; diff --git a/envoy/config/filter/http/jwt_authn/v2alpha/config.proto b/envoy/config/filter/http/jwt_authn/v2alpha/config.proto index 8ed5c990..861dc27e 100644 --- a/envoy/config/filter/http/jwt_authn/v2alpha/config.proto +++ b/envoy/config/filter/http/jwt_authn/v2alpha/config.proto @@ -4,7 +4,7 @@ package envoy.config.filter.http.jwt_authn.v2alpha; import "envoy/api/v2/core/base.proto"; import "envoy/api/v2/core/http_uri.proto"; -import "envoy/api/v2/route/route.proto"; +import "envoy/api/v2/route/route_components.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/empty.proto"; diff --git a/envoy/config/filter/network/dubbo_proxy/v2alpha1/route.proto b/envoy/config/filter/network/dubbo_proxy/v2alpha1/route.proto index b16ca9df..fc136c13 100644 --- a/envoy/config/filter/network/dubbo_proxy/v2alpha1/route.proto +++ b/envoy/config/filter/network/dubbo_proxy/v2alpha1/route.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.config.filter.network.dubbo_proxy.v2alpha1; -import "envoy/api/v2/route/route.proto"; +import "envoy/api/v2/route/route_components.proto"; import "envoy/type/matcher/string.proto"; import "envoy/type/range.proto"; diff --git a/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto b/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto index 13586971..76e12199 100644 --- a/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto +++ b/envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto @@ -4,8 +4,8 @@ package envoy.config.filter.network.http_connection_manager.v2; import "envoy/api/v2/core/config_source.proto"; import "envoy/api/v2/core/protocol.proto"; -import "envoy/api/v2/rds.proto"; -import "envoy/api/v2/srds.proto"; +import "envoy/api/v2/route.proto"; +import "envoy/api/v2/scoped_route.proto"; import "envoy/config/filter/accesslog/v2/accesslog.proto"; import "envoy/type/percent.proto"; import "envoy/type/tracing/v2/custom_tag.proto"; diff --git a/envoy/config/filter/network/thrift_proxy/v2alpha1/route.proto b/envoy/config/filter/network/thrift_proxy/v2alpha1/route.proto index 0be0babd..5c869edc 100644 --- a/envoy/config/filter/network/thrift_proxy/v2alpha1/route.proto +++ b/envoy/config/filter/network/thrift_proxy/v2alpha1/route.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package envoy.config.filter.network.thrift_proxy.v2alpha1; import "envoy/api/v2/core/base.proto"; -import "envoy/api/v2/route/route.proto"; +import "envoy/api/v2/route/route_components.proto"; import "google/protobuf/wrappers.proto"; diff --git a/envoy/config/rbac/v2/rbac.proto b/envoy/config/rbac/v2/rbac.proto index 9633e955..833eaa6f 100644 --- a/envoy/config/rbac/v2/rbac.proto +++ b/envoy/config/rbac/v2/rbac.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package envoy.config.rbac.v2; import "envoy/api/v2/core/address.proto"; -import "envoy/api/v2/route/route.proto"; +import "envoy/api/v2/route/route_components.proto"; import "envoy/type/matcher/metadata.proto"; import "envoy/type/matcher/string.proto"; diff --git a/envoy/config/rbac/v3alpha/rbac.proto b/envoy/config/rbac/v3alpha/rbac.proto index 17f55d13..7d874239 100644 --- a/envoy/config/rbac/v3alpha/rbac.proto +++ b/envoy/config/rbac/v3alpha/rbac.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package envoy.config.rbac.v3alpha; import "envoy/config/core/v3alpha/address.proto"; -import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; import "envoy/type/matcher/v3alpha/metadata.proto"; import "envoy/type/matcher/v3alpha/string.proto"; diff --git a/envoy/config/route/v3alpha/BUILD b/envoy/config/route/v3alpha/BUILD index d916de8b..8b724d7e 100644 --- a/envoy/config/route/v3alpha/BUILD +++ b/envoy/config/route/v3alpha/BUILD @@ -6,6 +6,7 @@ licenses(["notice"]) # Apache 2 api_proto_package( deps = [ + "//envoy/api/v2:pkg", "//envoy/api/v2/route:pkg", "//envoy/config/core/v3alpha:pkg", "//envoy/type/matcher/v3alpha:pkg", diff --git a/envoy/config/route/v3alpha/route.proto b/envoy/config/route/v3alpha/route.proto index d823b4eb..de92055b 100644 --- a/envoy/config/route/v3alpha/route.proto +++ b/envoy/config/route/v3alpha/route.proto @@ -3,15 +3,9 @@ syntax = "proto3"; package envoy.config.route.v3alpha; import "envoy/config/core/v3alpha/base.proto"; -import "envoy/type/matcher/v3alpha/regex.proto"; -import "envoy/type/matcher/v3alpha/string.proto"; -import "envoy/type/tracing/v2/custom_tag.proto"; -import "envoy/type/v3alpha/percent.proto"; -import "envoy/type/v3alpha/range.proto"; +import "envoy/config/core/v3alpha/config_source.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; -import "google/protobuf/any.proto"; -import "google/protobuf/duration.proto"; -import "google/protobuf/struct.proto"; import "google/protobuf/wrappers.proto"; import "udpa/annotations/versioning.proto"; @@ -22,1419 +16,94 @@ option java_package = "io.envoyproxy.envoy.config.route.v3alpha"; option java_outer_classname = "RouteProto"; option java_multiple_files = true; -// [#protodoc-title: HTTP route] +// [#protodoc-title: HTTP route configuration] // * Routing :ref:`architecture overview ` // * HTTP :ref:`router filter ` -// The top level element in the routing configuration is a virtual host. Each virtual host has -// a logical name as well as a set of domains that get routed to it based on the incoming request's -// host header. This allows a single listener to service multiple top level domain path trees. Once -// a virtual host is selected based on the domain, the routes are processed in order to see which -// upstream cluster to route to or whether to perform a redirect. -// [#next-free-field: 19] -message VirtualHost { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.VirtualHost"; - - 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 301 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 301 redirect - // will be sent telling the client to use HTTPS. - ALL = 2; - } - - reserved 9, 12; - - reserved "per_filter_config"; - - // The logical name of the virtual host. This is used when emitting certain - // statistics but is not relevant for routing. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // A list of domains (host/authority header) that will be matched to this - // virtual host. Wildcard hosts are supported in the suffix or prefix form. - // - // Domain search order: - // 1. Exact domain names: ``www.foo.com``. - // 2. Suffix domain wildcards: ``*.foo.com`` or ``*-bar.foo.com``. - // 3. Prefix domain wildcards: ``foo.*`` or ``foo-*``. - // 4. Special wildcard ``*`` matching any domain. - // - // .. note:: - // - // The wildcard will not match the empty string. - // e.g. ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``. - // The longest wildcards match first. - // 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 [(validate.rules).repeated = {min_items: 1}]; - - // 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; - - // Specifies the type of TLS enforcement the virtual host expects. If this option is not - // specified, there is no TLS requirement for the virtual host. - 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. Headers specified at this level are applied - // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the - // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including - // details on header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.v3alpha.HeaderValueOption request_headers_to_add = 7 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each request - // handled by this virtual host. - repeated string request_headers_to_remove = 13; - - // Specifies a list of HTTP headers that should be added to each response - // handled by this virtual host. Headers specified at this level are applied - // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the - // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including - // details on header value syntax, see the documentation on :ref:`custom request headers +// [#next-free-field: 11] +message RouteConfiguration { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.RouteConfiguration"; + + // The name of the route configuration. For example, it might match + // :ref:`route_config_name + // ` + // in :ref:`envoy_api_msg_config.filter.network.http_connection_manager.v2.Rds`. + string name = 1; + + // An array of virtual hosts that make up the route table. + repeated VirtualHost virtual_hosts = 2; + + // An array of virtual hosts will be dynamically loaded via the VHDS API. + // Both *virtual_hosts* and *vhds* fields will be used when present. *virtual_hosts* can be used + // for a base routing table or for infrequently changing virtual hosts. *vhds* is used for + // on-demand discovery of virtual hosts. The contents of these two fields will be merged to + // generate a routing table for a given RouteConfiguration, with *vhds* derived configuration + // taking precedence. + Vhds vhds = 9; + + // Optionally 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 :ref:`config_http_conn_man_headers_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. Headers specified at this level are applied + // after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or + // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers // `. - repeated core.v3alpha.HeaderValueOption response_headers_to_add = 10 + repeated core.v3alpha.HeaderValueOption response_headers_to_add = 4 [(validate.rules).repeated = {max_items: 1000}]; // Specifies a list of HTTP headers that should be removed from each response - // handled by this virtual host. - repeated string response_headers_to_remove = 11; - - // Indicates that the virtual host has a CORS policy. - CorsPolicy cors = 8; - - // The per_filter_config field can be used to provide virtual host-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` - // for if and how it is utilized. - map typed_per_filter_config = 15; - - // Decides whether the :ref:`x-envoy-attempt-count - // ` header should be included - // in the upstream request. Setting this option will cause it to override any existing header - // value, so in the case of two Envoys on the request path with this option enabled, the upstream - // will see the attempt count as perceived by the second Envoy. Defaults to false. - // This header is unaffected by the - // :ref:`suppress_envoy_headers - // ` flag. - bool include_request_attempt_count = 14; - - // Indicates the retry policy for all routes in this virtual host. Note that setting a - // route level entry will take precedence over this config and it'll be treated - // independently (e.g.: values are not inherited). - RetryPolicy retry_policy = 16; - - // Indicates the hedge policy for all routes in this virtual host. Note that setting a - // route level entry will take precedence over this config and it'll be treated - // independently (e.g.: values are not inherited). - HedgePolicy hedge_policy = 17; - - // The maximum bytes which will be buffered for retries and shadowing. - // If set and a route-specific limit is not set, the bytes actually buffered will be the minimum - // value of this and the listener per_connection_buffer_limit_bytes. - google.protobuf.UInt32Value per_request_buffer_limit_bytes = 18; -} - -// A filter-defined action type. -message FilterAction { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.FilterAction"; - - google.protobuf.Any action = 1; -} - -// A route is both a specification of how to match a request as well as an indication of what to do -// next (e.g., redirect, forward, rewrite, etc.). -// -// .. attention:: -// -// Envoy supports routing on HTTP method via :ref:`header matching -// `. -// [#next-free-field: 18] -message Route { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Route"; - - reserved 6, 8; - - reserved "per_filter_config"; + // that the connection manager encodes. + repeated string response_headers_to_remove = 5; - // Name for the route. - string name = 14; - - // Route matching parameters. - RouteMatch match = 1 [(validate.rules).message = {required: true}]; - - oneof action { - option (validate.required) = true; - - // Route request to some upstream cluster. - RouteAction route = 2; - - // Return a redirect. - RedirectAction redirect = 3; - - // Return an arbitrary HTTP response directly, without proxying. - DirectResponseAction direct_response = 7; - - // [#not-implemented-hide:] - // If true, a filter will define the action (e.g., it could dynamically generate the - // RouteAction). - FilterAction filter_action = 17; - } - - // The Metadata field can be used to provide additional information - // about the route. It can be used for configuration, stats, and logging. - // The metadata should go under the filter namespace that will need it. - // For instance, if the metadata is intended for the Router filter, - // the filter name should be specified as *envoy.router*. - core.v3alpha.Metadata metadata = 4; - - // Decorator for the matched route. - Decorator decorator = 5; - - // The per_filter_config field can be used to provide route-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` for - // if and how it is utilized. - map typed_per_filter_config = 13; - - // Specifies a set of headers that will be added to requests matching this - // route. Headers specified at this level are applied before headers from the - // enclosing :ref:`envoy_api_msg_route.VirtualHost` and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // Specifies a list of HTTP headers that should be added to each request + // routed by the HTTP connection manager. Headers specified at this level are + // applied after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or + // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on // header value syntax, see the documentation on :ref:`custom request headers // `. - repeated core.v3alpha.HeaderValueOption request_headers_to_add = 9 + repeated core.v3alpha.HeaderValueOption request_headers_to_add = 6 [(validate.rules).repeated = {max_items: 1000}]; // Specifies a list of HTTP headers that should be removed from each request - // matching this route. - repeated string request_headers_to_remove = 12; - - // Specifies a set of headers that will be added to responses to requests - // matching this route. Headers specified at this level are applied before - // headers from the enclosing :ref:`envoy_api_msg_route.VirtualHost` and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including - // details on header value syntax, see the documentation on - // :ref:`custom request headers `. - repeated core.v3alpha.HeaderValueOption response_headers_to_add = 10 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each response - // to requests matching this route. - repeated string response_headers_to_remove = 11; - - // Presence of the object defines whether the connection manager's tracing configuration - // is overridden by this route specific instance. - Tracing tracing = 15; - - // The maximum bytes which will be buffered for retries and shadowing. - // If set, the bytes actually buffered will be the minimum value of this and the - // listener per_connection_buffer_limit_bytes. - google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16; -} - -// Compared to the :ref:`cluster ` field -// that specifies a single upstream cluster as the target of a request, the :ref:`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 { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.WeightedCluster"; - - // [#next-free-field: 11] - message ClusterWeight { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.WeightedCluster.ClusterWeight"; - - reserved 7, 8; - - reserved "per_filter_config"; - - // Name of the upstream cluster. The cluster must exist in the - // :ref:`cluster manager configuration `. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // An integer between 0 and :ref:`total_weight - // `. 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 the total_weight, which defaults to - // 100. - google.protobuf.UInt32Value weight = 2; - - // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in - // the upstream cluster with metadata matching what is set in this field will be considered for - // load balancing. Note that this will be merged with what's provided in - // :ref:`RouteAction.metadata_match - // `, with values here taking - // precedence. The filter name should be specified as *envoy.lb*. - core.v3alpha.Metadata metadata_match = 3; - - // Specifies a list of headers to be added to requests when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. - // Headers specified at this level are applied before headers from the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.v3alpha.HeaderValueOption request_headers_to_add = 4 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each request when - // this cluster is selected through the enclosing :ref:`envoy_api_msg_route.RouteAction`. - repeated string request_headers_to_remove = 9; - - // Specifies a list of headers to be added to responses when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. - // Headers specified at this level are applied before headers from the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and - // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated core.v3alpha.HeaderValueOption response_headers_to_add = 5 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of headers to be removed from responses when this cluster is selected - // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. - repeated string response_headers_to_remove = 6; - - // The per_filter_config field can be used to provide weighted cluster-specific - // configurations for filters. The key should match the filter name, such as - // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter - // specific; see the :ref:`HTTP filter documentation ` - // for if and how it is utilized. - map typed_per_filter_config = 10; - } - - // Specifies one or more upstream clusters associated with the route. - repeated ClusterWeight clusters = 1 [(validate.rules).repeated = {min_items: 1}]; - - // Specifies the total weight across all clusters. The sum of all cluster weights must equal this - // value, which must be greater than 0. Defaults to 100. - google.protobuf.UInt32Value total_weight = 3 [(validate.rules).uint32 = {gte: 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 :ref:`runtime documentation - // ` for how key names map to the underlying implementation. - string runtime_key_prefix = 2; -} - -// [#next-free-field: 12] -message RouteMatch { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteMatch"; - - message GrpcRouteMatchOptions { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteMatch.GrpcRouteMatchOptions"; - } - - message TlsContextMatchOptions { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteMatch.TlsContextMatchOptions"; - - // If specified, the route will match against whether or not a certificate is presented. - google.protobuf.BoolValue presented = 1; - } - - reserved 5, 3; - - reserved "regex"; - - oneof path_specifier { - option (validate.required) = true; - - // 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 rule meaning that the - // regex must match the *:path* header once the query string is removed. The entire path - // (without the query string) must match the regex. The rule will not match if only a - // subsequence of the *:path* header matches the regex. - // - // [#next-major-version: In the v3 API we should redo how path specification works such - // that we utilize StringMatcher, and additionally have consistent options around whether we - // strip query strings, do a case sensitive match, etc. In the interim it will be too disruptive - // to deprecate the existing options. We should even consider whether we want to do away with - // path_specifier entirely and just rely on a set of header matchers which can already match - // on :path, etc. The issue with that is it is unclear how to generically deal with query string - // stripping. This needs more thought.] - type.matcher.v3alpha.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}]; - } - - // 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. Every time the route - // is considered for a match, it must also fall under the percentage of matches indicated by - // this field. For some fraction N/D, a random number in the range [0,D) is selected. If the - // number is <= the value of the numerator N, or if the key is not present, the default - // value, the router continues to evaluate the remaining match criteria. A runtime_fraction - // route configuration can be used to roll out route changes in a gradual manner without full - // code/config deploys. Refer to the :ref:`traffic shifting - // ` docs for additional documentation. - // - // .. note:: - // - // Parsing this field is implemented such that the runtime key's data may be represented - // as a FractionalPercent proto represented as JSON/YAML and may also be represented as an - // integer with the assumption that the value is an integral percentage out of 100. For - // instance, a runtime key lookup returning the value "42" would parse as a FractionalPercent - // whose numerator is 42 and denominator is HUNDRED. This preserves legacy semantics. - core.v3alpha.RuntimeFractionalPercent runtime_fraction = 9; - - // 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; - - // Specifies a set of URL query parameters on which the route should - // match. The router will check the query string from the *path* header - // against all the specified query parameters. If the number of specified - // query parameters is nonzero, they all must match the *path* header's - // query string for a match to occur. - repeated QueryParameterMatcher query_parameters = 7; - - // If specified, only gRPC requests will be matched. The router will check - // that the content-type header has a application/grpc or one of the various - // application/grpc+ values. - GrpcRouteMatchOptions grpc = 8; - - // If specified, the client tls context will be matched against the defined - // match options. - // - // [#next-major-version: unify with RBAC] - TlsContextMatchOptions tls_context = 11; -} - -// [#next-free-field: 12] -message CorsPolicy { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.CorsPolicy"; - - reserved 1, 8, 7; - - reserved "allow_origin", "allow_origin_regex", "enabled"; - - // Specifies string patterns that match allowed origins. An origin is allowed if any of the - // string matchers match. - repeated type.matcher.v3alpha.StringMatcher allow_origin_string_match = 11; - - // Specifies the content for the *access-control-allow-methods* header. - string allow_methods = 2; - - // Specifies the content for the *access-control-allow-headers* header. - string allow_headers = 3; - - // Specifies the content for the *access-control-expose-headers* header. - string expose_headers = 4; - - // Specifies the content for the *access-control-max-age* header. - string max_age = 5; - - // Specifies whether the resource allows credentials. - google.protobuf.BoolValue allow_credentials = 6; - - oneof enabled_specifier { - // Specifies the % of requests for which the CORS filter is enabled. - // - // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS - // filter will be enabled for 100% of the requests. - // - // If :ref:`runtime_key ` is - // specified, Envoy will lookup the runtime key to get the percentage of requests to filter. - core.v3alpha.RuntimeFractionalPercent filter_enabled = 9; - } - - // Specifies the % of requests for which the CORS policies will be evaluated and tracked, but not - // enforced. - // - // This field is intended to be used when ``filter_enabled`` and ``enabled`` are off. One of those - // fields have to explicitly disable the filter in order for this setting to take effect. - // - // If :ref:`runtime_key ` is specified, - // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate - // and track the request's *Origin* to determine if it's valid but will not enforce any policies. - core.v3alpha.RuntimeFractionalPercent shadow_enabled = 10; -} - -// [#next-free-field: 31] -message RouteAction { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteAction"; - - enum ClusterNotFoundResponseCode { - // HTTP status code - 503 Service Unavailable. - SERVICE_UNAVAILABLE = 0; - - // HTTP status code - 404 Not Found. - NOT_FOUND = 1; - } - - // Configures :ref:`internal redirect ` behavior. - enum InternalRedirectAction { - PASS_THROUGH_INTERNAL_REDIRECT = 0; - HANDLE_INTERNAL_REDIRECT = 1; - } - - // The router is capable of shadowing traffic from one cluster to another. The current - // implementation is "fire and forget," meaning Envoy will not wait for the shadow cluster to - // respond before returning the response from the primary cluster. All normal statistics are - // collected for the shadow cluster making this feature useful for testing. - // - // During shadowing, the host/authority header is altered such that *-shadow* is appended. This is - // useful for logging. For example, *cluster1* becomes *cluster1-shadow*. - message RequestMirrorPolicy { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteAction.RequestMirrorPolicy"; - - reserved 2; - - reserved "runtime_key"; - - // Specifies the cluster that requests will be mirrored to. The cluster must - // exist in the cluster manager configuration. - string cluster = 1 [(validate.rules).string = {min_bytes: 1}]; - - // If both :ref:`runtime_key - // ` and this - // field are not specified, all requests to the target cluster will be mirrored. - // - // If specified, this field takes precedence over the `runtime_key` field and requests must also - // fall under the percentage of matches indicated by this field. - // - // For some fraction N/D, a random number in the range [0,D) is selected. If the - // number is <= the value of the numerator N, or if the key is not present, the default - // value, the request will be mirrored. - core.v3alpha.RuntimeFractionalPercent runtime_fraction = 3; - } - - // Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer - // `. - // [#next-free-field: 6] - message HashPolicy { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteAction.HashPolicy"; - - message Header { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteAction.HashPolicy.Header"; - - // The name of the request header that will be used to obtain the hash - // key. If the request header is not present, no hash will be produced. - string header_name = 1 [(validate.rules).string = {min_bytes: 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. The cookie is generated by hashing the source and - // destination ports and addresses so that multiple independent HTTP2 - // streams on the same connection will independently receive the same - // cookie, even if they arrive at the Envoy simultaneously. - message Cookie { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteAction.HashPolicy.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, no hash will be - // produced. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // If specified, a cookie with the TTL will be generated if the cookie is - // not present. If the TTL is present and zero, the generated cookie will - // be a session cookie. - google.protobuf.Duration ttl = 2; - - // The name of the path for the cookie. If no path is specified here, no path - // will be set for the cookie. - string path = 3; - } - - message ConnectionProperties { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteAction.HashPolicy.ConnectionProperties"; - - // Hash on source IP address. - bool source_ip = 1; - } - - message QueryParameter { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteAction.HashPolicy.QueryParameter"; - - // The name of the URL query parameter that will be used to obtain the hash - // key. If the parameter is not present, no hash will be produced. Query - // parameter names are case-sensitive. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - } - - oneof policy_specifier { - option (validate.required) = true; - - // Header hash policy. - Header header = 1; - - // Cookie hash policy. - Cookie cookie = 2; - - // Connection properties hash policy. - ConnectionProperties connection_properties = 3; - - // Query parameter hash policy. - QueryParameter query_parameter = 5; - } - - // The flag that short-circuits the hash computing. This field provides a - // 'fallback' style of configuration: "if a terminal policy doesn't work, - // fallback to rest of the policy list", it saves time when the terminal - // policy works. - // - // If true, and there is already a hash computed, ignore rest of the - // list of hash polices. - // For example, if the following hash methods are configured: - // - // ========= ======== - // specifier terminal - // ========= ======== - // Header A true - // Header B false - // Header C false - // ========= ======== - // - // The generateHash process ends if policy "header A" generates a hash, as - // it's a terminal policy. - bool terminal = 4; - } - - // Allows enabling and disabling upgrades on a per-route basis. - // This overrides any enabled/disabled upgrade filter chain specified in the - // HttpConnectionManager - // :ref:`upgrade_configs - // ` - // but does not affect any custom filter chain specified there. - message UpgradeConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RouteAction.UpgradeConfig"; - - // The case-insensitive name of this upgrade, e.g. "websocket". - // For each upgrade type present in upgrade_configs, requests with - // Upgrade: [upgrade_type] will be proxied upstream. - string upgrade_type = 1; - - // Determines if upgrades are available on this route. Defaults to true. - google.protobuf.BoolValue enabled = 2; - } - - reserved 12, 18, 19, 16, 22, 21, 10; - - reserved "request_mirror_policy"; - - oneof cluster_specifier { - option (validate.required) = true; - - // Indicates the upstream cluster to which the request should be routed - // to. - string cluster = 1 [(validate.rules).string = {min_bytes: 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. - // - // .. attention:: - // - // Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 - // *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead. - string cluster_header = 2 [(validate.rules).string = {min_bytes: 1}]; - - // 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 - // :ref:`traffic splitting ` - // for additional documentation. - WeightedCluster weighted_clusters = 3; - } - - // The HTTP status code to use when configured cluster is not found. - // The default response code is 503 Service Unavailable. - ClusterNotFoundResponseCode cluster_not_found_response_code = 20 - [(validate.rules).enum = {defined_only: true}]; - - // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints - // in the upstream cluster with metadata matching what's set in this field will be considered - // for load balancing. If using :ref:`weighted_clusters - // `, metadata will be merged, - // with values provided there taking precedence. The filter name should be specified as - // *envoy.lb*. - core.v3alpha.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. The router filter will - // place the original path before rewrite into the :ref:`x-envoy-original-path - // ` header. - // - // .. attention:: - // - // Pay careful attention to the use of trailing slashes in the - // :ref:`route's match ` prefix value. - // Stripping a prefix from a path requires multiple Routes to handle all cases. For example, - // rewriting */prefix* to */* and */prefix/etc* to */etc* cannot be done in a single - // :ref:`Route `, as shown by the below config - // entries: - // - // .. code-block:: yaml - // - // - match: - // prefix: "/prefix/" - // route: - // prefix_rewrite: "/" - // - match: - // prefix: "/prefix" - // route: - // prefix_rewrite: "/" - // - // Having above entries in the config, requests to */prefix* will be stripped to */*, while - // requests to */prefix/etc* will be stripped to */etc*. - string prefix_rewrite = 5; - - oneof host_rewrite_specifier { - // Indicates that during forwarding, the host header will be swapped with - // this value. - string host_rewrite_literal = 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; - - // Indicates that during forwarding, the host header will be swapped with the content of given - // downstream or :ref:`custom ` header. - // If header value is empty, host header is left intact. - // - // .. attention:: - // - // Pay attention to the potential security implications of using this option. Provided header - // must come from trusted source. - string host_rewrite_header = 29; - } - - // Specifies the upstream timeout for the route. If not specified, the default is 15s. This - // spans between the point at which the entire downstream request (i.e. end-of-stream) has been - // processed and when the upstream response has been completely processed. A value of 0 will - // disable the route's timeout. - // - // .. note:: - // - // This timeout includes all retries. See also - // :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`, - // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the - // :ref:`retry overview `. - google.protobuf.Duration timeout = 8; - - // Specifies the idle timeout for the route. If not specified, there is no per-route idle timeout, - // although the connection manager wide :ref:`stream_idle_timeout - // ` - // will still apply. A value of 0 will completely disable the route's idle timeout, even if a - // connection manager stream idle timeout is configured. - // - // The idle timeout is distinct to :ref:`timeout - // `, which provides an upper bound - // on the upstream response time; :ref:`idle_timeout - // ` instead bounds the amount - // of time the request's stream may be idle. - // - // After header decoding, the idle timeout will apply on downstream and - // upstream request events. Each time an encode/decode event for headers or - // data is processed for the stream, the timer will be reset. If the timeout - // fires, the stream is terminated with a 408 Request Timeout error code if no - // upstream response header has been received, otherwise a stream reset - // occurs. - google.protobuf.Duration idle_timeout = 24; - - // Indicates that the route has a retry policy. Note that if this is set, - // it'll take precedence over the virtual host level retry policy entirely - // (e.g.: policies are not merged, most internal one becomes the enforced policy). - RetryPolicy retry_policy = 9; - - // Indicates that the route has request mirroring policies. - repeated RequestMirrorPolicy request_mirror_policies = 30; - - // Optionally specifies the :ref:`routing priority `. - core.v3alpha.RoutingPriority priority = 11 [(validate.rules).enum = {defined_only: true}]; - - // 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 - // :ref:`rate_limits ` are not - // applied to the request. - google.protobuf.BoolValue include_vh_rate_limits = 14; - - // Specifies a list of hash policies to use for ring hash load balancing. Each - // hash policy is evaluated individually and the combined result is used to - // route the request. The method of combination is deterministic such that - // identical lists of hash policies will produce the same hash. Since a hash - // policy examines specific parts of a request, it can fail to produce a hash - // (i.e. if the hashed header is not present). If (and only if) all configured - // hash policies fail to generate a hash, no hash will be produced for - // the route. In this case, the behavior is the same as if no hash policies - // were specified (i.e. the ring hash load balancer will choose a random - // backend). If a hash policy has the "terminal" attribute set to true, and - // there is already a hash generated, the hash is returned immediately, - // ignoring the rest of the hash policy list. - repeated HashPolicy hash_policy = 15; - - // Indicates that the route has a CORS policy. - CorsPolicy cors = 17; - - // If present, and the request is a gRPC request, use the - // `grpc-timeout header `_, - // or its default value (infinity) instead of - // :ref:`timeout `, but limit the - // applied timeout to the maximum value specified here. If configured as 0, the maximum allowed - // timeout for gRPC requests is infinity. If not configured at all, the `grpc-timeout` header is - // not used and gRPC requests time out like any other requests using :ref:`timeout - // ` or its default. This can be used to - // prevent unexpected upstream request timeouts due to potentially long time gaps between gRPC - // request and response in gRPC streaming mode. - google.protobuf.Duration max_grpc_timeout = 23; - - // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by subtracting - // the provided duration from the header. This is useful in allowing Envoy to set its global - // timeout to be less than that of the deadline imposed by the calling client, which makes it more - // likely that Envoy will handle the timeout instead of having the call canceled by the client. - // The offset will only be applied if the provided grpc_timeout is greater than the offset. This - // ensures that the offset will only ever decrease the timeout and never set it to 0 (meaning - // infinity). - google.protobuf.Duration grpc_timeout_offset = 28; - - repeated UpgradeConfig upgrade_configs = 25; - - InternalRedirectAction internal_redirect_action = 26; - - // Indicates that the route has a hedge policy. Note that if this is set, - // it'll take precedence over the virtual host level hedge policy entirely - // (e.g.: policies are not merged, most internal one becomes the enforced policy). - HedgePolicy hedge_policy = 27; -} - -// HTTP retry :ref:`architecture overview `. -// [#next-free-field: 11] -message RetryPolicy { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RetryPolicy"; - - message RetryPriority { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RetryPolicy.RetryPriority"; - - reserved 2; - - reserved "config"; - - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - oneof config_type { - google.protobuf.Any typed_config = 3; - } - } - - message RetryHostPredicate { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RetryPolicy.RetryHostPredicate"; - - reserved 2; - - reserved "config"; - - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - oneof config_type { - google.protobuf.Any typed_config = 3; - } - } - - message RetryBackOff { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RetryPolicy.RetryBackOff"; - - // Specifies the base interval between retries. This parameter is required and must be greater - // than zero. Values less than 1 ms are rounded up to 1 ms. - // See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion of Envoy's - // back-off algorithm. - google.protobuf.Duration base_interval = 1 [(validate.rules).duration = { - required: true - gt {} - }]; - - // Specifies the maximum interval between retries. This parameter is optional, but must be - // greater than or equal to the `base_interval` if set. The default is 10 times the - // `base_interval`. See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion - // of Envoy's back-off algorithm. - google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}]; - } - - // Specifies the conditions under which retry takes place. These are the same - // conditions documented for :ref:`config_http_filters_router_x-envoy-retry-on` and - // :ref:`config_http_filters_router_x-envoy-retry-grpc-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 - // :ref:`config_http_filters_router_x-envoy-max-retries`. - google.protobuf.UInt32Value num_retries = 2; - - // Specifies a non-zero upstream timeout per retry attempt. This parameter is optional. The - // same conditions documented for - // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms` apply. - // - // .. note:: - // - // If left unspecified, Envoy will use the global - // :ref:`route timeout ` for the - // request. Consequently, when using a :ref:`5xx ` - // based retry policy, a request that times out will not be retried as the total timeout budget - // would have been exhausted. - google.protobuf.Duration per_try_timeout = 3; - - // Specifies an implementation of a RetryPriority which is used to determine the - // distribution of load across priorities used for retries. Refer to - // :ref:`retry plugin configuration ` for more details. - RetryPriority retry_priority = 4; - - // Specifies a collection of RetryHostPredicates that will be consulted when selecting a host - // for retries. If any of the predicates reject the host, host selection will be reattempted. - // Refer to :ref:`retry plugin configuration ` for more - // details. - repeated RetryHostPredicate retry_host_predicate = 5; - - // The maximum number of times host selection will be reattempted before giving up, at which - // point the host that was last selected will be routed to. If unspecified, this will default to - // retrying once. - int64 host_selection_retry_max_attempts = 6; - - // HTTP status codes that should trigger a retry in addition to those specified by retry_on. - repeated uint32 retriable_status_codes = 7; - - // Specifies parameters that control retry back off. This parameter is optional, in which case the - // default base interval is 25 milliseconds or, if set, the current value of the - // `upstream.base_retry_backoff_ms` runtime parameter. The default maximum interval is 10 times - // the base interval. The documentation for :ref:`config_http_filters_router_x-envoy-max-retries` - // describes Envoy's back-off algorithm. - RetryBackOff retry_back_off = 8; - - // HTTP response headers that trigger a retry if present in the response. A retry will be - // triggered if any of the header matches match the upstream response headers. - // The field is only consulted if 'retriable-headers' retry policy is active. - repeated HeaderMatcher retriable_headers = 9; - - // HTTP headers which must be present in the request for retries to be attempted. - repeated HeaderMatcher retriable_request_headers = 10; -} - -// HTTP request hedging :ref:`architecture overview `. -message HedgePolicy { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.HedgePolicy"; - - // Specifies the number of initial requests that should be sent upstream. - // Must be at least 1. - // Defaults to 1. - // [#not-implemented-hide:] - google.protobuf.UInt32Value initial_requests = 1 [(validate.rules).uint32 = {gte: 1}]; - - // Specifies a probability that an additional upstream request should be sent - // on top of what is specified by initial_requests. - // Defaults to 0. - // [#not-implemented-hide:] - type.v3alpha.FractionalPercent additional_request_chance = 2; - - // Indicates that a hedged request should be sent when the per-try timeout - // is hit. This will only occur if the retry policy also indicates that a - // timed out request should be retried. - // Once a timed out request is retried due to per try timeout, the router - // filter will ensure that it is not retried again even if the returned - // response headers would otherwise be retried according the specified - // :ref:`RetryPolicy `. - // Defaults to false. - bool hedge_on_per_try_timeout = 3; -} - -// [#next-free-field: 9] -message RedirectAction { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RedirectAction"; - - enum RedirectResponseCode { - // Moved Permanently HTTP Status Code - 301. - MOVED_PERMANENTLY = 0; - - // Found HTTP Status Code - 302. - FOUND = 1; - - // See Other HTTP Status Code - 303. - SEE_OTHER = 2; - - // Temporary Redirect HTTP Status Code - 307. - TEMPORARY_REDIRECT = 3; - - // Permanent Redirect HTTP Status Code - 308. - PERMANENT_REDIRECT = 4; - } - - // When the scheme redirection take place, the following rules apply: - // 1. If the source URI scheme is `http` and the port is explicitly - // set to `:80`, the port will be removed after the redirection - // 2. If the source URI scheme is `https` and the port is explicitly - // set to `:443`, the port will be removed after the redirection - oneof scheme_rewrite_specifier { - // The scheme portion of the URL will be swapped with "https". - bool https_redirect = 4; - - // The scheme portion of the URL will be swapped with this value. - string scheme_redirect = 7; - } - - // The host portion of the URL will be swapped with this value. - string host_redirect = 1; - - // The port value of the URL will be swapped with this value. - uint32 port_redirect = 8; - - oneof path_rewrite_specifier { - // The path portion of the URL will be swapped with this value. - string path_redirect = 2; - - // Indicates that during redirection, the matched prefix (or path) - // should be swapped with this value. This option allows redirect URLs be dynamically created - // based on the request. - // - // .. attention:: - // - // Pay attention to the use of trailing slashes as mentioned in - // :ref:`RouteAction's prefix_rewrite - // `. - string prefix_rewrite = 5; - } - - // The HTTP status code to use in the redirect response. The default response - // code is MOVED_PERMANENTLY (301). - RedirectResponseCode response_code = 3 [(validate.rules).enum = {defined_only: true}]; - - // Indicates that during redirection, the query portion of the URL will - // be removed. Default value is false. - bool strip_query = 6; -} - -message DirectResponseAction { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.DirectResponseAction"; - - // Specifies the HTTP response status to be returned. - uint32 status = 1 [(validate.rules).uint32 = {lt: 600 gte: 100}]; - - // Specifies the content of the response body. If this setting is omitted, - // no body is included in the generated response. - // - // .. note:: - // - // Headers can be specified using *response_headers_to_add* in the enclosing - // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_RouteConfiguration` or - // :ref:`envoy_api_msg_route.VirtualHost`. - core.v3alpha.DataSource body = 2; -} - -message Decorator { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Decorator"; - - // The operation name associated with the request matched to this route. If tracing is - // enabled, this information will be used as the span name reported for this request. - // - // .. note:: - // - // For ingress (inbound) requests, or egress (outbound) responses, this value may be overridden - // by the :ref:`x-envoy-decorator-operation - // ` header. - string operation = 1 [(validate.rules).string = {min_bytes: 1}]; -} - -message Tracing { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Tracing"; - - // Target percentage of requests managed by this HTTP connection manager that will be force - // traced if the :ref:`x-client-trace-id ` - // header is set. This field is a direct analog for the runtime variable - // 'tracing.client_sampling' in the :ref:`HTTP Connection Manager - // `. - // Default: 100% - type.v3alpha.FractionalPercent client_sampling = 1; - - // Target percentage of requests managed by this HTTP connection manager that will be randomly - // selected for trace generation, if not requested by the client or not forced. This field is - // a direct analog for the runtime variable 'tracing.random_sampling' in the - // :ref:`HTTP Connection Manager `. - // Default: 100% - type.v3alpha.FractionalPercent random_sampling = 2; - - // Target percentage of requests managed by this HTTP connection manager that will be traced - // after all other sampling checks have been applied (client-directed, force tracing, random - // sampling). This field functions as an upper limit on the total configured sampling rate. For - // instance, setting client_sampling to 100% but overall_sampling to 1% will result in only 1% - // of client requests with the appropriate headers to be force traced. This field is a direct - // analog for the runtime variable 'tracing.global_enabled' in the - // :ref:`HTTP Connection Manager `. - // Default: 100% - type.v3alpha.FractionalPercent overall_sampling = 3; - - // A list of custom tags with unique tag name to create tags for the active span. - // It will take effect after merging with the :ref:`corresponding configuration - // ` - // configured in the HTTP connection manager. If two tags with the same name are configured - // each in the HTTP connection manager and the route level, the one configured here takes - // priority. - repeated type.tracing.v2.CustomTag custom_tags = 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. -// -// Documentation for :ref:`virtual cluster statistics `. -// -// .. note:: -// -// Virtual clusters are a useful tool, but we do not recommend setting up a virtual cluster for -// every application endpoint. This is both not easily maintainable and as well the matching and -// statistics output are not free. -message VirtualCluster { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.VirtualCluster"; - - reserved 1, 3; - - reserved "pattern", "method"; - - // Specifies a list of header matchers to use for matching requests. Each specified header must - // match. The pseudo-headers `:path` and `:method` can be used to match the request path and - // method, respectively. - repeated HeaderMatcher headers = 4; - - // Specifies the name of the virtual cluster. The virtual cluster name as well - // as the virtual host name are used when emitting statistics. The statistics are emitted by the - // router filter and are documented :ref:`here `. - string name = 2 [(validate.rules).string = {min_bytes: 1}]; -} - -// Global rate limiting :ref:`architecture overview `. -message RateLimit { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit"; - - // [#next-free-field: 7] - message Action { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RateLimit.Action"; - - // The following descriptor entry is appended to the descriptor: - // - // .. code-block:: cpp - // - // ("source_cluster", "") - // - // is derived from the :option:`--service-cluster` option. - message SourceCluster { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RateLimit.Action.SourceCluster"; - } - - // The following descriptor entry is appended to the descriptor: - // - // .. code-block:: cpp - // - // ("destination_cluster", "") - // - // Once a request matches against a route table rule, a routed cluster is determined by one of - // the following :ref:`route table configuration - // ` settings: - // - // * :ref:`cluster ` indicates the - // upstream cluster - // to route to. - // * :ref:`weighted_clusters - // ` - // chooses a cluster randomly from a set of clusters with attributed weight. - // * :ref:`cluster_header ` - // indicates which - // header in the request contains the target cluster. - message DestinationCluster { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RateLimit.Action.DestinationCluster"; - } - - // The following descriptor entry is appended when a header contains a key that matches the - // *header_name*: - // - // .. code-block:: cpp - // - // ("", "") - message RequestHeaders { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RateLimit.Action.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 [(validate.rules).string = {min_bytes: 1}]; - - // The key to use in the descriptor entry. - string descriptor_key = 2 [(validate.rules).string = {min_bytes: 1}]; - } - - // The following descriptor entry is appended to the descriptor and is populated using the - // trusted address from :ref:`x-forwarded-for `: - // - // .. code-block:: cpp - // - // ("remote_address", "") - message RemoteAddress { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RateLimit.Action.RemoteAddress"; - } - - // The following descriptor entry is appended to the descriptor: - // - // .. code-block:: cpp - // - // ("generic_key", "") - message GenericKey { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RateLimit.Action.GenericKey"; - - // The value to use in the descriptor entry. - string descriptor_value = 1 [(validate.rules).string = {min_bytes: 1}]; - } - - // The following descriptor entry is appended to the descriptor: - // - // .. code-block:: cpp - // - // ("header_match", "") - message HeaderValueMatch { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.RateLimit.Action.HeaderValueMatch"; - - // The value to use in the descriptor entry. - string descriptor_value = 1 [(validate.rules).string = {min_bytes: 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 [(validate.rules).repeated = {min_items: 1}]; - } - - oneof action_specifier { - option (validate.required) = true; - - // Rate limit on source cluster. - SourceCluster source_cluster = 1; - - // Rate limit on destination cluster. - DestinationCluster destination_cluster = 2; - - // Rate limit on request headers. - RequestHeaders request_headers = 3; - - // Rate limit on remote address. - RemoteAddress remote_address = 4; - - // Rate limit on a generic key. - GenericKey generic_key = 5; - - // Rate limit on the existence of request headers. - HeaderValueMatch header_value_match = 6; - } - } - - // 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 [(validate.rules).uint32 = {lte: 10}]; - - // The key to be set in runtime to disable this rate limit configuration. - string disable_key = 2; - - // 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 :ref:`composing actions - // ` for additional documentation. - repeated Action actions = 3 [(validate.rules).repeated = {min_items: 1}]; -} - -// .. attention:: -// -// Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host* -// header. Thus, if attempting to match on *Host*, match on *:authority* instead. -// -// .. attention:: -// -// To route on HTTP method, use the special HTTP/2 *:method* header. This works for both -// HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g., -// -// .. code-block:: json -// -// { -// "name": ":method", -// "exact_match": "POST" -// } -// -// .. attention:: -// In the absence of any header match specifier, match will default to :ref:`present_match -// `. i.e, a request that has -// the :ref:`name ` header will match, -// regardless of the header's value. -// -// [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.] -// [#next-free-field: 12] -message HeaderMatcher { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.HeaderMatcher"; - - reserved 2, 3, 5; - - reserved "regex_match"; - - // Specifies the name of the header in the request. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // Specifies how the header match will be performed to route the request. - oneof header_match_specifier { - // If specified, header match will be performed based on the value of the header. - string exact_match = 4; - - // If specified, this regex string is a regular expression rule which implies the entire request - // header value must match the regex. The rule will not match if only a subsequence of the - // request header value matches the regex. - type.matcher.v3alpha.RegexMatcher safe_regex_match = 11; - - // If specified, header match will be performed based on range. - // The rule will match if the request header value is within this range. - // The entire request header value must represent an integer in base 10 notation: consisting of - // an optional plus or minus sign followed by a sequence of digits. The rule will not match if - // the header value does not represent an integer. Match will fail for empty values, floating - // point numbers or if only a subsequence of the header value is an integer. - // - // Examples: - // - // * For range [-10,0), route will match for header value -1, but not for 0, "somestring", 10.9, - // "-1somestring" - type.v3alpha.Int64Range range_match = 6; - - // If specified, header match will be performed based on whether the header is in the - // request. - bool present_match = 7; - - // If specified, header match will be performed based on the prefix of the header value. - // Note: empty prefix is not allowed, please use present_match instead. - // - // Examples: - // - // * The prefix *abcd* matches the value *abcdxyz*, but not for *abcxyz*. - string prefix_match = 9 [(validate.rules).string = {min_bytes: 1}]; - - // If specified, header match will be performed based on the suffix of the header value. - // Note: empty suffix is not allowed, please use present_match instead. - // - // Examples: - // - // * The suffix *abcd* matches the value *xyzabcd*, but not for *xyzbcd*. - string suffix_match = 10 [(validate.rules).string = {min_bytes: 1}]; - } - - // If specified, the match result will be inverted before checking. Defaults to false. - // - // Examples: - // - // * The regex ``\d{3}`` does not match the value *1234*, so it will match when inverted. - // * The range [-10,0) will match the value -1, so it will not match when inverted. - bool invert_match = 8; -} - -// Query parameter matching treats the query string of a request's :path header -// as an ampersand-separated list of keys and/or key=value elements. -// [#next-free-field: 7] -message QueryParameterMatcher { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.route.QueryParameterMatcher"; - - reserved 3, 4; - - reserved "value", "regex"; - - // Specifies the name of a key that must be present in the requested - // *path*'s query string. - string name = 1 [(validate.rules).string = {min_bytes: 1 max_bytes: 1024}]; - - oneof query_parameter_match_specifier { - // Specifies whether a query parameter value should match against a string. - type.matcher.v3alpha.StringMatcher string_match = 5 - [(validate.rules).message = {required: true}]; - - // Specifies whether a query parameter should be present. - bool present_match = 6; - } + // routed by the HTTP connection manager. + repeated string request_headers_to_remove = 8; + + // By default, headers that should be added/removed are evaluated from most to least specific: + // + // * route level + // * virtual host level + // * connection manager level + // + // To allow setting overrides at the route or virtual host level, this order can be reversed + // by setting this option to true. Defaults to false. + // + // [#next-major-version: In the v3 API, this will default to true.] + bool most_specific_header_mutations_wins = 10; + + // 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 :ref:`route_config + // ` + // option. This setting default to false if the route table is loaded dynamically via the + // :ref:`rds + // ` + // option. Users may wish to override the default behavior in certain cases (for example when + // using CDS with a static route table). + google.protobuf.BoolValue validate_clusters = 7; +} + +message Vhds { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Vhds"; + + // Configuration source specifier for VHDS. + core.v3alpha.ConfigSource config_source = 1 [(validate.rules).message = {required: true}]; } diff --git a/envoy/config/route/v3alpha/route_components.proto b/envoy/config/route/v3alpha/route_components.proto new file mode 100644 index 00000000..a597f04e --- /dev/null +++ b/envoy/config/route/v3alpha/route_components.proto @@ -0,0 +1,1440 @@ +syntax = "proto3"; + +package envoy.config.route.v3alpha; + +import "envoy/config/core/v3alpha/base.proto"; +import "envoy/type/matcher/v3alpha/regex.proto"; +import "envoy/type/matcher/v3alpha/string.proto"; +import "envoy/type/tracing/v2/custom_tag.proto"; +import "envoy/type/v3alpha/percent.proto"; +import "envoy/type/v3alpha/range.proto"; + +import "google/protobuf/any.proto"; +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/wrappers.proto"; + +import "udpa/annotations/versioning.proto"; + +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.config.route.v3alpha"; +option java_outer_classname = "RouteComponentsProto"; +option java_multiple_files = true; + +// [#protodoc-title: HTTP route components] +// * Routing :ref:`architecture overview ` +// * HTTP :ref:`router filter ` + +// The top level element in the routing configuration is a virtual host. Each virtual host has +// a logical name as well as a set of domains that get routed to it based on the incoming request's +// host header. This allows a single listener to service multiple top level domain path trees. Once +// a virtual host is selected based on the domain, the routes are processed in order to see which +// upstream cluster to route to or whether to perform a redirect. +// [#next-free-field: 19] +message VirtualHost { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.VirtualHost"; + + 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 301 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 301 redirect + // will be sent telling the client to use HTTPS. + ALL = 2; + } + + reserved 9, 12; + + reserved "per_filter_config"; + + // The logical name of the virtual host. This is used when emitting certain + // statistics but is not relevant for routing. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // A list of domains (host/authority header) that will be matched to this + // virtual host. Wildcard hosts are supported in the suffix or prefix form. + // + // Domain search order: + // 1. Exact domain names: ``www.foo.com``. + // 2. Suffix domain wildcards: ``*.foo.com`` or ``*-bar.foo.com``. + // 3. Prefix domain wildcards: ``foo.*`` or ``foo-*``. + // 4. Special wildcard ``*`` matching any domain. + // + // .. note:: + // + // The wildcard will not match the empty string. + // e.g. ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``. + // The longest wildcards match first. + // 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 [(validate.rules).repeated = {min_items: 1}]; + + // 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; + + // Specifies the type of TLS enforcement the virtual host expects. If this option is not + // specified, there is no TLS requirement for the virtual host. + 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. Headers specified at this level are applied + // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the + // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // details on header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.v3alpha.HeaderValueOption request_headers_to_add = 7 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each request + // handled by this virtual host. + repeated string request_headers_to_remove = 13; + + // Specifies a list of HTTP headers that should be added to each response + // handled by this virtual host. Headers specified at this level are applied + // after headers from enclosed :ref:`envoy_api_msg_route.Route` and before headers from the + // enclosing :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // details on header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.v3alpha.HeaderValueOption response_headers_to_add = 10 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each response + // handled by this virtual host. + repeated string response_headers_to_remove = 11; + + // Indicates that the virtual host has a CORS policy. + CorsPolicy cors = 8; + + // The per_filter_config field can be used to provide virtual host-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` + // for if and how it is utilized. + map typed_per_filter_config = 15; + + // Decides whether the :ref:`x-envoy-attempt-count + // ` header should be included + // in the upstream request. Setting this option will cause it to override any existing header + // value, so in the case of two Envoys on the request path with this option enabled, the upstream + // will see the attempt count as perceived by the second Envoy. Defaults to false. + // This header is unaffected by the + // :ref:`suppress_envoy_headers + // ` flag. + bool include_request_attempt_count = 14; + + // Indicates the retry policy for all routes in this virtual host. Note that setting a + // route level entry will take precedence over this config and it'll be treated + // independently (e.g.: values are not inherited). + RetryPolicy retry_policy = 16; + + // Indicates the hedge policy for all routes in this virtual host. Note that setting a + // route level entry will take precedence over this config and it'll be treated + // independently (e.g.: values are not inherited). + HedgePolicy hedge_policy = 17; + + // The maximum bytes which will be buffered for retries and shadowing. + // If set and a route-specific limit is not set, the bytes actually buffered will be the minimum + // value of this and the listener per_connection_buffer_limit_bytes. + google.protobuf.UInt32Value per_request_buffer_limit_bytes = 18; +} + +// A filter-defined action type. +message FilterAction { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.FilterAction"; + + google.protobuf.Any action = 1; +} + +// A route is both a specification of how to match a request as well as an indication of what to do +// next (e.g., redirect, forward, rewrite, etc.). +// +// .. attention:: +// +// Envoy supports routing on HTTP method via :ref:`header matching +// `. +// [#next-free-field: 18] +message Route { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Route"; + + reserved 6, 8; + + reserved "per_filter_config"; + + // Name for the route. + string name = 14; + + // Route matching parameters. + RouteMatch match = 1 [(validate.rules).message = {required: true}]; + + oneof action { + option (validate.required) = true; + + // Route request to some upstream cluster. + RouteAction route = 2; + + // Return a redirect. + RedirectAction redirect = 3; + + // Return an arbitrary HTTP response directly, without proxying. + DirectResponseAction direct_response = 7; + + // [#not-implemented-hide:] + // If true, a filter will define the action (e.g., it could dynamically generate the + // RouteAction). + FilterAction filter_action = 17; + } + + // The Metadata field can be used to provide additional information + // about the route. It can be used for configuration, stats, and logging. + // The metadata should go under the filter namespace that will need it. + // For instance, if the metadata is intended for the Router filter, + // the filter name should be specified as *envoy.router*. + core.v3alpha.Metadata metadata = 4; + + // Decorator for the matched route. + Decorator decorator = 5; + + // The per_filter_config field can be used to provide route-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` for + // if and how it is utilized. + map typed_per_filter_config = 13; + + // Specifies a set of headers that will be added to requests matching this + // route. Headers specified at this level are applied before headers from the + // enclosing :ref:`envoy_api_msg_route.VirtualHost` and + // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.v3alpha.HeaderValueOption request_headers_to_add = 9 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each request + // matching this route. + repeated string request_headers_to_remove = 12; + + // Specifies a set of headers that will be added to responses to requests + // matching this route. Headers specified at this level are applied before + // headers from the enclosing :ref:`envoy_api_msg_route.VirtualHost` and + // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including + // details on header value syntax, see the documentation on + // :ref:`custom request headers `. + repeated core.v3alpha.HeaderValueOption response_headers_to_add = 10 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each response + // to requests matching this route. + repeated string response_headers_to_remove = 11; + + // Presence of the object defines whether the connection manager's tracing configuration + // is overridden by this route specific instance. + Tracing tracing = 15; + + // The maximum bytes which will be buffered for retries and shadowing. + // If set, the bytes actually buffered will be the minimum value of this and the + // listener per_connection_buffer_limit_bytes. + google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16; +} + +// Compared to the :ref:`cluster ` field +// that specifies a single upstream cluster as the target of a request, the :ref:`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 { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.WeightedCluster"; + + // [#next-free-field: 11] + message ClusterWeight { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.WeightedCluster.ClusterWeight"; + + reserved 7, 8; + + reserved "per_filter_config"; + + // Name of the upstream cluster. The cluster must exist in the + // :ref:`cluster manager configuration `. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // An integer between 0 and :ref:`total_weight + // `. 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 the total_weight, which defaults to + // 100. + google.protobuf.UInt32Value weight = 2; + + // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in + // the upstream cluster with metadata matching what is set in this field will be considered for + // load balancing. Note that this will be merged with what's provided in + // :ref:`RouteAction.metadata_match + // `, with values here taking + // precedence. The filter name should be specified as *envoy.lb*. + core.v3alpha.Metadata metadata_match = 3; + + // Specifies a list of headers to be added to requests when this cluster is selected + // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + // Headers specified at this level are applied before headers from the enclosing + // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and + // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.v3alpha.HeaderValueOption request_headers_to_add = 4 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of HTTP headers that should be removed from each request when + // this cluster is selected through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + repeated string request_headers_to_remove = 9; + + // Specifies a list of headers to be added to responses when this cluster is selected + // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + // Headers specified at this level are applied before headers from the enclosing + // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_route.VirtualHost`, and + // :ref:`envoy_api_msg_RouteConfiguration`. For more information, including details on + // header value syntax, see the documentation on :ref:`custom request headers + // `. + repeated core.v3alpha.HeaderValueOption response_headers_to_add = 5 + [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a list of headers to be removed from responses when this cluster is selected + // through the enclosing :ref:`envoy_api_msg_route.RouteAction`. + repeated string response_headers_to_remove = 6; + + // The per_filter_config field can be used to provide weighted cluster-specific + // configurations for filters. The key should match the filter name, such as + // *envoy.buffer* for the HTTP buffer filter. Use of this field is filter + // specific; see the :ref:`HTTP filter documentation ` + // for if and how it is utilized. + map typed_per_filter_config = 10; + } + + // Specifies one or more upstream clusters associated with the route. + repeated ClusterWeight clusters = 1 [(validate.rules).repeated = {min_items: 1}]; + + // Specifies the total weight across all clusters. The sum of all cluster weights must equal this + // value, which must be greater than 0. Defaults to 100. + google.protobuf.UInt32Value total_weight = 3 [(validate.rules).uint32 = {gte: 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 :ref:`runtime documentation + // ` for how key names map to the underlying implementation. + string runtime_key_prefix = 2; +} + +// [#next-free-field: 12] +message RouteMatch { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteMatch"; + + message GrpcRouteMatchOptions { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteMatch.GrpcRouteMatchOptions"; + } + + message TlsContextMatchOptions { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteMatch.TlsContextMatchOptions"; + + // If specified, the route will match against whether or not a certificate is presented. + google.protobuf.BoolValue presented = 1; + } + + reserved 5, 3; + + reserved "regex"; + + oneof path_specifier { + option (validate.required) = true; + + // 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 rule meaning that the + // regex must match the *:path* header once the query string is removed. The entire path + // (without the query string) must match the regex. The rule will not match if only a + // subsequence of the *:path* header matches the regex. + // + // [#next-major-version: In the v3 API we should redo how path specification works such + // that we utilize StringMatcher, and additionally have consistent options around whether we + // strip query strings, do a case sensitive match, etc. In the interim it will be too disruptive + // to deprecate the existing options. We should even consider whether we want to do away with + // path_specifier entirely and just rely on a set of header matchers which can already match + // on :path, etc. The issue with that is it is unclear how to generically deal with query string + // stripping. This needs more thought.] + type.matcher.v3alpha.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}]; + } + + // 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. Every time the route + // is considered for a match, it must also fall under the percentage of matches indicated by + // this field. For some fraction N/D, a random number in the range [0,D) is selected. If the + // number is <= the value of the numerator N, or if the key is not present, the default + // value, the router continues to evaluate the remaining match criteria. A runtime_fraction + // route configuration can be used to roll out route changes in a gradual manner without full + // code/config deploys. Refer to the :ref:`traffic shifting + // ` docs for additional documentation. + // + // .. note:: + // + // Parsing this field is implemented such that the runtime key's data may be represented + // as a FractionalPercent proto represented as JSON/YAML and may also be represented as an + // integer with the assumption that the value is an integral percentage out of 100. For + // instance, a runtime key lookup returning the value "42" would parse as a FractionalPercent + // whose numerator is 42 and denominator is HUNDRED. This preserves legacy semantics. + core.v3alpha.RuntimeFractionalPercent runtime_fraction = 9; + + // 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; + + // Specifies a set of URL query parameters on which the route should + // match. The router will check the query string from the *path* header + // against all the specified query parameters. If the number of specified + // query parameters is nonzero, they all must match the *path* header's + // query string for a match to occur. + repeated QueryParameterMatcher query_parameters = 7; + + // If specified, only gRPC requests will be matched. The router will check + // that the content-type header has a application/grpc or one of the various + // application/grpc+ values. + GrpcRouteMatchOptions grpc = 8; + + // If specified, the client tls context will be matched against the defined + // match options. + // + // [#next-major-version: unify with RBAC] + TlsContextMatchOptions tls_context = 11; +} + +// [#next-free-field: 12] +message CorsPolicy { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.CorsPolicy"; + + reserved 1, 8, 7; + + reserved "allow_origin", "allow_origin_regex", "enabled"; + + // Specifies string patterns that match allowed origins. An origin is allowed if any of the + // string matchers match. + repeated type.matcher.v3alpha.StringMatcher allow_origin_string_match = 11; + + // Specifies the content for the *access-control-allow-methods* header. + string allow_methods = 2; + + // Specifies the content for the *access-control-allow-headers* header. + string allow_headers = 3; + + // Specifies the content for the *access-control-expose-headers* header. + string expose_headers = 4; + + // Specifies the content for the *access-control-max-age* header. + string max_age = 5; + + // Specifies whether the resource allows credentials. + google.protobuf.BoolValue allow_credentials = 6; + + oneof enabled_specifier { + // Specifies the % of requests for which the CORS filter is enabled. + // + // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS + // filter will be enabled for 100% of the requests. + // + // If :ref:`runtime_key ` is + // specified, Envoy will lookup the runtime key to get the percentage of requests to filter. + core.v3alpha.RuntimeFractionalPercent filter_enabled = 9; + } + + // Specifies the % of requests for which the CORS policies will be evaluated and tracked, but not + // enforced. + // + // This field is intended to be used when ``filter_enabled`` and ``enabled`` are off. One of those + // fields have to explicitly disable the filter in order for this setting to take effect. + // + // If :ref:`runtime_key ` is specified, + // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate + // and track the request's *Origin* to determine if it's valid but will not enforce any policies. + core.v3alpha.RuntimeFractionalPercent shadow_enabled = 10; +} + +// [#next-free-field: 31] +message RouteAction { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteAction"; + + enum ClusterNotFoundResponseCode { + // HTTP status code - 503 Service Unavailable. + SERVICE_UNAVAILABLE = 0; + + // HTTP status code - 404 Not Found. + NOT_FOUND = 1; + } + + // Configures :ref:`internal redirect ` behavior. + enum InternalRedirectAction { + PASS_THROUGH_INTERNAL_REDIRECT = 0; + HANDLE_INTERNAL_REDIRECT = 1; + } + + // The router is capable of shadowing traffic from one cluster to another. The current + // implementation is "fire and forget," meaning Envoy will not wait for the shadow cluster to + // respond before returning the response from the primary cluster. All normal statistics are + // collected for the shadow cluster making this feature useful for testing. + // + // During shadowing, the host/authority header is altered such that *-shadow* is appended. This is + // useful for logging. For example, *cluster1* becomes *cluster1-shadow*. + message RequestMirrorPolicy { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteAction.RequestMirrorPolicy"; + + reserved 2; + + reserved "runtime_key"; + + // Specifies the cluster that requests will be mirrored to. The cluster must + // exist in the cluster manager configuration. + string cluster = 1 [(validate.rules).string = {min_bytes: 1}]; + + // If both :ref:`runtime_key + // ` and this + // field are not specified, all requests to the target cluster will be mirrored. + // + // If specified, this field takes precedence over the `runtime_key` field and requests must also + // fall under the percentage of matches indicated by this field. + // + // For some fraction N/D, a random number in the range [0,D) is selected. If the + // number is <= the value of the numerator N, or if the key is not present, the default + // value, the request will be mirrored. + core.v3alpha.RuntimeFractionalPercent runtime_fraction = 3; + } + + // Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer + // `. + // [#next-free-field: 6] + message HashPolicy { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteAction.HashPolicy"; + + message Header { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteAction.HashPolicy.Header"; + + // The name of the request header that will be used to obtain the hash + // key. If the request header is not present, no hash will be produced. + string header_name = 1 [(validate.rules).string = {min_bytes: 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. The cookie is generated by hashing the source and + // destination ports and addresses so that multiple independent HTTP2 + // streams on the same connection will independently receive the same + // cookie, even if they arrive at the Envoy simultaneously. + message Cookie { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteAction.HashPolicy.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, no hash will be + // produced. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // If specified, a cookie with the TTL will be generated if the cookie is + // not present. If the TTL is present and zero, the generated cookie will + // be a session cookie. + google.protobuf.Duration ttl = 2; + + // The name of the path for the cookie. If no path is specified here, no path + // will be set for the cookie. + string path = 3; + } + + message ConnectionProperties { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteAction.HashPolicy.ConnectionProperties"; + + // Hash on source IP address. + bool source_ip = 1; + } + + message QueryParameter { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteAction.HashPolicy.QueryParameter"; + + // The name of the URL query parameter that will be used to obtain the hash + // key. If the parameter is not present, no hash will be produced. Query + // parameter names are case-sensitive. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + } + + oneof policy_specifier { + option (validate.required) = true; + + // Header hash policy. + Header header = 1; + + // Cookie hash policy. + Cookie cookie = 2; + + // Connection properties hash policy. + ConnectionProperties connection_properties = 3; + + // Query parameter hash policy. + QueryParameter query_parameter = 5; + } + + // The flag that short-circuits the hash computing. This field provides a + // 'fallback' style of configuration: "if a terminal policy doesn't work, + // fallback to rest of the policy list", it saves time when the terminal + // policy works. + // + // If true, and there is already a hash computed, ignore rest of the + // list of hash polices. + // For example, if the following hash methods are configured: + // + // ========= ======== + // specifier terminal + // ========= ======== + // Header A true + // Header B false + // Header C false + // ========= ======== + // + // The generateHash process ends if policy "header A" generates a hash, as + // it's a terminal policy. + bool terminal = 4; + } + + // Allows enabling and disabling upgrades on a per-route basis. + // This overrides any enabled/disabled upgrade filter chain specified in the + // HttpConnectionManager + // :ref:`upgrade_configs + // ` + // but does not affect any custom filter chain specified there. + message UpgradeConfig { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RouteAction.UpgradeConfig"; + + // The case-insensitive name of this upgrade, e.g. "websocket". + // For each upgrade type present in upgrade_configs, requests with + // Upgrade: [upgrade_type] will be proxied upstream. + string upgrade_type = 1; + + // Determines if upgrades are available on this route. Defaults to true. + google.protobuf.BoolValue enabled = 2; + } + + reserved 12, 18, 19, 16, 22, 21, 10; + + reserved "request_mirror_policy"; + + oneof cluster_specifier { + option (validate.required) = true; + + // Indicates the upstream cluster to which the request should be routed + // to. + string cluster = 1 [(validate.rules).string = {min_bytes: 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. + // + // .. attention:: + // + // Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 + // *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead. + string cluster_header = 2 [(validate.rules).string = {min_bytes: 1}]; + + // 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 + // :ref:`traffic splitting ` + // for additional documentation. + WeightedCluster weighted_clusters = 3; + } + + // The HTTP status code to use when configured cluster is not found. + // The default response code is 503 Service Unavailable. + ClusterNotFoundResponseCode cluster_not_found_response_code = 20 + [(validate.rules).enum = {defined_only: true}]; + + // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints + // in the upstream cluster with metadata matching what's set in this field will be considered + // for load balancing. If using :ref:`weighted_clusters + // `, metadata will be merged, + // with values provided there taking precedence. The filter name should be specified as + // *envoy.lb*. + core.v3alpha.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. The router filter will + // place the original path before rewrite into the :ref:`x-envoy-original-path + // ` header. + // + // .. attention:: + // + // Pay careful attention to the use of trailing slashes in the + // :ref:`route's match ` prefix value. + // Stripping a prefix from a path requires multiple Routes to handle all cases. For example, + // rewriting */prefix* to */* and */prefix/etc* to */etc* cannot be done in a single + // :ref:`Route `, as shown by the below config + // entries: + // + // .. code-block:: yaml + // + // - match: + // prefix: "/prefix/" + // route: + // prefix_rewrite: "/" + // - match: + // prefix: "/prefix" + // route: + // prefix_rewrite: "/" + // + // Having above entries in the config, requests to */prefix* will be stripped to */*, while + // requests to */prefix/etc* will be stripped to */etc*. + string prefix_rewrite = 5; + + oneof host_rewrite_specifier { + // Indicates that during forwarding, the host header will be swapped with + // this value. + string host_rewrite_literal = 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; + + // Indicates that during forwarding, the host header will be swapped with the content of given + // downstream or :ref:`custom ` header. + // If header value is empty, host header is left intact. + // + // .. attention:: + // + // Pay attention to the potential security implications of using this option. Provided header + // must come from trusted source. + string host_rewrite_header = 29; + } + + // Specifies the upstream timeout for the route. If not specified, the default is 15s. This + // spans between the point at which the entire downstream request (i.e. end-of-stream) has been + // processed and when the upstream response has been completely processed. A value of 0 will + // disable the route's timeout. + // + // .. note:: + // + // This timeout includes all retries. See also + // :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`, + // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the + // :ref:`retry overview `. + google.protobuf.Duration timeout = 8; + + // Specifies the idle timeout for the route. If not specified, there is no per-route idle timeout, + // although the connection manager wide :ref:`stream_idle_timeout + // ` + // will still apply. A value of 0 will completely disable the route's idle timeout, even if a + // connection manager stream idle timeout is configured. + // + // The idle timeout is distinct to :ref:`timeout + // `, which provides an upper bound + // on the upstream response time; :ref:`idle_timeout + // ` instead bounds the amount + // of time the request's stream may be idle. + // + // After header decoding, the idle timeout will apply on downstream and + // upstream request events. Each time an encode/decode event for headers or + // data is processed for the stream, the timer will be reset. If the timeout + // fires, the stream is terminated with a 408 Request Timeout error code if no + // upstream response header has been received, otherwise a stream reset + // occurs. + google.protobuf.Duration idle_timeout = 24; + + // Indicates that the route has a retry policy. Note that if this is set, + // it'll take precedence over the virtual host level retry policy entirely + // (e.g.: policies are not merged, most internal one becomes the enforced policy). + RetryPolicy retry_policy = 9; + + // Indicates that the route has request mirroring policies. + repeated RequestMirrorPolicy request_mirror_policies = 30; + + // Optionally specifies the :ref:`routing priority `. + core.v3alpha.RoutingPriority priority = 11 [(validate.rules).enum = {defined_only: true}]; + + // 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 + // :ref:`rate_limits ` are not + // applied to the request. + google.protobuf.BoolValue include_vh_rate_limits = 14; + + // Specifies a list of hash policies to use for ring hash load balancing. Each + // hash policy is evaluated individually and the combined result is used to + // route the request. The method of combination is deterministic such that + // identical lists of hash policies will produce the same hash. Since a hash + // policy examines specific parts of a request, it can fail to produce a hash + // (i.e. if the hashed header is not present). If (and only if) all configured + // hash policies fail to generate a hash, no hash will be produced for + // the route. In this case, the behavior is the same as if no hash policies + // were specified (i.e. the ring hash load balancer will choose a random + // backend). If a hash policy has the "terminal" attribute set to true, and + // there is already a hash generated, the hash is returned immediately, + // ignoring the rest of the hash policy list. + repeated HashPolicy hash_policy = 15; + + // Indicates that the route has a CORS policy. + CorsPolicy cors = 17; + + // If present, and the request is a gRPC request, use the + // `grpc-timeout header `_, + // or its default value (infinity) instead of + // :ref:`timeout `, but limit the + // applied timeout to the maximum value specified here. If configured as 0, the maximum allowed + // timeout for gRPC requests is infinity. If not configured at all, the `grpc-timeout` header is + // not used and gRPC requests time out like any other requests using :ref:`timeout + // ` or its default. This can be used to + // prevent unexpected upstream request timeouts due to potentially long time gaps between gRPC + // request and response in gRPC streaming mode. + google.protobuf.Duration max_grpc_timeout = 23; + + // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by subtracting + // the provided duration from the header. This is useful in allowing Envoy to set its global + // timeout to be less than that of the deadline imposed by the calling client, which makes it more + // likely that Envoy will handle the timeout instead of having the call canceled by the client. + // The offset will only be applied if the provided grpc_timeout is greater than the offset. This + // ensures that the offset will only ever decrease the timeout and never set it to 0 (meaning + // infinity). + google.protobuf.Duration grpc_timeout_offset = 28; + + repeated UpgradeConfig upgrade_configs = 25; + + InternalRedirectAction internal_redirect_action = 26; + + // Indicates that the route has a hedge policy. Note that if this is set, + // it'll take precedence over the virtual host level hedge policy entirely + // (e.g.: policies are not merged, most internal one becomes the enforced policy). + HedgePolicy hedge_policy = 27; +} + +// HTTP retry :ref:`architecture overview `. +// [#next-free-field: 11] +message RetryPolicy { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RetryPolicy"; + + message RetryPriority { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RetryPolicy.RetryPriority"; + + reserved 2; + + reserved "config"; + + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + oneof config_type { + google.protobuf.Any typed_config = 3; + } + } + + message RetryHostPredicate { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RetryPolicy.RetryHostPredicate"; + + reserved 2; + + reserved "config"; + + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + oneof config_type { + google.protobuf.Any typed_config = 3; + } + } + + message RetryBackOff { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RetryPolicy.RetryBackOff"; + + // Specifies the base interval between retries. This parameter is required and must be greater + // than zero. Values less than 1 ms are rounded up to 1 ms. + // See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion of Envoy's + // back-off algorithm. + google.protobuf.Duration base_interval = 1 [(validate.rules).duration = { + required: true + gt {} + }]; + + // Specifies the maximum interval between retries. This parameter is optional, but must be + // greater than or equal to the `base_interval` if set. The default is 10 times the + // `base_interval`. See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion + // of Envoy's back-off algorithm. + google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}]; + } + + // Specifies the conditions under which retry takes place. These are the same + // conditions documented for :ref:`config_http_filters_router_x-envoy-retry-on` and + // :ref:`config_http_filters_router_x-envoy-retry-grpc-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 + // :ref:`config_http_filters_router_x-envoy-max-retries`. + google.protobuf.UInt32Value num_retries = 2; + + // Specifies a non-zero upstream timeout per retry attempt. This parameter is optional. The + // same conditions documented for + // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms` apply. + // + // .. note:: + // + // If left unspecified, Envoy will use the global + // :ref:`route timeout ` for the + // request. Consequently, when using a :ref:`5xx ` + // based retry policy, a request that times out will not be retried as the total timeout budget + // would have been exhausted. + google.protobuf.Duration per_try_timeout = 3; + + // Specifies an implementation of a RetryPriority which is used to determine the + // distribution of load across priorities used for retries. Refer to + // :ref:`retry plugin configuration ` for more details. + RetryPriority retry_priority = 4; + + // Specifies a collection of RetryHostPredicates that will be consulted when selecting a host + // for retries. If any of the predicates reject the host, host selection will be reattempted. + // Refer to :ref:`retry plugin configuration ` for more + // details. + repeated RetryHostPredicate retry_host_predicate = 5; + + // The maximum number of times host selection will be reattempted before giving up, at which + // point the host that was last selected will be routed to. If unspecified, this will default to + // retrying once. + int64 host_selection_retry_max_attempts = 6; + + // HTTP status codes that should trigger a retry in addition to those specified by retry_on. + repeated uint32 retriable_status_codes = 7; + + // Specifies parameters that control retry back off. This parameter is optional, in which case the + // default base interval is 25 milliseconds or, if set, the current value of the + // `upstream.base_retry_backoff_ms` runtime parameter. The default maximum interval is 10 times + // the base interval. The documentation for :ref:`config_http_filters_router_x-envoy-max-retries` + // describes Envoy's back-off algorithm. + RetryBackOff retry_back_off = 8; + + // HTTP response headers that trigger a retry if present in the response. A retry will be + // triggered if any of the header matches match the upstream response headers. + // The field is only consulted if 'retriable-headers' retry policy is active. + repeated HeaderMatcher retriable_headers = 9; + + // HTTP headers which must be present in the request for retries to be attempted. + repeated HeaderMatcher retriable_request_headers = 10; +} + +// HTTP request hedging :ref:`architecture overview `. +message HedgePolicy { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.HedgePolicy"; + + // Specifies the number of initial requests that should be sent upstream. + // Must be at least 1. + // Defaults to 1. + // [#not-implemented-hide:] + google.protobuf.UInt32Value initial_requests = 1 [(validate.rules).uint32 = {gte: 1}]; + + // Specifies a probability that an additional upstream request should be sent + // on top of what is specified by initial_requests. + // Defaults to 0. + // [#not-implemented-hide:] + type.v3alpha.FractionalPercent additional_request_chance = 2; + + // Indicates that a hedged request should be sent when the per-try timeout + // is hit. This will only occur if the retry policy also indicates that a + // timed out request should be retried. + // Once a timed out request is retried due to per try timeout, the router + // filter will ensure that it is not retried again even if the returned + // response headers would otherwise be retried according the specified + // :ref:`RetryPolicy `. + // Defaults to false. + bool hedge_on_per_try_timeout = 3; +} + +// [#next-free-field: 9] +message RedirectAction { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RedirectAction"; + + enum RedirectResponseCode { + // Moved Permanently HTTP Status Code - 301. + MOVED_PERMANENTLY = 0; + + // Found HTTP Status Code - 302. + FOUND = 1; + + // See Other HTTP Status Code - 303. + SEE_OTHER = 2; + + // Temporary Redirect HTTP Status Code - 307. + TEMPORARY_REDIRECT = 3; + + // Permanent Redirect HTTP Status Code - 308. + PERMANENT_REDIRECT = 4; + } + + // When the scheme redirection take place, the following rules apply: + // 1. If the source URI scheme is `http` and the port is explicitly + // set to `:80`, the port will be removed after the redirection + // 2. If the source URI scheme is `https` and the port is explicitly + // set to `:443`, the port will be removed after the redirection + oneof scheme_rewrite_specifier { + // The scheme portion of the URL will be swapped with "https". + bool https_redirect = 4; + + // The scheme portion of the URL will be swapped with this value. + string scheme_redirect = 7; + } + + // The host portion of the URL will be swapped with this value. + string host_redirect = 1; + + // The port value of the URL will be swapped with this value. + uint32 port_redirect = 8; + + oneof path_rewrite_specifier { + // The path portion of the URL will be swapped with this value. + string path_redirect = 2; + + // Indicates that during redirection, the matched prefix (or path) + // should be swapped with this value. This option allows redirect URLs be dynamically created + // based on the request. + // + // .. attention:: + // + // Pay attention to the use of trailing slashes as mentioned in + // :ref:`RouteAction's prefix_rewrite + // `. + string prefix_rewrite = 5; + } + + // The HTTP status code to use in the redirect response. The default response + // code is MOVED_PERMANENTLY (301). + RedirectResponseCode response_code = 3 [(validate.rules).enum = {defined_only: true}]; + + // Indicates that during redirection, the query portion of the URL will + // be removed. Default value is false. + bool strip_query = 6; +} + +message DirectResponseAction { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.DirectResponseAction"; + + // Specifies the HTTP response status to be returned. + uint32 status = 1 [(validate.rules).uint32 = {lt: 600 gte: 100}]; + + // Specifies the content of the response body. If this setting is omitted, + // no body is included in the generated response. + // + // .. note:: + // + // Headers can be specified using *response_headers_to_add* in the enclosing + // :ref:`envoy_api_msg_route.Route`, :ref:`envoy_api_msg_RouteConfiguration` or + // :ref:`envoy_api_msg_route.VirtualHost`. + core.v3alpha.DataSource body = 2; +} + +message Decorator { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Decorator"; + + // The operation name associated with the request matched to this route. If tracing is + // enabled, this information will be used as the span name reported for this request. + // + // .. note:: + // + // For ingress (inbound) requests, or egress (outbound) responses, this value may be overridden + // by the :ref:`x-envoy-decorator-operation + // ` header. + string operation = 1 [(validate.rules).string = {min_bytes: 1}]; +} + +message Tracing { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Tracing"; + + // Target percentage of requests managed by this HTTP connection manager that will be force + // traced if the :ref:`x-client-trace-id ` + // header is set. This field is a direct analog for the runtime variable + // 'tracing.client_sampling' in the :ref:`HTTP Connection Manager + // `. + // Default: 100% + type.v3alpha.FractionalPercent client_sampling = 1; + + // Target percentage of requests managed by this HTTP connection manager that will be randomly + // selected for trace generation, if not requested by the client or not forced. This field is + // a direct analog for the runtime variable 'tracing.random_sampling' in the + // :ref:`HTTP Connection Manager `. + // Default: 100% + type.v3alpha.FractionalPercent random_sampling = 2; + + // Target percentage of requests managed by this HTTP connection manager that will be traced + // after all other sampling checks have been applied (client-directed, force tracing, random + // sampling). This field functions as an upper limit on the total configured sampling rate. For + // instance, setting client_sampling to 100% but overall_sampling to 1% will result in only 1% + // of client requests with the appropriate headers to be force traced. This field is a direct + // analog for the runtime variable 'tracing.global_enabled' in the + // :ref:`HTTP Connection Manager `. + // Default: 100% + type.v3alpha.FractionalPercent overall_sampling = 3; + + // A list of custom tags with unique tag name to create tags for the active span. + // It will take effect after merging with the :ref:`corresponding configuration + // ` + // configured in the HTTP connection manager. If two tags with the same name are configured + // each in the HTTP connection manager and the route level, the one configured here takes + // priority. + repeated type.tracing.v2.CustomTag custom_tags = 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. +// +// Documentation for :ref:`virtual cluster statistics `. +// +// .. note:: +// +// Virtual clusters are a useful tool, but we do not recommend setting up a virtual cluster for +// every application endpoint. This is both not easily maintainable and as well the matching and +// statistics output are not free. +message VirtualCluster { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.VirtualCluster"; + + reserved 1, 3; + + reserved "pattern", "method"; + + // Specifies a list of header matchers to use for matching requests. Each specified header must + // match. The pseudo-headers `:path` and `:method` can be used to match the request path and + // method, respectively. + repeated HeaderMatcher headers = 4; + + // Specifies the name of the virtual cluster. The virtual cluster name as well + // as the virtual host name are used when emitting statistics. The statistics are emitted by the + // router filter and are documented :ref:`here `. + string name = 2 [(validate.rules).string = {min_bytes: 1}]; +} + +// Global rate limiting :ref:`architecture overview `. +message RateLimit { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit"; + + // [#next-free-field: 7] + message Action { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RateLimit.Action"; + + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("source_cluster", "") + // + // is derived from the :option:`--service-cluster` option. + message SourceCluster { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RateLimit.Action.SourceCluster"; + } + + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("destination_cluster", "") + // + // Once a request matches against a route table rule, a routed cluster is determined by one of + // the following :ref:`route table configuration + // ` settings: + // + // * :ref:`cluster ` indicates the + // upstream cluster + // to route to. + // * :ref:`weighted_clusters + // ` + // chooses a cluster randomly from a set of clusters with attributed weight. + // * :ref:`cluster_header ` + // indicates which + // header in the request contains the target cluster. + message DestinationCluster { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RateLimit.Action.DestinationCluster"; + } + + // The following descriptor entry is appended when a header contains a key that matches the + // *header_name*: + // + // .. code-block:: cpp + // + // ("", "") + message RequestHeaders { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RateLimit.Action.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 [(validate.rules).string = {min_bytes: 1}]; + + // The key to use in the descriptor entry. + string descriptor_key = 2 [(validate.rules).string = {min_bytes: 1}]; + } + + // The following descriptor entry is appended to the descriptor and is populated using the + // trusted address from :ref:`x-forwarded-for `: + // + // .. code-block:: cpp + // + // ("remote_address", "") + message RemoteAddress { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RateLimit.Action.RemoteAddress"; + } + + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("generic_key", "") + message GenericKey { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RateLimit.Action.GenericKey"; + + // The value to use in the descriptor entry. + string descriptor_value = 1 [(validate.rules).string = {min_bytes: 1}]; + } + + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("header_match", "") + message HeaderValueMatch { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.RateLimit.Action.HeaderValueMatch"; + + // The value to use in the descriptor entry. + string descriptor_value = 1 [(validate.rules).string = {min_bytes: 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 [(validate.rules).repeated = {min_items: 1}]; + } + + oneof action_specifier { + option (validate.required) = true; + + // Rate limit on source cluster. + SourceCluster source_cluster = 1; + + // Rate limit on destination cluster. + DestinationCluster destination_cluster = 2; + + // Rate limit on request headers. + RequestHeaders request_headers = 3; + + // Rate limit on remote address. + RemoteAddress remote_address = 4; + + // Rate limit on a generic key. + GenericKey generic_key = 5; + + // Rate limit on the existence of request headers. + HeaderValueMatch header_value_match = 6; + } + } + + // 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 [(validate.rules).uint32 = {lte: 10}]; + + // The key to be set in runtime to disable this rate limit configuration. + string disable_key = 2; + + // 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 :ref:`composing actions + // ` for additional documentation. + repeated Action actions = 3 [(validate.rules).repeated = {min_items: 1}]; +} + +// .. attention:: +// +// Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host* +// header. Thus, if attempting to match on *Host*, match on *:authority* instead. +// +// .. attention:: +// +// To route on HTTP method, use the special HTTP/2 *:method* header. This works for both +// HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g., +// +// .. code-block:: json +// +// { +// "name": ":method", +// "exact_match": "POST" +// } +// +// .. attention:: +// In the absence of any header match specifier, match will default to :ref:`present_match +// `. i.e, a request that has +// the :ref:`name ` header will match, +// regardless of the header's value. +// +// [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.] +// [#next-free-field: 12] +message HeaderMatcher { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.HeaderMatcher"; + + reserved 2, 3, 5; + + reserved "regex_match"; + + // Specifies the name of the header in the request. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // Specifies how the header match will be performed to route the request. + oneof header_match_specifier { + // If specified, header match will be performed based on the value of the header. + string exact_match = 4; + + // If specified, this regex string is a regular expression rule which implies the entire request + // header value must match the regex. The rule will not match if only a subsequence of the + // request header value matches the regex. + type.matcher.v3alpha.RegexMatcher safe_regex_match = 11; + + // If specified, header match will be performed based on range. + // The rule will match if the request header value is within this range. + // The entire request header value must represent an integer in base 10 notation: consisting of + // an optional plus or minus sign followed by a sequence of digits. The rule will not match if + // the header value does not represent an integer. Match will fail for empty values, floating + // point numbers or if only a subsequence of the header value is an integer. + // + // Examples: + // + // * For range [-10,0), route will match for header value -1, but not for 0, "somestring", 10.9, + // "-1somestring" + type.v3alpha.Int64Range range_match = 6; + + // If specified, header match will be performed based on whether the header is in the + // request. + bool present_match = 7; + + // If specified, header match will be performed based on the prefix of the header value. + // Note: empty prefix is not allowed, please use present_match instead. + // + // Examples: + // + // * The prefix *abcd* matches the value *abcdxyz*, but not for *abcxyz*. + string prefix_match = 9 [(validate.rules).string = {min_bytes: 1}]; + + // If specified, header match will be performed based on the suffix of the header value. + // Note: empty suffix is not allowed, please use present_match instead. + // + // Examples: + // + // * The suffix *abcd* matches the value *xyzabcd*, but not for *xyzbcd*. + string suffix_match = 10 [(validate.rules).string = {min_bytes: 1}]; + } + + // If specified, the match result will be inverted before checking. Defaults to false. + // + // Examples: + // + // * The regex ``\d{3}`` does not match the value *1234*, so it will match when inverted. + // * The range [-10,0) will match the value -1, so it will not match when inverted. + bool invert_match = 8; +} + +// Query parameter matching treats the query string of a request's :path header +// as an ampersand-separated list of keys and/or key=value elements. +// [#next-free-field: 7] +message QueryParameterMatcher { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.route.QueryParameterMatcher"; + + reserved 3, 4; + + reserved "value", "regex"; + + // Specifies the name of a key that must be present in the requested + // *path*'s query string. + string name = 1 [(validate.rules).string = {min_bytes: 1 max_bytes: 1024}]; + + oneof query_parameter_match_specifier { + // Specifies whether a query parameter value should match against a string. + type.matcher.v3alpha.StringMatcher string_match = 5 + [(validate.rules).message = {required: true}]; + + // Specifies whether a query parameter should be present. + bool present_match = 6; + } +} diff --git a/envoy/config/route/v3alpha/scoped_route.proto b/envoy/config/route/v3alpha/scoped_route.proto new file mode 100644 index 00000000..7e5172cb --- /dev/null +++ b/envoy/config/route/v3alpha/scoped_route.proto @@ -0,0 +1,116 @@ +syntax = "proto3"; + +package envoy.config.route.v3alpha; + +import "udpa/annotations/versioning.proto"; + +import "validate/validate.proto"; + +option java_package = "io.envoyproxy.envoy.config.route.v3alpha"; +option java_outer_classname = "ScopedRouteProto"; +option java_multiple_files = true; + +// [#protodoc-title: HTTP scoped routing configuration] +// * Routing :ref:`architecture overview ` + +// Specifies a routing scope, which associates a +// :ref:`Key` to a +// :ref:`envoy_api_msg_RouteConfiguration` (identified by its resource name). +// +// The HTTP connection manager builds up a table consisting of these Key to +// RouteConfiguration mappings, and looks up the RouteConfiguration to use per +// request according to the algorithm specified in the +// :ref:`scope_key_builder` +// assigned to the HttpConnectionManager. +// +// For example, with the following configurations (in YAML): +// +// HttpConnectionManager config: +// +// .. code:: +// +// ... +// scoped_routes: +// name: foo-scoped-routes +// scope_key_builder: +// fragments: +// - header_value_extractor: +// name: X-Route-Selector +// element_separator: , +// element: +// separator: = +// key: vip +// +// ScopedRouteConfiguration resources (specified statically via +// :ref:`scoped_route_configurations_list` +// or obtained dynamically via SRDS): +// +// .. code:: +// +// (1) +// name: route-scope1 +// route_configuration_name: route-config1 +// key: +// fragments: +// - string_key: 172.10.10.20 +// +// (2) +// name: route-scope2 +// route_configuration_name: route-config2 +// key: +// fragments: +// - string_key: 172.20.20.30 +// +// A request from a client such as: +// +// .. code:: +// +// GET / HTTP/1.1 +// Host: foo.com +// X-Route-Selector: vip=172.10.10.20 +// +// would result in the routing table defined by the `route-config1` +// RouteConfiguration being assigned to the HTTP request/stream. +// +message ScopedRouteConfiguration { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.ScopedRouteConfiguration"; + + // Specifies a key which is matched against the output of the + // :ref:`scope_key_builder` + // specified in the HttpConnectionManager. The matching is done per HTTP + // request and is dependent on the order of the fragments contained in the + // Key. + message Key { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.ScopedRouteConfiguration.Key"; + + message Fragment { + option (udpa.annotations.versioning).previous_message_type = + "envoy.api.v2.ScopedRouteConfiguration.Key.Fragment"; + + oneof type { + option (validate.required) = true; + + // A string to match against. + string string_key = 1; + } + } + + // The ordered set of fragments to match against. The order must match the + // fragments in the corresponding + // :ref:`scope_key_builder`. + repeated Fragment fragments = 1 [(validate.rules).repeated = {min_items: 1}]; + } + + // The name assigned to the routing scope. + string name = 1 [(validate.rules).string = {min_bytes: 1}]; + + // The resource name to use for a :ref:`envoy_api_msg_DiscoveryRequest` to an + // RDS server to fetch the :ref:`envoy_api_msg_RouteConfiguration` associated + // with this scope. + string route_configuration_name = 2 [(validate.rules).string = {min_bytes: 1}]; + + // The key to match against. + Key key = 3 [(validate.rules).message = {required: true}]; +} diff --git a/envoy/config/tap/v3alpha/BUILD b/envoy/config/tap/v3alpha/BUILD new file mode 100644 index 00000000..89f7885d --- /dev/null +++ b/envoy/config/tap/v3alpha/BUILD @@ -0,0 +1,14 @@ +# DO NOT EDIT. This file is generated by tools/proto_sync.py. + +load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package") + +licenses(["notice"]) # Apache 2 + +api_proto_package( + deps = [ + "//envoy/config/core/v3alpha:pkg", + "//envoy/config/route/v3alpha:pkg", + "//envoy/service/tap/v2alpha:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", + ], +) diff --git a/envoy/service/tap/v3alpha/common.proto b/envoy/config/tap/v3alpha/common.proto similarity index 96% rename from envoy/service/tap/v3alpha/common.proto rename to envoy/config/tap/v3alpha/common.proto index 2d528a0e..b1f775e0 100644 --- a/envoy/service/tap/v3alpha/common.proto +++ b/envoy/config/tap/v3alpha/common.proto @@ -1,10 +1,10 @@ syntax = "proto3"; -package envoy.service.tap.v3alpha; +package envoy.config.tap.v3alpha; import "envoy/config/core/v3alpha/base.proto"; import "envoy/config/core/v3alpha/grpc_service.proto"; -import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; import "google/protobuf/wrappers.proto"; @@ -12,7 +12,7 @@ import "udpa/annotations/versioning.proto"; import "validate/validate.proto"; -option java_package = "io.envoyproxy.envoy.service.tap.v3alpha"; +option java_package = "io.envoyproxy.envoy.config.tap.v3alpha"; option java_outer_classname = "CommonProto"; option java_multiple_files = true; @@ -41,7 +41,7 @@ message TapConfig { // // This field defaults to 100/:ref:`HUNDRED // `. - config.core.v3alpha.RuntimeFractionalPercent tap_enabled = 3; + core.v3alpha.RuntimeFractionalPercent tap_enabled = 3; } // Tap match configuration. This is a recursive structure which allows complex nested match @@ -97,7 +97,7 @@ message HttpHeadersMatch { "envoy.service.tap.v2alpha.HttpHeadersMatch"; // HTTP headers to match. - repeated config.route.v3alpha.HeaderMatcher headers = 1; + repeated route.v3alpha.HeaderMatcher headers = 1; } // Tap output configuration. @@ -225,5 +225,5 @@ message StreamingGrpcSink { string tap_id = 1; // The gRPC server that hosts the Tap Sink Service. - config.core.v3alpha.GrpcService grpc_service = 2 [(validate.rules).message = {required: true}]; + core.v3alpha.GrpcService grpc_service = 2 [(validate.rules).message = {required: true}]; } diff --git a/envoy/data/tap/v3alpha/common.proto b/envoy/data/tap/v3alpha/common.proto index abb6c751..44a92602 100644 --- a/envoy/data/tap/v3alpha/common.proto +++ b/envoy/data/tap/v3alpha/common.proto @@ -21,15 +21,15 @@ message Body { bytes as_bytes = 1; // Body data as string. This field is only used when the :ref:`JSON_BODY_AS_STRING - // ` sink + // ` sink // format type is selected. See the documentation for that option for why this is useful. string as_string = 2; } // Specifies whether body data has been truncated to fit within the specified // :ref:`max_buffered_rx_bytes - // ` and + // ` and // :ref:`max_buffered_tx_bytes - // ` settings. + // ` settings. bool truncated = 3; } diff --git a/envoy/data/tap/v3alpha/transport.proto b/envoy/data/tap/v3alpha/transport.proto index aa88e01d..27589615 100644 --- a/envoy/data/tap/v3alpha/transport.proto +++ b/envoy/data/tap/v3alpha/transport.proto @@ -93,11 +93,11 @@ message SocketBufferedTrace { repeated SocketEvent events = 3; // Set to true if read events were truncated due to the :ref:`max_buffered_rx_bytes - // ` setting. + // ` setting. bool read_truncated = 4; // Set to true if write events were truncated due to the :ref:`max_buffered_tx_bytes - // ` setting. + // ` setting. bool write_truncated = 5; } diff --git a/envoy/extensions/common/dynamic_forward_proxy/v3alpha/BUILD b/envoy/extensions/common/dynamic_forward_proxy/v3alpha/BUILD index 91b609b3..6fe66b77 100644 --- a/envoy/extensions/common/dynamic_forward_proxy/v3alpha/BUILD +++ b/envoy/extensions/common/dynamic_forward_proxy/v3alpha/BUILD @@ -6,8 +6,8 @@ licenses(["notice"]) # Apache 2 api_proto_package( deps = [ + "//envoy/config/cluster/v3alpha:pkg", "//envoy/config/common/dynamic_forward_proxy/v2alpha:pkg", - "//envoy/service/cluster/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/extensions/common/dynamic_forward_proxy/v3alpha/dns_cache.proto b/envoy/extensions/common/dynamic_forward_proxy/v3alpha/dns_cache.proto index 449dc7c5..115d80d1 100644 --- a/envoy/extensions/common/dynamic_forward_proxy/v3alpha/dns_cache.proto +++ b/envoy/extensions/common/dynamic_forward_proxy/v3alpha/dns_cache.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.extensions.common.dynamic_forward_proxy.v3alpha; -import "envoy/service/cluster/v3alpha/cds.proto"; +import "envoy/config/cluster/v3alpha/cluster.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; @@ -39,7 +39,7 @@ message DnsCacheConfig { // likely build a "happy eyeballs" connection pool which would race the primary / fall back // address and return the one that wins. This same method could potentially also be used for // QUIC to TCP fall back.] - service.cluster.v3alpha.Cluster.DnsLookupFamily dns_lookup_family = 2 + config.cluster.v3alpha.Cluster.DnsLookupFamily dns_lookup_family = 2 [(validate.rules).enum = {defined_only: true}]; // The DNS refresh rate for currently cached DNS hosts. If not specified defaults to 60s. diff --git a/envoy/extensions/common/tap/v3alpha/BUILD b/envoy/extensions/common/tap/v3alpha/BUILD index eb8035bf..83de9485 100644 --- a/envoy/extensions/common/tap/v3alpha/BUILD +++ b/envoy/extensions/common/tap/v3alpha/BUILD @@ -8,7 +8,7 @@ api_proto_package( deps = [ "//envoy/config/common/tap/v2alpha:pkg", "//envoy/config/core/v3alpha:pkg", - "//envoy/service/tap/v3alpha:pkg", + "//envoy/config/tap/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/extensions/common/tap/v3alpha/common.proto b/envoy/extensions/common/tap/v3alpha/common.proto index 5e3a425f..a14c8cb5 100644 --- a/envoy/extensions/common/tap/v3alpha/common.proto +++ b/envoy/extensions/common/tap/v3alpha/common.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package envoy.extensions.common.tap.v3alpha; import "envoy/config/core/v3alpha/config_source.proto"; -import "envoy/service/tap/v3alpha/common.proto"; +import "envoy/config/tap/v3alpha/common.proto"; import "udpa/annotations/versioning.proto"; @@ -41,7 +41,7 @@ message CommonExtensionConfig { // If specified, the tap filter will be configured via a static configuration that cannot be // changed. - service.tap.v3alpha.TapConfig static_config = 2; + config.tap.v3alpha.TapConfig static_config = 2; // [#not-implemented-hide:] Configuration to use for TapDS updates for the filter. TapDSConfig tapds_config = 3; diff --git a/envoy/extensions/filters/http/fault/v3alpha/fault.proto b/envoy/extensions/filters/http/fault/v3alpha/fault.proto index ef584cd8..796f3435 100644 --- a/envoy/extensions/filters/http/fault/v3alpha/fault.proto +++ b/envoy/extensions/filters/http/fault/v3alpha/fault.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.extensions.filters.http.fault.v3alpha; -import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; import "envoy/extensions/filters/common/fault/v3alpha/fault.proto"; import "envoy/type/v3alpha/percent.proto"; diff --git a/envoy/extensions/filters/http/health_check/v3alpha/health_check.proto b/envoy/extensions/filters/http/health_check/v3alpha/health_check.proto index 1a04333e..6d2753c4 100644 --- a/envoy/extensions/filters/http/health_check/v3alpha/health_check.proto +++ b/envoy/extensions/filters/http/health_check/v3alpha/health_check.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.extensions.filters.http.health_check.v3alpha; -import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; import "envoy/type/v3alpha/percent.proto"; import "google/protobuf/duration.proto"; diff --git a/envoy/extensions/filters/http/jwt_authn/v3alpha/config.proto b/envoy/extensions/filters/http/jwt_authn/v3alpha/config.proto index 4822b070..dfb0d6d1 100644 --- a/envoy/extensions/filters/http/jwt_authn/v3alpha/config.proto +++ b/envoy/extensions/filters/http/jwt_authn/v3alpha/config.proto @@ -4,7 +4,7 @@ package envoy.extensions.filters.http.jwt_authn.v3alpha; import "envoy/config/core/v3alpha/base.proto"; import "envoy/config/core/v3alpha/http_uri.proto"; -import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/empty.proto"; diff --git a/envoy/extensions/filters/network/dubbo_proxy/v3alpha/route.proto b/envoy/extensions/filters/network/dubbo_proxy/v3alpha/route.proto index cf1a7083..0a0f271d 100644 --- a/envoy/extensions/filters/network/dubbo_proxy/v3alpha/route.proto +++ b/envoy/extensions/filters/network/dubbo_proxy/v3alpha/route.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.extensions.filters.network.dubbo_proxy.v3alpha; -import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; import "envoy/type/matcher/v3alpha/string.proto"; import "envoy/type/v3alpha/range.proto"; diff --git a/envoy/extensions/filters/network/http_connection_manager/v3alpha/BUILD b/envoy/extensions/filters/network/http_connection_manager/v3alpha/BUILD index c62effd3..06a47c54 100644 --- a/envoy/extensions/filters/network/http_connection_manager/v3alpha/BUILD +++ b/envoy/extensions/filters/network/http_connection_manager/v3alpha/BUILD @@ -9,7 +9,7 @@ api_proto_package( "//envoy/config/core/v3alpha:pkg", "//envoy/config/filter/accesslog/v3alpha:pkg", "//envoy/config/filter/network/http_connection_manager/v2:pkg", - "//envoy/service/route/v3alpha:pkg", + "//envoy/config/route/v3alpha:pkg", "//envoy/type/tracing/v2:pkg", "//envoy/type/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", diff --git a/envoy/extensions/filters/network/http_connection_manager/v3alpha/http_connection_manager.proto b/envoy/extensions/filters/network/http_connection_manager/v3alpha/http_connection_manager.proto index d911adf6..1237bfbb 100644 --- a/envoy/extensions/filters/network/http_connection_manager/v3alpha/http_connection_manager.proto +++ b/envoy/extensions/filters/network/http_connection_manager/v3alpha/http_connection_manager.proto @@ -5,8 +5,8 @@ package envoy.extensions.filters.network.http_connection_manager.v3alpha; import "envoy/config/core/v3alpha/config_source.proto"; import "envoy/config/core/v3alpha/protocol.proto"; import "envoy/config/filter/accesslog/v3alpha/accesslog.proto"; -import "envoy/service/route/v3alpha/rds.proto"; -import "envoy/service/route/v3alpha/srds.proto"; +import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/scoped_route.proto"; import "envoy/type/tracing/v2/custom_tag.proto"; import "envoy/type/v3alpha/percent.proto"; @@ -239,7 +239,7 @@ message HttpConnectionManager { Rds rds = 3; // The route table for the connection manager is static and is specified in this property. - service.route.v3alpha.RouteConfiguration route_config = 4; + config.route.v3alpha.RouteConfiguration route_config = 4; // A route table will be dynamically assigned to each request based on request attributes // (e.g., the value of a header). The "routing scopes" (i.e., route tables) and "scope keys" are @@ -495,7 +495,7 @@ message ScopedRouteConfigurationsList { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.ScopedRouteConfigurationsList"; - repeated service.route.v3alpha.ScopedRouteConfiguration scoped_route_configurations = 1 + repeated config.route.v3alpha.ScopedRouteConfiguration scoped_route_configurations = 1 [(validate.rules).repeated = {min_items: 1}]; } @@ -506,15 +506,15 @@ message ScopedRoutes { // Specifies the mechanism for constructing "scope keys" based on HTTP request attributes. These // keys are matched against a set of - // :ref:`Key` objects assembled + // :ref:`Key` objects assembled // from - // :ref:`ScopedRouteConfiguration` + // :ref:`ScopedRouteConfiguration` // messages distributed via SRDS (the Scoped Route Discovery Service) or assigned statically via // :ref:`scoped_route_configurations_list`. // // Upon receiving a request's headers, the Router will build a key using the algorithm specified // by this message. This key will be used to look up the routing table (i.e., the - // :ref:`RouteConfiguration`) to use for + // :ref:`RouteConfiguration`) to use for // the request. message ScopeKeyBuilder { option (udpa.annotations.versioning).previous_message_type = diff --git a/envoy/extensions/filters/network/redis_proxy/v3alpha/redis_proxy.proto b/envoy/extensions/filters/network/redis_proxy/v3alpha/redis_proxy.proto index 065ef361..fbce339c 100644 --- a/envoy/extensions/filters/network/redis_proxy/v3alpha/redis_proxy.proto +++ b/envoy/extensions/filters/network/redis_proxy/v3alpha/redis_proxy.proto @@ -234,7 +234,7 @@ message RedisProxy { } // RedisProtocolOptions specifies Redis upstream protocol options. This object is used in -// :ref:`extension_protocol_options`, +// :ref:`extension_protocol_options`, // keyed by the name `envoy.redis_proxy`. message RedisProtocolOptions { option (udpa.annotations.versioning).previous_message_type = diff --git a/envoy/extensions/filters/network/thrift_proxy/v3alpha/route.proto b/envoy/extensions/filters/network/thrift_proxy/v3alpha/route.proto index 3e7ad031..a37e7a3e 100644 --- a/envoy/extensions/filters/network/thrift_proxy/v3alpha/route.proto +++ b/envoy/extensions/filters/network/thrift_proxy/v3alpha/route.proto @@ -3,7 +3,7 @@ syntax = "proto3"; package envoy.extensions.filters.network.thrift_proxy.v3alpha; import "envoy/config/core/v3alpha/base.proto"; -import "envoy/config/route/v3alpha/route.proto"; +import "envoy/config/route/v3alpha/route_components.proto"; import "google/protobuf/wrappers.proto"; diff --git a/envoy/extensions/filters/network/thrift_proxy/v3alpha/thrift_proxy.proto b/envoy/extensions/filters/network/thrift_proxy/v3alpha/thrift_proxy.proto index f1248471..d29837ad 100644 --- a/envoy/extensions/filters/network/thrift_proxy/v3alpha/thrift_proxy.proto +++ b/envoy/extensions/filters/network/thrift_proxy/v3alpha/thrift_proxy.proto @@ -109,7 +109,7 @@ message ThriftFilter { // ThriftProtocolOptions specifies Thrift upstream protocol options. This object is used in // in -// :ref:`extension_protocol_options`, +// :ref:`extension_protocol_options`, // keyed by the name `envoy.filters.network.thrift_proxy`. message ThriftProtocolOptions { option (udpa.annotations.versioning).previous_message_type = diff --git a/envoy/service/cluster/v3alpha/BUILD b/envoy/service/cluster/v3alpha/BUILD index a1a72a9c..69659b01 100644 --- a/envoy/service/cluster/v3alpha/BUILD +++ b/envoy/service/cluster/v3alpha/BUILD @@ -8,11 +8,7 @@ api_proto_package( has_services = True, deps = [ "//envoy/api/v2:pkg", - "//envoy/config/cluster/v3alpha:pkg", - "//envoy/config/core/v3alpha:pkg", "//envoy/service/discovery/v3alpha:pkg", - "//envoy/service/endpoint/v3alpha:pkg", - "//envoy/type/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/service/cluster/v3alpha/cds.proto b/envoy/service/cluster/v3alpha/cds.proto index 49e7abc4..2cd1c9d6 100644 --- a/envoy/service/cluster/v3alpha/cds.proto +++ b/envoy/service/cluster/v3alpha/cds.proto @@ -2,34 +2,18 @@ syntax = "proto3"; package envoy.service.cluster.v3alpha; -import "envoy/config/cluster/v3alpha/circuit_breaker.proto"; -import "envoy/config/cluster/v3alpha/filter.proto"; -import "envoy/config/cluster/v3alpha/outlier_detection.proto"; -import "envoy/config/core/v3alpha/address.proto"; -import "envoy/config/core/v3alpha/base.proto"; -import "envoy/config/core/v3alpha/config_source.proto"; -import "envoy/config/core/v3alpha/health_check.proto"; -import "envoy/config/core/v3alpha/protocol.proto"; import "envoy/service/discovery/v3alpha/discovery.proto"; -import "envoy/service/endpoint/v3alpha/eds.proto"; -import "envoy/type/v3alpha/percent.proto"; import "google/api/annotations.proto"; -import "google/protobuf/any.proto"; -import "google/protobuf/duration.proto"; -import "google/protobuf/struct.proto"; -import "google/protobuf/wrappers.proto"; import "udpa/annotations/versioning.proto"; -import "validate/validate.proto"; - option java_package = "io.envoyproxy.envoy.service.cluster.v3alpha"; option java_outer_classname = "CdsProto"; option java_multiple_files = true; option java_generic_services = true; -// [#protodoc-title: Clusters] +// [#protodoc-title: CDS] // Return list of all clusters this proxy will load balance to. service ClusterDiscoveryService { @@ -48,856 +32,8 @@ service ClusterDiscoveryService { } } -// Configuration for a single upstream cluster. -// [#next-free-field: 46] -message Cluster { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster"; - - // Refer to :ref:`service discovery type ` - // for an explanation on each type. - enum DiscoveryType { - // Refer to the :ref:`static discovery type` - // for an explanation. - STATIC = 0; - - // Refer to the :ref:`strict DNS discovery - // type` - // for an explanation. - STRICT_DNS = 1; - - // Refer to the :ref:`logical DNS discovery - // type` - // for an explanation. - LOGICAL_DNS = 2; - - // Refer to the :ref:`service discovery type` - // for an explanation. - EDS = 3; - - // Refer to the :ref:`original destination discovery - // type` - // for an explanation. - ORIGINAL_DST = 4; - } - - // Refer to :ref:`load balancer type ` architecture - // overview section for information on each type. - enum LbPolicy { - reserved 4; - - reserved "ORIGINAL_DST_LB"; - - // Refer to the :ref:`round robin load balancing - // policy` - // for an explanation. - ROUND_ROBIN = 0; - - // Refer to the :ref:`least request load balancing - // policy` - // for an explanation. - LEAST_REQUEST = 1; - - // Refer to the :ref:`ring hash load balancing - // policy` - // for an explanation. - RING_HASH = 2; - - // Refer to the :ref:`random load balancing - // policy` - // for an explanation. - RANDOM = 3; - - // Refer to the :ref:`Maglev load balancing policy` - // for an explanation. - MAGLEV = 5; - - // This load balancer type must be specified if the configured cluster provides a cluster - // specific load balancer. Consult the configured cluster's documentation for whether to set - // this option or not. - CLUSTER_PROVIDED = 6; - - // [#not-implemented-hide:] Use the new :ref:`load_balancing_policy - // ` field to determine - // the LB policy. - // [#next-major-version: In the v3 API, we should consider deprecating the lb_policy field - // and instead using the new load_balancing_policy field as the one and only mechanism for - // configuring this.] - LOAD_BALANCING_POLICY_CONFIG = 7; - } - - // When V4_ONLY is selected, the DNS resolver will only perform a lookup for - // addresses in the IPv4 family. If V6_ONLY is selected, the DNS resolver will - // only perform a lookup for addresses in the IPv6 family. If AUTO is - // specified, the DNS resolver will first perform a lookup for addresses in - // the IPv6 family and fallback to a lookup for addresses in the IPv4 family. - // For cluster types other than - // :ref:`STRICT_DNS` - // and - // :ref:`LOGICAL_DNS`, - // this setting is - // ignored. - enum DnsLookupFamily { - AUTO = 0; - V4_ONLY = 1; - V6_ONLY = 2; - } - - enum ClusterProtocolSelection { - // Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2). - // If :ref:`http2_protocol_options - // ` are present, HTTP2 - // will be used, otherwise HTTP1.1 will be used. - USE_CONFIGURED_PROTOCOL = 0; - - // Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection. - USE_DOWNSTREAM_PROTOCOL = 1; - } - - // TransportSocketMatch specifies what transport socket config will be used - // when the match conditions are satisfied. - message TransportSocketMatch { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.TransportSocketMatch"; - - // The name of the match, used in stats generation. - string name = 1 [(validate.rules).string = {min_len: 1}]; - - // Optional endpoint metadata match criteria. - // The connection to the endpoint with metadata matching what is set in this field - // will use the transport socket configuration specified here. - // The endpoint's metadata entry in *envoy.transport_socket_match* is used to match - // against the values specified in this field. - google.protobuf.Struct match = 2; - - // The configuration of the transport socket. - config.core.v3alpha.TransportSocket transport_socket = 3; - } - - // Extended cluster type. - message CustomClusterType { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.CustomClusterType"; - - // The type of the cluster to instantiate. The name must match a supported cluster type. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // Cluster specific configuration which depends on the cluster being instantiated. - // See the supported cluster for further documentation. - google.protobuf.Any typed_config = 2; - } - - // Only valid when discovery type is EDS. - message EdsClusterConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.EdsClusterConfig"; - - // Configuration for the source of EDS updates for this Cluster. - config.core.v3alpha.ConfigSource eds_config = 1; - - // Optional alternative to cluster name to present to EDS. This does not - // have the same restrictions as cluster name, i.e. it may be arbitrary - // length. - string service_name = 2; - } - - // Optionally divide the endpoints in this cluster into subsets defined by - // endpoint metadata and selected by route and weighted cluster metadata. - // [#next-free-field: 8] - message LbSubsetConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.LbSubsetConfig"; - - // If NO_FALLBACK is selected, a result - // equivalent to no healthy hosts is reported. If ANY_ENDPOINT is selected, - // any cluster endpoint may be returned (subject to policy, health checks, - // etc). If DEFAULT_SUBSET is selected, load balancing is performed over the - // endpoints matching the values from the default_subset field. - enum LbSubsetFallbackPolicy { - NO_FALLBACK = 0; - ANY_ENDPOINT = 1; - DEFAULT_SUBSET = 2; - } - - // Specifications for subsets. - message LbSubsetSelector { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.LbSubsetConfig.LbSubsetSelector"; - - // Allows to override top level fallback policy per selector. - enum LbSubsetSelectorFallbackPolicy { - // If NOT_DEFINED top level config fallback policy is used instead. - NOT_DEFINED = 0; - - // If NO_FALLBACK is selected, a result equivalent to no healthy hosts is reported. - NO_FALLBACK = 1; - - // If ANY_ENDPOINT is selected, any cluster endpoint may be returned - // (subject to policy, health checks, etc). - ANY_ENDPOINT = 2; - - // If DEFAULT_SUBSET is selected, load balancing is performed over the - // endpoints matching the values from the default_subset field. - DEFAULT_SUBSET = 3; - - // If KEYS_SUBSET is selected, subset selector matching is performed again with metadata - // keys reduced to - // :ref:`fallback_keys_subset`. - // It allows for a fallback to a different, less specific selector if some of the keys of - // the selector are considered optional. - KEYS_SUBSET = 4; - } - - // List of keys to match with the weighted cluster metadata. - repeated string keys = 1; - - // The behavior used when no endpoint subset matches the selected route's - // metadata. - LbSubsetSelectorFallbackPolicy fallback_policy = 2 - [(validate.rules).enum = {defined_only: true}]; - - // Subset of - // :ref:`keys` - // used by - // :ref:`KEYS_SUBSET` - // fallback policy. - // It has to be a non empty list if KEYS_SUBSET fallback policy is selected. - // For any other fallback policy the parameter is not used and should not be set. - // Only values also present in - // :ref:`keys` - // are allowed, but `fallback_keys_subset` cannot be equal to `keys`. - repeated string fallback_keys_subset = 3; - } - - // The behavior used when no endpoint subset matches the selected route's - // metadata. The value defaults to - // :ref:`NO_FALLBACK`. - LbSubsetFallbackPolicy fallback_policy = 1 [(validate.rules).enum = {defined_only: true}]; - - // Specifies the default subset of endpoints used during fallback if - // fallback_policy is - // :ref:`DEFAULT_SUBSET`. - // Each field in default_subset is - // compared to the matching LbEndpoint.Metadata under the *envoy.lb* - // namespace. It is valid for no hosts to match, in which case the behavior - // is the same as a fallback_policy of - // :ref:`NO_FALLBACK`. - google.protobuf.Struct default_subset = 2; - - // For each entry, LbEndpoint.Metadata's - // *envoy.lb* namespace is traversed and a subset is created for each unique - // combination of key and value. For example: - // - // .. code-block:: json - // - // { "subset_selectors": [ - // { "keys": [ "version" ] }, - // { "keys": [ "stage", "hardware_type" ] } - // ]} - // - // A subset is matched when the metadata from the selected route and - // weighted cluster contains the same keys and values as the subset's - // metadata. The same host may appear in multiple subsets. - repeated LbSubsetSelector subset_selectors = 3; - - // If true, routing to subsets will take into account the localities and locality weights of the - // endpoints when making the routing decision. - // - // There are some potential pitfalls associated with enabling this feature, as the resulting - // traffic split after applying both a subset match and locality weights might be undesirable. - // - // Consider for example a situation in which you have 50/50 split across two localities X/Y - // which have 100 hosts each without subsetting. If the subset LB results in X having only 1 - // host selected but Y having 100, then a lot more load is being dumped on the single host in X - // than originally anticipated in the load balancing assignment delivered via EDS. - bool locality_weight_aware = 4; - - // When used with locality_weight_aware, scales the weight of each locality by the ratio - // of hosts in the subset vs hosts in the original subset. This aims to even out the load - // going to an individual locality if said locality is disproportionately affected by the - // subset predicate. - bool scale_locality_weight = 5; - - // If true, when a fallback policy is configured and its corresponding subset fails to find - // a host this will cause any host to be selected instead. - // - // This is useful when using the default subset as the fallback policy, given the default - // subset might become empty. With this option enabled, if that happens the LB will attempt - // to select a host from the entire cluster. - bool panic_mode_any = 6; - - // If true, metadata specified for a metadata key will be matched against the corresponding - // endpoint metadata if the endpoint metadata matches the value exactly OR it is a list value - // and any of the elements in the list matches the criteria. - bool list_as_any = 7; - } - - // Specific configuration for the LeastRequest load balancing policy. - message LeastRequestLbConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.LeastRequestLbConfig"; - - // The number of random healthy hosts from which the host with the fewest active requests will - // be chosen. Defaults to 2 so that we perform two-choice selection if the field is not set. - google.protobuf.UInt32Value choice_count = 1 [(validate.rules).uint32 = {gte: 2}]; - } - - // Specific configuration for the :ref:`RingHash` - // load balancing policy. - message RingHashLbConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.RingHashLbConfig"; - - // The hash function used to hash hosts onto the ketama ring. - enum HashFunction { - // Use `xxHash `_, this is the default hash function. - XX_HASH = 0; - - // Use `MurmurHash2 `_, this is compatible with - // std:hash in GNU libstdc++ 3.4.20 or above. This is typically the case when compiled - // on Linux and not macOS. - MURMUR_HASH_2 = 1; - } - - reserved 2; - - // Minimum hash ring size. The larger the ring is (that is, the more hashes there are for each - // provided host) the better the request distribution will reflect the desired weights. Defaults - // to 1024 entries, and limited to 8M entries. See also - // :ref:`maximum_ring_size`. - google.protobuf.UInt64Value minimum_ring_size = 1 [(validate.rules).uint64 = {lte: 8388608}]; - - // The hash function used to hash hosts onto the ketama ring. The value defaults to - // :ref:`XX_HASH`. - HashFunction hash_function = 3 [(validate.rules).enum = {defined_only: true}]; - - // Maximum hash ring size. Defaults to 8M entries, and limited to 8M entries, but can be lowered - // to further constrain resource use. See also - // :ref:`minimum_ring_size`. - google.protobuf.UInt64Value maximum_ring_size = 4 [(validate.rules).uint64 = {lte: 8388608}]; - } - - // Specific configuration for the - // :ref:`Original Destination ` - // load balancing policy. - message OriginalDstLbConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.OriginalDstLbConfig"; - - // When true, :ref:`x-envoy-original-dst-host - // ` can be used to override destination - // address. - // - // .. attention:: - // - // This header isn't sanitized by default, so enabling this feature allows HTTP clients to - // route traffic to arbitrary hosts and/or ports, which may have serious security - // consequences. - bool use_http_header = 1; - } - - // Common configuration for all load balancer implementations. - // [#next-free-field: 7] - message CommonLbConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.CommonLbConfig"; - - // Configuration for :ref:`zone aware routing - // `. - message ZoneAwareLbConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.CommonLbConfig.ZoneAwareLbConfig"; - - // Configures percentage of requests that will be considered for zone aware routing - // if zone aware routing is configured. If not specified, the default is 100%. - // * :ref:`runtime values `. - // * :ref:`Zone aware routing support `. - type.v3alpha.Percent routing_enabled = 1; - - // Configures minimum upstream cluster size required for zone aware routing - // If upstream cluster size is less than specified, zone aware routing is not performed - // even if zone aware routing is configured. If not specified, the default is 6. - // * :ref:`runtime values `. - // * :ref:`Zone aware routing support `. - google.protobuf.UInt64Value min_cluster_size = 2; - - // If set to true, Envoy will not consider any hosts when the cluster is in :ref:`panic - // mode`. Instead, the cluster will fail all - // requests as if all hosts are unhealthy. This can help avoid potentially overwhelming a - // failing service. - bool fail_traffic_on_panic = 3; - } - - // Configuration for :ref:`locality weighted load balancing - // ` - message LocalityWeightedLbConfig { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.Cluster.CommonLbConfig.LocalityWeightedLbConfig"; - } - - // Configures the :ref:`healthy panic threshold `. - // If not specified, the default is 50%. - // To disable panic mode, set to 0%. - // - // .. note:: - // The specified percent will be truncated to the nearest 1%. - type.v3alpha.Percent healthy_panic_threshold = 1; - - oneof locality_config_specifier { - ZoneAwareLbConfig zone_aware_lb_config = 2; - - LocalityWeightedLbConfig locality_weighted_lb_config = 3; - } - - // If set, all health check/weight/metadata updates that happen within this duration will be - // merged and delivered in one shot when the duration expires. The start of the duration is when - // the first update happens. This is useful for big clusters, with potentially noisy deploys - // that might trigger excessive CPU usage due to a constant stream of healthcheck state changes - // or metadata updates. The first set of updates to be seen apply immediately (e.g.: a new - // cluster). Please always keep in mind that the use of sandbox technologies may change this - // behavior. - // - // If this is not set, we default to a merge window of 1000ms. To disable it, set the merge - // window to 0. - // - // Note: merging does not apply to cluster membership changes (e.g.: adds/removes); this is - // because merging those updates isn't currently safe. See - // https://github.com/envoyproxy/envoy/pull/3941. - google.protobuf.Duration update_merge_window = 4; - - // If set to true, Envoy will not consider new hosts when computing load balancing weights until - // they have been health checked for the first time. This will have no effect unless - // active health checking is also configured. - // - // Ignoring a host means that for any load balancing calculations that adjust weights based - // on the ratio of eligible hosts and total hosts (priority spillover, locality weighting and - // panic mode) Envoy will exclude these hosts in the denominator. - // - // For example, with hosts in two priorities P0 and P1, where P0 looks like - // {healthy, unhealthy (new), unhealthy (new)} - // and where P1 looks like - // {healthy, healthy} - // all traffic will still hit P0, as 1 / (3 - 2) = 1. - // - // Enabling this will allow scaling up the number of hosts for a given cluster without entering - // panic mode or triggering priority spillover, assuming the hosts pass the first health check. - // - // If panic mode is triggered, new hosts are still eligible for traffic; they simply do not - // contribute to the calculation when deciding whether panic mode is enabled or not. - bool ignore_new_hosts_until_first_hc = 5; - - // If set to `true`, the cluster manager will drain all existing - // connections to upstream hosts whenever hosts are added or removed from the cluster. - bool close_connections_on_host_set_change = 6; - } - - message RefreshRate { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster.RefreshRate"; - - // Specifies the base interval between refreshes. This parameter is required and must be greater - // than zero and less than - // :ref:`max_interval - // `. - google.protobuf.Duration base_interval = 1 [(validate.rules).duration = { - required: true - gt {nanos: 1000000} - }]; - - // Specifies the maximum interval between refreshes. This parameter is optional, but must be - // greater than or equal to the - // :ref:`base_interval - // ` if set. The - // default is 10 times the :ref:`base_interval - // `. - google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {nanos: 1000000}}]; - } - - reserved 12, 15, 11, 35; - - reserved "tls_context", "extension_protocol_options"; - - // Configuration to use different transport sockets for different endpoints. - // The entry of *envoy.transport_socket* in the - // :ref:`LbEndpoint.Metadata ` - // is used to match against the transport sockets as they appear in the list. The first - // :ref:`match ` is used. - // For example, with the following match - // - // .. code-block:: yaml - // - // transport_socket_matches: - // - name: "enableMTLS" - // match: - // acceptMTLS: true - // transport_socket: - // name: envoy.transport_sockets.tls - // config: { ... } # tls socket configuration - // - name: "defaultToPlaintext" - // match: {} - // transport_socket: - // name: envoy.transport_sockets.raw_buffer - // - // Connections to the endpoints whose metadata value under *envoy.transport_socket* - // having "acceptMTLS"/"true" key/value pair use the "enableMTLS" socket configuration. - // - // If a :ref:`socket match ` - // with empty match criteria is provided, that always match any endpoint. For example, the - // "defaultToPlaintext" socket match in case above. - // - // If an endpoint metadata's value under *envoy.transport_socket* does not match any - // *TransportSocketMatch*, socket configuration fallbacks to use the *tls_context* or - // *transport_socket* specified in this cluster. - // - // This field allows gradual and flexible transport socket configuration changes. - // - // The metadata of endpoints in EDS can indicate transport socket capabilities. For example, - // an endpoint's metadata can have two key value pairs as "acceptMTLS": "true", - // "acceptPlaintext": "true". While some other endpoints, only accepting plaintext traffic - // has "acceptPlaintext": "true" metadata information. - // - // Then the xDS server can configure the CDS to a client, Envoy A, to send mutual TLS - // traffic for endpoints with "acceptMTLS": "true", by adding a corresponding - // *TransportSocketMatch* in this field. Other client Envoys receive CDS without - // *transport_socket_match* set, and still send plain text traffic to the same cluster. - // - // [#comment:TODO(incfly): add a detailed architecture doc on intended usage.] - repeated TransportSocketMatch transport_socket_matches = 43; - - // Supplies the name of the cluster which must be unique across all clusters. - // The cluster name is used when emitting - // :ref:`statistics ` if :ref:`alt_stat_name - // ` is not provided. - // Any ``:`` in the cluster name will be converted to ``_`` when emitting statistics. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // An optional alternative to the cluster name to be used while emitting stats. - // Any ``:`` in the name will be converted to ``_`` when emitting statistics. This should not be - // confused with :ref:`Router Filter Header - // `. - string alt_stat_name = 28; - - oneof cluster_discovery_type { - // The :ref:`service discovery type ` - // to use for resolving the cluster. - DiscoveryType type = 2 [(validate.rules).enum = {defined_only: true}]; - - // The custom cluster type. - CustomClusterType cluster_type = 38; - } - - // Configuration to use for EDS updates for the Cluster. - EdsClusterConfig eds_cluster_config = 3; - - // The timeout for new network connections to hosts in the cluster. - google.protobuf.Duration connect_timeout = 4 [(validate.rules).duration = {gt {}}]; - - // Soft limit on size of the cluster’s connections read and write buffers. If - // unspecified, an implementation defined default is applied (1MiB). - google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5; - - // The :ref:`load balancer type ` to use - // when picking a host in the cluster. - LbPolicy lb_policy = 6 [(validate.rules).enum = {defined_only: true}]; - - // If the service discovery type is - // :ref:`STATIC`, - // :ref:`STRICT_DNS` - // or - // :ref:`LOGICAL_DNS`, - // then hosts is required. - // - // .. attention:: - // - // **This field is deprecated**. Set the - // :ref:`load_assignment` field - // instead. - // - repeated config.core.v3alpha.Address hosts = 7; - - // Setting this is required for specifying members of - // :ref:`STATIC`, - // :ref:`STRICT_DNS` - // or - // :ref:`LOGICAL_DNS` - // clusters. This field supersedes - // :ref:`hosts` field. - // [#comment:TODO(dio): Deprecate the hosts field and add it to :ref:`deprecated log` - // once load_assignment is implemented.] - // - // .. attention:: - // - // Setting this allows non-EDS cluster types to contain embedded EDS equivalent - // :ref:`endpoint assignments`. - // Setting this overrides :ref:`hosts` - // values. - // - endpoint.v3alpha.ClusterLoadAssignment load_assignment = 33; - - // Optional :ref:`active health checking ` - // configuration for the cluster. If no - // configuration is specified no health checking will be done and all cluster - // members will be considered healthy at all times. - repeated config.core.v3alpha.HealthCheck health_checks = 8; - - // Optional maximum requests for a single upstream connection. This parameter - // is respected by both the HTTP/1.1 and HTTP/2 connection pool - // implementations. If not specified, there is no limit. Setting this - // parameter to 1 will effectively disable keep alive. - google.protobuf.UInt32Value max_requests_per_connection = 9; - - // Optional :ref:`circuit breaking ` for the cluster. - config.cluster.v3alpha.CircuitBreakers circuit_breakers = 10; - - // Additional options when handling HTTP requests upstream. These options will be applicable to - // both HTTP1 and HTTP2 requests. - config.core.v3alpha.HttpProtocolOptions common_http_protocol_options = 29; - - // Additional options when handling HTTP1 requests. - config.core.v3alpha.Http1ProtocolOptions http_protocol_options = 13; - - // Even if default HTTP2 protocol options are desired, this field must be - // set so that Envoy will assume that the upstream supports HTTP/2 when - // making new HTTP connection pool connections. Currently, Envoy only - // supports prior knowledge for upstream connections. Even if TLS is used - // with ALPN, `http2_protocol_options` must be specified. As an aside this allows HTTP/2 - // connections to happen over plain text. - config.core.v3alpha.Http2ProtocolOptions http2_protocol_options = 14; - - // The extension_protocol_options field is used to provide extension-specific protocol options - // for upstream connections. The key should match the extension filter name, such as - // "envoy.filters.network.thrift_proxy". See the extension's documentation for details on - // specific options. - map typed_extension_protocol_options = 36; - - // If the DNS refresh rate is specified and the cluster type is either - // :ref:`STRICT_DNS`, - // or - // :ref:`LOGICAL_DNS`, - // this value is used as the cluster’s DNS refresh - // rate. The value configured must be at least 1ms. If this setting is not specified, the - // value defaults to 5000ms. For cluster types other than - // :ref:`STRICT_DNS` - // and - // :ref:`LOGICAL_DNS` - // this setting is ignored. - google.protobuf.Duration dns_refresh_rate = 16 - [(validate.rules).duration = {gt {nanos: 1000000}}]; - - // If the DNS failure refresh rate is specified and the cluster type is either - // :ref:`STRICT_DNS`, - // or - // :ref:`LOGICAL_DNS`, - // this is used as the cluster’s DNS refresh rate when requests are failing. If this setting is - // not specified, the failure refresh rate defaults to the DNS refresh rate. For cluster types - // other than - // :ref:`STRICT_DNS` - // and - // :ref:`LOGICAL_DNS` - // this setting is ignored. - // - // Note: Currently, DNS failures and empty DNS responses are not treated differently and this - // configuration is applied in both situations. - RefreshRate dns_failure_refresh_rate = 44; - - // Optional configuration for setting cluster's DNS refresh rate. If the value is set to true, - // cluster's DNS refresh rate will be set to resource record's TTL which comes from DNS - // resolution. - bool respect_dns_ttl = 39; - - // The DNS IP address resolution policy. If this setting is not specified, the - // value defaults to - // :ref:`AUTO`. - DnsLookupFamily dns_lookup_family = 17 [(validate.rules).enum = {defined_only: true}]; - - // If DNS resolvers are specified and the cluster type is either - // :ref:`STRICT_DNS`, - // or - // :ref:`LOGICAL_DNS`, - // this value is used to specify the cluster’s dns resolvers. - // If this setting is not specified, the value defaults to the default - // resolver, which uses /etc/resolv.conf for configuration. For cluster types - // other than - // :ref:`STRICT_DNS` - // and - // :ref:`LOGICAL_DNS` - // this setting is ignored. - repeated config.core.v3alpha.Address dns_resolvers = 18; - - // [#next-major-version: Reconcile DNS options in a single message.] - // Always use TCP queries instead of UDP queries for DNS lookups. - bool use_tcp_for_dns_lookups = 45; - - // If specified, outlier detection will be enabled for this upstream cluster. - // Each of the configuration values can be overridden via - // :ref:`runtime values `. - config.cluster.v3alpha.OutlierDetection outlier_detection = 19; - - // The interval for removing stale hosts from a cluster type - // :ref:`ORIGINAL_DST`. - // Hosts are considered stale if they have not been used - // as upstream destinations during this interval. New hosts are added - // to original destination clusters on demand as new connections are - // redirected to Envoy, causing the number of hosts in the cluster to - // grow over time. Hosts that are not stale (they are actively used as - // destinations) are kept in the cluster, which allows connections to - // them remain open, saving the latency that would otherwise be spent - // on opening new connections. If this setting is not specified, the - // value defaults to 5000ms. For cluster types other than - // :ref:`ORIGINAL_DST` - // this setting is ignored. - google.protobuf.Duration cleanup_interval = 20 [(validate.rules).duration = {gt {}}]; - - // Optional configuration used to bind newly established upstream connections. - // This overrides any bind_config specified in the bootstrap proto. - // If the address and port are empty, no bind will be performed. - config.core.v3alpha.BindConfig upstream_bind_config = 21; - - // Configuration for load balancing subsetting. - LbSubsetConfig lb_subset_config = 22; - - // Optional configuration for the load balancing algorithm selected by - // LbPolicy. Currently only - // :ref:`RING_HASH` and - // :ref:`LEAST_REQUEST` - // has additional configuration options. - // Specifying ring_hash_lb_config or least_request_lb_config without setting the corresponding - // LbPolicy will generate an error at runtime. - oneof lb_config { - // Optional configuration for the Ring Hash load balancing policy. - RingHashLbConfig ring_hash_lb_config = 23; - - // Optional configuration for the Original Destination load balancing policy. - OriginalDstLbConfig original_dst_lb_config = 34; - - // Optional configuration for the LeastRequest load balancing policy. - LeastRequestLbConfig least_request_lb_config = 37; - } - - // Common configuration for all load balancer implementations. - CommonLbConfig common_lb_config = 27; - - // Optional custom transport socket implementation to use for upstream connections. - // To setup TLS, set a transport socket with name `tls` and - // :ref:`UpstreamTlsContexts - // ` in the - // `typed_config`. If no transport socket configuration is specified, new connections will be set - // up with plaintext. - config.core.v3alpha.TransportSocket transport_socket = 24; - - // The Metadata field can be used to provide additional information about the - // cluster. It can be used for stats, logging, and varying filter behavior. - // Fields should use reverse DNS notation to denote which entity within Envoy - // will need the information. For instance, if the metadata is intended for - // the Router filter, the filter name should be specified as *envoy.router*. - config.core.v3alpha.Metadata metadata = 25; - - // Determines how Envoy selects the protocol used to speak to upstream hosts. - ClusterProtocolSelection protocol_selection = 26; - - // Optional options for upstream connections. - UpstreamConnectionOptions upstream_connection_options = 30; - - // If an upstream host becomes unhealthy (as determined by the configured health checks - // or outlier detection), immediately close all connections to the failed host. - // - // .. note:: - // - // This is currently only supported for connections created by tcp_proxy. - // - // .. note:: - // - // The current implementation of this feature closes all connections immediately when - // the unhealthy status is detected. If there are a large number of connections open - // to an upstream host that becomes unhealthy, Envoy may spend a substantial amount of - // time exclusively closing these connections, and not processing any other traffic. - bool close_connections_on_host_health_failure = 31; - - // If set to true, Envoy will ignore the health value of a host when processing its removal - // from service discovery. This means that if active health checking is used, Envoy will *not* - // wait for the endpoint to go unhealthy before removing it. - bool ignore_health_on_host_removal = 32; - - // An (optional) network filter chain, listed in the order the filters should be applied. - // The chain will be applied to all outgoing connections that Envoy makes to the upstream - // servers of this cluster. - repeated config.cluster.v3alpha.Filter filters = 40; - - // [#not-implemented-hide:] New mechanism for LB policy configuration. Used only if the - // :ref:`lb_policy` field has the value - // :ref:`LOAD_BALANCING_POLICY_CONFIG`. - LoadBalancingPolicy load_balancing_policy = 41; - - // [#not-implemented-hide:] - // If present, tells the client where to send load reports via LRS. If not present, the - // client will fall back to a client-side default, which may be either (a) don't send any - // load reports or (b) send load reports for all clusters to a single default server - // (which may be configured in the bootstrap file). - // - // Note that if multiple clusters point to the same LRS server, the client may choose to - // create a separate stream for each cluster or it may choose to coalesce the data for - // multiple clusters onto a single stream. Either way, the client must make sure to send - // the data for any given cluster on no more than one stream. - // - // [#next-major-version: In the v3 API, we should consider restructuring this somehow, - // maybe by allowing LRS to go on the ADS stream, or maybe by moving some of the negotiation - // from the LRS stream here.] - config.core.v3alpha.ConfigSource lrs_server = 42; -} - -// [#not-implemented-hide:] Extensible load balancing policy configuration. -// -// Every LB policy defined via this mechanism will be identified via a unique name using reverse -// DNS notation. If the policy needs configuration parameters, it must define a message for its -// own configuration, which will be stored in the config field. The name of the policy will tell -// clients which type of message they should expect to see in the config field. -// -// Note that there are cases where it is useful to be able to independently select LB policies -// for choosing a locality and for choosing an endpoint within that locality. For example, a -// given deployment may always use the same policy to choose the locality, but for choosing the -// endpoint within the locality, some clusters may use weighted-round-robin, while others may -// use some sort of session-based balancing. -// -// This can be accomplished via hierarchical LB policies, where the parent LB policy creates a -// child LB policy for each locality. For each request, the parent chooses the locality and then -// delegates to the child policy for that locality to choose the endpoint within the locality. -// -// To facilitate this, the config message for the top-level LB policy may include a field of -// type LoadBalancingPolicy that specifies the child policy. -message LoadBalancingPolicy { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.LoadBalancingPolicy"; - - message Policy { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.LoadBalancingPolicy.Policy"; - - reserved 2; - - reserved "config"; - - // Required. The name of the LB policy. - string name = 1; - - google.protobuf.Any typed_config = 3; - } - - // Each client will iterate over the list in order and stop at the first policy that it - // supports. This provides a mechanism for starting to use new LB policies that are not yet - // supported by all clients. - repeated Policy policies = 1; -} - -// An extensible structure containing the address Envoy should bind to when -// establishing upstream connections. -message UpstreamBindConfig { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.UpstreamBindConfig"; - - // The address Envoy should bind to when establishing upstream connections. - config.core.v3alpha.Address source_address = 1; -} - -message UpstreamConnectionOptions { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.UpstreamConnectionOptions"; - - // If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives. - config.core.v3alpha.TcpKeepalive tcp_keepalive = 1; +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 and protoxform to upgrade the file. +message CdsDummy { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.CdsDummy"; } diff --git a/envoy/service/discovery/v2/hds.proto b/envoy/service/discovery/v2/hds.proto index 64975351..60c1caeb 100644 --- a/envoy/service/discovery/v2/hds.proto +++ b/envoy/service/discovery/v2/hds.proto @@ -4,7 +4,7 @@ package envoy.service.discovery.v2; import "envoy/api/v2/core/base.proto"; import "envoy/api/v2/core/health_check.proto"; -import "envoy/api/v2/endpoint/endpoint.proto"; +import "envoy/api/v2/endpoint/endpoint_components.proto"; import "google/api/annotations.proto"; import "google/protobuf/duration.proto"; diff --git a/envoy/service/endpoint/v3alpha/BUILD b/envoy/service/endpoint/v3alpha/BUILD index ff6cde99..69659b01 100644 --- a/envoy/service/endpoint/v3alpha/BUILD +++ b/envoy/service/endpoint/v3alpha/BUILD @@ -8,9 +8,7 @@ api_proto_package( has_services = True, deps = [ "//envoy/api/v2:pkg", - "//envoy/config/endpoint/v3alpha:pkg", "//envoy/service/discovery/v3alpha:pkg", - "//envoy/type/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/service/endpoint/v3alpha/eds.proto b/envoy/service/endpoint/v3alpha/eds.proto index 1b81f2c0..c2dcdbd8 100644 --- a/envoy/service/endpoint/v3alpha/eds.proto +++ b/envoy/service/endpoint/v3alpha/eds.proto @@ -2,9 +2,7 @@ syntax = "proto3"; package envoy.service.endpoint.v3alpha; -import "envoy/config/endpoint/v3alpha/endpoint.proto"; import "envoy/service/discovery/v3alpha/discovery.proto"; -import "envoy/type/v3alpha/percent.proto"; import "google/api/annotations.proto"; import "google/protobuf/duration.proto"; @@ -40,106 +38,8 @@ service EndpointDiscoveryService { } } -// Each route from RDS will map to a single cluster or traffic split across -// clusters using weights expressed in the RDS WeightedCluster. -// -// With EDS, each cluster is treated independently from a LB perspective, with -// LB taking place between the Localities within a cluster and at a finer -// granularity between the hosts within a locality. The percentage of traffic -// for each endpoint is determined by both its load_balancing_weight, and the -// load_balancing_weight of its locality. First, a locality will be selected, -// then an endpoint within that locality will be chose based on its weight. -// [#next-free-field: 6] -message ClusterLoadAssignment { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.ClusterLoadAssignment"; - - // Load balancing policy settings. - // [#next-free-field: 6] - message Policy { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.ClusterLoadAssignment.Policy"; - - message DropOverload { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.ClusterLoadAssignment.Policy.DropOverload"; - - // Identifier for the policy specifying the drop. - string category = 1 [(validate.rules).string = {min_bytes: 1}]; - - // Percentage of traffic that should be dropped for the category. - type.v3alpha.FractionalPercent drop_percentage = 2; - } - - reserved 1; - - // Action to trim the overall incoming traffic to protect the upstream - // hosts. This action allows protection in case the hosts are unable to - // recover from an outage, or unable to autoscale or unable to handle - // incoming traffic volume for any reason. - // - // At the client each category is applied one after the other to generate - // the 'actual' drop percentage on all outgoing traffic. For example: - // - // .. code-block:: json - // - // { "drop_overloads": [ - // { "category": "throttle", "drop_percentage": 60 } - // { "category": "lb", "drop_percentage": 50 } - // ]} - // - // The actual drop percentages applied to the traffic at the clients will be - // "throttle"_drop = 60% - // "lb"_drop = 20% // 50% of the remaining 'actual' load, which is 40%. - // actual_outgoing_load = 20% // remaining after applying all categories. - repeated DropOverload drop_overloads = 2; - - // Priority levels and localities are considered overprovisioned with this - // factor (in percentage). This means that we don't consider a priority - // level or locality unhealthy until the percentage of healthy hosts - // multiplied by the overprovisioning factor drops below 100. - // With the default value 140(1.4), Envoy doesn't consider a priority level - // or a locality unhealthy until their percentage of healthy hosts drops - // below 72%. For example: - // - // .. code-block:: json - // - // { "overprovisioning_factor": 100 } - // - // Read more at :ref:`priority levels ` and - // :ref:`localities `. - google.protobuf.UInt32Value overprovisioning_factor = 3 [(validate.rules).uint32 = {gt: 0}]; - - // The max time until which the endpoints from this assignment can be used. - // If no new assignments are received before this time expires the endpoints - // are considered stale and should be marked unhealthy. - // Defaults to 0 which means endpoints never go stale. - google.protobuf.Duration endpoint_stale_after = 4 [(validate.rules).duration = {gt {}}]; - - // The flag to disable overprovisioning. If it is set to true, - // :ref:`overprovisioning factor - // ` will be ignored - // and Envoy will not perform graceful failover between priority levels or - // localities as endpoints become unhealthy. Otherwise Envoy will perform - // graceful failover as :ref:`overprovisioning factor - // ` suggests. - // [#next-major-version: Unify with overprovisioning config as a single message.] - // [#not-implemented-hide:] - bool disable_overprovisioning = 5; - } - - // Name of the cluster. This will be the :ref:`service_name - // ` value if - // specified in the cluster :ref:`EdsClusterConfig - // `. - string cluster_name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // List of endpoints to load balance to. - repeated config.endpoint.v3alpha.LocalityLbEndpoints endpoints = 2; - - // Map of named endpoints that can be referenced in LocalityLbEndpoints. - // [#not-implemented-hide:] - map named_endpoints = 5; - - // Load balancing policy settings. - Policy policy = 4; +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 and protoxform to upgrade the file. +message EdsDummy { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.EdsDummy"; } diff --git a/envoy/service/health/v3alpha/hds.proto b/envoy/service/health/v3alpha/hds.proto index 390faf5d..34c7b871 100644 --- a/envoy/service/health/v3alpha/hds.proto +++ b/envoy/service/health/v3alpha/hds.proto @@ -4,7 +4,7 @@ package envoy.service.health.v3alpha; import "envoy/config/core/v3alpha/base.proto"; import "envoy/config/core/v3alpha/health_check.proto"; -import "envoy/config/endpoint/v3alpha/endpoint.proto"; +import "envoy/config/endpoint/v3alpha/endpoint_components.proto"; import "google/api/annotations.proto"; import "google/protobuf/duration.proto"; diff --git a/envoy/service/route/v3alpha/BUILD b/envoy/service/route/v3alpha/BUILD index 72914fff..69659b01 100644 --- a/envoy/service/route/v3alpha/BUILD +++ b/envoy/service/route/v3alpha/BUILD @@ -8,8 +8,6 @@ api_proto_package( has_services = True, deps = [ "//envoy/api/v2:pkg", - "//envoy/config/core/v3alpha:pkg", - "//envoy/config/route/v3alpha:pkg", "//envoy/service/discovery/v3alpha:pkg", "@com_github_cncf_udpa//udpa/annotations:pkg", ], diff --git a/envoy/service/route/v3alpha/rds.proto b/envoy/service/route/v3alpha/rds.proto index 75abbb57..b5fe9af3 100644 --- a/envoy/service/route/v3alpha/rds.proto +++ b/envoy/service/route/v3alpha/rds.proto @@ -2,9 +2,6 @@ syntax = "proto3"; package envoy.service.route.v3alpha; -import "envoy/config/core/v3alpha/base.proto"; -import "envoy/config/core/v3alpha/config_source.proto"; -import "envoy/config/route/v3alpha/route.proto"; import "envoy/service/discovery/v3alpha/discovery.proto"; import "google/api/annotations.proto"; @@ -19,9 +16,7 @@ option java_outer_classname = "RdsProto"; option java_multiple_files = true; option java_generic_services = true; -// [#protodoc-title: HTTP route configuration] -// * Routing :ref:`architecture overview ` -// * HTTP :ref:`router filter ` +// [#protodoc-title: RDS] // The resource_names field in DiscoveryRequest specifies a route configuration. // This allows an Envoy configuration with multiple HTTP listeners (and @@ -62,90 +57,8 @@ service VirtualHostDiscoveryService { } } -// [#next-free-field: 11] -message RouteConfiguration { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.RouteConfiguration"; - - // The name of the route configuration. For example, it might match - // :ref:`route_config_name - // ` - // in :ref:`envoy_api_msg_config.filter.network.http_connection_manager.v2.Rds`. - string name = 1; - - // An array of virtual hosts that make up the route table. - repeated config.route.v3alpha.VirtualHost virtual_hosts = 2; - - // An array of virtual hosts will be dynamically loaded via the VHDS API. - // Both *virtual_hosts* and *vhds* fields will be used when present. *virtual_hosts* can be used - // for a base routing table or for infrequently changing virtual hosts. *vhds* is used for - // on-demand discovery of virtual hosts. The contents of these two fields will be merged to - // generate a routing table for a given RouteConfiguration, with *vhds* derived configuration - // taking precedence. - Vhds vhds = 9; - - // Optionally 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 :ref:`config_http_conn_man_headers_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. Headers specified at this level are applied - // after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or - // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated config.core.v3alpha.HeaderValueOption response_headers_to_add = 4 - [(validate.rules).repeated = {max_items: 1000}]; - - // 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. Headers specified at this level are - // applied after headers from any enclosed :ref:`envoy_api_msg_route.VirtualHost` or - // :ref:`envoy_api_msg_route.RouteAction`. For more information, including details on - // header value syntax, see the documentation on :ref:`custom request headers - // `. - repeated config.core.v3alpha.HeaderValueOption request_headers_to_add = 6 - [(validate.rules).repeated = {max_items: 1000}]; - - // Specifies a list of HTTP headers that should be removed from each request - // routed by the HTTP connection manager. - repeated string request_headers_to_remove = 8; - - // By default, headers that should be added/removed are evaluated from most to least specific: - // - // * route level - // * virtual host level - // * connection manager level - // - // To allow setting overrides at the route or virtual host level, this order can be reversed - // by setting this option to true. Defaults to false. - // - // [#next-major-version: In the v3 API, this will default to true.] - bool most_specific_header_mutations_wins = 10; - - // 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 :ref:`route_config - // ` - // option. This setting default to false if the route table is loaded dynamically via the - // :ref:`rds - // ` - // option. Users may wish to override the default behavior in certain cases (for example when - // using CDS with a static route table). - google.protobuf.BoolValue validate_clusters = 7; -} - -message Vhds { - option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Vhds"; - - // Configuration source specifier for VHDS. - config.core.v3alpha.ConfigSource config_source = 1 [(validate.rules).message = {required: true}]; +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 and protoxform to upgrade the file. +message RdsDummy { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.RdsDummy"; } diff --git a/envoy/service/route/v3alpha/srds.proto b/envoy/service/route/v3alpha/srds.proto index a1437396..32d803fb 100644 --- a/envoy/service/route/v3alpha/srds.proto +++ b/envoy/service/route/v3alpha/srds.proto @@ -8,14 +8,12 @@ import "google/api/annotations.proto"; import "udpa/annotations/versioning.proto"; -import "validate/validate.proto"; - option java_package = "io.envoyproxy.envoy.service.route.v3alpha"; option java_outer_classname = "SrdsProto"; option java_multiple_files = true; option java_generic_services = true; -// [#protodoc-title: HTTP scoped routing configuration] +// [#protodoc-title: SRDS] // * Routing :ref:`architecture overview ` // The Scoped Routes Discovery Service (SRDS) API distributes @@ -23,8 +21,8 @@ option java_generic_services = true; // resources. Each ScopedRouteConfiguration resource represents a "routing // scope" containing a mapping that allows the HTTP connection manager to // dynamically assign a routing table (specified via a -// :ref:`RouteConfiguration` message) to -// each HTTP request. +// :ref:`RouteConfiguration` message) to each +// HTTP request. service ScopedRoutesDiscoveryService { rpc StreamScopedRoutes(stream discovery.v3alpha.DiscoveryRequest) returns (stream discovery.v3alpha.DiscoveryResponse) { @@ -41,104 +39,8 @@ service ScopedRoutesDiscoveryService { } } -// Specifies a routing scope, which associates a -// :ref:`Key` to a -// :ref:`envoy_api_msg_RouteConfiguration` (identified by its resource name). -// -// The HTTP connection manager builds up a table consisting of these Key to -// RouteConfiguration mappings, and looks up the RouteConfiguration to use per -// request according to the algorithm specified in the -// :ref:`scope_key_builder` -// assigned to the HttpConnectionManager. -// -// For example, with the following configurations (in YAML): -// -// HttpConnectionManager config: -// -// .. code:: -// -// ... -// scoped_routes: -// name: foo-scoped-routes -// scope_key_builder: -// fragments: -// - header_value_extractor: -// name: X-Route-Selector -// element_separator: , -// element: -// separator: = -// key: vip -// -// ScopedRouteConfiguration resources (specified statically via -// :ref:`scoped_route_configurations_list` -// or obtained dynamically via SRDS): -// -// .. code:: -// -// (1) -// name: route-scope1 -// route_configuration_name: route-config1 -// key: -// fragments: -// - string_key: 172.10.10.20 -// -// (2) -// name: route-scope2 -// route_configuration_name: route-config2 -// key: -// fragments: -// - string_key: 172.20.20.30 -// -// A request from a client such as: -// -// .. code:: -// -// GET / HTTP/1.1 -// Host: foo.com -// X-Route-Selector: vip=172.10.10.20 -// -// would result in the routing table defined by the `route-config1` -// RouteConfiguration being assigned to the HTTP request/stream. -// -message ScopedRouteConfiguration { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.ScopedRouteConfiguration"; - - // Specifies a key which is matched against the output of the - // :ref:`scope_key_builder` - // specified in the HttpConnectionManager. The matching is done per HTTP - // request and is dependent on the order of the fragments contained in the - // Key. - message Key { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.ScopedRouteConfiguration.Key"; - - message Fragment { - option (udpa.annotations.versioning).previous_message_type = - "envoy.api.v2.ScopedRouteConfiguration.Key.Fragment"; - - oneof type { - option (validate.required) = true; - - // A string to match against. - string string_key = 1; - } - } - - // The ordered set of fragments to match against. The order must match the - // fragments in the corresponding - // :ref:`scope_key_builder`. - repeated Fragment fragments = 1 [(validate.rules).repeated = {min_items: 1}]; - } - - // The name assigned to the routing scope. - string name = 1 [(validate.rules).string = {min_bytes: 1}]; - - // The resource name to use for a :ref:`envoy_api_msg_DiscoveryRequest` to an - // RDS server to fetch the :ref:`envoy_api_msg_RouteConfiguration` associated - // with this scope. - string route_configuration_name = 2 [(validate.rules).string = {min_bytes: 1}]; - - // The key to match against. - Key key = 3 [(validate.rules).message = {required: true}]; +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 and protoxform to upgrade the file. +message SrdsDummy { + option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.SrdsDummy"; } diff --git a/envoy/service/tap/v2alpha/BUILD b/envoy/service/tap/v2alpha/BUILD index 73a7e5d9..fcc1d0fc 100644 --- a/envoy/service/tap/v2alpha/BUILD +++ b/envoy/service/tap/v2alpha/BUILD @@ -11,5 +11,6 @@ api_proto_package( "//envoy/api/v2/core:pkg", "//envoy/api/v2/route:pkg", "//envoy/data/tap/v2alpha:pkg", + "@com_github_cncf_udpa//udpa/annotations:pkg", ], ) diff --git a/envoy/service/tap/v2alpha/common.proto b/envoy/service/tap/v2alpha/common.proto index a1efca2e..14087476 100644 --- a/envoy/service/tap/v2alpha/common.proto +++ b/envoy/service/tap/v2alpha/common.proto @@ -4,15 +4,17 @@ package envoy.service.tap.v2alpha; import "envoy/api/v2/core/base.proto"; import "envoy/api/v2/core/grpc_service.proto"; -import "envoy/api/v2/route/route.proto"; +import "envoy/api/v2/route/route_components.proto"; import "google/protobuf/wrappers.proto"; +import "udpa/annotations/migrate.proto"; import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.service.tap.v2alpha"; option java_outer_classname = "CommonProto"; option java_multiple_files = true; +option (udpa.annotations.file_migrate).move_to_package = "envoy.config.tap.v3alpha"; // [#protodoc-title: Common tap configuration] diff --git a/envoy/service/tap/v3alpha/BUILD b/envoy/service/tap/v3alpha/BUILD index 03eccfa1..d8a044dc 100644 --- a/envoy/service/tap/v3alpha/BUILD +++ b/envoy/service/tap/v3alpha/BUILD @@ -8,7 +8,7 @@ api_proto_package( has_services = True, deps = [ "//envoy/config/core/v3alpha:pkg", - "//envoy/config/route/v3alpha:pkg", + "//envoy/config/tap/v3alpha:pkg", "//envoy/data/tap/v3alpha:pkg", "//envoy/service/discovery/v3alpha:pkg", "//envoy/service/tap/v2alpha:pkg", diff --git a/envoy/service/tap/v3alpha/tap.proto b/envoy/service/tap/v3alpha/tap.proto index 395371b6..2a6f1e24 100644 --- a/envoy/service/tap/v3alpha/tap.proto +++ b/envoy/service/tap/v3alpha/tap.proto @@ -40,7 +40,7 @@ message StreamTapsRequest { config.core.v3alpha.Node node = 1 [(validate.rules).message = {required: true}]; // The opaque identifier that was set in the :ref:`output config - // `. + // `. string tap_id = 2; } diff --git a/envoy/service/tap/v3alpha/tapds.proto b/envoy/service/tap/v3alpha/tapds.proto index d21b09c2..9826aefe 100644 --- a/envoy/service/tap/v3alpha/tapds.proto +++ b/envoy/service/tap/v3alpha/tapds.proto @@ -2,8 +2,8 @@ syntax = "proto3"; package envoy.service.tap.v3alpha; +import "envoy/config/tap/v3alpha/common.proto"; import "envoy/service/discovery/v3alpha/discovery.proto"; -import "envoy/service/tap/v3alpha/common.proto"; import "google/api/annotations.proto"; @@ -45,5 +45,5 @@ message TapResource { string name = 1 [(validate.rules).string = {min_bytes: 1}]; // Tap config to apply - TapConfig config = 2; + config.tap.v3alpha.TapConfig config = 2; } diff --git a/test/validate/pgv_test.cc b/test/validate/pgv_test.cc index afb75083..b9b1bf05 100644 --- a/test/validate/pgv_test.cc +++ b/test/validate/pgv_test.cc @@ -4,10 +4,10 @@ // We don't use all the headers in the test below, but including them anyway as // a cheap way to get some C++ compiler sanity checking. -#include "envoy/api/v2/cds.pb.validate.h" -#include "envoy/api/v2/eds.pb.validate.h" -#include "envoy/api/v2/lds.pb.validate.h" -#include "envoy/api/v2/rds.pb.validate.h" +#include "envoy/api/v2/cluster.pb.validate.h" +#include "envoy/api/v2/endpoint.pb.validate.h" +#include "envoy/api/v2/listener.pb.validate.h" +#include "envoy/api/v2/route.pb.validate.h" #include "envoy/api/v2/core/protocol.pb.validate.h" #include "envoy/config/health_checker/redis/v2/redis.pb.validate.h" #include "envoy/config/filter/accesslog/v2/accesslog.pb.validate.h"