mirror of https://github.com/istio/istio.io.git
123 lines
40 KiB
HTML
123 lines
40 KiB
HTML
<!DOCTYPE html><html lang="en" itemscope itemtype="https://schema.org/WebPage" style="overflow-y: scroll;"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="title" content="Routing Rules"><meta name="og:title" content="Routing Rules"><meta name="og:image" content="/v0.4/img/logo.png"/><meta name="theme-color" content="#466BB0"/><meta name="description" content="Traffic routing rule configuration schema"><meta name="og:description" content="Traffic routing rule configuration schema"><title>Istioldie 0.4 / Routing Rules</title><script> window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date; ga('create', 'UA-98480406-2', 'auto'); ga('send', 'pageview'); </script> <script async src='https://www.google-analytics.com/analytics.js'></script><link rel="alternate" type="application/rss+xml" title="Istio Blog RSS" href="/v0.4/feed.xml"><link rel="shortcut icon" href="/v0.4/favicons/favicon.ico" ><link rel="apple-touch-icon" href="/v0.4/favicons/apple-touch-icon-180x180.png" sizes="180x180"><link rel="icon" type="image/png" href="/v0.4/favicons/favicon-16x16.png" sizes="16x16"><link rel="icon" type="image/png" href="/v0.4/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/v0.4/favicons/android-36x36.png" sizes="36x36"><link rel="icon" type="image/png" href="/v0.4/favicons/android-48x48.png" sizes="48x48"><link rel="icon" type="image/png" href="/v0.4/favicons/android-72x72.png" sizes="72x72"><link rel="icon" type="image/png" href="/v0.4/favicons/android-96x196.png" sizes="96x196"><link rel="icon" type="image/png" href="/v0.4/favicons/android-144x144.png" sizes="144x144"><link rel="icon" type="image/png" href="/v0.4/favicons/android-192x192.png" sizes="192x192"><link rel="manifest" href="/v0.4/manifest.json"><meta name="apple-mobile-web-app-title" content="Istio"><meta name="application-name" content="Istio"><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic"><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"><link rel="stylesheet" href="/v0.4/css/all.css"><link rel="stylesheet" href="/v0.4/css/prism.css"></head><body class="language-unknown"> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script><div class="nav-hero-container" style="z-index: 200000;"><nav id="header-nav" class="navbar navbar-inverse" role="navigation" style="z-index: 200000;"><div class="container"><div class="row"><div class="col-md-11 nofloat center-block "><div class="navbar-header"> <button type="button" class="hamburger navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-collapse-1" aria-expanded="false"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/v0.4/"><div> <img src="/v0.4/img/istio-logo.svg" alt="Istio Logo" height="54px"/> <span class="brand-name">Istioldie 0.4</span></div></a></div><div class="collapse navbar-collapse" id="navbar-collapse-1"><ul class="nav navbar-nav navbar-right"><li><a href="/v0.4/about" >About</a></li><li><a href="/v0.4/blog/posts/2017/mixer-spof-myth.html" >Blog</a></li><li><a href="/v0.4/docs/welcome" class='current'>Docs</a></li><li><a href="/v0.4/help" >Help</a></li><li><a href="/v0.4/community" >Community</a></li><li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown" href=""> <i class='fa fa-lg fa-cog'></i> <span class="caret"></span> </a><ul class="dropdown-menu"><h6 class="dropdown-header">Other versions of this site</h6><li> <a href="https://istio.io">Current Release</a></li><li> <a href="https://preliminary.istio.io">Next Release</a></li><li> <a href="https://archive.istio.io">Older Releases</a></li></ul></li><li><form name="cse" id="searchbox_demo" class="navbar-form navbar-right" role="search"> <input type="hidden" name="cx" value="013699703217164175118:iwwf17ikgf4" /> <input type="hidden" name="ie" value="utf-8" /> <input type="hidden" name="hl" value="en" /><div class="form-group"><div class="input-group"> <input name="q" class="form-control search-box" type="text" size="30" /><div class="input-group-addon"> <span class="btn-search glyphicon glyphicon-search"></span></div></div></div></form> <script type="text/javascript" src="https://www.google.com/cse/brand?form=searchbox_demo"></script></li></ul></div></div></div></div></nav></div><div class="container"><div class="row"><div class="col-md-11 nofloat center-block" style="margin-top: 3px;"><ul class="col-sm-10 nav nav-tabs"><li role="presentation" ><a href="/v0.4/docs/welcome/">Welcome</a></li><li role="presentation" ><a href="/v0.4/docs/concepts/">Concepts</a></li><li role="presentation" ><a href="/v0.4/docs/setup/">Setup</a></li><li role="presentation" ><a href="/v0.4/docs/tasks/">Tasks</a></li><li role="presentation" ><a href="/v0.4/docs/guides/">Guides</a></li><li role="presentation" class='active'><a href="/v0.4/docs/reference/">Reference</a></li></ul></div></div></div><script src="/v0.4/js/navtree.min.js"></script><div class="container docs"><div class="row"><div class="col-md-11 nofloat center-block"><div class="row"><div id="sidebar-container" class="col-sm-3"><ul class="sidebar"><li><h5 class='sidebar-title'>Reference</h5></li><script type="text/javascript"> var docs = []; docs.push({path: [ "api", "index.md", ], url: "/docs/reference/api/", title: "API", order: 10, overview: "Detailed information on API parameters."}); docs.push({path: [ "api", "mixer", "index.md", ], url: "/docs/reference/api/mixer/", title: "Mixer", order: 10, overview: "Detailed information on configuration and API exposed by Mixer."}); docs.push({path: [ "api", "mixer", "mixer-service.md", ], url: "/docs/reference/api/mixer/mixer-service.html", title: "Mixer Service", order: 20, overview: "Generated documentation for Mixer's API Surface"}); docs.push({path: [ "api", "mixer", "status.md", ], url: "/docs/reference/api/mixer/status.html", title: "Status RPC", order: 40, overview: "Google's rpc.Status proto"}); docs.push({path: [ "commands", "index.md", ], url: "/docs/reference/commands/", title: "CLI", order: 30, overview: "Describes usage and options of the Istio CLI and other utilities."}); docs.push({path: [ "commands", "istio_ca.md", ], url: "/docs/reference/commands/istio_ca.html", title: "istio_ca", order: 301, overview: "Istio Certificate Authority (CA)"}); docs.push({path: [ "commands", "istioctl.md", ], url: "/docs/reference/commands/istioctl.html", title: "istioctl", order: 20, overview: "Istio control interface"}); docs.push({path: [ "commands", "mixc.md", ], url: "/docs/reference/commands/mixc.html", title: "mixc", order: 101, overview: "Utility to trigger direct calls to Mixer's API."}); docs.push({path: [ "commands", "mixs.md", ], url: "/docs/reference/commands/mixs.html", title: "mixs", order: 201, overview: "Mixer is Istio's abstraction on top of infrastructure backends."}); docs.push({path: [ "config", "index.md", ], url: "/docs/reference/config/", title: "Configuration", order: 20, overview: "Detailed information on configuration options."}); docs.push({path: [ "config", "mixer", "adapters", "denier.md", ], url: "/docs/reference/config/mixer/adapters/denier.html", title: "denier Config", order: 100, overview: "Generated documentation for Mixer's denier Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "index.md", ], url: "/docs/reference/config/mixer/adapters/", title: "Adapters", order: 40, overview: "Generated documentation for Mixer's adapters."}); docs.push({path: [ "config", "mixer", "adapters", "kubernetes.md", ], url: "/docs/reference/config/mixer/adapters/kubernetes.html", title: "kubernetes Config", order: 10, overview: "Generated documentation for Mixer's kubernetes Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "list.md", ], url: "/docs/reference/config/mixer/adapters/list.html", title: "list Config", order: 20, overview: "Generated documentation for Mixer's list Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "memquota.md", ], url: "/docs/reference/config/mixer/adapters/memquota.html", title: "memquota Config", order: 30, overview: "Generated documentation for Mixer's memquota Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "prometheus.md", ], url: "/docs/reference/config/mixer/adapters/prometheus.html", title: "prometheus Config", order: 40, overview: "Generated documentation for Mixer's prometheus Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "stackdriver.md", ], url: "/docs/reference/config/mixer/adapters/stackdriver.html", title: "stackdriver Config", order: 50, overview: "Generated documentation for Mixer's stackdriver Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "statsd.md", ], url: "/docs/reference/config/mixer/adapters/statsd.html", title: "statsd Config", order: 60, overview: "Generated documentation for Mixer's statsd Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "stdio.md", ], url: "/docs/reference/config/mixer/adapters/stdio.html", title: "stdio Config", order: 70, overview: "Generated documentation for Mixer's stdio Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "svcctrl.md", ], url: "/docs/reference/config/mixer/adapters/svcctrl.html", title: "svcctrl Config", order: 80, overview: "Generated documentation for Mixer's svcctrl Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "attribute-manifests.md", ], url: "/docs/reference/config/mixer/attribute-manifests.html", title: "Attribute Manifests", order: 15, overview: "Describes the resource containing the collection of attributes known to Mixer at runtime."}); docs.push({path: [ "config", "mixer", "attribute-vocabulary.md", ], url: "/docs/reference/config/mixer/attribute-vocabulary.html", title: "Attribute Vocabulary", order: 10, overview: "Describes the base attribute vocabulary used for policy and control."}); docs.push({path: [ "config", "mixer", "expression-language.md", ], url: "/docs/reference/config/mixer/expression-language.html", title: "Expression Language", order: 20, overview: "Mixer config expression language reference."}); docs.push({path: [ "config", "mixer", "index.md", ], url: "/docs/reference/config/mixer/", title: "Mixer", order: 30, overview: "Detailed information on configuration and API exposed by Mixer."}); docs.push({path: [ "config", "mixer", "policy-and-telemetry-rules.md", ], url: "/docs/reference/config/mixer/policy-and-telemetry-rules.html", title: "Policy and Telemetry Rules", order: 40, overview: "Describes the rules used to configure Mixer policy and telemetry."}); docs.push({path: [ "config", "mixer", "template", "checknothing.md", ], url: "/docs/reference/config/mixer/template/checknothing.html", title: "checknothing Config", order: 1150, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "index.md", ], url: "/docs/reference/config/mixer/template/", title: "Templates", order: 50, overview: "Generated documentation for Mixer's Templates."}); docs.push({path: [ "config", "mixer", "template", "listentry.md", ], url: "/docs/reference/config/mixer/template/listentry.html", title: "listentry Config", order: 1160, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "logentry.md", ], url: "/docs/reference/config/mixer/template/logentry.html", title: "logentry Config", order: 1170, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "metric.md", ], url: "/docs/reference/config/mixer/template/metric.html", title: "metric Config", order: 1180, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "quota.md", ], url: "/docs/reference/config/mixer/template/quota.html", title: "quota Config", order: 1190, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "reportnothing.md", ], url: "/docs/reference/config/mixer/template/reportnothing.html", title: "reportnothing Config", order: 1200, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "value-type.md", ], url: "/docs/reference/config/mixer/value-type.html", title: "Value Type", order: 50, overview: "Generated documentation for Mixer Config's Value Type"}); docs.push({path: [ "config", "service-mesh.md", ], url: "/docs/reference/config/service-mesh.html", title: "Service Mesh", order: 15, overview: "Global Configuration Schema"}); docs.push({path: [ "config", "traffic-rules", "destination-policies.md", ], url: "/docs/reference/config/traffic-rules/destination-policies.html", title: "Destination Policies", order: 30, overview: "Configuration schema for Client-side traffic management policies"}); docs.push({path: [ "config", "traffic-rules", "egress-rules.md", ], url: "/docs/reference/config/traffic-rules/egress-rules.html", title: "Egress Rules", order: 40, overview: "Routing configuration for traffic exiting the service mesh"}); docs.push({path: [ "config", "traffic-rules", "index.md", ], url: "/docs/reference/config/traffic-rules/", title: "Traffic Management Rules", order: 20, overview: "Detailed information on rules configuration and API exposed by Pilot for managing them."}); docs.push({path: [ "config", "traffic-rules", "routing-rules.md", ], url: "/docs/reference/config/traffic-rules/routing-rules.html", title: "Routing Rules", order: 20, overview: "Traffic routing rule configuration schema"}); docs.push({path: [ "index.md", ], url: "/docs/reference/", title: "Reference", order: 60, overview: "The Reference section contains detailed authoritative reference material such as command-line options, configuration options, and API calling parameters."}); docs.push({path: [ "writing-config.md", ], url: "/docs/reference/writing-config.html", title: "Writing Configuration", order: 70, overview: "How to write Istio config YAML content."}); genSideBarTree(docs) </script></ul></div><div id="tab-container" class="col-xs-1 tab-neg-margin pull-left"> <a id="sidebar-tab" class="glyphicon glyphicon-chevron-left" href="javascript:void 0;"> </a></div><div id="content-container" class="thin-left-border col-sm-9 markdown"><div id="toc" class="toc"></div><div id="doc-content"><h1>Routing Rules</h1><p><a name="istio.proxy.v1.config.RouteRule"></a></p><h3 id="routerule">RouteRule</h3><p><a name="rpcIstio.proxy.v1.configIstio.proxy.v1.config.RouteRuleDescriptionSubsectionSubsectionSubsection"></a></p><h4 id="glossary--concepts">Glossary & concepts</h4><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><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>apiVersion: config.istio.io/v1alpha2
|
|
kind: RouteRule
|
|
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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.RouteRule.destination"></a><tr><td><code>destination</code></td><td><a href="#istio.proxy.v1.config.IstioService">IstioService</a></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><a name="istio.proxy.v1.config.RouteRule.precedence"></a><tr><td><code>precedence</code></td><td>int32</td><td>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.</td></tr><a name="istio.proxy.v1.config.RouteRule.match"></a><tr><td><code>match</code></td><td><a href="#istio.proxy.v1.config.MatchCondition">MatchCondition</a></td><td>Match condtions to be satisfied for the route rule to be activated. If match is omitted, the route rule applies only to HTTP traffic.</td></tr><a name="istio.proxy.v1.config.RouteRule.route"></a><tr><td><code>route[]</code></td><td>repeated <a href="#istio.proxy.v1.config.DestinationWeight">DestinationWeight</a></td><td>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.</td></tr><a name="istio.proxy.v1.config.RouteRule.redirect"></a><tr><td><code>redirect</code></td><td><a href="#istio.proxy.v1.config.HTTPRedirect">HTTPRedirect</a></td><td>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.</td></tr><a name="istio.proxy.v1.config.RouteRule.rewrite"></a><tr><td><code>rewrite</code></td><td><a href="#istio.proxy.v1.config.HTTPRewrite">HTTPRewrite</a></td><td>Rewrite HTTP URIs and Authority headers. Rewrite cannot be used with Redirect primitive. Rewrite will be performed before forwarding.</td></tr><a name="istio.proxy.v1.config.RouteRule.websocketUpgrade"></a><tr><td><code>websocketUpgrade</code></td><td>bool</td><td>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.</td></tr><a name="istio.proxy.v1.config.RouteRule.httpReqTimeout"></a><tr><td><code>httpReqTimeout</code></td><td><a href="#istio.proxy.v1.config.HTTPTimeout">HTTPTimeout</a></td><td>Timeout policy for HTTP requests.</td></tr><a name="istio.proxy.v1.config.RouteRule.httpReqRetries"></a><tr><td><code>httpReqRetries</code></td><td><a href="#istio.proxy.v1.config.HTTPRetry">HTTPRetry</a></td><td>Retry policy for HTTP requests.</td></tr><a name="istio.proxy.v1.config.RouteRule.httpFault"></a><tr><td><code>httpFault</code></td><td><a href="#istio.proxy.v1.config.HTTPFaultInjection">HTTPFaultInjection</a></td><td>Fault injection policy to apply on HTTP traffic</td></tr></table><p><a name="istio.proxy.v1.config.IstioService"></a></p><h3 id="istioservice">IstioService</h3><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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.IstioService.name"></a><tr><td><code>name</code></td><td>string</td><td>The short name of the service such as "foo".</td></tr><a name="istio.proxy.v1.config.IstioService.namespace"></a><tr><td><code>namespace</code></td><td>string</td><td>Optional namespace of the service. Defaults to value of metadata namespace field.</td></tr><a name="istio.proxy.v1.config.IstioService.domain"></a><tr><td><code>domain</code></td><td>string</td><td>Domain suffix used to construct the service FQDN in implementations that support such specification.</td></tr><a name="istio.proxy.v1.config.IstioService.service"></a><tr><td><code>service</code></td><td>string</td><td>The service FQDN.</td></tr><a name="istio.proxy.v1.config.IstioService.labels"></a><tr><td><code>labels</code></td><td>repeated map<string, string></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></table><p><a name="istio.proxy.v1.config.MatchCondition"></a></p><h3 id="matchcondition">MatchCondition</h3><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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.MatchCondition.source"></a><tr><td><code>source</code></td><td><a href="#istio.proxy.v1.config.IstioService">IstioService</a></td><td>Identifies the service initiating a connection or a request.</td></tr><a name="istio.proxy.v1.config.MatchCondition.request"></a><tr><td><code>request</code></td><td><a href="#istio.proxy.v1.config.MatchRequest">MatchRequest</a></td><td>Attributes of an HTTP request to match.</td></tr></table><p><a name="istio.proxy.v1.config.MatchRequest"></a></p><h4 id="matchrequest">MatchRequest</h4><p>MatchRequest specifies the attributes of an HTTP request to be used for matching a request.</p><table><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.MatchRequest.headers"></a><tr><td><code>headers</code></td><td>repeated map<string, <a href="#istio.proxy.v1.config.StringMatch">StringMatch</a>></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></table><p><a name="istio.proxy.v1.config.StringMatch"></a></p><h4 id="stringmatch">StringMatch</h4><p>Describes how to match a given string in HTTP headers. Match is case-sensitive.</p><table><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.StringMatch.exact"></a><tr><td><code>exact</code></td><td>string (oneof )</td><td>exact string match</td></tr><a name="istio.proxy.v1.config.StringMatch.prefix"></a><tr><td><code>prefix</code></td><td>string (oneof )</td><td>prefix-based match</td></tr><a name="istio.proxy.v1.config.StringMatch.regex"></a><tr><td><code>regex</code></td><td>string (oneof )</td><td>ECMAscript style regex-based match</td></tr></table><p><a name="istio.proxy.v1.config.DestinationWeight"></a></p><h3 id="destinationweight">DestinationWeight</h3><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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.DestinationWeight.destination"></a><tr><td><code>destination</code></td><td><a href="#istio.proxy.v1.config.IstioService">IstioService</a></td><td>Sometimes required. Optional destination uniquely identifies the destination service. If not specified, the value is inherited from the parent route rule.</td></tr><a name="istio.proxy.v1.config.DestinationWeight.labels"></a><tr><td><code>labels</code></td><td>repeated map<string, string></td><td>Sometimes required. Service version identifier for the destination service.</td></tr><a name="istio.proxy.v1.config.DestinationWeight.weight"></a><tr><td><code>weight</code></td><td>int32</td><td>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.</td></tr></table><p><a name="istio.proxy.v1.config.HTTPRedirect"></a></p><h3 id="httpredirect">HTTPRedirect</h3><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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPRedirect.uri"></a><tr><td><code>uri</code></td><td>string</td><td>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.</td></tr><a name="istio.proxy.v1.config.HTTPRedirect.authority"></a><tr><td><code>authority</code></td><td>string</td><td>On a redirect, overwrite the Authority/Host portion of the URL with this value</td></tr></table><p><a name="istio.proxy.v1.config.HTTPRewrite"></a></p><h3 id="httprewrite">HTTPRewrite</h3><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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPRewrite.uri"></a><tr><td><code>uri</code></td><td>string</td><td>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.</td></tr><a name="istio.proxy.v1.config.HTTPRewrite.authority"></a><tr><td><code>authority</code></td><td>string</td><td>rewrite the Authority/Host header with this value.</td></tr></table><p><a name="istio.proxy.v1.config.HTTPTimeout"></a></p><h3 id="httptimeout">HTTPTimeout</h3><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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPTimeout.simpleTimeout"></a><tr><td><code>simpleTimeout</code></td><td><a href="#istio.proxy.v1.config.HTTPTimeout.SimpleTimeoutPolicy">SimpleTimeoutPolicy</a></td><td></td></tr></table><p><a name="istio.proxy.v1.config.HTTPTimeout.SimpleTimeoutPolicy"></a></p><h4 id="simpletimeoutpolicy">SimpleTimeoutPolicy</h4><table><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPTimeout.SimpleTimeoutPolicy.timeout"></a><tr><td><code>timeout</code></td><td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td><td>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.</td></tr></table><p><a name="istio.proxy.v1.config.HTTPRetry"></a></p><h3 id="httpretry">HTTPRetry</h3><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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPRetry.simpleRetry"></a><tr><td><code>simpleRetry</code></td><td><a href="#istio.proxy.v1.config.HTTPRetry.SimpleRetryPolicy">SimpleRetryPolicy</a></td><td></td></tr></table><p><a name="istio.proxy.v1.config.HTTPRetry.SimpleRetryPolicy"></a></p><h4 id="simpleretrypolicy">SimpleRetryPolicy</h4><table><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPRetry.SimpleRetryPolicy.attempts"></a><tr><td><code>attempts</code></td><td>int32</td><td>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.</td></tr><a name="istio.proxy.v1.config.HTTPRetry.SimpleRetryPolicy.perTryTimeout"></a><tr><td><code>perTryTimeout</code></td><td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td><td>Timeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.</td></tr></table><p><a name="istio.proxy.v1.config.HTTPFaultInjection"></a></p><h3 id="httpfaultinjection">HTTPFaultInjection</h3><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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPFaultInjection.delay"></a><tr><td><code>delay</code></td><td><a href="#istio.proxy.v1.config.HTTPFaultInjection.Delay">Delay</a></td><td>Delay requests before forwarding, emulating various failures such as network issues, overloaded upstream service, etc.</td></tr><a name="istio.proxy.v1.config.HTTPFaultInjection.abort"></a><tr><td><code>abort</code></td><td><a href="#istio.proxy.v1.config.HTTPFaultInjection.Abort">Abort</a></td><td>Abort Http request attempts and return error codes back to downstream service, giving the impression that the upstream service is faulty.</td></tr></table><p><a name="istio.proxy.v1.config.HTTPFaultInjection.Abort"></a></p><h4 id="abort">Abort</h4><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 HttpStatus_ field is used to indicate the HTTP status code to return to the caller. The optional Percent_ 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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPFaultInjection.Abort.percent"></a><tr><td><code>percent</code></td><td>float</td><td>percentage of requests to be aborted with the error code provided (0-100).</td></tr><a name="istio.proxy.v1.config.HTTPFaultInjection.Abort.httpStatus"></a><tr><td><code>httpStatus</code></td><td>int32</td><td>REQUIRED. HTTP status code to use to abort the Http request.</td></tr></table><p><a name="istio.proxy.v1.config.HTTPFaultInjection.Delay"></a></p><h4 id="delay">Delay</h4><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 FixedDelay_ field is used to indicate the amount of delay in seconds. An optional Percent_ 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><tr><th>Field</th><th>Type</th><th>Description</th></tr><a name="istio.proxy.v1.config.HTTPFaultInjection.Delay.percent"></a><tr><td><code>percent</code></td><td>float</td><td>percentage of requests on which the delay will be injected (0-100)</td></tr><a name="istio.proxy.v1.config.HTTPFaultInjection.Delay.fixedDelay"></a><tr><td><code>fixedDelay</code></td><td><a href="https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration">Duration</a></td><td>REQUIRED. Add a fixed delay before forwarding the request. Format: 1h/1m/1s/1ms. MUST be >=1ms.</td></tr></table></div></div></div></div></div></div><script src="/v0.4/js/sidebar.min.js"></script><footer><div class="container"><div class="row"><div class="col-lg-2 col-md-2 col-sm-2"></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li><a class="header" href="/v0.4/docs/welcome">Docs</a></li><li><a href="/v0.4/docs/concepts">Concepts</a></li><li><a href="/v0.4/docs/setup">Setup</a></li><li><a href="/v0.4/docs/tasks">Tasks</a></li><li><a href="/v0.4/docs/guides">Guides</a></li><li><a href="/v0.4/docs/reference">Reference</a></li></ul></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li><a class="header" href="/v0.4/help">Help</a></li><li><a href="/v0.4/faq">FAQ</a></li><li><a href="/v0.4/glossary">Glossary</a></li><li><a href="/v0.4/troubleshooting">Troubleshooting</a></li><li><a href="/v0.4/bugs">Report Bugs</a></li><li><a href="https://github.com/istio/istio.github.io/issues/new?title=Issue with _docs/reference/config/traffic-rules/routing-rules.md">Doc Bugs & Gaps</a></li><li><a href="https://github.com/istio/istio.github.io/edit/master/_docs/reference/config/traffic-rules/routing-rules.md">Edit This Page</a></li></ul></div><div class="col-lg-3 col-md-3 col-sm-3 col-xs-12 center-block"><ul><li> <a class="header" href="/v0.4/community">Community</a></li><li> <a href="https://groups.google.com/forum/#!forum/istio-users" target="_blank" rel="noopener">User</a> | <a href="https://groups.google.com/forum/#!forum/istio-dev" target="_blank" rel="noopener">Dev Mailing Lists</a></li><li><a href="https://twitter.com/IstioMesh" target="_blank" rel="noopener">Twitter</a></li><li><a href="https://stackoverflow.com/questions/tagged/istio" target="_blank" rel="noopener">Stack Overflow</a></li><li><a href="https://github.com/istio/community" target="_blank" rel="noopener">GitHub</a></li><li><a href="https://github.com/istio/community/blob/master/WORKING-GROUPS.md" target="_blank" rel="noopener">Working Groups</a></li></ul></div><div class="col-lg-1 col-md-1 col-sm-1"></div></div><div class="row"><p class="description small text-center"> Istio 0.4, Copyright © 2017 Istio Authors<br> Archived on 20-Dec-2017</p></div></div></footer><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.15.0/jquery.validate.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.form/4.2.1/jquery.form.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-visible/1.2.0/jquery.visible.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/slick-carousel/1.6.0/slick.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script> <script src="/v0.4/js/common.min.js"></script> <script src="/v0.4/js/search.js"></script> <script src="/v0.4/js/prism.min.js"></script></body></html>
|