Join us at KubeCon Europe 2020, March 30 - April 2, Amsterdam
Virtual Service
25 minute read
Configuration affecting traffic routing. Here are a few terms useful to define
in the context of traffic routing.
Service a unit of application behavior bound to a unique name in a
service registry. Services consist of multiple network endpoints
implemented by workload instances running on pods, containers, VMs etc.
Service versions (a.k.a. subsets) - In a continuous deployment
scenario, for a given service, there can be distinct subsets of
instances running 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.
Source - A downstream client calling a service.
Host - The address used by a client when attempting to connect to a
service.
Access model - Applications address only the destination service
(Host) without knowledge of individual service versions (subsets). The
actual choice of the version is determined by the proxy/sidecar, enabling the
application code to decouple itself from the evolution of dependent
services.
A VirtualService defines a set of traffic routing rules to apply when a host is
addressed. Each routing rule defines matching criteria for traffic of a specific
protocol. If the traffic is matched, then it is sent to a named destination service
(or subset/version of it) defined in the registry.
The source of traffic can also be matched in a routing rule. This allows routing
to be customized for specific client contexts.
The following example on Kubernetes, routes all HTTP traffic by default to
pods of the reviews service with label “version: v1”. In addition,
HTTP requests with path starting with /wpcatalog/ or /consumercatalog/ will
be rewritten to /newcatalog and sent to pods with label “version: v2”.
A subset/version of a route destination is identified with a reference
to a named service subset which must be declared in a corresponding
DestinationRule.
Describes the Cross-Origin Resource Sharing (CORS) policy, for a given
service. Refer to CORS1
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.
String patterns that match allowed origins.
An origin is allowed if any of the string matchers match.
If a match is found, then the outgoing Access-Control-Allow-Origin would be set to the origin as provided by the client.
No
allowMethods
string[]
List of HTTP methods allowed to access the resource. The content will
be serialized into the Access-Control-Allow-Methods header.
No
allowHeaders
string[]
List of HTTP headers that can be used when requesting the
resource. Serialized to Access-Control-Allow-Headers header.
No
exposeHeaders
string[]
A white list of HTTP headers that the browsers are allowed to
access. Serialized into Access-Control-Expose-Headers header.
Indicates whether the caller is allowed to send the actual request
(not the preflight) using credentials. Translates to
Access-Control-Allow-Credentials header.
No
Destination
Destination indicates the network addressable service to which the
request/connection will be sent after processing a routing rule. The
destination.host should unambiguously refer to a service in the service
registry. Istio’s service registry is composed of all the services found
in the platform’s service registry (e.g., Kubernetes services, Consul
services), as well as services declared through the
ServiceEntry resource.
Note for Kubernetes users: When short names are used (e.g. “reviews”
instead of “reviews.default.svc.cluster.local”), Istio will interpret
the short name based on the namespace of the rule, not the service. A
rule in the “default” namespace containing a host “reviews will be
interpreted as “reviews.default.svc.cluster.local”, irrespective of the
actual namespace associated with the reviews service. To avoid potential
misconfigurations, it is recommended to always use fully qualified
domain names over short names.
The following Kubernetes example routes all traffic by default to pods
of the reviews service with label “version: v1” (i.e., subset v1), and
some to subset v2, in a Kubernetes environment.
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:name: reviews-route
namespace: foo
spec:hosts:- reviews # interpreted as reviews.foo.svc.cluster.localhttp:-match:-uri:prefix:"/wpcatalog"-uri:prefix:"/consumercatalog"rewrite:uri:"/newcatalog"route:-destination:host: reviews # interpreted as reviews.foo.svc.cluster.localsubset: v2
-route:-destination:host: reviews # interpreted as reviews.foo.svc.cluster.localsubset: v1
The following VirtualService sets a timeout of 5s for all calls to
productpage.prod.svc.cluster.local service in Kubernetes. Notice that
there are no subsets defined in this rule. Istio will fetch all
instances of productpage.prod.svc.cluster.local service from the service
registry and populate the sidecar’s load balancing pool. Also, notice
that this rule is set in the istio-system namespace but uses the fully
qualified domain name of the productpage service,
productpage.prod.svc.cluster.local. Therefore the rule’s namespace does
not have an impact in resolving the name of the productpage service.
To control routing for traffic bound to services outside the mesh, external
services must first be added to Istio’s internal service registry using the
ServiceEntry resource. VirtualServices can then be defined to control traffic
bound to these external services. For example, the following rules define a
Service for wikipedia.org and set a timeout of 5s for HTTP requests.
The name of a service from the service registry. Service
names are looked up from the platform’s service registry (e.g.,
Kubernetes services, Consul services, etc.) and from the hosts
declared by ServiceEntry. Traffic forwarded to
destinations that are not found in either of the two, will be dropped.
Note for Kubernetes users: When short names are used (e.g. “reviews”
instead of “reviews.default.svc.cluster.local”), Istio will interpret
the short name based on the namespace of the rule, not the service. A
rule in the “default” namespace containing a host “reviews will be
interpreted as “reviews.default.svc.cluster.local”, irrespective of
the actual namespace associated with the reviews service. To avoid
potential misconfiguration, it is recommended to always use fully
qualified domain names over short names.
Yes
subset
string
The name of a subset within the service. Applicable only to services
within the mesh. The subset must be defined in a corresponding
DestinationRule.
Specifies the port on the host that is being addressed. If a service
exposes only a single port it is not required to explicitly select the
port.
No
HTTPFaultInjection
HTTPFaultInjection can be used to specify one or more faults to inject
while forwarding HTTP requests to the destination specified in a route.
Fault specification is part of a VirtualService 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.
Note: Delay and abort faults are independent of one another, even if
both are specified simultaneously.
Abort Http request attempts and return error codes back to downstream
service, giving the impression that the upstream service is faulty.
No
HTTPFaultInjection.Abort
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 1 out of every 1000 requests to the “ratings” service “v1”.
The httpStatus field is used to indicate the HTTP status code to
return to the caller. The optional percentage field can be used to only
abort a certain percentage of requests. If not specified, all requests are
aborted.
Field
Type
Description
Required
httpStatus
int32 (oneof)
HTTP status code to use to abort the Http request.
Percentage of requests to be aborted with the error code provided.
No
HTTPFaultInjection.Delay
Delay specification is used to inject latency into the request
forwarding path. The following example will introduce a 5 second delay
in 1 out of every 1000 requests to the “v1” version of the “reviews”
service from all pods with label env: prod
The fixedDelay field is used to indicate the amount of delay in seconds.
The optional percentage field can be used to only delay a certain
percentage of requests. If left unspecified, all request will be delayed.
Percentage of requests on which the delay will be injected.
No
percent
int32
Percentage of requests on which the delay will be injected (0-100).
Use of integer percent value is deprecated. Use the double percentage
field instead.
No
HTTPMatchRequest
HttpMatchRequest specifies a set of criterion to be met in order for the
rule to be applied to the HTTP request. For example, the following
restricts the rule to match only requests where the URL path
starts with /ratings/v2/ and the request contains a custom end-user header
with value jason.
The name assigned to a match. The match’s name will be
concatenated with the parent route’s name and will be logged in
the access logs for requests matching this route.
The header keys must be lowercase and use hyphen as the separator,
e.g. x-request-id.
Header values are case-sensitive and formatted as follows:
exact: "value" for exact string match
prefix: "value" for prefix-based match
regex: "value" for ECMAscript style regex-based match
Note: The keys uri, scheme, method, and authority will be ignored.
No
port
uint32
Specifies the ports on the host that is being addressed. Many services
only expose a single port or label ports with the protocols they support,
in these cases it is not required to explicitly select the port.
No
sourceLabels
map<string, string>
One or more labels that constrain the applicability of a rule to
workloads with the given labels. If the VirtualService has a list of
gateways specified in the top-level gateways field, it must include the reserved gateway
mesh for this field to be applicable.
No
gateways
string[]
Names of gateways where the rule should be applied. Gateway names
in the top-level gateways field of the VirtualService (if any) are overridden. The gateway
match is independent of sourceLabels.
Ex:
- For a query parameter like “?key=true”, the map key would be “key” and
the string match could be defined as exact: "true".
- For a query parameter like “?key”, the map key would be “key” and the
string match could be defined as exact: "".
- For a query parameter like “?key=123”, the map key would be “key” and the
string match could be defined as regex: "\d+$". Note that this
configuration will only match values like “123” but not “a123” or “123a”.
Note:prefix matching is currently not supported.
No
ignoreUriCase
bool
Flag to specify whether the URI matching should be case-insensitive.
Note: The case will be ignored only in the case of exact and prefix
URI matches.
No
sourceNamespace
string
Source namespace constraining the applicability of a rule to workloads in that namespace.
If the VirtualService has a list of gateways specified in the top-level gateways field,
it must include the reserved gateway mesh for this field to be applicable.
No
HTTPRedirect
HTTPRedirect can be used to send a 301 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 rule redirects
requests for /v1/getProductRatings API on the ratings service to
/v1/bookRatings provided by the bookratings service.
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.
No
authority
string
On a redirect, overwrite the Authority/Host portion of the URL with
this value.
No
redirectCode
uint32
On a redirect, Specifies the HTTP status code to use in the redirect
response. The default response code is MOVED_PERMANENTLY (301).
No
HTTPRetry
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.
Number of retries for a given request. The interval
between retries will be determined automatically (25ms+). Actual
number of retries attempted depends on the request timeout of the
HTTP route.
Timeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.
No
retryOn
string
Specifies the conditions under which retry takes place.
One or more policies can be specified using a ‘,’ delimited list.
See the retry policies4
and gRPC retry policies5 for more details.
No
HTTPRewrite
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 HTTPRouteDestination. The following example
demonstrates how to rewrite the URL prefix for api call (/ratings) to
ratings service before making the actual API call.
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.
No
authority
string
rewrite the Authority/Host header with this value.
No
HTTPRoute
Describes match conditions and actions for routing HTTP/1.1, HTTP2, and
gRPC traffic. See VirtualService for usage examples.
Field
Type
Description
Required
name
string
The name assigned to the route for debugging purposes. The
route’s name will be concatenated with the match’s name and will
be logged in the access logs for requests matching this
route/match.
Match conditions to be satisfied for the rule to be
activated. All conditions inside a single match block have AND
semantics, while the list of match blocks have OR semantics. The rule
is matched if any one of the match blocks succeed.
A HTTP rule can either redirect or forward (default) 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.
A HTTP rule can either redirect or forward (default) traffic. If
traffic passthrough option is specified in the rule,
route/redirect will be ignored. The redirect primitive can be used to
send a HTTP 301 redirect to a different URI or Authority.
Fault injection policy to apply on HTTP traffic at the client side.
Note that timeouts or retries will not be enabled when faults are
enabled on the client side.
Mirror HTTP traffic to a another destination in addition to forwarding
the requests to the intended destination. Mirrored traffic is on a
best effort basis where the sidecar/gateway 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.
Percentage of the traffic to be mirrored by the mirror field.
Use of integer mirror_percent value is deprecated. Use the
double mirror_percentage field instead
No
HTTPRouteDestination
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”.
Traffic can also be split across two entirely different services without
having to define new subsets. For example, the following rule forwards 25% of
traffic to reviews.com to dev.reviews.com
Destination uniquely identifies the instances of a service
to which the request/connection should be forwarded to.
Yes
weight
int32
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 one destination in a rule, the weight value is assumed to
be 100.
Message headers can be manipulated when Envoy forwards requests to,
or responses from, a destination service. Header manipulation rules can
be specified for a specific route destination or for all destinations.
The following VirtualService adds a test header with the value true
to requests that are routed to any reviews service destination.
It also romoves the foo response header, but only from responses
coming from the v1 subset (version) of the reviews service.
Header manipulation rules to apply before returning a response
to the caller
No
Headers.HeaderOperations
HeaderOperations Describes the header manipulations to apply
Field
Type
Description
Required
set
map<string, string>
Overwrite the headers specified by key with the given values
No
add
map<string, string>
Append the given values to the headers specified by keys
(will create a comma-separated list of values)
No
remove
string[]
Remove a the specified headers
No
L4MatchAttributes
L4 connection match attributes. Note that L4 connection matching support
is incomplete.
Field
Type
Description
Required
destinationSubnets
string[]
IPv4 or IPv6 ip addresses of destination with optional subnet. E.g.,
a.b.c.d/xx form or just a.b.c.d.
No
port
uint32
Specifies the port on the host that is being addressed. Many services
only expose a single port or label ports with the protocols they support,
in these cases it is not required to explicitly select the port.
No
sourceLabels
map<string, string>
One or more labels that constrain the applicability of a rule to
workloads with the given labels. If the VirtualService has a list of
gateways specified in the top-level gateways field, it should include the reserved gateway
mesh in order for this field to be applicable.
No
gateways
string[]
Names of gateways where the rule should be applied. Gateway names
in the top-level gateways field of the VirtualService (if any) are overridden. The gateway
match is independent of sourceLabels.
No
sourceNamespace
string
Source namespace constraining the applicability of a rule to workloads in that namespace.
If the VirtualService has a list of gateways specified in the top-level gateways field,
it must include the reserved gateway mesh for this field to be applicable.
No
Percent
Percent specifies a percentage in the range of [0.0, 100.0].
Field
Type
Description
Required
value
double
No
PortSelector
PortSelector specifies the number of a port to be used for
matching or selection for final routing.
Destination uniquely identifies the instances of a service
to which the request/connection should be forwarded to.
Yes
weight
int32
The proportion of traffic to be forwarded to the service
version. If there is only one destination in a rule, all traffic will be
routed to it irrespective of the weight.
No
StringMatch
Describes how to match a given string in HTTP headers. Match is
case-sensitive.
Field
Type
Description
Required
exact
string (oneof)
exact string match
Yes
prefix
string (oneof)
prefix-based match
Yes
regex
string (oneof)
ECMAscript style regex-based match
Yes
TCPRoute
Describes match conditions and actions for routing TCP traffic. The
following routing rule forwards traffic arriving at port 27017 for
mongo.prod.svc.cluster.local to another Mongo server on port 5555.
Match conditions to be satisfied for the rule to be
activated. All conditions inside a single match block have AND
semantics, while the list of match blocks have OR semantics. The rule
is matched if any one of the match blocks succeed.
The destination to which the connection should be forwarded to.
No
TLSMatchAttributes
TLS connection match attributes.
Field
Type
Description
Required
sniHosts
string[]
SNI (server name indicator) to match on. Wildcard prefixes
can be used in the SNI value, e.g., *.com will match foo.example.com
as well as example.com. An SNI value must be a subset (i.e., fall
within the domain) of the corresponding virtual serivce’s hosts.
Yes
destinationSubnets
string[]
IPv4 or IPv6 ip addresses of destination with optional subnet. E.g.,
a.b.c.d/xx form or just a.b.c.d.
No
port
uint32
Specifies the port on the host that is being addressed. Many services
only expose a single port or label ports with the protocols they
support, in these cases it is not required to explicitly select the
port.
No
sourceLabels
map<string, string>
One or more labels that constrain the applicability of a rule to
workloads with the given labels. If the VirtualService has a list of
gateways specified in the top-level gateways field, it should include the reserved gateway
mesh in order for this field to be applicable.
No
gateways
string[]
Names of gateways where the rule should be applied. Gateway names
in the top-level gateways field of the VirtualService (if any) are overridden. The gateway
match is independent of sourceLabels.
No
sourceNamespace
string
Source namespace constraining the applicability of a rule to workloads in that namespace.
If the VirtualService has a list of gateways specified in the top-level gateways field,
it must include the reserved gateway mesh for this field to be applicable.
No
TLSRoute
Describes match conditions and actions for routing unterminated TLS
traffic (TLS/HTTPS) The following routing rule forwards unterminated TLS
traffic arriving at port 443 of gateway called “mygateway” to internal
services in the mesh based on the SNI value.
Match conditions to be satisfied for the rule to be
activated. All conditions inside a single match block have AND
semantics, while the list of match blocks have OR semantics. The rule
is matched if any one of the match blocks succeed.
The destination to which the connection should be forwarded to.
No
VirtualService
Configuration affecting traffic routing.
Field
Type
Description
Required
hosts
string[]
The destination hosts to which traffic is being sent. Could
be a DNS name with wildcard prefix or an IP address. Depending on the
platform, short-names can also be used instead of a FQDN (i.e. has no
dots in the name). In such a scenario, the FQDN of the host would be
derived based on the underlying platform.
A single VirtualService can be used to describe all the traffic
properties of the corresponding hosts, including those for multiple
HTTP and TCP ports. Alternatively, the traffic properties of a host
can be defined using more than one VirtualService, with certain
caveats. Refer to the
Operations Guide
for details.
Note for Kubernetes users: When short names are used (e.g. “reviews”
instead of “reviews.default.svc.cluster.local”), Istio will interpret
the short name based on the namespace of the rule, not the service. A
rule in the “default” namespace containing a host “reviews” will be
interpreted as “reviews.default.svc.cluster.local”, irrespective of
the actual namespace associated with the reviews service. To avoid
potential misconfigurations, it is recommended to always use fully
qualified domain names over short names.
The hosts field applies to both HTTP and TCP services. Service inside
the mesh, i.e., those found in the service registry, must always be
referred to using their alphanumeric names. IP addresses are allowed
only for services defined via the Gateway.
Yes
gateways
string[]
The names of gateways and sidecars that should apply these routes.
Gateways in other namespaces may be referred to by
<gateway namespace>/<gateway name>; specifying a gateway with no
namespace qualifier is the same as specifying the VirtualService’s
namespace. A single VirtualService is used for sidecars inside the mesh as
well as for one or more gateways. The selection condition imposed by this
field can be overridden using the source field in the match conditions
of protocol-specific routes. The reserved word mesh is used to imply
all the sidecars in the mesh. When this field is omitted, the default
gateway (mesh) will be used, which would apply the rule to all
sidecars in the mesh. If a list of gateway names is provided, the
rules will apply only to the gateways. To apply the rules to both
gateways and sidecars, specify mesh as one of the gateway names.
An ordered list of route rules for HTTP traffic. HTTP routes will be
applied to platform service ports named ‘http-’/‘http2-’/‘grpc-*’, gateway
ports with protocol HTTP/HTTP2/GRPC/ TLS-terminated-HTTPS and service
entry ports using HTTP/HTTP2/GRPC protocols. The first rule matching
an incoming request is used.
An ordered list of route rule for non-terminated TLS & HTTPS
traffic. Routing is typically performed using the SNI value presented
by the ClientHello message. TLS routes will be applied to platform
service ports named ‘https-’, ‘tls-’, unterminated gateway ports using
HTTPS/TLS protocols (i.e. with “passthrough” TLS mode) and service
entry ports using HTTPS/TLS protocols. The first rule matching an
incoming request is used. NOTE: Traffic ‘https-’ or ‘tls-’ ports
without associated virtual service will be treated as opaque TCP
traffic.
An ordered list of route rules for opaque TCP traffic. TCP routes will
be applied to any port that is not a HTTP or TLS port. The first rule
matching an incoming request is used.
No
exportTo
string[]
A list of namespaces to which this virtual service is exported. Exporting a
virtual service allows it to be used by sidecars and gateways defined in
other namespaces. This feature provides a mechanism for service owners
and mesh administrators to control the visibility of virtual services
across namespace boundaries.
If no namespaces are specified then the virtual service is exported to all
namespaces by default.
The value “.” is reserved and defines an export to the same namespace that
the virtual service is declared in. Similarly the value “*” is reserved and
defines an export to all namespaces.
NOTE: in the current release, the exportTo value is restricted to
“.” or “*” (i.e., the current namespace or all namespaces).
No
google.protobuf.UInt32Value
Wrapper message for uint32.
The JSON representation for UInt32Value is JSON number.