1syntax = "proto3";
2
3package envoy.config.route.v3;
4
5import "envoy/config/core/v3/base.proto";
6import "envoy/config/core/v3/extension.proto";
7import "envoy/config/core/v3/proxy_protocol.proto";
8import "envoy/type/matcher/v3/regex.proto";
9import "envoy/type/matcher/v3/string.proto";
10import "envoy/type/metadata/v3/metadata.proto";
11import "envoy/type/tracing/v3/custom_tag.proto";
12import "envoy/type/v3/percent.proto";
13import "envoy/type/v3/range.proto";
14
15import "google/protobuf/any.proto";
16import "google/protobuf/duration.proto";
17import "google/protobuf/struct.proto";
18import "google/protobuf/wrappers.proto";
19
20import "envoy/annotations/deprecation.proto";
21import "udpa/annotations/migrate.proto";
22import "udpa/annotations/status.proto";
23import "udpa/annotations/versioning.proto";
24import "validate/validate.proto";
25
26option java_package = "io.envoyproxy.envoy.config.route.v3";
27option java_outer_classname = "RouteComponentsProto";
28option java_multiple_files = true;
29option (udpa.annotations.file_status).package_version_status = ACTIVE;
30
31// [#protodoc-title: HTTP route components]
32// * Routing :ref:`architecture overview <arch_overview_http_routing>`
33// * HTTP :ref:`router filter <config_http_filters_router>`
34
35// The top level element in the routing configuration is a virtual host. Each virtual host has
36// a logical name as well as a set of domains that get routed to it based on the incoming request's
37// host header. This allows a single listener to service multiple top level domain path trees. Once
38// a virtual host is selected based on the domain, the routes are processed in order to see which
39// upstream cluster to route to or whether to perform a redirect.
40// [#next-free-field: 21]
41message VirtualHost {
42 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.VirtualHost";
43
44 enum TlsRequirementType {
45 // No TLS requirement for the virtual host.
46 NONE = 0;
47
48 // External requests must use TLS. If a request is external and it is not
49 // using TLS, a 301 redirect will be sent telling the client to use HTTPS.
50 EXTERNAL_ONLY = 1;
51
52 // All requests must use TLS. If a request is not using TLS, a 301 redirect
53 // will be sent telling the client to use HTTPS.
54 ALL = 2;
55 }
56
57 reserved 9, 12;
58
59 reserved "per_filter_config";
60
61 // The logical name of the virtual host. This is used when emitting certain
62 // statistics but is not relevant for routing.
63 string name = 1 [(validate.rules).string = {min_len: 1}];
64
65 // A list of domains (host/authority header) that will be matched to this
66 // virtual host. Wildcard hosts are supported in the suffix or prefix form.
67 //
68 // Domain search order:
69 // 1. Exact domain names: ``www.foo.com``.
70 // 2. Suffix domain wildcards: ``*.foo.com`` or ``*-bar.foo.com``.
71 // 3. Prefix domain wildcards: ``foo.*`` or ``foo-*``.
72 // 4. Special wildcard ``*`` matching any domain.
73 //
74 // .. note::
75 //
76 // The wildcard will not match the empty string.
77 // e.g. ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``.
78 // The longest wildcards match first.
79 // Only a single virtual host in the entire route configuration can match on ``*``. A domain
80 // must be unique across all virtual hosts or the config will fail to load.
81 //
82 // Domains cannot contain control characters. This is validated by the well_known_regex HTTP_HEADER_VALUE.
83 repeated string domains = 2 [(validate.rules).repeated = {
84 min_items: 1
85 items {string {well_known_regex: HTTP_HEADER_VALUE strict: false}}
86 }];
87
88 // The list of routes that will be matched, in order, for incoming requests.
89 // The first route that matches will be used.
90 repeated Route routes = 3;
91
92 // Specifies the type of TLS enforcement the virtual host expects. If this option is not
93 // specified, there is no TLS requirement for the virtual host.
94 TlsRequirementType require_tls = 4 [(validate.rules).enum = {defined_only: true}];
95
96 // A list of virtual clusters defined for this virtual host. Virtual clusters
97 // are used for additional statistics gathering.
98 repeated VirtualCluster virtual_clusters = 5;
99
100 // Specifies a set of rate limit configurations that will be applied to the
101 // virtual host.
102 repeated RateLimit rate_limits = 6;
103
104 // Specifies a list of HTTP headers that should be added to each request
105 // handled by this virtual host. Headers specified at this level are applied
106 // after headers from enclosed :ref:`envoy_api_msg_config.route.v3.Route` and before headers from the
107 // enclosing :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including
108 // details on header value syntax, see the documentation on :ref:`custom request headers
109 // <config_http_conn_man_headers_custom_request_headers>`.
110 repeated core.v3.HeaderValueOption request_headers_to_add = 7
111 [(validate.rules).repeated = {max_items: 1000}];
112
113 // Specifies a list of HTTP headers that should be removed from each request
114 // handled by this virtual host.
115 repeated string request_headers_to_remove = 13 [(validate.rules).repeated = {
116 items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}}
117 }];
118
119 // Specifies a list of HTTP headers that should be added to each response
120 // handled by this virtual host. Headers specified at this level are applied
121 // after headers from enclosed :ref:`envoy_api_msg_config.route.v3.Route` and before headers from the
122 // enclosing :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including
123 // details on header value syntax, see the documentation on :ref:`custom request headers
124 // <config_http_conn_man_headers_custom_request_headers>`.
125 repeated core.v3.HeaderValueOption response_headers_to_add = 10
126 [(validate.rules).repeated = {max_items: 1000}];
127
128 // Specifies a list of HTTP headers that should be removed from each response
129 // handled by this virtual host.
130 repeated string response_headers_to_remove = 11 [(validate.rules).repeated = {
131 items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}}
132 }];
133
134 // Indicates that the virtual host has a CORS policy.
135 CorsPolicy cors = 8;
136
137 // The per_filter_config field can be used to provide virtual host-specific
138 // configurations for filters. The key should match the filter name, such as
139 // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter
140 // specific; see the :ref:`HTTP filter documentation <config_http_filters>`
141 // for if and how it is utilized.
142 map<string, google.protobuf.Any> typed_per_filter_config = 15;
143
144 // Decides whether the :ref:`x-envoy-attempt-count
145 // <config_http_filters_router_x-envoy-attempt-count>` header should be included
146 // in the upstream request. Setting this option will cause it to override any existing header
147 // value, so in the case of two Envoys on the request path with this option enabled, the upstream
148 // will see the attempt count as perceived by the second Envoy. Defaults to false.
149 // This header is unaffected by the
150 // :ref:`suppress_envoy_headers
151 // <envoy_api_field_extensions.filters.http.router.v3.Router.suppress_envoy_headers>` flag.
152 //
153 // [#next-major-version: rename to include_attempt_count_in_request.]
154 bool include_request_attempt_count = 14;
155
156 // Decides whether the :ref:`x-envoy-attempt-count
157 // <config_http_filters_router_x-envoy-attempt-count>` header should be included
158 // in the downstream response. Setting this option will cause the router to override any existing header
159 // value, so in the case of two Envoys on the request path with this option enabled, the downstream
160 // will see the attempt count as perceived by the Envoy closest upstream from itself. Defaults to false.
161 // This header is unaffected by the
162 // :ref:`suppress_envoy_headers
163 // <envoy_api_field_extensions.filters.http.router.v3.Router.suppress_envoy_headers>` flag.
164 bool include_attempt_count_in_response = 19;
165
166 // Indicates the retry policy for all routes in this virtual host. Note that setting a
167 // route level entry will take precedence over this config and it'll be treated
168 // independently (e.g.: values are not inherited).
169 RetryPolicy retry_policy = 16;
170
171 // [#not-implemented-hide:]
172 // Specifies the configuration for retry policy extension. Note that setting a route level entry
173 // will take precedence over this config and it'll be treated independently (e.g.: values are not
174 // inherited). :ref:`Retry policy <envoy_api_field_config.route.v3.VirtualHost.retry_policy>` should not be
175 // set if this field is used.
176 google.protobuf.Any retry_policy_typed_config = 20;
177
178 // Indicates the hedge policy for all routes in this virtual host. Note that setting a
179 // route level entry will take precedence over this config and it'll be treated
180 // independently (e.g.: values are not inherited).
181 HedgePolicy hedge_policy = 17;
182
183 // The maximum bytes which will be buffered for retries and shadowing.
184 // If set and a route-specific limit is not set, the bytes actually buffered will be the minimum
185 // value of this and the listener per_connection_buffer_limit_bytes.
186 google.protobuf.UInt32Value per_request_buffer_limit_bytes = 18;
187}
188
189// A filter-defined action type.
190message FilterAction {
191 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.FilterAction";
192
193 google.protobuf.Any action = 1;
194}
195
196// A route is both a specification of how to match a request as well as an indication of what to do
197// next (e.g., redirect, forward, rewrite, etc.).
198//
199// .. attention::
200//
201// Envoy supports routing on HTTP method via :ref:`header matching
202// <envoy_api_msg_config.route.v3.HeaderMatcher>`.
203// [#next-free-field: 18]
204message Route {
205 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Route";
206
207 reserved 6, 8;
208
209 reserved "per_filter_config";
210
211 // Name for the route.
212 string name = 14;
213
214 // Route matching parameters.
215 RouteMatch match = 1 [(validate.rules).message = {required: true}];
216
217 oneof action {
218 option (validate.required) = true;
219
220 // Route request to some upstream cluster.
221 RouteAction route = 2;
222
223 // Return a redirect.
224 RedirectAction redirect = 3;
225
226 // Return an arbitrary HTTP response directly, without proxying.
227 DirectResponseAction direct_response = 7;
228
229 // [#not-implemented-hide:]
230 // If true, a filter will define the action (e.g., it could dynamically generate the
231 // RouteAction).
232 // [#comment: TODO(samflattery): Remove cleanup in route_fuzz_test.cc when
233 // implemented]
234 FilterAction filter_action = 17;
235 }
236
237 // The Metadata field can be used to provide additional information
238 // about the route. It can be used for configuration, stats, and logging.
239 // The metadata should go under the filter namespace that will need it.
240 // For instance, if the metadata is intended for the Router filter,
241 // the filter name should be specified as *envoy.filters.http.router*.
242 core.v3.Metadata metadata = 4;
243
244 // Decorator for the matched route.
245 Decorator decorator = 5;
246
247 // The typed_per_filter_config field can be used to provide route-specific
248 // configurations for filters. The key should match the filter name, such as
249 // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter
250 // specific; see the :ref:`HTTP filter documentation <config_http_filters>` for
251 // if and how it is utilized.
252 map<string, google.protobuf.Any> typed_per_filter_config = 13;
253
254 // Specifies a set of headers that will be added to requests matching this
255 // route. Headers specified at this level are applied before headers from the
256 // enclosing :ref:`envoy_api_msg_config.route.v3.VirtualHost` and
257 // :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including details on
258 // header value syntax, see the documentation on :ref:`custom request headers
259 // <config_http_conn_man_headers_custom_request_headers>`.
260 repeated core.v3.HeaderValueOption request_headers_to_add = 9
261 [(validate.rules).repeated = {max_items: 1000}];
262
263 // Specifies a list of HTTP headers that should be removed from each request
264 // matching this route.
265 repeated string request_headers_to_remove = 12 [(validate.rules).repeated = {
266 items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}}
267 }];
268
269 // Specifies a set of headers that will be added to responses to requests
270 // matching this route. Headers specified at this level are applied before
271 // headers from the enclosing :ref:`envoy_api_msg_config.route.v3.VirtualHost` and
272 // :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including
273 // details on header value syntax, see the documentation on
274 // :ref:`custom request headers <config_http_conn_man_headers_custom_request_headers>`.
275 repeated core.v3.HeaderValueOption response_headers_to_add = 10
276 [(validate.rules).repeated = {max_items: 1000}];
277
278 // Specifies a list of HTTP headers that should be removed from each response
279 // to requests matching this route.
280 repeated string response_headers_to_remove = 11 [(validate.rules).repeated = {
281 items {string {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}}
282 }];
283
284 // Presence of the object defines whether the connection manager's tracing configuration
285 // is overridden by this route specific instance.
286 Tracing tracing = 15;
287
288 // The maximum bytes which will be buffered for retries and shadowing.
289 // If set, the bytes actually buffered will be the minimum value of this and the
290 // listener per_connection_buffer_limit_bytes.
291 google.protobuf.UInt32Value per_request_buffer_limit_bytes = 16;
292}
293
294// Compared to the :ref:`cluster <envoy_api_field_config.route.v3.RouteAction.cluster>` field that specifies a
295// single upstream cluster as the target of a request, the :ref:`weighted_clusters
296// <envoy_api_field_config.route.v3.RouteAction.weighted_clusters>` option allows for specification of
297// multiple upstream clusters along with weights that indicate the percentage of
298// traffic to be forwarded to each cluster. The router selects an upstream cluster based on the
299// weights.
300message WeightedCluster {
301 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.WeightedCluster";
302
303 // [#next-free-field: 11]
304 message ClusterWeight {
305 option (udpa.annotations.versioning).previous_message_type =
306 "envoy.api.v2.route.WeightedCluster.ClusterWeight";
307
308 reserved 7, 8;
309
310 reserved "per_filter_config";
311
312 // Name of the upstream cluster. The cluster must exist in the
313 // :ref:`cluster manager configuration <config_cluster_manager>`.
314 string name = 1 [(validate.rules).string = {min_len: 1}];
315
316 // An integer between 0 and :ref:`total_weight
317 // <envoy_api_field_config.route.v3.WeightedCluster.total_weight>`. When a request matches the route,
318 // the choice of an upstream cluster is determined by its weight. The sum of weights across all
319 // entries in the clusters array must add up to the total_weight, which defaults to 100.
320 google.protobuf.UInt32Value weight = 2;
321
322 // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints in
323 // the upstream cluster with metadata matching what is set in this field will be considered for
324 // load balancing. Note that this will be merged with what's provided in
325 // :ref:`RouteAction.metadata_match <envoy_api_field_config.route.v3.RouteAction.metadata_match>`, with
326 // values here taking precedence. The filter name should be specified as *envoy.lb*.
327 core.v3.Metadata metadata_match = 3;
328
329 // Specifies a list of headers to be added to requests when this cluster is selected
330 // through the enclosing :ref:`envoy_api_msg_config.route.v3.RouteAction`.
331 // Headers specified at this level are applied before headers from the enclosing
332 // :ref:`envoy_api_msg_config.route.v3.Route`, :ref:`envoy_api_msg_config.route.v3.VirtualHost`, and
333 // :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including details on
334 // header value syntax, see the documentation on :ref:`custom request headers
335 // <config_http_conn_man_headers_custom_request_headers>`.
336 repeated core.v3.HeaderValueOption request_headers_to_add = 4
337 [(validate.rules).repeated = {max_items: 1000}];
338
339 // Specifies a list of HTTP headers that should be removed from each request when
340 // this cluster is selected through the enclosing :ref:`envoy_api_msg_config.route.v3.RouteAction`.
341 repeated string request_headers_to_remove = 9 [(validate.rules).repeated = {
342 items {string {well_known_regex: HTTP_HEADER_NAME strict: false}}
343 }];
344
345 // Specifies a list of headers to be added to responses when this cluster is selected
346 // through the enclosing :ref:`envoy_api_msg_config.route.v3.RouteAction`.
347 // Headers specified at this level are applied before headers from the enclosing
348 // :ref:`envoy_api_msg_config.route.v3.Route`, :ref:`envoy_api_msg_config.route.v3.VirtualHost`, and
349 // :ref:`envoy_api_msg_config.route.v3.RouteConfiguration`. For more information, including details on
350 // header value syntax, see the documentation on :ref:`custom request headers
351 // <config_http_conn_man_headers_custom_request_headers>`.
352 repeated core.v3.HeaderValueOption response_headers_to_add = 5
353 [(validate.rules).repeated = {max_items: 1000}];
354
355 // Specifies a list of headers to be removed from responses when this cluster is selected
356 // through the enclosing :ref:`envoy_api_msg_config.route.v3.RouteAction`.
357 repeated string response_headers_to_remove = 6 [(validate.rules).repeated = {
358 items {string {well_known_regex: HTTP_HEADER_NAME strict: false}}
359 }];
360
361 // The per_filter_config field can be used to provide weighted cluster-specific
362 // configurations for filters. The key should match the filter name, such as
363 // *envoy.filters.http.buffer* for the HTTP buffer filter. Use of this field is filter
364 // specific; see the :ref:`HTTP filter documentation <config_http_filters>`
365 // for if and how it is utilized.
366 map<string, google.protobuf.Any> typed_per_filter_config = 10;
367 }
368
369 // Specifies one or more upstream clusters associated with the route.
370 repeated ClusterWeight clusters = 1 [(validate.rules).repeated = {min_items: 1}];
371
372 // Specifies the total weight across all clusters. The sum of all cluster weights must equal this
373 // value, which must be greater than 0. Defaults to 100.
374 google.protobuf.UInt32Value total_weight = 3 [(validate.rules).uint32 = {gte: 1}];
375
376 // Specifies the runtime key prefix that should be used to construct the
377 // runtime keys associated with each cluster. When the *runtime_key_prefix* is
378 // specified, the router will look for weights associated with each upstream
379 // cluster under the key *runtime_key_prefix* + "." + *cluster[i].name* where
380 // *cluster[i]* denotes an entry in the clusters array field. If the runtime
381 // key for the cluster does not exist, the value specified in the
382 // configuration file will be used as the default weight. See the :ref:`runtime documentation
383 // <operations_runtime>` for how key names map to the underlying implementation.
384 string runtime_key_prefix = 2;
385}
386
387// [#next-free-field: 13]
388message RouteMatch {
389 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteMatch";
390
391 message GrpcRouteMatchOptions {
392 option (udpa.annotations.versioning).previous_message_type =
393 "envoy.api.v2.route.RouteMatch.GrpcRouteMatchOptions";
394 }
395
396 message TlsContextMatchOptions {
397 option (udpa.annotations.versioning).previous_message_type =
398 "envoy.api.v2.route.RouteMatch.TlsContextMatchOptions";
399
400 // If specified, the route will match against whether or not a certificate is presented.
401 // If not specified, certificate presentation status (true or false) will not be considered when route matching.
402 google.protobuf.BoolValue presented = 1;
403
404 // If specified, the route will match against whether or not a certificate is validated.
405 // If not specified, certificate validation status (true or false) will not be considered when route matching.
406 google.protobuf.BoolValue validated = 2;
407 }
408
409 // An extensible message for matching CONNECT requests.
410 message ConnectMatcher {
411 }
412
413 reserved 5, 3;
414
415 reserved "regex";
416
417 oneof path_specifier {
418 option (validate.required) = true;
419
420 // If specified, the route is a prefix rule meaning that the prefix must
421 // match the beginning of the *:path* header.
422 string prefix = 1;
423
424 // If specified, the route is an exact path rule meaning that the path must
425 // exactly match the *:path* header once the query string is removed.
426 string path = 2;
427
428 // If specified, the route is a regular expression rule meaning that the
429 // regex must match the *:path* header once the query string is removed. The entire path
430 // (without the query string) must match the regex. The rule will not match if only a
431 // subsequence of the *:path* header matches the regex.
432 //
433 // [#next-major-version: In the v3 API we should redo how path specification works such
434 // that we utilize StringMatcher, and additionally have consistent options around whether we
435 // strip query strings, do a case sensitive match, etc. In the interim it will be too disruptive
436 // to deprecate the existing options. We should even consider whether we want to do away with
437 // path_specifier entirely and just rely on a set of header matchers which can already match
438 // on :path, etc. The issue with that is it is unclear how to generically deal with query string
439 // stripping. This needs more thought.]
440 type.matcher.v3.RegexMatcher safe_regex = 10 [(validate.rules).message = {required: true}];
441
442 // If this is used as the matcher, the matcher will only match CONNECT requests.
443 // Note that this will not match HTTP/2 upgrade-style CONNECT requests
444 // (WebSocket and the like) as they are normalized in Envoy as HTTP/1.1 style
445 // upgrades.
446 // This is the only way to match CONNECT requests for HTTP/1.1. For HTTP/2,
447 // where Extended CONNECT requests may have a path, the path matchers will work if
448 // there is a path present.
449 // Note that CONNECT support is currently considered alpha in Envoy.
450 // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
451 ConnectMatcher connect_matcher = 12;
452 }
453
454 // Indicates that prefix/path matching should be case sensitive. The default
455 // is true.
456 google.protobuf.BoolValue case_sensitive = 4;
457
458 // Indicates that the route should additionally match on a runtime key. Every time the route
459 // is considered for a match, it must also fall under the percentage of matches indicated by
460 // this field. For some fraction N/D, a random number in the range [0,D) is selected. If the
461 // number is <= the value of the numerator N, or if the key is not present, the default
462 // value, the router continues to evaluate the remaining match criteria. A runtime_fraction
463 // route configuration can be used to roll out route changes in a gradual manner without full
464 // code/config deploys. Refer to the :ref:`traffic shifting
465 // <config_http_conn_man_route_table_traffic_splitting_shift>` docs for additional documentation.
466 //
467 // .. note::
468 //
469 // Parsing this field is implemented such that the runtime key's data may be represented
470 // as a FractionalPercent proto represented as JSON/YAML and may also be represented as an
471 // integer with the assumption that the value is an integral percentage out of 100. For
472 // instance, a runtime key lookup returning the value "42" would parse as a FractionalPercent
473 // whose numerator is 42 and denominator is HUNDRED. This preserves legacy semantics.
474 core.v3.RuntimeFractionalPercent runtime_fraction = 9;
475
476 // Specifies a set of headers that the route should match on. The router will
477 // check the request’s headers against all the specified headers in the route
478 // config. A match will happen if all the headers in the route are present in
479 // the request with the same values (or based on presence if the value field
480 // is not in the config).
481 repeated HeaderMatcher headers = 6;
482
483 // Specifies a set of URL query parameters on which the route should
484 // match. The router will check the query string from the *path* header
485 // against all the specified query parameters. If the number of specified
486 // query parameters is nonzero, they all must match the *path* header's
487 // query string for a match to occur.
488 repeated QueryParameterMatcher query_parameters = 7;
489
490 // If specified, only gRPC requests will be matched. The router will check
491 // that the content-type header has a application/grpc or one of the various
492 // application/grpc+ values.
493 GrpcRouteMatchOptions grpc = 8;
494
495 // If specified, the client tls context will be matched against the defined
496 // match options.
497 //
498 // [#next-major-version: unify with RBAC]
499 TlsContextMatchOptions tls_context = 11;
500}
501
502// [#next-free-field: 12]
503message CorsPolicy {
504 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.CorsPolicy";
505
506 reserved 1, 8, 7;
507
508 reserved "allow_origin", "allow_origin_regex", "enabled";
509
510 // Specifies string patterns that match allowed origins. An origin is allowed if any of the
511 // string matchers match.
512 repeated type.matcher.v3.StringMatcher allow_origin_string_match = 11;
513
514 // Specifies the content for the *access-control-allow-methods* header.
515 string allow_methods = 2;
516
517 // Specifies the content for the *access-control-allow-headers* header.
518 string allow_headers = 3;
519
520 // Specifies the content for the *access-control-expose-headers* header.
521 string expose_headers = 4;
522
523 // Specifies the content for the *access-control-max-age* header.
524 string max_age = 5;
525
526 // Specifies whether the resource allows credentials.
527 google.protobuf.BoolValue allow_credentials = 6;
528
529 oneof enabled_specifier {
530 // Specifies the % of requests for which the CORS filter is enabled.
531 //
532 // If neither ``enabled``, ``filter_enabled``, nor ``shadow_enabled`` are specified, the CORS
533 // filter will be enabled for 100% of the requests.
534 //
535 // If :ref:`runtime_key <envoy_api_field_config.core.v3.RuntimeFractionalPercent.runtime_key>` is
536 // specified, Envoy will lookup the runtime key to get the percentage of requests to filter.
537 core.v3.RuntimeFractionalPercent filter_enabled = 9;
538 }
539
540 // Specifies the % of requests for which the CORS policies will be evaluated and tracked, but not
541 // enforced.
542 //
543 // This field is intended to be used when ``filter_enabled`` and ``enabled`` are off. One of those
544 // fields have to explicitly disable the filter in order for this setting to take effect.
545 //
546 // If :ref:`runtime_key <envoy_api_field_config.core.v3.RuntimeFractionalPercent.runtime_key>` is specified,
547 // Envoy will lookup the runtime key to get the percentage of requests for which it will evaluate
548 // and track the request's *Origin* to determine if it's valid but will not enforce any policies.
549 core.v3.RuntimeFractionalPercent shadow_enabled = 10;
550}
551
552// [#next-free-field: 37]
553message RouteAction {
554 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteAction";
555
556 enum ClusterNotFoundResponseCode {
557 // HTTP status code - 503 Service Unavailable.
558 SERVICE_UNAVAILABLE = 0;
559
560 // HTTP status code - 404 Not Found.
561 NOT_FOUND = 1;
562 }
563
564 // Configures :ref:`internal redirect <arch_overview_internal_redirects>` behavior.
565 // [#next-major-version: remove this definition - it's defined in the InternalRedirectPolicy message.]
566 enum InternalRedirectAction {
567 option deprecated = true;
568
569 PASS_THROUGH_INTERNAL_REDIRECT = 0;
570 HANDLE_INTERNAL_REDIRECT = 1;
571 }
572
573 // The router is capable of shadowing traffic from one cluster to another. The current
574 // implementation is "fire and forget," meaning Envoy will not wait for the shadow cluster to
575 // respond before returning the response from the primary cluster. All normal statistics are
576 // collected for the shadow cluster making this feature useful for testing.
577 //
578 // During shadowing, the host/authority header is altered such that *-shadow* is appended. This is
579 // useful for logging. For example, *cluster1* becomes *cluster1-shadow*.
580 //
581 // .. note::
582 //
583 // Shadowing will not be triggered if the primary cluster does not exist.
584 message RequestMirrorPolicy {
585 option (udpa.annotations.versioning).previous_message_type =
586 "envoy.api.v2.route.RouteAction.RequestMirrorPolicy";
587
588 reserved 2;
589
590 reserved "runtime_key";
591
592 // Specifies the cluster that requests will be mirrored to. The cluster must
593 // exist in the cluster manager configuration.
594 string cluster = 1 [(validate.rules).string = {min_len: 1}];
595
596 // If not specified, all requests to the target cluster will be mirrored.
597 //
598 // If specified, this field takes precedence over the `runtime_key` field and requests must also
599 // fall under the percentage of matches indicated by this field.
600 //
601 // For some fraction N/D, a random number in the range [0,D) is selected. If the
602 // number is <= the value of the numerator N, or if the key is not present, the default
603 // value, the request will be mirrored.
604 core.v3.RuntimeFractionalPercent runtime_fraction = 3;
605
606 // Determines if the trace span should be sampled. Defaults to true.
607 google.protobuf.BoolValue trace_sampled = 4;
608 }
609
610 // Specifies the route's hashing policy if the upstream cluster uses a hashing :ref:`load balancer
611 // <arch_overview_load_balancing_types>`.
612 // [#next-free-field: 7]
613 message HashPolicy {
614 option (udpa.annotations.versioning).previous_message_type =
615 "envoy.api.v2.route.RouteAction.HashPolicy";
616
617 message Header {
618 option (udpa.annotations.versioning).previous_message_type =
619 "envoy.api.v2.route.RouteAction.HashPolicy.Header";
620
621 // The name of the request header that will be used to obtain the hash
622 // key. If the request header is not present, no hash will be produced.
623 string header_name = 1
624 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
625
626 // If specified, the request header value will be rewritten and used
627 // to produce the hash key.
628 type.matcher.v3.RegexMatchAndSubstitute regex_rewrite = 2;
629 }
630
631 // Envoy supports two types of cookie affinity:
632 //
633 // 1. Passive. Envoy takes a cookie that's present in the cookies header and
634 // hashes on its value.
635 //
636 // 2. Generated. Envoy generates and sets a cookie with an expiration (TTL)
637 // on the first request from the client in its response to the client,
638 // based on the endpoint the request gets sent to. The client then
639 // presents this on the next and all subsequent requests. The hash of
640 // this is sufficient to ensure these requests get sent to the same
641 // endpoint. The cookie is generated by hashing the source and
642 // destination ports and addresses so that multiple independent HTTP2
643 // streams on the same connection will independently receive the same
644 // cookie, even if they arrive at the Envoy simultaneously.
645 message Cookie {
646 option (udpa.annotations.versioning).previous_message_type =
647 "envoy.api.v2.route.RouteAction.HashPolicy.Cookie";
648
649 // The name of the cookie that will be used to obtain the hash key. If the
650 // cookie is not present and ttl below is not set, no hash will be
651 // produced.
652 string name = 1 [(validate.rules).string = {min_len: 1}];
653
654 // If specified, a cookie with the TTL will be generated if the cookie is
655 // not present. If the TTL is present and zero, the generated cookie will
656 // be a session cookie.
657 google.protobuf.Duration ttl = 2;
658
659 // The name of the path for the cookie. If no path is specified here, no path
660 // will be set for the cookie.
661 string path = 3;
662 }
663
664 message ConnectionProperties {
665 option (udpa.annotations.versioning).previous_message_type =
666 "envoy.api.v2.route.RouteAction.HashPolicy.ConnectionProperties";
667
668 // Hash on source IP address.
669 bool source_ip = 1;
670 }
671
672 message QueryParameter {
673 option (udpa.annotations.versioning).previous_message_type =
674 "envoy.api.v2.route.RouteAction.HashPolicy.QueryParameter";
675
676 // The name of the URL query parameter that will be used to obtain the hash
677 // key. If the parameter is not present, no hash will be produced. Query
678 // parameter names are case-sensitive.
679 string name = 1 [(validate.rules).string = {min_len: 1}];
680 }
681
682 message FilterState {
683 option (udpa.annotations.versioning).previous_message_type =
684 "envoy.api.v2.route.RouteAction.HashPolicy.FilterState";
685
686 // The name of the Object in the per-request filterState, which is an
687 // Envoy::Http::Hashable object. If there is no data associated with the key,
688 // or the stored object is not Envoy::Http::Hashable, no hash will be produced.
689 string key = 1 [(validate.rules).string = {min_len: 1}];
690 }
691
692 oneof policy_specifier {
693 option (validate.required) = true;
694
695 // Header hash policy.
696 Header header = 1;
697
698 // Cookie hash policy.
699 Cookie cookie = 2;
700
701 // Connection properties hash policy.
702 ConnectionProperties connection_properties = 3;
703
704 // Query parameter hash policy.
705 QueryParameter query_parameter = 5;
706
707 // Filter state hash policy.
708 FilterState filter_state = 6;
709 }
710
711 // The flag that short-circuits the hash computing. This field provides a
712 // 'fallback' style of configuration: "if a terminal policy doesn't work,
713 // fallback to rest of the policy list", it saves time when the terminal
714 // policy works.
715 //
716 // If true, and there is already a hash computed, ignore rest of the
717 // list of hash polices.
718 // For example, if the following hash methods are configured:
719 //
720 // ========= ========
721 // specifier terminal
722 // ========= ========
723 // Header A true
724 // Header B false
725 // Header C false
726 // ========= ========
727 //
728 // The generateHash process ends if policy "header A" generates a hash, as
729 // it's a terminal policy.
730 bool terminal = 4;
731 }
732
733 // Allows enabling and disabling upgrades on a per-route basis.
734 // This overrides any enabled/disabled upgrade filter chain specified in the
735 // HttpConnectionManager
736 // :ref:`upgrade_configs
737 // <envoy_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.upgrade_configs>`
738 // but does not affect any custom filter chain specified there.
739 message UpgradeConfig {
740 option (udpa.annotations.versioning).previous_message_type =
741 "envoy.api.v2.route.RouteAction.UpgradeConfig";
742
743 // Configuration for sending data upstream as a raw data payload. This is used for
744 // CONNECT requests, when forwarding CONNECT payload as raw TCP.
745 message ConnectConfig {
746 // If present, the proxy protocol header will be prepended to the CONNECT payload sent upstream.
747 core.v3.ProxyProtocolConfig proxy_protocol_config = 1;
748 }
749
750 // The case-insensitive name of this upgrade, e.g. "websocket".
751 // For each upgrade type present in upgrade_configs, requests with
752 // Upgrade: [upgrade_type] will be proxied upstream.
753 string upgrade_type = 1
754 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_VALUE strict: false}];
755
756 // Determines if upgrades are available on this route. Defaults to true.
757 google.protobuf.BoolValue enabled = 2;
758
759 // Configuration for sending data upstream as a raw data payload. This is used for
760 // CONNECT requests, when forwarding CONNECT payload as raw TCP.
761 // Note that CONNECT support is currently considered alpha in Envoy.
762 // [#comment:TODO(htuch): Replace the above comment with an alpha tag.
763 ConnectConfig connect_config = 3;
764 }
765
766 message MaxStreamDuration {
767 // Specifies the maximum duration allowed for streams on the route. If not specified, the value
768 // from the :ref:`max_stream_duration
769 // <envoy_api_field_config.core.v3.HttpProtocolOptions.max_stream_duration>` field in
770 // :ref:`HttpConnectionManager.common_http_protocol_options
771 // <envoy_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.common_http_protocol_options>`
772 // is used. If this field is set explicitly to zero, any
773 // HttpConnectionManager max_stream_duration timeout will be disabled for
774 // this route.
775 google.protobuf.Duration max_stream_duration = 1;
776
777 // If present, and the request contains a `grpc-timeout header
778 // <https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md>`_, use that value as the
779 // *max_stream_duration*, but limit the applied timeout to the maximum value specified here.
780 // If set to 0, the `grpc-timeout` header is used without modification.
781 google.protobuf.Duration grpc_timeout_header_max = 2;
782
783 // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by
784 // subtracting the provided duration from the header. This is useful for allowing Envoy to set
785 // its global timeout to be less than that of the deadline imposed by the calling client, which
786 // makes it more likely that Envoy will handle the timeout instead of having the call canceled
787 // by the client. If, after applying the offset, the resulting timeout is zero or negative,
788 // the stream will timeout immediately.
789 google.protobuf.Duration grpc_timeout_header_offset = 3;
790 }
791
792 reserved 12, 18, 19, 16, 22, 21, 10;
793
794 reserved "request_mirror_policy";
795
796 oneof cluster_specifier {
797 option (validate.required) = true;
798
799 // Indicates the upstream cluster to which the request should be routed
800 // to.
801 string cluster = 1 [(validate.rules).string = {min_len: 1}];
802
803 // Envoy will determine the cluster to route to by reading the value of the
804 // HTTP header named by cluster_header from the request headers. If the
805 // header is not found or the referenced cluster does not exist, Envoy will
806 // return a 404 response.
807 //
808 // .. attention::
809 //
810 // Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1
811 // *Host* header. Thus, if attempting to match on *Host*, match on *:authority* instead.
812 //
813 // .. note::
814 //
815 // If the header appears multiple times only the first value is used.
816 string cluster_header = 2
817 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
818
819 // Multiple upstream clusters can be specified for a given route. The
820 // request is routed to one of the upstream clusters based on weights
821 // assigned to each cluster. See
822 // :ref:`traffic splitting <config_http_conn_man_route_table_traffic_splitting_split>`
823 // for additional documentation.
824 WeightedCluster weighted_clusters = 3;
825 }
826
827 // The HTTP status code to use when configured cluster is not found.
828 // The default response code is 503 Service Unavailable.
829 ClusterNotFoundResponseCode cluster_not_found_response_code = 20
830 [(validate.rules).enum = {defined_only: true}];
831
832 // Optional endpoint metadata match criteria used by the subset load balancer. Only endpoints
833 // in the upstream cluster with metadata matching what's set in this field will be considered
834 // for load balancing. If using :ref:`weighted_clusters
835 // <envoy_api_field_config.route.v3.RouteAction.weighted_clusters>`, metadata will be merged, with values
836 // provided there taking precedence. The filter name should be specified as *envoy.lb*.
837 core.v3.Metadata metadata_match = 4;
838
839 // Indicates that during forwarding, the matched prefix (or path) should be
840 // swapped with this value. This option allows application URLs to be rooted
841 // at a different path from those exposed at the reverse proxy layer. The router filter will
842 // place the original path before rewrite into the :ref:`x-envoy-original-path
843 // <config_http_filters_router_x-envoy-original-path>` header.
844 //
845 // Only one of *prefix_rewrite* or
846 // :ref:`regex_rewrite <envoy_api_field_config.route.v3.RouteAction.regex_rewrite>`
847 // may be specified.
848 //
849 // .. attention::
850 //
851 // Pay careful attention to the use of trailing slashes in the
852 // :ref:`route's match <envoy_api_field_config.route.v3.Route.match>` prefix value.
853 // Stripping a prefix from a path requires multiple Routes to handle all cases. For example,
854 // rewriting */prefix* to */* and */prefix/etc* to */etc* cannot be done in a single
855 // :ref:`Route <envoy_api_msg_config.route.v3.Route>`, as shown by the below config entries:
856 //
857 // .. code-block:: yaml
858 //
859 // - match:
860 // prefix: "/prefix/"
861 // route:
862 // prefix_rewrite: "/"
863 // - match:
864 // prefix: "/prefix"
865 // route:
866 // prefix_rewrite: "/"
867 //
868 // Having above entries in the config, requests to */prefix* will be stripped to */*, while
869 // requests to */prefix/etc* will be stripped to */etc*.
870 string prefix_rewrite = 5
871 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
872
873 // Indicates that during forwarding, portions of the path that match the
874 // pattern should be rewritten, even allowing the substitution of capture
875 // groups from the pattern into the new path as specified by the rewrite
876 // substitution string. This is useful to allow application paths to be
877 // rewritten in a way that is aware of segments with variable content like
878 // identifiers. The router filter will place the original path as it was
879 // before the rewrite into the :ref:`x-envoy-original-path
880 // <config_http_filters_router_x-envoy-original-path>` header.
881 //
882 // Only one of :ref:`prefix_rewrite <envoy_api_field_config.route.v3.RouteAction.prefix_rewrite>`
883 // or *regex_rewrite* may be specified.
884 //
885 // Examples using Google's `RE2 <https://github.com/google/re2>`_ engine:
886 //
887 // * The path pattern ``^/service/([^/]+)(/.*)$`` paired with a substitution
888 // string of ``\2/instance/\1`` would transform ``/service/foo/v1/api``
889 // into ``/v1/api/instance/foo``.
890 //
891 // * The pattern ``one`` paired with a substitution string of ``two`` would
892 // transform ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/two/zzz``.
893 //
894 // * The pattern ``^(.*?)one(.*)$`` paired with a substitution string of
895 // ``\1two\2`` would replace only the first occurrence of ``one``,
896 // transforming path ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/one/zzz``.
897 //
898 // * The pattern ``(?i)/xxx/`` paired with a substitution string of ``/yyy/``
899 // would do a case-insensitive match and transform path ``/aaa/XxX/bbb`` to
900 // ``/aaa/yyy/bbb``.
901 type.matcher.v3.RegexMatchAndSubstitute regex_rewrite = 32;
902
903 oneof host_rewrite_specifier {
904 // Indicates that during forwarding, the host header will be swapped with
905 // this value.
906 string host_rewrite_literal = 6
907 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
908
909 // Indicates that during forwarding, the host header will be swapped with
910 // the hostname of the upstream host chosen by the cluster manager. This
911 // option is applicable only when the destination cluster for a route is of
912 // type *strict_dns* or *logical_dns*. Setting this to true with other cluster
913 // types has no effect.
914 google.protobuf.BoolValue auto_host_rewrite = 7;
915
916 // Indicates that during forwarding, the host header will be swapped with the content of given
917 // downstream or :ref:`custom <config_http_conn_man_headers_custom_request_headers>` header.
918 // If header value is empty, host header is left intact.
919 //
920 // .. attention::
921 //
922 // Pay attention to the potential security implications of using this option. Provided header
923 // must come from trusted source.
924 //
925 // .. note::
926 //
927 // If the header appears multiple times only the first value is used.
928 string host_rewrite_header = 29
929 [(validate.rules).string = {well_known_regex: HTTP_HEADER_NAME strict: false}];
930
931 // Indicates that during forwarding, the host header will be swapped with
932 // the result of the regex substitution executed on path value with query and fragment removed.
933 // This is useful for transitioning variable content between path segment and subdomain.
934 //
935 // For example with the following config:
936 //
937 // .. code-block:: yaml
938 //
939 // host_rewrite_path_regex:
940 // pattern:
941 // google_re2: {}
942 // regex: "^/(.+)/.+$"
943 // substitution: \1
944 //
945 // Would rewrite the host header to `envoyproxy.io` given the path `/envoyproxy.io/some/path`.
946 type.matcher.v3.RegexMatchAndSubstitute host_rewrite_path_regex = 35;
947 }
948
949 // Specifies the upstream timeout for the route. If not specified, the default is 15s. This
950 // spans between the point at which the entire downstream request (i.e. end-of-stream) has been
951 // processed and when the upstream response has been completely processed. A value of 0 will
952 // disable the route's timeout.
953 //
954 // .. note::
955 //
956 // This timeout includes all retries. See also
957 // :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`,
958 // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the
959 // :ref:`retry overview <arch_overview_http_routing_retry>`.
960 google.protobuf.Duration timeout = 8;
961
962 // Specifies the idle timeout for the route. If not specified, there is no per-route idle timeout,
963 // although the connection manager wide :ref:`stream_idle_timeout
964 // <envoy_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_idle_timeout>`
965 // will still apply. A value of 0 will completely disable the route's idle timeout, even if a
966 // connection manager stream idle timeout is configured.
967 //
968 // The idle timeout is distinct to :ref:`timeout
969 // <envoy_api_field_config.route.v3.RouteAction.timeout>`, which provides an upper bound
970 // on the upstream response time; :ref:`idle_timeout
971 // <envoy_api_field_config.route.v3.RouteAction.idle_timeout>` instead bounds the amount
972 // of time the request's stream may be idle.
973 //
974 // After header decoding, the idle timeout will apply on downstream and
975 // upstream request events. Each time an encode/decode event for headers or
976 // data is processed for the stream, the timer will be reset. If the timeout
977 // fires, the stream is terminated with a 408 Request Timeout error code if no
978 // upstream response header has been received, otherwise a stream reset
979 // occurs.
980 //
981 // If the :ref:`overload action <config_overload_manager_overload_actions>` "envoy.overload_actions.reduce_timeouts"
982 // is configured, this timeout is scaled according to the value for
983 // :ref:`HTTP_DOWNSTREAM_STREAM_IDLE <envoy_api_enum_value_config.overload.v3.ScaleTimersOverloadActionConfig.TimerType.HTTP_DOWNSTREAM_STREAM_IDLE>`.
984 google.protobuf.Duration idle_timeout = 24;
985
986 // Indicates that the route has a retry policy. Note that if this is set,
987 // it'll take precedence over the virtual host level retry policy entirely
988 // (e.g.: policies are not merged, most internal one becomes the enforced policy).
989 RetryPolicy retry_policy = 9;
990
991 // [#not-implemented-hide:]
992 // Specifies the configuration for retry policy extension. Note that if this is set, it'll take
993 // precedence over the virtual host level retry policy entirely (e.g.: policies are not merged,
994 // most internal one becomes the enforced policy). :ref:`Retry policy <envoy_api_field_config.route.v3.VirtualHost.retry_policy>`
995 // should not be set if this field is used.
996 google.protobuf.Any retry_policy_typed_config = 33;
997
998 // Indicates that the route has request mirroring policies.
999 repeated RequestMirrorPolicy request_mirror_policies = 30;
1000
1001 // Optionally specifies the :ref:`routing priority <arch_overview_http_routing_priority>`.
1002 core.v3.RoutingPriority priority = 11 [(validate.rules).enum = {defined_only: true}];
1003
1004 // Specifies a set of rate limit configurations that could be applied to the
1005 // route.
1006 repeated RateLimit rate_limits = 13;
1007
1008 // Specifies if the rate limit filter should include the virtual host rate
1009 // limits. By default, if the route configured rate limits, the virtual host
1010 // :ref:`rate_limits <envoy_api_field_config.route.v3.VirtualHost.rate_limits>` are not applied to the
1011 // request.
1012 //
1013 // This field is deprecated. Please use :ref:`vh_rate_limits <envoy_v3_api_field_extensions.filters.http.ratelimit.v3.RateLimitPerRoute.vh_rate_limits>`
1014 google.protobuf.BoolValue include_vh_rate_limits = 14 [deprecated = true];
1015
1016 // Specifies a list of hash policies to use for ring hash load balancing. Each
1017 // hash policy is evaluated individually and the combined result is used to
1018 // route the request. The method of combination is deterministic such that
1019 // identical lists of hash policies will produce the same hash. Since a hash
1020 // policy examines specific parts of a request, it can fail to produce a hash
1021 // (i.e. if the hashed header is not present). If (and only if) all configured
1022 // hash policies fail to generate a hash, no hash will be produced for
1023 // the route. In this case, the behavior is the same as if no hash policies
1024 // were specified (i.e. the ring hash load balancer will choose a random
1025 // backend). If a hash policy has the "terminal" attribute set to true, and
1026 // there is already a hash generated, the hash is returned immediately,
1027 // ignoring the rest of the hash policy list.
1028 repeated HashPolicy hash_policy = 15;
1029
1030 // Indicates that the route has a CORS policy.
1031 CorsPolicy cors = 17;
1032
1033 // Deprecated by :ref:`grpc_timeout_header_max <envoy_api_field_config.route.v3.RouteAction.MaxStreamDuration.grpc_timeout_header_max>`
1034 // If present, and the request is a gRPC request, use the
1035 // `grpc-timeout header <https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md>`_,
1036 // or its default value (infinity) instead of
1037 // :ref:`timeout <envoy_api_field_config.route.v3.RouteAction.timeout>`, but limit the applied timeout
1038 // to the maximum value specified here. If configured as 0, the maximum allowed timeout for
1039 // gRPC requests is infinity. If not configured at all, the `grpc-timeout` header is not used
1040 // and gRPC requests time out like any other requests using
1041 // :ref:`timeout <envoy_api_field_config.route.v3.RouteAction.timeout>` or its default.
1042 // This can be used to prevent unexpected upstream request timeouts due to potentially long
1043 // time gaps between gRPC request and response in gRPC streaming mode.
1044 //
1045 // .. note::
1046 //
1047 // If a timeout is specified using :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`, it takes
1048 // precedence over `grpc-timeout header <https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md>`_, when
1049 // both are present. See also
1050 // :ref:`config_http_filters_router_x-envoy-upstream-rq-timeout-ms`,
1051 // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms`, and the
1052 // :ref:`retry overview <arch_overview_http_routing_retry>`.
1053 google.protobuf.Duration max_grpc_timeout = 23 [deprecated = true];
1054
1055 // Deprecated by :ref:`grpc_timeout_header_offset <envoy_api_field_config.route.v3.RouteAction.MaxStreamDuration.grpc_timeout_header_offset>`.
1056 // If present, Envoy will adjust the timeout provided by the `grpc-timeout` header by subtracting
1057 // the provided duration from the header. This is useful in allowing Envoy to set its global
1058 // timeout to be less than that of the deadline imposed by the calling client, which makes it more
1059 // likely that Envoy will handle the timeout instead of having the call canceled by the client.
1060 // The offset will only be applied if the provided grpc_timeout is greater than the offset. This
1061 // ensures that the offset will only ever decrease the timeout and never set it to 0 (meaning
1062 // infinity).
1063 google.protobuf.Duration grpc_timeout_offset = 28 [deprecated = true];
1064
1065 repeated UpgradeConfig upgrade_configs = 25;
1066
1067 // If present, Envoy will try to follow an upstream redirect response instead of proxying the
1068 // response back to the downstream. An upstream redirect response is defined
1069 // by :ref:`redirect_response_codes
1070 // <envoy_api_field_config.route.v3.InternalRedirectPolicy.redirect_response_codes>`.
1071 InternalRedirectPolicy internal_redirect_policy = 34;
1072
1073 InternalRedirectAction internal_redirect_action = 26 [deprecated = true];
1074
1075 // An internal redirect is handled, iff the number of previous internal redirects that a
1076 // downstream request has encountered is lower than this value, and
1077 // :ref:`internal_redirect_action <envoy_api_field_config.route.v3.RouteAction.internal_redirect_action>`
1078 // is set to :ref:`HANDLE_INTERNAL_REDIRECT
1079 // <envoy_api_enum_value_config.route.v3.RouteAction.InternalRedirectAction.HANDLE_INTERNAL_REDIRECT>`
1080 // In the case where a downstream request is bounced among multiple routes by internal redirect,
1081 // the first route that hits this threshold, or has
1082 // :ref:`internal_redirect_action <envoy_api_field_config.route.v3.RouteAction.internal_redirect_action>`
1083 // set to
1084 // :ref:`PASS_THROUGH_INTERNAL_REDIRECT
1085 // <envoy_api_enum_value_config.route.v3.RouteAction.InternalRedirectAction.PASS_THROUGH_INTERNAL_REDIRECT>`
1086 // will pass the redirect back to downstream.
1087 //
1088 // If not specified, at most one redirect will be followed.
1089 google.protobuf.UInt32Value max_internal_redirects = 31 [deprecated = true];
1090
1091 // Indicates that the route has a hedge policy. Note that if this is set,
1092 // it'll take precedence over the virtual host level hedge policy entirely
1093 // (e.g.: policies are not merged, most internal one becomes the enforced policy).
1094 HedgePolicy hedge_policy = 27;
1095
1096 // Specifies the maximum stream duration for this route.
1097 MaxStreamDuration max_stream_duration = 36;
1098}
1099
1100// HTTP retry :ref:`architecture overview <arch_overview_http_routing_retry>`.
1101// [#next-free-field: 12]
1102message RetryPolicy {
1103 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RetryPolicy";
1104
1105 enum ResetHeaderFormat {
1106 SECONDS = 0;
1107 UNIX_TIMESTAMP = 1;
1108 }
1109
1110 message RetryPriority {
1111 option (udpa.annotations.versioning).previous_message_type =
1112 "envoy.api.v2.route.RetryPolicy.RetryPriority";
1113
1114 reserved 2;
1115
1116 reserved "config";
1117
1118 string name = 1 [(validate.rules).string = {min_len: 1}];
1119
1120 oneof config_type {
1121 google.protobuf.Any typed_config = 3;
1122 }
1123 }
1124
1125 message RetryHostPredicate {
1126 option (udpa.annotations.versioning).previous_message_type =
1127 "envoy.api.v2.route.RetryPolicy.RetryHostPredicate";
1128
1129 reserved 2;
1130
1131 reserved "config";
1132
1133 string name = 1 [(validate.rules).string = {min_len: 1}];
1134
1135 oneof config_type {
1136 google.protobuf.Any typed_config = 3;
1137 }
1138 }
1139
1140 message RetryBackOff {
1141 option (udpa.annotations.versioning).previous_message_type =
1142 "envoy.api.v2.route.RetryPolicy.RetryBackOff";
1143
1144 // Specifies the base interval between retries. This parameter is required and must be greater
1145 // than zero. Values less than 1 ms are rounded up to 1 ms.
1146 // See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion of Envoy's
1147 // back-off algorithm.
1148 google.protobuf.Duration base_interval = 1 [(validate.rules).duration = {
1149 required: true
1150 gt {}
1151 }];
1152
1153 // Specifies the maximum interval between retries. This parameter is optional, but must be
1154 // greater than or equal to the `base_interval` if set. The default is 10 times the
1155 // `base_interval`. See :ref:`config_http_filters_router_x-envoy-max-retries` for a discussion
1156 // of Envoy's back-off algorithm.
1157 google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}];
1158 }
1159
1160 message ResetHeader {
1161 // The name of the reset header.
1162 //
1163 // .. note::
1164 //
1165 // If the header appears multiple times only the first value is used.
1166 string name = 1
1167 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
1168
1169 // The format of the reset header.
1170 ResetHeaderFormat format = 2 [(validate.rules).enum = {defined_only: true}];
1171 }
1172
1173 // A retry back-off strategy that applies when the upstream server rate limits
1174 // the request.
1175 //
1176 // Given this configuration:
1177 //
1178 // .. code-block:: yaml
1179 //
1180 // rate_limited_retry_back_off:
1181 // reset_headers:
1182 // - name: Retry-After
1183 // format: SECONDS
1184 // - name: X-RateLimit-Reset
1185 // format: UNIX_TIMESTAMP
1186 // max_interval: "300s"
1187 //
1188 // The following algorithm will apply:
1189 //
1190 // 1. If the response contains the header ``Retry-After`` its value must be on
1191 // the form ``120`` (an integer that represents the number of seconds to
1192 // wait before retrying). If so, this value is used as the back-off interval.
1193 // 2. Otherwise, if the response contains the header ``X-RateLimit-Reset`` its
1194 // value must be on the form ``1595320702`` (an integer that represents the
1195 // point in time at which to retry, as a Unix timestamp in seconds). If so,
1196 // the current time is subtracted from this value and the result is used as
1197 // the back-off interval.
1198 // 3. Otherwise, Envoy will use the default
1199 // :ref:`exponential back-off <envoy_v3_api_field_config.route.v3.RetryPolicy.retry_back_off>`
1200 // strategy.
1201 //
1202 // No matter which format is used, if the resulting back-off interval exceeds
1203 // ``max_interval`` it is discarded and the next header in ``reset_headers``
1204 // is tried. If a request timeout is configured for the route it will further
1205 // limit how long the request will be allowed to run.
1206 //
1207 // To prevent many clients retrying at the same point in time jitter is added
1208 // to the back-off interval, so the resulting interval is decided by taking:
1209 // ``random(interval, interval * 1.5)``.
1210 //
1211 // .. attention::
1212 //
1213 // Configuring ``rate_limited_retry_back_off`` will not by itself cause a request
1214 // to be retried. You will still need to configure the right retry policy to match
1215 // the responses from the upstream server.
1216 message RateLimitedRetryBackOff {
1217 // Specifies the reset headers (like ``Retry-After`` or ``X-RateLimit-Reset``)
1218 // to match against the response. Headers are tried in order, and matched case
1219 // insensitive. The first header to be parsed successfully is used. If no headers
1220 // match the default exponential back-off is used instead.
1221 repeated ResetHeader reset_headers = 1 [(validate.rules).repeated = {min_items: 1}];
1222
1223 // Specifies the maximum back off interval that Envoy will allow. If a reset
1224 // header contains an interval longer than this then it will be discarded and
1225 // the next header will be tried. Defaults to 300 seconds.
1226 google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}];
1227 }
1228
1229 // Specifies the conditions under which retry takes place. These are the same
1230 // conditions documented for :ref:`config_http_filters_router_x-envoy-retry-on` and
1231 // :ref:`config_http_filters_router_x-envoy-retry-grpc-on`.
1232 string retry_on = 1;
1233
1234 // Specifies the allowed number of retries. This parameter is optional and
1235 // defaults to 1. These are the same conditions documented for
1236 // :ref:`config_http_filters_router_x-envoy-max-retries`.
1237 google.protobuf.UInt32Value num_retries = 2
1238 [(udpa.annotations.field_migrate).rename = "max_retries"];
1239
1240 // Specifies a non-zero upstream timeout per retry attempt. This parameter is optional. The
1241 // same conditions documented for
1242 // :ref:`config_http_filters_router_x-envoy-upstream-rq-per-try-timeout-ms` apply.
1243 //
1244 // .. note::
1245 //
1246 // If left unspecified, Envoy will use the global
1247 // :ref:`route timeout <envoy_api_field_config.route.v3.RouteAction.timeout>` for the request.
1248 // Consequently, when using a :ref:`5xx <config_http_filters_router_x-envoy-retry-on>` based
1249 // retry policy, a request that times out will not be retried as the total timeout budget
1250 // would have been exhausted.
1251 google.protobuf.Duration per_try_timeout = 3;
1252
1253 // Specifies an implementation of a RetryPriority which is used to determine the
1254 // distribution of load across priorities used for retries. Refer to
1255 // :ref:`retry plugin configuration <arch_overview_http_retry_plugins>` for more details.
1256 RetryPriority retry_priority = 4;
1257
1258 // Specifies a collection of RetryHostPredicates that will be consulted when selecting a host
1259 // for retries. If any of the predicates reject the host, host selection will be reattempted.
1260 // Refer to :ref:`retry plugin configuration <arch_overview_http_retry_plugins>` for more
1261 // details.
1262 repeated RetryHostPredicate retry_host_predicate = 5;
1263
1264 // The maximum number of times host selection will be reattempted before giving up, at which
1265 // point the host that was last selected will be routed to. If unspecified, this will default to
1266 // retrying once.
1267 int64 host_selection_retry_max_attempts = 6;
1268
1269 // HTTP status codes that should trigger a retry in addition to those specified by retry_on.
1270 repeated uint32 retriable_status_codes = 7;
1271
1272 // Specifies parameters that control exponential retry back off. This parameter is optional, in which case the
1273 // default base interval is 25 milliseconds or, if set, the current value of the
1274 // `upstream.base_retry_backoff_ms` runtime parameter. The default maximum interval is 10 times
1275 // the base interval. The documentation for :ref:`config_http_filters_router_x-envoy-max-retries`
1276 // describes Envoy's back-off algorithm.
1277 RetryBackOff retry_back_off = 8;
1278
1279 // Specifies parameters that control a retry back-off strategy that is used
1280 // when the request is rate limited by the upstream server. The server may
1281 // return a response header like ``Retry-After`` or ``X-RateLimit-Reset`` to
1282 // provide feedback to the client on how long to wait before retrying. If
1283 // configured, this back-off strategy will be used instead of the
1284 // default exponential back off strategy (configured using `retry_back_off`)
1285 // whenever a response includes the matching headers.
1286 RateLimitedRetryBackOff rate_limited_retry_back_off = 11;
1287
1288 // HTTP response headers that trigger a retry if present in the response. A retry will be
1289 // triggered if any of the header matches match the upstream response headers.
1290 // The field is only consulted if 'retriable-headers' retry policy is active.
1291 repeated HeaderMatcher retriable_headers = 9;
1292
1293 // HTTP headers which must be present in the request for retries to be attempted.
1294 repeated HeaderMatcher retriable_request_headers = 10;
1295}
1296
1297// HTTP request hedging :ref:`architecture overview <arch_overview_http_routing_hedging>`.
1298message HedgePolicy {
1299 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.HedgePolicy";
1300
1301 // Specifies the number of initial requests that should be sent upstream.
1302 // Must be at least 1.
1303 // Defaults to 1.
1304 // [#not-implemented-hide:]
1305 google.protobuf.UInt32Value initial_requests = 1 [(validate.rules).uint32 = {gte: 1}];
1306
1307 // Specifies a probability that an additional upstream request should be sent
1308 // on top of what is specified by initial_requests.
1309 // Defaults to 0.
1310 // [#not-implemented-hide:]
1311 type.v3.FractionalPercent additional_request_chance = 2;
1312
1313 // Indicates that a hedged request should be sent when the per-try timeout is hit.
1314 // This means that a retry will be issued without resetting the original request, leaving multiple upstream requests in flight.
1315 // The first request to complete successfully will be the one returned to the caller.
1316 //
1317 // * At any time, a successful response (i.e. not triggering any of the retry-on conditions) would be returned to the client.
1318 // * Before per-try timeout, an error response (per retry-on conditions) would be retried immediately or returned ot the client
1319 // if there are no more retries left.
1320 // * After per-try timeout, an error response would be discarded, as a retry in the form of a hedged request is already in progress.
1321 //
1322 // Note: For this to have effect, you must have a :ref:`RetryPolicy <envoy_api_msg_config.route.v3.RetryPolicy>` that retries at least
1323 // one error code and specifies a maximum number of retries.
1324 //
1325 // Defaults to false.
1326 bool hedge_on_per_try_timeout = 3;
1327}
1328
1329// [#next-free-field: 10]
1330message RedirectAction {
1331 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RedirectAction";
1332
1333 enum RedirectResponseCode {
1334 // Moved Permanently HTTP Status Code - 301.
1335 MOVED_PERMANENTLY = 0;
1336
1337 // Found HTTP Status Code - 302.
1338 FOUND = 1;
1339
1340 // See Other HTTP Status Code - 303.
1341 SEE_OTHER = 2;
1342
1343 // Temporary Redirect HTTP Status Code - 307.
1344 TEMPORARY_REDIRECT = 3;
1345
1346 // Permanent Redirect HTTP Status Code - 308.
1347 PERMANENT_REDIRECT = 4;
1348 }
1349
1350 // When the scheme redirection take place, the following rules apply:
1351 // 1. If the source URI scheme is `http` and the port is explicitly
1352 // set to `:80`, the port will be removed after the redirection
1353 // 2. If the source URI scheme is `https` and the port is explicitly
1354 // set to `:443`, the port will be removed after the redirection
1355 oneof scheme_rewrite_specifier {
1356 // The scheme portion of the URL will be swapped with "https".
1357 bool https_redirect = 4;
1358
1359 // The scheme portion of the URL will be swapped with this value.
1360 string scheme_redirect = 7;
1361 }
1362
1363 // The host portion of the URL will be swapped with this value.
1364 string host_redirect = 1
1365 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
1366
1367 // The port value of the URL will be swapped with this value.
1368 uint32 port_redirect = 8;
1369
1370 oneof path_rewrite_specifier {
1371 // The path portion of the URL will be swapped with this value.
1372 // Please note that query string in path_redirect will override the
1373 // request's query string and will not be stripped.
1374 //
1375 // For example, let's say we have the following routes:
1376 //
1377 // - match: { path: "/old-path-1" }
1378 // redirect: { path_redirect: "/new-path-1" }
1379 // - match: { path: "/old-path-2" }
1380 // redirect: { path_redirect: "/new-path-2", strip-query: "true" }
1381 // - match: { path: "/old-path-3" }
1382 // redirect: { path_redirect: "/new-path-3?foo=1", strip_query: "true" }
1383 //
1384 // 1. if request uri is "/old-path-1?bar=1", users will be redirected to "/new-path-1?bar=1"
1385 // 2. if request uri is "/old-path-2?bar=1", users will be redirected to "/new-path-2"
1386 // 3. if request uri is "/old-path-3?bar=1", users will be redirected to "/new-path-3?foo=1"
1387 string path_redirect = 2
1388 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
1389
1390 // Indicates that during redirection, the matched prefix (or path)
1391 // should be swapped with this value. This option allows redirect URLs be dynamically created
1392 // based on the request.
1393 //
1394 // .. attention::
1395 //
1396 // Pay attention to the use of trailing slashes as mentioned in
1397 // :ref:`RouteAction's prefix_rewrite <envoy_api_field_config.route.v3.RouteAction.prefix_rewrite>`.
1398 string prefix_rewrite = 5
1399 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}];
1400
1401 // Indicates that during redirect, portions of the path that match the
1402 // pattern should be rewritten, even allowing the substitution of capture
1403 // groups from the pattern into the new path as specified by the rewrite
1404 // substitution string. This is useful to allow application paths to be
1405 // rewritten in a way that is aware of segments with variable content like
1406 // identifiers.
1407 //
1408 // Examples using Google's `RE2 <https://github.com/google/re2>`_ engine:
1409 //
1410 // * The path pattern ``^/service/([^/]+)(/.*)$`` paired with a substitution
1411 // string of ``\2/instance/\1`` would transform ``/service/foo/v1/api``
1412 // into ``/v1/api/instance/foo``.
1413 //
1414 // * The pattern ``one`` paired with a substitution string of ``two`` would
1415 // transform ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/two/zzz``.
1416 //
1417 // * The pattern ``^(.*?)one(.*)$`` paired with a substitution string of
1418 // ``\1two\2`` would replace only the first occurrence of ``one``,
1419 // transforming path ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/one/zzz``.
1420 //
1421 // * The pattern ``(?i)/xxx/`` paired with a substitution string of ``/yyy/``
1422 // would do a case-insensitive match and transform path ``/aaa/XxX/bbb`` to
1423 // ``/aaa/yyy/bbb``.
1424 type.matcher.v3.RegexMatchAndSubstitute regex_rewrite = 9;
1425 }
1426
1427 // The HTTP status code to use in the redirect response. The default response
1428 // code is MOVED_PERMANENTLY (301).
1429 RedirectResponseCode response_code = 3 [(validate.rules).enum = {defined_only: true}];
1430
1431 // Indicates that during redirection, the query portion of the URL will
1432 // be removed. Default value is false.
1433 bool strip_query = 6;
1434}
1435
1436message DirectResponseAction {
1437 option (udpa.annotations.versioning).previous_message_type =
1438 "envoy.api.v2.route.DirectResponseAction";
1439
1440 // Specifies the HTTP response status to be returned.
1441 uint32 status = 1 [(validate.rules).uint32 = {lt: 600 gte: 100}];
1442
1443 // Specifies the content of the response body. If this setting is omitted,
1444 // no body is included in the generated response.
1445 //
1446 // .. note::
1447 //
1448 // Headers can be specified using *response_headers_to_add* in the enclosing
1449 // :ref:`envoy_api_msg_config.route.v3.Route`, :ref:`envoy_api_msg_config.route.v3.RouteConfiguration` or
1450 // :ref:`envoy_api_msg_config.route.v3.VirtualHost`.
1451 core.v3.DataSource body = 2;
1452}
1453
1454message Decorator {
1455 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Decorator";
1456
1457 // The operation name associated with the request matched to this route. If tracing is
1458 // enabled, this information will be used as the span name reported for this request.
1459 //
1460 // .. note::
1461 //
1462 // For ingress (inbound) requests, or egress (outbound) responses, this value may be overridden
1463 // by the :ref:`x-envoy-decorator-operation
1464 // <config_http_filters_router_x-envoy-decorator-operation>` header.
1465 string operation = 1 [(validate.rules).string = {min_len: 1}];
1466
1467 // Whether the decorated details should be propagated to the other party. The default is true.
1468 google.protobuf.BoolValue propagate = 2;
1469}
1470
1471message Tracing {
1472 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.Tracing";
1473
1474 // Target percentage of requests managed by this HTTP connection manager that will be force
1475 // traced if the :ref:`x-client-trace-id <config_http_conn_man_headers_x-client-trace-id>`
1476 // header is set. This field is a direct analog for the runtime variable
1477 // 'tracing.client_sampling' in the :ref:`HTTP Connection Manager
1478 // <config_http_conn_man_runtime>`.
1479 // Default: 100%
1480 type.v3.FractionalPercent client_sampling = 1;
1481
1482 // Target percentage of requests managed by this HTTP connection manager that will be randomly
1483 // selected for trace generation, if not requested by the client or not forced. This field is
1484 // a direct analog for the runtime variable 'tracing.random_sampling' in the
1485 // :ref:`HTTP Connection Manager <config_http_conn_man_runtime>`.
1486 // Default: 100%
1487 type.v3.FractionalPercent random_sampling = 2;
1488
1489 // Target percentage of requests managed by this HTTP connection manager that will be traced
1490 // after all other sampling checks have been applied (client-directed, force tracing, random
1491 // sampling). This field functions as an upper limit on the total configured sampling rate. For
1492 // instance, setting client_sampling to 100% but overall_sampling to 1% will result in only 1%
1493 // of client requests with the appropriate headers to be force traced. This field is a direct
1494 // analog for the runtime variable 'tracing.global_enabled' in the
1495 // :ref:`HTTP Connection Manager <config_http_conn_man_runtime>`.
1496 // Default: 100%
1497 type.v3.FractionalPercent overall_sampling = 3;
1498
1499 // A list of custom tags with unique tag name to create tags for the active span.
1500 // It will take effect after merging with the :ref:`corresponding configuration
1501 // <envoy_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.Tracing.custom_tags>`
1502 // configured in the HTTP connection manager. If two tags with the same name are configured
1503 // each in the HTTP connection manager and the route level, the one configured here takes
1504 // priority.
1505 repeated type.tracing.v3.CustomTag custom_tags = 4;
1506}
1507
1508// A virtual cluster is a way of specifying a regex matching rule against
1509// certain important endpoints such that statistics are generated explicitly for
1510// the matched requests. The reason this is useful is that when doing
1511// prefix/path matching Envoy does not always know what the application
1512// considers to be an endpoint. Thus, it’s impossible for Envoy to generically
1513// emit per endpoint statistics. However, often systems have highly critical
1514// endpoints that they wish to get “perfect” statistics on. Virtual cluster
1515// statistics are perfect in the sense that they are emitted on the downstream
1516// side such that they include network level failures.
1517//
1518// Documentation for :ref:`virtual cluster statistics <config_http_filters_router_vcluster_stats>`.
1519//
1520// .. note::
1521//
1522// Virtual clusters are a useful tool, but we do not recommend setting up a virtual cluster for
1523// every application endpoint. This is both not easily maintainable and as well the matching and
1524// statistics output are not free.
1525message VirtualCluster {
1526 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.VirtualCluster";
1527
1528 reserved 1, 3;
1529
1530 reserved "pattern", "method";
1531
1532 // Specifies a list of header matchers to use for matching requests. Each specified header must
1533 // match. The pseudo-headers `:path` and `:method` can be used to match the request path and
1534 // method, respectively.
1535 repeated HeaderMatcher headers = 4;
1536
1537 // Specifies the name of the virtual cluster. The virtual cluster name as well
1538 // as the virtual host name are used when emitting statistics. The statistics are emitted by the
1539 // router filter and are documented :ref:`here <config_http_filters_router_stats>`.
1540 string name = 2 [(validate.rules).string = {min_len: 1}];
1541}
1542
1543// Global rate limiting :ref:`architecture overview <arch_overview_global_rate_limit>`.
1544message RateLimit {
1545 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit";
1546
1547 // [#next-free-field: 10]
1548 message Action {
1549 option (udpa.annotations.versioning).previous_message_type =
1550 "envoy.api.v2.route.RateLimit.Action";
1551
1552 // The following descriptor entry is appended to the descriptor:
1553 //
1554 // .. code-block:: cpp
1555 //
1556 // ("source_cluster", "<local service cluster>")
1557 //
1558 // <local service cluster> is derived from the :option:`--service-cluster` option.
1559 message SourceCluster {
1560 option (udpa.annotations.versioning).previous_message_type =
1561 "envoy.api.v2.route.RateLimit.Action.SourceCluster";
1562 }
1563
1564 // The following descriptor entry is appended to the descriptor:
1565 //
1566 // .. code-block:: cpp
1567 //
1568 // ("destination_cluster", "<routed target cluster>")
1569 //
1570 // Once a request matches against a route table rule, a routed cluster is determined by one of
1571 // the following :ref:`route table configuration <envoy_api_msg_config.route.v3.RouteConfiguration>`
1572 // settings:
1573 //
1574 // * :ref:`cluster <envoy_api_field_config.route.v3.RouteAction.cluster>` indicates the upstream cluster
1575 // to route to.
1576 // * :ref:`weighted_clusters <envoy_api_field_config.route.v3.RouteAction.weighted_clusters>`
1577 // chooses a cluster randomly from a set of clusters with attributed weight.
1578 // * :ref:`cluster_header <envoy_api_field_config.route.v3.RouteAction.cluster_header>` indicates which
1579 // header in the request contains the target cluster.
1580 message DestinationCluster {
1581 option (udpa.annotations.versioning).previous_message_type =
1582 "envoy.api.v2.route.RateLimit.Action.DestinationCluster";
1583 }
1584
1585 // The following descriptor entry is appended when a header contains a key that matches the
1586 // *header_name*:
1587 //
1588 // .. code-block:: cpp
1589 //
1590 // ("<descriptor_key>", "<header_value_queried_from_header>")
1591 message RequestHeaders {
1592 option (udpa.annotations.versioning).previous_message_type =
1593 "envoy.api.v2.route.RateLimit.Action.RequestHeaders";
1594
1595 // The header name to be queried from the request headers. The header’s
1596 // value is used to populate the value of the descriptor entry for the
1597 // descriptor_key.
1598 string header_name = 1
1599 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
1600
1601 // The key to use in the descriptor entry.
1602 string descriptor_key = 2 [(validate.rules).string = {min_len: 1}];
1603
1604 // If set to true, Envoy skips the descriptor while calling rate limiting service
1605 // when header is not present in the request. By default it skips calling the
1606 // rate limiting service if this header is not present in the request.
1607 bool skip_if_absent = 3;
1608 }
1609
1610 // The following descriptor entry is appended to the descriptor and is populated using the
1611 // trusted address from :ref:`x-forwarded-for <config_http_conn_man_headers_x-forwarded-for>`:
1612 //
1613 // .. code-block:: cpp
1614 //
1615 // ("remote_address", "<trusted address from x-forwarded-for>")
1616 message RemoteAddress {
1617 option (udpa.annotations.versioning).previous_message_type =
1618 "envoy.api.v2.route.RateLimit.Action.RemoteAddress";
1619 }
1620
1621 // The following descriptor entry is appended to the descriptor:
1622 //
1623 // .. code-block:: cpp
1624 //
1625 // ("generic_key", "<descriptor_value>")
1626 message GenericKey {
1627 option (udpa.annotations.versioning).previous_message_type =
1628 "envoy.api.v2.route.RateLimit.Action.GenericKey";
1629
1630 // The value to use in the descriptor entry.
1631 string descriptor_value = 1 [(validate.rules).string = {min_len: 1}];
1632
1633 // An optional key to use in the descriptor entry. If not set it defaults
1634 // to 'generic_key' as the descriptor key.
1635 string descriptor_key = 2;
1636 }
1637
1638 // The following descriptor entry is appended to the descriptor:
1639 //
1640 // .. code-block:: cpp
1641 //
1642 // ("header_match", "<descriptor_value>")
1643 message HeaderValueMatch {
1644 option (udpa.annotations.versioning).previous_message_type =
1645 "envoy.api.v2.route.RateLimit.Action.HeaderValueMatch";
1646
1647 // The value to use in the descriptor entry.
1648 string descriptor_value = 1 [(validate.rules).string = {min_len: 1}];
1649
1650 // If set to true, the action will append a descriptor entry when the
1651 // request matches the headers. If set to false, the action will append a
1652 // descriptor entry when the request does not match the headers. The
1653 // default value is true.
1654 google.protobuf.BoolValue expect_match = 2;
1655
1656 // Specifies a set of headers that the rate limit action should match
1657 // on. The action will check the request’s headers against all the
1658 // specified headers in the config. A match will happen if all the
1659 // headers in the config are present in the request with the same values
1660 // (or based on presence if the value field is not in the config).
1661 repeated HeaderMatcher headers = 3 [(validate.rules).repeated = {min_items: 1}];
1662 }
1663
1664 // The following descriptor entry is appended when the
1665 // :ref:`dynamic metadata <well_known_dynamic_metadata>` contains a key value:
1666 //
1667 // .. code-block:: cpp
1668 //
1669 // ("<descriptor_key>", "<value_queried_from_dynamic_metadata>")
1670 //
1671 // .. attention::
1672 // This action has been deprecated in favor of the :ref:`metadata <envoy_api_msg_config.route.v3.RateLimit.Action.MetaData>` action
1673 message DynamicMetaData {
1674 // The key to use in the descriptor entry.
1675 string descriptor_key = 1 [(validate.rules).string = {min_len: 1}];
1676
1677 // Metadata struct that defines the key and path to retrieve the string value. A match will
1678 // only happen if the value in the dynamic metadata is of type string.
1679 type.metadata.v3.MetadataKey metadata_key = 2 [(validate.rules).message = {required: true}];
1680
1681 // An optional value to use if *metadata_key* is empty. If not set and
1682 // no value is present under the metadata_key then no descriptor is generated.
1683 string default_value = 3;
1684 }
1685
1686 // The following descriptor entry is appended when the metadata contains a key value:
1687 //
1688 // .. code-block:: cpp
1689 //
1690 // ("<descriptor_key>", "<value_queried_from_metadata>")
1691 message MetaData {
1692 enum Source {
1693 // Query :ref:`dynamic metadata <well_known_dynamic_metadata>`
1694 DYNAMIC = 0;
1695
1696 // Query :ref:`route entry metadata <envoy_api_field_config.route.v3.Route.metadata>`
1697 ROUTE_ENTRY = 1;
1698 }
1699
1700 // The key to use in the descriptor entry.
1701 string descriptor_key = 1 [(validate.rules).string = {min_len: 1}];
1702
1703 // Metadata struct that defines the key and path to retrieve the string value. A match will
1704 // only happen if the value in the metadata is of type string.
1705 type.metadata.v3.MetadataKey metadata_key = 2 [(validate.rules).message = {required: true}];
1706
1707 // An optional value to use if *metadata_key* is empty. If not set and
1708 // no value is present under the metadata_key then no descriptor is generated.
1709 string default_value = 3;
1710
1711 // Source of metadata
1712 Source source = 4 [(validate.rules).enum = {defined_only: true}];
1713 }
1714
1715 oneof action_specifier {
1716 option (validate.required) = true;
1717
1718 // Rate limit on source cluster.
1719 SourceCluster source_cluster = 1;
1720
1721 // Rate limit on destination cluster.
1722 DestinationCluster destination_cluster = 2;
1723
1724 // Rate limit on request headers.
1725 RequestHeaders request_headers = 3;
1726
1727 // Rate limit on remote address.
1728 RemoteAddress remote_address = 4;
1729
1730 // Rate limit on a generic key.
1731 GenericKey generic_key = 5;
1732
1733 // Rate limit on the existence of request headers.
1734 HeaderValueMatch header_value_match = 6;
1735
1736 // Rate limit on dynamic metadata.
1737 //
1738 // .. attention::
1739 // This field has been deprecated in favor of the :ref:`metadata <envoy_api_field_config.route.v3.RateLimit.Action.metadata>` field
1740 DynamicMetaData dynamic_metadata = 7
1741 [deprecated = true, (envoy.annotations.disallowed_by_default) = true];
1742
1743 // Rate limit on metadata.
1744 MetaData metadata = 8;
1745
1746 // Rate limit descriptor extension. See the rate limit descriptor extensions documentation.
1747 core.v3.TypedExtensionConfig extension = 9;
1748 }
1749 }
1750
1751 message Override {
1752 // Fetches the override from the dynamic metadata.
1753 message DynamicMetadata {
1754 // Metadata struct that defines the key and path to retrieve the struct value.
1755 // The value must be a struct containing an integer "requests_per_unit" property
1756 // and a "unit" property with a value parseable to :ref:`RateLimitUnit
1757 // enum <envoy_api_enum_type.v3.RateLimitUnit>`
1758 type.metadata.v3.MetadataKey metadata_key = 1 [(validate.rules).message = {required: true}];
1759 }
1760
1761 oneof override_specifier {
1762 option (validate.required) = true;
1763
1764 // Limit override from dynamic metadata.
1765 DynamicMetadata dynamic_metadata = 1;
1766 }
1767 }
1768
1769 // Refers to the stage set in the filter. The rate limit configuration only
1770 // applies to filters with the same stage number. The default stage number is
1771 // 0.
1772 //
1773 // .. note::
1774 //
1775 // The filter supports a range of 0 - 10 inclusively for stage numbers.
1776 google.protobuf.UInt32Value stage = 1 [(validate.rules).uint32 = {lte: 10}];
1777
1778 // The key to be set in runtime to disable this rate limit configuration.
1779 string disable_key = 2;
1780
1781 // A list of actions that are to be applied for this rate limit configuration.
1782 // Order matters as the actions are processed sequentially and the descriptor
1783 // is composed by appending descriptor entries in that sequence. If an action
1784 // cannot append a descriptor entry, no descriptor is generated for the
1785 // configuration. See :ref:`composing actions
1786 // <config_http_filters_rate_limit_composing_actions>` for additional documentation.
1787 repeated Action actions = 3 [(validate.rules).repeated = {min_items: 1}];
1788
1789 // An optional limit override to be appended to the descriptor produced by this
1790 // rate limit configuration. If the override value is invalid or cannot be resolved
1791 // from metadata, no override is provided. See :ref:`rate limit override
1792 // <config_http_filters_rate_limit_rate_limit_override>` for more information.
1793 Override limit = 4;
1794}
1795
1796// .. attention::
1797//
1798// Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host*
1799// header. Thus, if attempting to match on *Host*, match on *:authority* instead.
1800//
1801// .. attention::
1802//
1803// To route on HTTP method, use the special HTTP/2 *:method* header. This works for both
1804// HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g.,
1805//
1806// .. code-block:: json
1807//
1808// {
1809// "name": ":method",
1810// "exact_match": "POST"
1811// }
1812//
1813// .. attention::
1814// In the absence of any header match specifier, match will default to :ref:`present_match
1815// <envoy_api_field_config.route.v3.HeaderMatcher.present_match>`. i.e, a request that has the :ref:`name
1816// <envoy_api_field_config.route.v3.HeaderMatcher.name>` header will match, regardless of the header's
1817// value.
1818//
1819// [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.]
1820// [#next-free-field: 13]
1821message HeaderMatcher {
1822 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.HeaderMatcher";
1823
1824 reserved 2, 3, 5;
1825
1826 reserved "regex_match";
1827
1828 // Specifies the name of the header in the request.
1829 string name = 1
1830 [(validate.rules).string = {min_len: 1 well_known_regex: HTTP_HEADER_NAME strict: false}];
1831
1832 // Specifies how the header match will be performed to route the request.
1833 oneof header_match_specifier {
1834 // If specified, header match will be performed based on the value of the header.
1835 string exact_match = 4;
1836
1837 // If specified, this regex string is a regular expression rule which implies the entire request
1838 // header value must match the regex. The rule will not match if only a subsequence of the
1839 // request header value matches the regex.
1840 type.matcher.v3.RegexMatcher safe_regex_match = 11;
1841
1842 // If specified, header match will be performed based on range.
1843 // The rule will match if the request header value is within this range.
1844 // The entire request header value must represent an integer in base 10 notation: consisting of
1845 // an optional plus or minus sign followed by a sequence of digits. The rule will not match if
1846 // the header value does not represent an integer. Match will fail for empty values, floating
1847 // point numbers or if only a subsequence of the header value is an integer.
1848 //
1849 // Examples:
1850 //
1851 // * For range [-10,0), route will match for header value -1, but not for 0, "somestring", 10.9,
1852 // "-1somestring"
1853 type.v3.Int64Range range_match = 6;
1854
1855 // If specified, header match will be performed based on whether the header is in the
1856 // request.
1857 bool present_match = 7;
1858
1859 // If specified, header match will be performed based on the prefix of the header value.
1860 // Note: empty prefix is not allowed, please use present_match instead.
1861 //
1862 // Examples:
1863 //
1864 // * The prefix *abcd* matches the value *abcdxyz*, but not for *abcxyz*.
1865 string prefix_match = 9 [(validate.rules).string = {min_len: 1}];
1866
1867 // If specified, header match will be performed based on the suffix of the header value.
1868 // Note: empty suffix is not allowed, please use present_match instead.
1869 //
1870 // Examples:
1871 //
1872 // * The suffix *abcd* matches the value *xyzabcd*, but not for *xyzbcd*.
1873 string suffix_match = 10 [(validate.rules).string = {min_len: 1}];
1874
1875 // If specified, header match will be performed based on whether the header value contains
1876 // the given value or not.
1877 // Note: empty contains match is not allowed, please use present_match instead.
1878 //
1879 // Examples:
1880 //
1881 // * The value *abcd* matches the value *xyzabcdpqr*, but not for *xyzbcdpqr*.
1882 string contains_match = 12 [(validate.rules).string = {min_len: 1}];
1883 }
1884
1885 // If specified, the match result will be inverted before checking. Defaults to false.
1886 //
1887 // Examples:
1888 //
1889 // * The regex ``\d{3}`` does not match the value *1234*, so it will match when inverted.
1890 // * The range [-10,0) will match the value -1, so it will not match when inverted.
1891 bool invert_match = 8;
1892}
1893
1894// Query parameter matching treats the query string of a request's :path header
1895// as an ampersand-separated list of keys and/or key=value elements.
1896// [#next-free-field: 7]
1897message QueryParameterMatcher {
1898 option (udpa.annotations.versioning).previous_message_type =
1899 "envoy.api.v2.route.QueryParameterMatcher";
1900
1901 reserved 3, 4;
1902
1903 reserved "value", "regex";
1904
1905 // Specifies the name of a key that must be present in the requested
1906 // *path*'s query string.
1907 string name = 1 [(validate.rules).string = {min_len: 1 max_bytes: 1024}];
1908
1909 oneof query_parameter_match_specifier {
1910 // Specifies whether a query parameter value should match against a string.
1911 type.matcher.v3.StringMatcher string_match = 5 [(validate.rules).message = {required: true}];
1912
1913 // Specifies whether a query parameter should be present.
1914 bool present_match = 6;
1915 }
1916}
1917
1918// HTTP Internal Redirect :ref:`architecture overview <arch_overview_internal_redirects>`.
1919message InternalRedirectPolicy {
1920 // An internal redirect is not handled, unless the number of previous internal redirects that a
1921 // downstream request has encountered is lower than this value.
1922 // In the case where a downstream request is bounced among multiple routes by internal redirect,
1923 // the first route that hits this threshold, or does not set :ref:`internal_redirect_policy
1924 // <envoy_api_field_config.route.v3.RouteAction.internal_redirect_policy>`
1925 // will pass the redirect back to downstream.
1926 //
1927 // If not specified, at most one redirect will be followed.
1928 google.protobuf.UInt32Value max_internal_redirects = 1;
1929
1930 // Defines what upstream response codes are allowed to trigger internal redirect. If unspecified,
1931 // only 302 will be treated as internal redirect.
1932 // Only 301, 302, 303, 307 and 308 are valid values. Any other codes will be ignored.
1933 repeated uint32 redirect_response_codes = 2 [(validate.rules).repeated = {max_items: 5}];
1934
1935 // Specifies a list of predicates that are queried when an upstream response is deemed
1936 // to trigger an internal redirect by all other criteria. Any predicate in the list can reject
1937 // the redirect, causing the response to be proxied to downstream.
1938 repeated core.v3.TypedExtensionConfig predicates = 3;
1939
1940 // Allow internal redirect to follow a target URI with a different scheme than the value of
1941 // x-forwarded-proto. The default is false.
1942 bool allow_cross_scheme_redirect = 4;
1943}
View as plain text