mirror of https://github.com/istio/istio.io.git
1837 lines
53 KiB
HTML
1837 lines
53 KiB
HTML
---
|
|
title: Route Rules v1alpha1 (deprecated)
|
|
description: Configuration affecting traffic routing
|
|
location: https://istio.io/docs/reference/config/istio.routing.v1alpha1.html
|
|
layout: protoc-gen-docs
|
|
generator: protoc-gen-docs
|
|
redirect_from: /docs/reference/config/traffic-rules/routing-rules.html
|
|
number_of_entries: 28
|
|
---
|
|
<p><strong>Note: This version of the traffic management API has been deprecated and will
|
|
not be supported after Istio 0.8.</strong></p>
|
|
|
|
<p>Configuration affecting traffic routing. Here are a few terms useful to define
|
|
in the context of routing rules.</p>
|
|
|
|
<p><em>Service</em> is a unit of an application with a unique name that other services
|
|
use to refer to the functionality being called. Service instances are
|
|
pods/VMs/containers that implement the service.</p>
|
|
|
|
<p><em>Service versions</em> - In a continuous deployment scenario, for a given service,
|
|
there can be multiple sets of instances running potentially different
|
|
variants of the application binary. These variants are not necessarily
|
|
different API versions. They could be iterative changes to the same service,
|
|
deployed in different environments (prod, staging, dev, etc.). Common
|
|
scenarios where this occurs include A/B testing, canary rollouts, etc. The
|
|
choice of a particular version can be decided based on various criterion
|
|
(headers, url, etc.) and/or by weights assigned to each version. Each
|
|
service has a default version consisting of all its instances.</p>
|
|
|
|
<p><em>Source</em> - downstream client (browser or another service) calling the
|
|
Envoy proxy/sidecar (typically to reach another service).</p>
|
|
|
|
<p><em>Destination</em> - The remote upstream service to which the Envoy proxy/sidecar is
|
|
talking to, on behalf of the source service. There can be one or more
|
|
service versions for a given service (see the discussion on versions above).
|
|
Envoy would choose the version based on various routing rules.</p>
|
|
|
|
<p><em>Access model</em> - Applications address only the destination service
|
|
without knowledge of individual service versions. The actual choice of
|
|
the version is determined by Envoy, enabling the application code to
|
|
decouple itself from the evolution of dependent services.</p>
|
|
|
|
<h2 id="CircuitBreaker">CircuitBreaker</h2>
|
|
<section>
|
|
<p>Circuit breaker configuration for Envoy. The circuit breaker
|
|
implementation is fine-grained in that it tracks the success/failure
|
|
rates of individual hosts in the load balancing pool. Hosts that
|
|
continually return errors for API calls are ejected from the pool for a
|
|
pre-defined period of time.
|
|
See Envoy’s
|
|
<a href="https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/circuit_breaking">circuit breaker</a>
|
|
and <a href="https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/outlier">outlier detection</a>
|
|
for more details.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="CircuitBreaker.simple_cb" class="oneof oneof-start">
|
|
<td><code>simpleCb</code></td>
|
|
<td><code><a href="#CircuitBreaker.SimpleCircuitBreakerPolicy">CircuitBreaker.SimpleCircuitBreakerPolicy (oneof)</a></code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.custom" class="oneof">
|
|
<td><code>custom</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any">google.protobuf.Any (oneof)</a></code></td>
|
|
<td>
|
|
<p>(– For proxies that support custom circuit breaker policies. –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="CircuitBreaker.SimpleCircuitBreakerPolicy">CircuitBreaker.SimpleCircuitBreakerPolicy</h2>
|
|
<section>
|
|
<p>A simple circuit breaker can be set based on a number of criteria such as
|
|
connection and request limits. For example, the following destination
|
|
policy sets a limit of 100 connections to “reviews” service version
|
|
“v1” backends.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: reviews-cb-policy
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: reviews
|
|
labels:
|
|
version: v1
|
|
circuitBreaker:
|
|
simpleCb:
|
|
maxConnections: 100
|
|
</code></pre>
|
|
|
|
<p>The following destination policy sets a limit of 100 connections and
|
|
1000 concurrent requests, with no more than 10 req/connection to
|
|
“reviews” service version “v1” backends. In addition, it configures
|
|
hosts to be scanned every 5 mins, such that any host that fails 7
|
|
consecutive times with 5XX error code will be ejected for 15 minutes.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: reviews-cb-policy
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: reviews
|
|
labels:
|
|
version: v1
|
|
circuitBreaker:
|
|
simpleCb:
|
|
maxConnections: 100
|
|
httpMaxRequests: 1000
|
|
httpMaxRequestsPerConnection: 10
|
|
httpConsecutiveErrors: 7
|
|
sleepWindow: 15m
|
|
httpDetectionInterval: 5m
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.max_connections">
|
|
<td><code>maxConnections</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Maximum number of connections to a backend.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.http_max_pending_requests">
|
|
<td><code>httpMaxPendingRequests</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Maximum number of pending requests to a backend. Default 1024</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.http_max_requests">
|
|
<td><code>httpMaxRequests</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Maximum number of requests to a backend. Default 1024</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.sleep_window">
|
|
<td><code>sleepWindow</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>Minimum time the circuit will be open. format: 1h/1m/1s/1ms. MUST
|
|
BE >=1ms. Default is 30s.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.http_consecutive_errors">
|
|
<td><code>httpConsecutiveErrors</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Number of 5XX errors before circuit is opened. Defaults to 5.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.http_detection_interval">
|
|
<td><code>httpDetectionInterval</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>Time interval between ejection sweep analysis. format:
|
|
1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.http_max_requests_per_connection">
|
|
<td><code>httpMaxRequestsPerConnection</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Maximum number of requests per connection to a backend. Setting this
|
|
parameter to 1 disables keep alive.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.http_max_ejection_percent">
|
|
<td><code>httpMaxEjectionPercent</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Maximum % of hosts in the load balancing pool for the destination
|
|
service that can be ejected by the circuit breaker. Defaults to
|
|
10%.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CircuitBreaker.SimpleCircuitBreakerPolicy.http_max_retries">
|
|
<td><code>httpMaxRetries</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>Maximum number of retries that can be outstanding to all hosts in a
|
|
cluster at a given time. Defaults to 3.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="CorsPolicy">CorsPolicy</h2>
|
|
<section>
|
|
<p>Describes the Cross-Origin Resource Sharing (CORS) policy, for a given
|
|
service. Refer to
|
|
https://developer.mozilla.org/en-US/docs/Web/HTTP/Access<em>control</em>CORS
|
|
for further details about cross origin resource sharing. For example,
|
|
the following rule restricts cross origin requests to those originating
|
|
from example.com domain using HTTP POST/GET, and sets the
|
|
Access-Control-Allow-Credentials header to false. In addition, it only exposes
|
|
X-Foo-bar header and sets an expiry period of 1 day.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: ratings
|
|
route:
|
|
- labels:
|
|
version: v1
|
|
corsPolicy:
|
|
allowOrigin:
|
|
- example.com
|
|
allowMethods:
|
|
- POST
|
|
- GET
|
|
allowCredentials: false
|
|
allowHeaders:
|
|
- X-Foo-Bar
|
|
maxAge: "1d"
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="CorsPolicy.allow_origin">
|
|
<td><code>allowOrigin</code></td>
|
|
<td><code>string[]</code></td>
|
|
<td>
|
|
<p>The list of origins that are allowed to perform CORS requests. The content will
|
|
be serialized into the Access-Control-Allow-Origin header. Wildcard * will allow
|
|
all origins.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CorsPolicy.allow_methods">
|
|
<td><code>allowMethods</code></td>
|
|
<td><code>string[]</code></td>
|
|
<td>
|
|
<p>List of HTTP methods allowed to access the resource. The content will
|
|
be serialized into the Access-Control-Allow-Methods header.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CorsPolicy.allow_headers">
|
|
<td><code>allowHeaders</code></td>
|
|
<td><code>string[]</code></td>
|
|
<td>
|
|
<p>List of HTTP headers that can be used when requesting the
|
|
resource. Serialized to Access-Control-Allow-Methods header.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CorsPolicy.expose_headers">
|
|
<td><code>exposeHeaders</code></td>
|
|
<td><code>string[]</code></td>
|
|
<td>
|
|
<p>A white list of HTTP headers that the browsers are allowed to
|
|
access. Serialized into Access-Control-Expose-Headers header.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CorsPolicy.max_age">
|
|
<td><code>maxAge</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>Specifies how long the the results of a preflight request can be
|
|
cached. Translates to the Access-Control-Max-Age header.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="CorsPolicy.allow_credentials">
|
|
<td><code>allowCredentials</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#boolvalue">google.protobuf.BoolValue</a></code></td>
|
|
<td>
|
|
<p>Indicates whether the caller is allowed to send the actual request
|
|
(not the preflight) using credentials. Translates to
|
|
Access-Control-Allow-Credentials header.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="DestinationPolicy">DestinationPolicy</h2>
|
|
<section>
|
|
<p>DestinationPolicy defines client/caller-side policies that determine how
|
|
to handle traffic bound to a particular destination service. The policy
|
|
specifies configuration for load balancing and circuit breakers. For
|
|
example, a simple load balancing policy for the ratings service would
|
|
look as follows:</p>
|
|
|
|
<pre><code>metadata:
|
|
name: ratings-lb-policy
|
|
namespace: default # optional (default is "default")
|
|
spec:
|
|
destination:
|
|
name: ratings
|
|
loadBalancing:
|
|
name: ROUND_ROBIN
|
|
</code></pre>
|
|
|
|
<p>The FQDN of the destination service is composed from the destination name and meta namespace fields, along with
|
|
a platform-specific domain suffix
|
|
(e.g. on Kubernetes, “reviews” + “default” + “svc.cluster.local” -> “reviews.default.svc.cluster.local”).</p>
|
|
|
|
<p>A destination policy can be restricted to a particular version of a
|
|
service or applied to all versions. It can also be restricted to calls from
|
|
a particular source. For example, the following load balancing policy
|
|
applies to version v1 of the ratings service running in the prod
|
|
environment but only when called from version v2 of the reviews service:</p>
|
|
|
|
<pre><code>metadata:
|
|
name: ratings-lb-policy
|
|
namespace: default
|
|
spec:
|
|
source:
|
|
name: reviews
|
|
labels:
|
|
version: v2
|
|
destination:
|
|
name: ratings
|
|
labels:
|
|
env: prod
|
|
version: v1
|
|
loadBalancing:
|
|
name: ROUND_ROBIN
|
|
</code></pre>
|
|
|
|
<p><em>Note:</em> Destination policies will be applied only if the corresponding
|
|
tagged instances are explicitly routed to. In other words, for every
|
|
destination policy defined, at least one route rule must refer to the
|
|
service version indicated in the destination policy.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="DestinationPolicy.destination">
|
|
<td><code>destination</code></td>
|
|
<td><code><a href="#IstioService">IstioService</a></code></td>
|
|
<td>
|
|
<p>Optional: Destination uniquely identifies the destination service associated
|
|
with this policy.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="DestinationPolicy.source">
|
|
<td><code>source</code></td>
|
|
<td><code><a href="#IstioService">IstioService</a></code></td>
|
|
<td>
|
|
<p>Optional: Source uniquely identifies the source service associated
|
|
with this policy.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="DestinationPolicy.load_balancing">
|
|
<td><code>loadBalancing</code></td>
|
|
<td><code><a href="#LoadBalancing">LoadBalancing</a></code></td>
|
|
<td>
|
|
<p>Load balancing policy.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="DestinationPolicy.circuit_breaker">
|
|
<td><code>circuitBreaker</code></td>
|
|
<td><code><a href="#CircuitBreaker">CircuitBreaker</a></code></td>
|
|
<td>
|
|
<p>Circuit breaker policy.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="DestinationPolicy.custom">
|
|
<td><code>custom</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any">google.protobuf.Any</a></code></td>
|
|
<td>
|
|
<p>(– Other custom policy implementations –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="DestinationWeight">DestinationWeight</h2>
|
|
<section>
|
|
<p>Each routing rule is associated with one or more service versions (see
|
|
glossary in beginning of document). Weights associated with the version
|
|
determine the proportion of traffic it receives. For example, the
|
|
following rule will route 25% of traffic for the “reviews” service to
|
|
instances with the “v2” tag and the remaining traffic (i.e., 75%) to
|
|
“v1”.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: reviews
|
|
route:
|
|
- labels:
|
|
version: v2
|
|
weight: 25
|
|
- labels:
|
|
version: v1
|
|
weight: 75
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="DestinationWeight.destination">
|
|
<td><code>destination</code></td>
|
|
<td><code><a href="#IstioService">IstioService</a></code></td>
|
|
<td>
|
|
<p>Sometimes required. Optional destination uniquely identifies the destination service. If not
|
|
specified, the value is inherited from the parent route rule.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="DestinationWeight.labels">
|
|
<td><code>labels</code></td>
|
|
<td><code>map<string, string></code></td>
|
|
<td>
|
|
<p>Sometimes required. Service version identifier for the destination service.
|
|
(– N.B. The map is used instead of pstruct due to lack of serialization support
|
|
in golang protobuf library (see https://github.com/golang/protobuf/pull/208) –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="DestinationWeight.weight">
|
|
<td><code>weight</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>REQUIRED. The proportion of traffic to be forwarded to the service
|
|
version. (0-100). Sum of weights across destinations SHOULD BE ==
|
|
100. If there is only destination in a rule, the weight value is
|
|
assumed to be 100. When using multiple weights, either destination or labels must be
|
|
specified.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="EgressRule">EgressRule</h2>
|
|
<section>
|
|
<p>Egress rules describe the properties of a service outside Istio. When transparent proxying
|
|
is used, egress rules signify a white listed set of external services that microserves in the mesh
|
|
are allowed to access. A subset of routing rules and all destination policies can be applied
|
|
on the service targeted by an egress rule. TCP services and HTTP-based services can be expressed
|
|
by an egress rule. The destination of an egress rule for HTTP-based services must be an IP or a domain name,
|
|
optionally with a wildcard prefix (e.g., *.foo.com). For TCP based services, the destination of an
|
|
egress rule must be an IP or a block of IPs in CIDR notation.</p>
|
|
|
|
<p>If TLS origination from the sidecar is desired, the protocol
|
|
associated with the service port must be marked as HTTPS, and the service is expected to
|
|
be accessed over HTTP (e.g., http://gmail.com:443). The sidecar will automatically upgrade
|
|
the connection to TLS when initiating a connection with the external service.</p>
|
|
|
|
<p>For example, the following egress rule describes the set of services hosted under the *.foo.com domain</p>
|
|
|
|
<pre><code>kind: EgressRule
|
|
metadata:
|
|
name: foo-egress-rule
|
|
spec:
|
|
destination:
|
|
service: *.foo.com
|
|
ports:
|
|
- port: 80
|
|
protocol: http
|
|
- port: 443
|
|
protocol: https
|
|
</code></pre>
|
|
|
|
<p>The following egress rule describes the set of services accessed by a block of IPs</p>
|
|
|
|
<pre><code>kind: EgressRule
|
|
metadata:
|
|
name: bar-egress-rule
|
|
spec:
|
|
destination:
|
|
service: 92.198.174.192/27
|
|
ports:
|
|
- port: 111
|
|
protocol: tcp
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="EgressRule.destination">
|
|
<td><code>destination</code></td>
|
|
<td><code><a href="#IstioService">IstioService</a></code></td>
|
|
<td>
|
|
<p>REQUIRED: A domain name, optionally with a wildcard prefix, or an IP, or a block of IPs
|
|
associated with the external service.
|
|
ONLY the “service” field of “destination” will be taken into consideration. Name,
|
|
namespace, domain and labels are ignored. Routing rules and destination policies that
|
|
refer to these external services must have identical specification for the destination
|
|
as the corresponding egress rule.</p>
|
|
|
|
<p>The “service” field of “destination” for HTTP-based services must be an IP or a domain name,
|
|
optionally with a wildcard prefix. Wildcard domain specifications must conform to format
|
|
allowed by Envoy’s Virtual Host specification, such as “<em>.foo.com” or “</em>-bar.foo.com”.
|
|
The character ‘<em>’ in a domain specification indicates a non-empty string. Hence, a wildcard
|
|
domain of form “</em>-bar.foo.com” will match “baz-bar.foo.com” but not “-bar.foo.com”.</p>
|
|
|
|
<p>The “service” field of “destination” for TCP services must be an IP or a block of IPs in CIDR notation.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="EgressRule.ports">
|
|
<td><code>ports</code></td>
|
|
<td><code><a href="#EgressRule.Port">EgressRule.Port[]</a></code></td>
|
|
<td>
|
|
<p>REQUIRED: list of ports on which the external service is available.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="EgressRule.use_egress_proxy">
|
|
<td><code>useEgressProxy</code></td>
|
|
<td><code>bool</code></td>
|
|
<td>
|
|
<p>Forward all the external traffic through a dedicated egress proxy. It is used in some scenarios
|
|
where there is a requirement that all the external traffic goes through special dedicated nodes/pods.
|
|
These dedicated egress nodes could then be more closely monitored for security vulnerabilities.</p>
|
|
|
|
<p>The default is false, i.e. the sidecar forwards external traffic directly to the external service.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="EgressRule.Port">EgressRule.Port</h2>
|
|
<section>
|
|
<p>Port describes the properties of a specific TCP port of an external service.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="EgressRule.Port.port">
|
|
<td><code>port</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>A valid non-negative integer port number.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="EgressRule.Port.protocol">
|
|
<td><code>protocol</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>The protocol to communicate with the external services.
|
|
MUST BE one of HTTP|HTTPS|GRPC|HTTP2|TCP|MONGO.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPFaultInjection">HTTPFaultInjection</h2>
|
|
<section>
|
|
<p>HTTPFaultInjection can be used to specify one or more faults to inject
|
|
while forwarding http requests to the destination specified in the route
|
|
rule. Fault specification is part of a route rule. Faults include
|
|
aborting the Http request from downstream service, and/or delaying
|
|
proxying of requests. A fault rule MUST HAVE delay or abort or both.</p>
|
|
|
|
<p><em>Note:</em> Delay and abort faults are independent of one another, even if
|
|
both are specified simultaneously.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPFaultInjection.delay">
|
|
<td><code>delay</code></td>
|
|
<td><code><a href="#HTTPFaultInjection.Delay">HTTPFaultInjection.Delay</a></code></td>
|
|
<td>
|
|
<p>Delay requests before forwarding, emulating various failures such as
|
|
network issues, overloaded upstream service, etc.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPFaultInjection.abort">
|
|
<td><code>abort</code></td>
|
|
<td><code><a href="#HTTPFaultInjection.Abort">HTTPFaultInjection.Abort</a></code></td>
|
|
<td>
|
|
<p>Abort Http request attempts and return error codes back to downstream
|
|
service, giving the impression that the upstream service is faulty.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPFaultInjection.Abort">HTTPFaultInjection.Abort</h2>
|
|
<section>
|
|
<p>Abort specification is used to prematurely abort a request with a
|
|
pre-specified error code. The following example will return an HTTP
|
|
400 error code for 10% of the requests to the “ratings” service “v1”.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
spec:
|
|
destination:
|
|
name: reviews
|
|
route:
|
|
- labels:
|
|
version: v1
|
|
httpFault:
|
|
abort:
|
|
percent: 10
|
|
httpStatus: 400
|
|
</code></pre>
|
|
|
|
<p>The <em>httpStatus</em> field is used to indicate the HTTP status code to
|
|
return to the caller. The optional <em>percent</em> field, a value between 0
|
|
and 100, is used to only abort a certain percentage of requests. If
|
|
not specified, all requests are aborted.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPFaultInjection.Abort.percent">
|
|
<td><code>percent</code></td>
|
|
<td><code>float</code></td>
|
|
<td>
|
|
<p>percentage of requests to be aborted with the error code provided (0-100).</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPFaultInjection.Abort.grpc_status" class="oneof oneof-start">
|
|
<td><code>grpcStatus</code></td>
|
|
<td><code>string (oneof)</code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPFaultInjection.Abort.http2_error" class="oneof">
|
|
<td><code>http2Error</code></td>
|
|
<td><code>string (oneof)</code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPFaultInjection.Abort.http_status" class="oneof">
|
|
<td><code>httpStatus</code></td>
|
|
<td><code>int32 (oneof)</code></td>
|
|
<td>
|
|
<p>REQUIRED. HTTP status code to use to abort the Http request.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPFaultInjection.Abort.override_header_name">
|
|
<td><code>overrideHeaderName</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>(– Specify abort code as part of Http request.
|
|
TODO: The semantics and syntax of the headers is undefined. –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPFaultInjection.Delay">HTTPFaultInjection.Delay</h2>
|
|
<section>
|
|
<p>Delay specification is used to inject latency into the request
|
|
forwarding path. The following example will introduce a 5 second delay
|
|
in 10% of the requests to the “v1” version of the “reviews”
|
|
service.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
spec:
|
|
destination:
|
|
name: reviews
|
|
route:
|
|
- labels:
|
|
version: v1
|
|
httpFault:
|
|
delay:
|
|
percent: 10
|
|
fixedDelay: 5s
|
|
</code></pre>
|
|
|
|
<p>The <em>fixedDelay</em> field is used to indicate the amount of delay in
|
|
seconds. An optional <em>percent</em> field, a value between 0 and 100, can
|
|
be used to only delay a certain percentage of requests. If left
|
|
unspecified, all request will be delayed.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPFaultInjection.Delay.percent">
|
|
<td><code>percent</code></td>
|
|
<td><code>float</code></td>
|
|
<td>
|
|
<p>percentage of requests on which the delay will be injected (0-100)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPFaultInjection.Delay.fixed_delay" class="oneof oneof-start">
|
|
<td><code>fixedDelay</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration (oneof)</a></code></td>
|
|
<td>
|
|
<p>REQUIRED. Add a fixed delay before forwarding the request. Format: 1h/1m/1s/1ms. MUST be >=1ms.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPFaultInjection.Delay.exponential_delay" class="oneof">
|
|
<td><code>exponentialDelay</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration (oneof)</a></code></td>
|
|
<td>
|
|
<p>(– Add a delay (based on an exponential function) before forwarding
|
|
the request. mean delay needed to derive the exponential delay
|
|
values –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPFaultInjection.Delay.override_header_name">
|
|
<td><code>overrideHeaderName</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>(– Specify delay duration as part of Http request.
|
|
TODO: The semantics and syntax of the headers is undefined. –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPRedirect">HTTPRedirect</h2>
|
|
<section>
|
|
<p>HTTPRedirect can be used to send a 302 redirect response to the caller,
|
|
where the Authority/Host and the URI in the response can be swapped with
|
|
the specified values. For example, the following route rule redirects
|
|
requests for /v1/getProductRatings API on the ratings service to
|
|
/v1/bookRatings provided by the bookratings service.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: ratings
|
|
match:
|
|
request:
|
|
headers:
|
|
uri: /v1/getProductRatings
|
|
redirect:
|
|
uri: /v1/bookRatings
|
|
authority: bookratings.default.svc.cluster.local
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPRedirect.uri">
|
|
<td><code>uri</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>On a redirect, overwrite the Path portion of the URL with this
|
|
value. Note that the entire path will be replaced, irrespective of the
|
|
request URI being matched as an exact path or prefix.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPRedirect.authority">
|
|
<td><code>authority</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>On a redirect, overwrite the Authority/Host portion of the URL with
|
|
this value</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPRetry">HTTPRetry</h2>
|
|
<section>
|
|
<p>Describes the retry policy to use when a HTTP request fails. For
|
|
example, the following rule sets the maximum number of retries to 3 when
|
|
calling ratings:v1 service, with a 2s timeout per retry attempt.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: ratings
|
|
route:
|
|
- labels:
|
|
version: v1
|
|
httpReqRetries:
|
|
simpleRetry:
|
|
attempts: 3
|
|
perTryTimeout: 2s
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPRetry.simple_retry" class="oneof oneof-start">
|
|
<td><code>simpleRetry</code></td>
|
|
<td><code><a href="#HTTPRetry.SimpleRetryPolicy">HTTPRetry.SimpleRetryPolicy (oneof)</a></code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPRetry.custom" class="oneof">
|
|
<td><code>custom</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any">google.protobuf.Any (oneof)</a></code></td>
|
|
<td>
|
|
<p>(– For proxies that support custom retry policies –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPRetry.SimpleRetryPolicy">HTTPRetry.SimpleRetryPolicy</h2>
|
|
<section>
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPRetry.SimpleRetryPolicy.attempts">
|
|
<td><code>attempts</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>REQUIRED. Number of retries for a given request. The interval
|
|
between retries will be determined automatically (25ms+). Actual
|
|
number of retries attempted depends on the httpReqTimeout.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPRetry.SimpleRetryPolicy.per_try_timeout">
|
|
<td><code>perTryTimeout</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>Timeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPRetry.SimpleRetryPolicy.override_header_name">
|
|
<td><code>overrideHeaderName</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>(– Downstream Service could specify retry attempts via Http header to
|
|
Envoy, if Envoy supports such a feature. –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPRewrite">HTTPRewrite</h2>
|
|
<section>
|
|
<p>HTTPRewrite can be used to rewrite specific parts of a HTTP request
|
|
before forwarding the request to the destination. Rewrite primitive can
|
|
be used only with the DestinationWeights. The following example
|
|
demonstrates how to rewrite the URL prefix for api call (/ratings) to
|
|
ratings service before making the actual API call.</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: ratings
|
|
match:
|
|
request:
|
|
headers:
|
|
uri:
|
|
prefix: /ratings
|
|
rewrite:
|
|
uri: /v1/bookRatings
|
|
route:
|
|
- labels:
|
|
version: v1
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPRewrite.uri">
|
|
<td><code>uri</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>rewrite the Path (or the prefix) portion of the URI with this
|
|
value. If the original URI was matched based on prefix, the value
|
|
provided in this field will replace the corresponding matched prefix.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPRewrite.authority">
|
|
<td><code>authority</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>rewrite the Authority/Host header with this value.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPTimeout">HTTPTimeout</h2>
|
|
<section>
|
|
<p>Describes HTTP request timeout. For example, the following rule sets a
|
|
10 second timeout for calls to the ratings:v1 service</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: ratings
|
|
route:
|
|
- labels:
|
|
version: v1
|
|
httpReqTimeout:
|
|
simpleTimeout:
|
|
timeout: 10s
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPTimeout.simple_timeout" class="oneof oneof-start">
|
|
<td><code>simpleTimeout</code></td>
|
|
<td><code><a href="#HTTPTimeout.SimpleTimeoutPolicy">HTTPTimeout.SimpleTimeoutPolicy (oneof)</a></code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPTimeout.custom" class="oneof">
|
|
<td><code>custom</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any">google.protobuf.Any (oneof)</a></code></td>
|
|
<td>
|
|
<p>(– For proxies that support custom timeout policies –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="HTTPTimeout.SimpleTimeoutPolicy">HTTPTimeout.SimpleTimeoutPolicy</h2>
|
|
<section>
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="HTTPTimeout.SimpleTimeoutPolicy.timeout">
|
|
<td><code>timeout</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>REQUIRED. Timeout for a HTTP request. Includes retries as well. Default
|
|
15s. format: 1h/1m/1s/1ms. MUST BE >=1ms. It is possible to control
|
|
timeout per request by supplying the timeout value via
|
|
x-envoy-upstream-rq-timeout-ms HTTP header.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="HTTPTimeout.SimpleTimeoutPolicy.override_header_name">
|
|
<td><code>overrideHeaderName</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>(– Downstream service could specify timeout via Http header to
|
|
Envoy, if Envoy supports such a feature. –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="IngressRule">IngressRule</h2>
|
|
<section>
|
|
<p>Ingress rules are routing rules applied to the ingress proxy pool. The
|
|
ingress proxes serve as the receiving edge proxy for the entire mesh, but
|
|
can also be addressed from inside the mesh. Each ingress rule defines a
|
|
destination service and port. Rules that do not resolve to a service or a
|
|
port in the mesh should be ignored.</p>
|
|
|
|
<p>The routing rules for the destination service are applied at the ingress
|
|
proxy. That means the routing rule match conditions are composed and its
|
|
actions are enforced. The traffic splitting for the destination service is
|
|
also effective.</p>
|
|
|
|
<p>WARNING: This API is experimental and under active development</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="IngressRule.port">
|
|
<td><code>port</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>REQUIRED: Port on which the ingress proxy listens and applies the rule.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IngressRule.tls_secret">
|
|
<td><code>tlsSecret</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>Optional TLS secret path to apply server-side TLS context on the port.
|
|
It is up to the underlying secret store to interpret the path to the secret.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IngressRule.precedence">
|
|
<td><code>precedence</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>RECOMMENDED. Precedence is used to disambiguate the order of application
|
|
of rules. A higher number takes priority. If not specified, the value is
|
|
assumed to be 0. The order of application for rules with the same
|
|
precedence is unspecified.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IngressRule.match">
|
|
<td><code>match</code></td>
|
|
<td><code><a href="#MatchCondition">MatchCondition</a></code></td>
|
|
<td>
|
|
<p>Match conditions to be satisfied for the ingress rule to be
|
|
activated.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IngressRule.destination">
|
|
<td><code>destination</code></td>
|
|
<td><code><a href="#IstioService">IstioService</a></code></td>
|
|
<td>
|
|
<p>REQUIRED: Destination uniquely identifies the destination service.</p>
|
|
|
|
<p><em>Note:</em> The ingress rule destination specification represents all version
|
|
of the service and therefore the IstioService’s labels field MUST be empty.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IngressRule.destination_port" class="oneof oneof-start">
|
|
<td><code>destinationPort</code></td>
|
|
<td><code>int32 (oneof)</code></td>
|
|
<td>
|
|
<p>Identifies the destination service port by value</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IngressRule.destination_port_name" class="oneof">
|
|
<td><code>destinationPortName</code></td>
|
|
<td><code>string (oneof)</code></td>
|
|
<td>
|
|
<p>Identifies the destination service port by name</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="IstioService">IstioService</h2>
|
|
<section>
|
|
<p>IstioService identifies a service and optionally service version.
|
|
The FQDN of the service is composed from the name, namespace, and implementation-specific domain suffix
|
|
(e.g. on Kubernetes, “reviews” + “default” + “svc.cluster.local” -> “reviews.default.svc.cluster.local”).</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="IstioService.name">
|
|
<td><code>name</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>The short name of the service such as “foo”.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IstioService.namespace">
|
|
<td><code>namespace</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>Optional namespace of the service. Defaults to value of metadata namespace field.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IstioService.domain">
|
|
<td><code>domain</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>Domain suffix used to construct the service FQDN in implementations that support such specification.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IstioService.service">
|
|
<td><code>service</code></td>
|
|
<td><code>string</code></td>
|
|
<td>
|
|
<p>The service FQDN.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="IstioService.labels">
|
|
<td><code>labels</code></td>
|
|
<td><code>map<string, string></code></td>
|
|
<td>
|
|
<p>Optional one or more labels that uniquely identify the service version.</p>
|
|
|
|
<p><em>Note:</em> When used for a RouteRule destination, labels MUST be empty.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="L4FaultInjection">L4FaultInjection</h2>
|
|
<section>
|
|
<p>(– Faults can be injected into the connections from downstream by the
|
|
Envoy, for testing the failure recovery capabilities of downstream
|
|
services. Faults include aborting the connection from downstream
|
|
service, delaying proxying of connection to the destination
|
|
service, and throttling the bandwidth of the connection (either
|
|
end). Bandwidth throttling for failure testing should not be confused
|
|
with the rate limiting policy enforcement provided by the Mixer
|
|
component. L4 fault injection is not supported at the moment. –)</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="L4FaultInjection.throttle">
|
|
<td><code>throttle</code></td>
|
|
<td><code><a href="#L4FaultInjection.Throttle">L4FaultInjection.Throttle</a></code></td>
|
|
<td>
|
|
<p>Unlike Http services, we have very little context for raw Tcp|Udp
|
|
connections. We could throttle bandwidth of the connections (slow down
|
|
the connection) and/or abruptly reset (terminate) the Tcp connection
|
|
after it has been established.
|
|
We first throttle (if set) and then terminate the connection.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="L4FaultInjection.terminate">
|
|
<td><code>terminate</code></td>
|
|
<td><code><a href="#L4FaultInjection.Terminate">L4FaultInjection.Terminate</a></code></td>
|
|
<td>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="L4FaultInjection.Terminate">L4FaultInjection.Terminate</h2>
|
|
<section>
|
|
<p>Abruptly reset (terminate) the Tcp connection after it has been
|
|
established, emulating remote server crash or link failure.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="L4FaultInjection.Terminate.percent">
|
|
<td><code>percent</code></td>
|
|
<td><code>float</code></td>
|
|
<td>
|
|
<p>percentage of established Tcp connections to be terminated/reset</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="L4FaultInjection.Terminate.terminate_after_period">
|
|
<td><code>terminateAfterPeriod</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>TODO: see if it makes sense to create a generic Duration type to
|
|
express time interval related configs.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="L4FaultInjection.Throttle">L4FaultInjection.Throttle</h2>
|
|
<section>
|
|
<p>Bandwidth throttling for Tcp and Udp connections</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="L4FaultInjection.Throttle.percent">
|
|
<td><code>percent</code></td>
|
|
<td><code>float</code></td>
|
|
<td>
|
|
<p>percentage of connections to throttle.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="L4FaultInjection.Throttle.downstream_limit_bps">
|
|
<td><code>downstreamLimitBps</code></td>
|
|
<td><code>int64</code></td>
|
|
<td>
|
|
<p>bandwidth limit in “bits” per second between downstream and Envoy</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="L4FaultInjection.Throttle.upstream_limit_bps">
|
|
<td><code>upstreamLimitBps</code></td>
|
|
<td><code>int64</code></td>
|
|
<td>
|
|
<p>bandwidth limits in “bits” per second between Envoy and upstream</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="L4FaultInjection.Throttle.throttle_after_period" class="oneof oneof-start">
|
|
<td><code>throttleAfterPeriod</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration (oneof)</a></code></td>
|
|
<td>
|
|
<p>Wait a while after the connection is established, before
|
|
starting bandwidth throttling. This would allow us to inject fault
|
|
after the application protocol (e.g., MySQL) has had time to
|
|
establish sessions/whatever handshake necessary.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="L4FaultInjection.Throttle.throttle_after_bytes" class="oneof">
|
|
<td><code>throttleAfterBytes</code></td>
|
|
<td><code>double (oneof)</code></td>
|
|
<td>
|
|
<p>Alternatively, we could wait for a certain number of bytes to be
|
|
transferred to upstream before throttling the bandwidth.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="L4FaultInjection.Throttle.throttle_for_period">
|
|
<td><code>throttleForPeriod</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">google.protobuf.Duration</a></code></td>
|
|
<td>
|
|
<p>Stop throttling after the given duration. If not set, the connection
|
|
will be throttled for its lifetime.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="L4MatchAttributes">L4MatchAttributes</h2>
|
|
<section>
|
|
<p>(– L4 connection match attributes. Note that L4 connection matching
|
|
support is incomplete. –)</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="L4MatchAttributes.source_subnet">
|
|
<td><code>sourceSubnet</code></td>
|
|
<td><code>string[]</code></td>
|
|
<td>
|
|
<p>IPv4 or IPv6 ip address with optional subnet. E.g., a.b.c.d/xx form or
|
|
just a.b.c.d</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="L4MatchAttributes.destination_subnet">
|
|
<td><code>destinationSubnet</code></td>
|
|
<td><code>string[]</code></td>
|
|
<td>
|
|
<p>IPv4 or IPv6 ip address of destination with optional subnet.
|
|
E.g., a.b.c.d/xx form or just a.b.c.d. This is only valid when the destination
|
|
service has several IPs and the application explicitly specifies a particular IP.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="LoadBalancing">LoadBalancing</h2>
|
|
<section>
|
|
<p>Load balancing policy to use when forwarding traffic. These policies
|
|
directly correlate to <a href="https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/load_balancing">load balancer
|
|
types</a>
|
|
supported by Envoy. Example,</p>
|
|
|
|
<pre><code>metadata:
|
|
name: reviews-lb-policy
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: reviews
|
|
loadBalancing:
|
|
name: RANDOM
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="LoadBalancing.name" class="oneof oneof-start">
|
|
<td><code>name</code></td>
|
|
<td><code><a href="#LoadBalancing.SimpleLBPolicy">LoadBalancing.SimpleLBPolicy (oneof)</a></code></td>
|
|
<td>
|
|
<p>Load balancing policy name (as defined in SimpleLBPolicy below)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="LoadBalancing.custom" class="oneof">
|
|
<td><code>custom</code></td>
|
|
<td><code><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any">google.protobuf.Any (oneof)</a></code></td>
|
|
<td>
|
|
<p>(– Custom LB policy implementations –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="LoadBalancing.SimpleLBPolicy">LoadBalancing.SimpleLBPolicy</h2>
|
|
<section>
|
|
<p>Load balancing algorithms supported by Envoy.</p>
|
|
|
|
<table class="enum-values">
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="LoadBalancing.SimpleLBPolicy.ROUND_ROBIN">
|
|
<td><code>ROUND_ROBIN</code></td>
|
|
<td>
|
|
<p>Simple round robin policy.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="LoadBalancing.SimpleLBPolicy.LEAST_CONN">
|
|
<td><code>LEAST_CONN</code></td>
|
|
<td>
|
|
<p>The least request load balancer uses an O(1) algorithm which selects
|
|
two random healthy hosts and picks the host which has fewer active
|
|
requests.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="LoadBalancing.SimpleLBPolicy.RANDOM">
|
|
<td><code>RANDOM</code></td>
|
|
<td>
|
|
<p>The random load balancer selects a random healthy host. The random
|
|
load balancer generally performs better than round robin if no health
|
|
checking policy is configured.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="MatchCondition">MatchCondition</h2>
|
|
<section>
|
|
<p>Match condition specifies a set of criterion to be met in order for the
|
|
route rule to be applied to the connection or HTTP request. The
|
|
condition provides distinct set of conditions for each protocol with the
|
|
intention that conditions apply only to the service ports that match the
|
|
protocol. For example, the following route rule restricts the rule to
|
|
match only requests originating from “reviews:v2”, accessing ratings
|
|
service where the URL path starts with /ratings/v2/ and the request
|
|
contains a “cookie” with value “user=jason”,</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
namespace: default
|
|
spec:
|
|
destination:
|
|
name: ratings
|
|
match:
|
|
source:
|
|
name: reviews
|
|
labels:
|
|
version: v2
|
|
request:
|
|
headers:
|
|
cookie:
|
|
regex: "^(.*?;)?(user=jason)(;.*)?"
|
|
uri:
|
|
prefix: "/ratings/v2/"
|
|
</code></pre>
|
|
|
|
<p>MatchCondition CANNOT be empty. At least one source or
|
|
request header must be specified.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="MatchCondition.source">
|
|
<td><code>source</code></td>
|
|
<td><code><a href="#IstioService">IstioService</a></code></td>
|
|
<td>
|
|
<p>Identifies the service initiating a connection or a request.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="MatchCondition.tcp">
|
|
<td><code>tcp</code></td>
|
|
<td><code><a href="#L4MatchAttributes">L4MatchAttributes</a></code></td>
|
|
<td>
|
|
<p>(– Set of layer 4 match conditions based on the IP ranges –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="MatchCondition.udp">
|
|
<td><code>udp</code></td>
|
|
<td><code><a href="#L4MatchAttributes">L4MatchAttributes</a></code></td>
|
|
<td>
|
|
<p>(– Set of layer 4 match conditions based on the IP ranges –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="MatchCondition.request">
|
|
<td><code>request</code></td>
|
|
<td><code><a href="#MatchRequest">MatchRequest</a></code></td>
|
|
<td>
|
|
<p>Attributes of an HTTP request to match.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="MatchRequest">MatchRequest</h2>
|
|
<section>
|
|
<p>MatchRequest specifies the attributes of an HTTP request to be used for matching a request.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="MatchRequest.headers">
|
|
<td><code>headers</code></td>
|
|
<td><code>map<string, <a href="#StringMatch">StringMatch</a>></code></td>
|
|
<td>
|
|
<p>Set of HTTP match conditions based on HTTP/1.1, HTTP/2, GRPC request
|
|
metadata, such as <em>uri</em>, <em>scheme</em>, <em>authority</em>. The header keys must be
|
|
lowercase and use hyphen as the separator, e.g. <em>x-request-id</em>.</p>
|
|
|
|
<p>Header values are case-sensitive and formatted as follows:</p>
|
|
|
|
<p><em>exact: “value”</em> or just <em>“value”</em> for exact string match</p>
|
|
|
|
<p><em>prefix: “value”</em> for prefix-based match</p>
|
|
|
|
<p><em>regex: “value”</em> for ECMAscript style regex-based match</p>
|
|
|
|
<p><em>Note 1:</em> The keys <em>uri</em>, <em>scheme</em>, <em>method</em>, and <em>authority</em> correspond
|
|
to URI, protocol scheme (e.g., HTTP, HTTPS), HTTP method
|
|
(e.g., GET, POST), and the HTTP Host header respectively.</p>
|
|
|
|
<p><em>Note 2:</em> <em>uri</em> can be used to perform URL matches.
|
|
For all HTTP headers including <em>uri</em>, exact, prefix and ECMA style
|
|
regular expression matches are supported.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="RouteRule">RouteRule</h2>
|
|
<section>
|
|
<p>Route rule provides a custom routing policy based on the source and
|
|
destination service versions and connection/request metadata. The rule
|
|
must provide a set of conditions for each protocol (TCP, UDP, HTTP) that
|
|
the destination service exposes on its ports.</p>
|
|
|
|
<p>The rule applies only to the ports on the destination service for which
|
|
it provides protocol-specific match condition, e.g. if the rule does not
|
|
specify TCP condition, the rule does not apply to TCP traffic towards
|
|
the destination service.</p>
|
|
|
|
<p>For example, a simple rule to send 100% of incoming traffic for a
|
|
“reviews” service to version “v1” can be specified as follows:</p>
|
|
|
|
<pre><code>metadata:
|
|
name: my-rule
|
|
namespace: default # optional (default is "default")
|
|
spec:
|
|
destination:
|
|
name: reviews
|
|
namespace: my-namespace # optional (default is metadata namespace field)
|
|
route:
|
|
- labels:
|
|
version: v1
|
|
weight: 100
|
|
</code></pre>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="RouteRule.destination">
|
|
<td><code>destination</code></td>
|
|
<td><code><a href="#IstioService">IstioService</a></code></td>
|
|
<td>
|
|
<p>REQUIRED: Destination uniquely identifies the destination associated
|
|
with this routing rule. This field is applicable for hostname-based
|
|
resolution for HTTP traffic as well as IP-based resolution for
|
|
TCP/UDP traffic.</p>
|
|
|
|
<p><em>Note:</em> The route rule destination specification represents all version
|
|
of the service and therefore the IstioService’s labels field MUST be empty.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.precedence">
|
|
<td><code>precedence</code></td>
|
|
<td><code>int32</code></td>
|
|
<td>
|
|
<p>RECOMMENDED. Precedence is used to disambiguate the order of
|
|
application of rules for the same destination service. A higher number
|
|
takes priority. If not specified, the value is assumed to be 0. The
|
|
order of application for rules with the same precedence is
|
|
unspecified.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.match">
|
|
<td><code>match</code></td>
|
|
<td><code><a href="#MatchCondition">MatchCondition</a></code></td>
|
|
<td>
|
|
<p>Match condtions to be satisfied for the route rule to be
|
|
activated. If match is omitted, the route rule applies only to HTTP
|
|
traffic.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.route">
|
|
<td><code>route</code></td>
|
|
<td><code><a href="#DestinationWeight">DestinationWeight[]</a></code></td>
|
|
<td>
|
|
<p>REQUIRED (route|redirect). A routing rule can either redirect traffic or
|
|
forward traffic. The forwarding target can be one of several versions
|
|
of a service (see glossary in beginning of document). Weights
|
|
associated with the service version determine the proportion of
|
|
traffic it receives.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.redirect">
|
|
<td><code>redirect</code></td>
|
|
<td><code><a href="#HTTPRedirect">HTTPRedirect</a></code></td>
|
|
<td>
|
|
<p>REQUIRED (route|redirect). A routing rule can either redirect traffic or
|
|
forward traffic. The redirect primitive can be used to send a HTTP 302
|
|
redirect to a different URI or Authority.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.rewrite">
|
|
<td><code>rewrite</code></td>
|
|
<td><code><a href="#HTTPRewrite">HTTPRewrite</a></code></td>
|
|
<td>
|
|
<p>Rewrite HTTP URIs and Authority headers. Rewrite cannot be used with
|
|
Redirect primitive. Rewrite will be performed before forwarding.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.websocket_upgrade">
|
|
<td><code>websocketUpgrade</code></td>
|
|
<td><code>bool</code></td>
|
|
<td>
|
|
<p>Indicates that a HTTP/1.1 client connection to this particular route
|
|
should be allowed (and expected) to upgrade to a WebSocket connection.
|
|
The default is false. Envoy expects the first request to this route
|
|
to contain the WebSocket upgrade headers. Otherwise, the request
|
|
will be rejected.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.http_req_timeout">
|
|
<td><code>httpReqTimeout</code></td>
|
|
<td><code><a href="#HTTPTimeout">HTTPTimeout</a></code></td>
|
|
<td>
|
|
<p>Timeout policy for HTTP requests.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.http_req_retries">
|
|
<td><code>httpReqRetries</code></td>
|
|
<td><code><a href="#HTTPRetry">HTTPRetry</a></code></td>
|
|
<td>
|
|
<p>Retry policy for HTTP requests.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.http_fault">
|
|
<td><code>httpFault</code></td>
|
|
<td><code><a href="#HTTPFaultInjection">HTTPFaultInjection</a></code></td>
|
|
<td>
|
|
<p>Fault injection policy to apply on HTTP traffic</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.l4_fault">
|
|
<td><code>l4Fault</code></td>
|
|
<td><code><a href="#L4FaultInjection">L4FaultInjection</a></code></td>
|
|
<td>
|
|
<p>(– L4 fault injection policy applies to Tcp/Udp (not HTTP) traffic –)</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.mirror">
|
|
<td><code>mirror</code></td>
|
|
<td><code><a href="#IstioService">IstioService</a></code></td>
|
|
<td>
|
|
<p>Mirror HTTP traffic to a another destination in addition to forwarding
|
|
the requests to the intended destination. Mirrored traffic is on best
|
|
effort basis where Envoy will not wait for the mirrored cluster to
|
|
respond before returning the response from the original destination.
|
|
Statistics will be generated for the mirrored destination.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.cors_policy">
|
|
<td><code>corsPolicy</code></td>
|
|
<td><code><a href="#CorsPolicy">CorsPolicy</a></code></td>
|
|
<td>
|
|
<p>Cross-Origin Resource Sharing policy (CORS). Refer to
|
|
https://developer.mozilla.org/en-US/docs/Web/HTTP/Access<em>control</em>CORS for
|
|
further details about cross origin resource sharing.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="RouteRule.append_headers">
|
|
<td><code>appendHeaders</code></td>
|
|
<td><code>map<string, string></code></td>
|
|
<td>
|
|
<p>Additional HTTP headers to add before forwarding a request to the
|
|
destnation service.</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<h2 id="StringMatch">StringMatch</h2>
|
|
<section>
|
|
<p>Describes how to match a given string in HTTP headers. Match is case-sensitive.</p>
|
|
|
|
<table class="message-fields">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr id="StringMatch.exact" class="oneof oneof-start">
|
|
<td><code>exact</code></td>
|
|
<td><code>string (oneof)</code></td>
|
|
<td>
|
|
<p>exact string match</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="StringMatch.prefix" class="oneof">
|
|
<td><code>prefix</code></td>
|
|
<td><code>string (oneof)</code></td>
|
|
<td>
|
|
<p>prefix-based match</p>
|
|
|
|
</td>
|
|
</tr>
|
|
<tr id="StringMatch.regex" class="oneof">
|
|
<td><code>regex</code></td>
|
|
<td><code>string (oneof)</code></td>
|
|
<td>
|
|
<p>ECMAscript style regex-based match</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|