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.
CaptureMode describes how traffic to a listener is expected to be -captured. Applicable only when the listener is bound to an IP.
- -| Name | -Description | -
|---|---|
DEFAULT |
-
- The default capture mode defined by the environment - - |
-
IPTABLES |
-
- Capture traffic using IPtables redirection - - |
-
NONE |
-
- No traffic capture. When used in egress listener, the application is -expected to explicitly communicate with the listener port/unix -domain socket. When used in ingress listener, care needs to be taken -to ensure that the listener port is not in use by other processes on -the host. - - |
-
Connection pool settings for an upstream host. The settings apply to -each individual host in the upstream service. See Envoy’s circuit -breaker -for more details. Connection pool settings can be applied at the TCP -level as well as at HTTP level.
- -For example, the following rule sets a limit of 100 connections to redis -service called myredissrv with a connect timeout of 30ms
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: bookinfo-redis
-spec:
- host: myredissrv.prod.svc.cluster.local
- trafficPolicy:
- connectionPool:
- tcp:
- maxConnections: 100
- connectTimeout: 30ms
- tcpKeepalive:
- time: 7200s
- interval: 75s
-Settings applicable to HTTP1.1/HTTP2/GRPC connections.
- - -Settings common to both HTTP and TCP upstream connections.
- - -TCP keepalive.
- - -Describes the Cross-Origin Resource Sharing (CORS) policy, for a given
-service. Refer to
-https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_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.
apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: ratings-route
-spec:
- hosts:
- - ratings.prod.svc.cluster.local
- http:
- - route:
- - destination:
- host: ratings.prod.svc.cluster.local
- subset: v1
- corsPolicy:
- allowOrigin:
- - example.com
- allowMethods:
- - POST
- - GET
- allowCredentials: false
- allowHeaders:
- - X-Foo-Bar
- maxAge: "1d"
-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/v1alpha3
-kind: VirtualService
-metadata:
- name: reviews-route
- namespace: foo
-spec:
- hosts:
- - reviews # interpreted as reviews.foo.svc.cluster.local
- http:
- - match:
- - uri:
- prefix: "/wpcatalog"
- - uri:
- prefix: "/consumercatalog"
- rewrite:
- uri: "/newcatalog"
- route:
- - destination:
- host: reviews # interpreted as reviews.foo.svc.cluster.local
- subset: v2
- - route:
- - destination:
- host: reviews # interpreted as reviews.foo.svc.cluster.local
- subset: v1
-And the associated DestinationRule
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: reviews-destination
- namespace: foo
-spec:
- host: reviews # interpreted as reviews.foo.svc.cluster.local
- subsets:
- - name: v1
- labels:
- version: v1
- - name: v2
- labels:
- version: v2
-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.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: my-productpage-rule
- namespace: istio-system
-spec:
- hosts:
- - productpage.prod.svc.cluster.local # ignores rule namespace
- http:
- - timeout: 5s
- route:
- - destination:
- host: productpage.prod.svc.cluster.local
-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.
- -apiVersion: networking.istio.io/v1alpha3
-kind: ServiceEntry
-metadata:
- name: external-svc-wikipedia
-spec:
- hosts:
- - wikipedia.org
- location: MESH_EXTERNAL
- ports:
- - number: 80
- name: example-http
- protocol: HTTP
- resolution: DNS
-
-apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: my-wiki-rule
-spec:
- hosts:
- - wikipedia.org
- http:
- - timeout: 5s
- route:
- - destination:
- host: wikipedia.org
-DestinationRule defines policies that apply to traffic intended for a
-service after routing has occurred. These rules specify configuration
-for load balancing, connection pool size from the sidecar, and outlier
-detection settings to detect and evict unhealthy hosts from the load
-balancing pool. For example, a simple load balancing policy for the
-ratings service would look as follows:
apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: bookinfo-ratings
-spec:
- host: ratings.prod.svc.cluster.local
- trafficPolicy:
- loadBalancer:
- simple: LEAST_CONN
-Version specific policies can be specified by defining a named
-subset and overriding the settings specified at the service level. The
-following rule uses a round robin load balancing policy for all traffic
-going to a subset named testversion that is composed of endpoints (e.g.,
-pods) with labels (version:v3).
apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: bookinfo-ratings
-spec:
- host: ratings.prod.svc.cluster.local
- trafficPolicy:
- loadBalancer:
- simple: LEAST_CONN
- subsets:
- - name: testversion
- labels:
- version: v3
- trafficPolicy:
- loadBalancer:
- simple: ROUND_ROBIN
-Note: Policies specified for subsets will not take effect until -a route rule explicitly sends traffic to this subset.
- -Traffic policies can be customized to specific ports as well. The -following rule uses the least connection load balancing policy for all -traffic to port 80, while uses a round robin load balancing setting for -traffic to the port 9080.
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: bookinfo-ratings-port
-spec:
- host: ratings.prod.svc.cluster.local
- trafficPolicy: # Apply to all ports
- portLevelSettings:
- - port:
- number: 80
- loadBalancer:
- simple: LEAST_CONN
- - port:
- number: 9080
- loadBalancer:
- simple: ROUND_ROBIN
-EnvoyFilter describes Envoy proxy-specific filters that can be used to
-customize the Envoy proxy configuration generated by Istio networking
-subsystem (Pilot). This feature must be used with care, as incorrect
-configurations could potentially destabilize the entire mesh.
NOTE 1: Since this is break glass configuration, there will not be any -backward compatibility across different Istio releases. In other words, -this configuration is subject to change based on internal implementation -of Istio networking subsystem.
- -NOTE 2: When multiple EnvoyFilters are bound to the same workload, all filter -configurations will be processed sequentially in order of creation time. -The behavior is undefined if multiple EnvoyFilter configurations conflict -with each other.
- -The following example for Kubernetes enables Envoy’s Lua filter for all -inbound calls arriving at service port 8080 of the reviews service pod with -labels “app: reviews”.
- -apiVersion: networking.istio.io/v1alpha3
-kind: EnvoyFilter
-metadata:
- name: reviews-lua
-spec:
- workloadLabels:
- app: reviews
- filters:
- - listenerMatch:
- portNumber: 8080
- listenerType: SIDECAR_INBOUND #will match with the inbound listener for reviews:8080
- filterName: envoy.lua
- filterType: HTTP
- filterConfig:
- inlineCode: |
- ... lua code ...
-Envoy filters to be added to a network or http filter chain.
- - -| Name | -Description | -
|---|---|
INVALID |
-
- placeholder - - |
-
HTTP |
-
- Http filter - - |
-
NETWORK |
-
- Network filter - - |
-
Indicates the relative index in the filter chain where the filter should be inserted.
- - -Index/position in the filter chain.
- -| Name | -Description | -
|---|---|
FIRST |
-
- Insert first - - |
-
LAST |
-
- Insert last - - |
-
BEFORE |
-
- Insert before the named filter. - - |
-
AFTER |
-
- Insert after the named filter. - - |
-
Select a listener to add the filter to based on the match conditions. -All conditions specified in the ListenerMatch must be met for the filter -to be applied to a listener.
- - -| Name | -Description | -
|---|---|
ALL |
-
- All protocols - - |
-
HTTP |
-
- HTTP or HTTPS (with termination) / HTTP2/gRPC - - |
-
TCP |
-
- Any non-HTTP listener - - |
-
| Name | -Description | -
|---|---|
ANY |
-
- All listeners - - |
-
SIDECAR_INBOUND |
-
- Inbound listener in sidecar - - |
-
SIDECAR_OUTBOUND |
-
- Outbound listener in sidecar - - |
-
GATEWAY |
-
- Gateway listener - - |
-
Gateway describes a load balancer operating at the edge of the mesh
-receiving incoming or outgoing HTTP/TCP connections. The specification
-describes a set of ports that should be exposed, the type of protocol to
-use, SNI configuration for the load balancer, etc.
For example, the following Gateway configuration sets up a proxy to act
-as a load balancer exposing port 80 and 9080 (http), 443 (https), and
-port 2379 (TCP) for ingress. The gateway will be applied to the proxy
-running on a pod with labels app: my-gateway-controller. While Istio
-will configure the proxy to listen on these ports, it is the
-responsibility of the user to ensure that external traffic to these
-ports are allowed into the mesh.
apiVersion: networking.istio.io/v1alpha3
-kind: Gateway
-metadata:
- name: my-gateway
- namespace: some-config-namespace
-spec:
- selector:
- app: my-gateway-controller
- servers:
- - port:
- number: 80
- name: http
- protocol: HTTP
- hosts:
- - uk.bookinfo.com
- - eu.bookinfo.com
- tls:
- httpsRedirect: true # sends 301 redirect for http requests
- - port:
- number: 443
- name: https
- protocol: HTTPS
- hosts:
- - uk.bookinfo.com
- - eu.bookinfo.com
- tls:
- mode: SIMPLE #enables HTTPS on this port
- serverCertificate: /etc/certs/servercert.pem
- privateKey: /etc/certs/privatekey.pem
- - port:
- number: 9080
- name: http-wildcard
- protocol: HTTP
- hosts:
- - "*"
- - port:
- number: 2379 # to expose internal service via external port 2379
- name: mongo
- protocol: MONGO
- hosts:
- - "*"
-The Gateway specification above describes the L4-L6 properties of a load
-balancer. A VirtualService can then be bound to a gateway to control
-the forwarding of traffic arriving at a particular host or gateway port.
For example, the following VirtualService splits traffic for -“https://uk.bookinfo.com/reviews”, “https://eu.bookinfo.com/reviews”, -“http://uk.bookinfo.com:9080/reviews”, -“http://eu.bookinfo.com:9080/reviews” into two versions (prod and qa) of -an internal reviews service on port 9080. In addition, requests -containing the cookie “user: dev-123” will be sent to special port 7777 -in the qa version. The same rule is also applicable inside the mesh for -requests to the “reviews.prod.svc.cluster.local” service. This rule is -applicable across ports 443, 9080. Note that “http://uk.bookinfo.com” -gets redirected to “https://uk.bookinfo.com” (i.e. 80 redirects to 443).
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: bookinfo-rule
- namespace: bookinfo-namespace
-spec:
- hosts:
- - reviews.prod.svc.cluster.local
- - uk.bookinfo.com
- - eu.bookinfo.com
- gateways:
- - some-config-namespace/my-gateway
- - mesh # applies to all the sidecars in the mesh
- http:
- - match:
- - headers:
- cookie:
- user: dev-123
- route:
- - destination:
- port:
- number: 7777
- host: reviews.qa.svc.cluster.local
- - match:
- uri:
- prefix: /reviews/
- route:
- - destination:
- port:
- number: 9080 # can be omitted if its the only port for reviews
- host: reviews.prod.svc.cluster.local
- weight: 80
- - destination:
- host: reviews.qa.svc.cluster.local
- weight: 20
-The following VirtualService forwards traffic arriving at (external)
-port 27017 to internal Mongo server on port 5555. This rule is not
-applicable internally in the mesh as the gateway list omits the
-reserved name mesh.
apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: bookinfo-Mongo
- namespace: bookinfo-namespace
-spec:
- hosts:
- - mongosvr.prod.svc.cluster.local #name of internal Mongo service
- gateways:
- - some-config-namespace/my-gateway # can omit the namespace if gateway is in same
- namespace as virtual service.
- tcp:
- - match:
- - port: 27017
- route:
- - destination:
- host: mongo.prod.svc.cluster.local
- port:
- number: 5555
-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 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”.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: ratings-route
-spec:
- hosts:
- - ratings.prod.svc.cluster.local
- http:
- - route:
- - destination:
- host: ratings.prod.svc.cluster.local
- subset: v1
- fault:
- abort:
- percentage:
- value: 0.001
- httpStatus: 400
-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.
- - -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
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: reviews-route
-spec:
- hosts:
- - reviews.prod.svc.cluster.local
- http:
- - match:
- - sourceLabels:
- env: prod
- route:
- - destination:
- host: reviews.prod.svc.cluster.local
- subset: v1
- fault:
- delay:
- percentage:
- value: 0.001
- fixedDelay: 5s
-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.
- - -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.
apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: ratings-route
-spec:
- hosts:
- - ratings.prod.svc.cluster.local
- http:
- - match:
- - headers:
- end-user:
- exact: jason
- uri:
- prefix: "/ratings/v2/"
- route:
- - destination:
- host: ratings.prod.svc.cluster.local
-HTTPMatchRequest CANNOT be empty.
- - -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.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: ratings-route
-spec:
- hosts:
- - ratings.prod.svc.cluster.local
- http:
- - match:
- - uri:
- exact: /v1/getProductRatings
- redirect:
- uri: /v1/bookRatings
- authority: newratings.default.svc.cluster.local
- ...
-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.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: ratings-route
-spec:
- hosts:
- - ratings.prod.svc.cluster.local
- http:
- - route:
- - destination:
- host: ratings.prod.svc.cluster.local
- subset: v1
- retries:
- attempts: 3
- perTryTimeout: 2s
- retryOn: gateway-error,connect-failure,refused-stream
-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.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: ratings-route
-spec:
- hosts:
- - ratings.prod.svc.cluster.local
- http:
- - match:
- - uri:
- prefix: /ratings
- rewrite:
- uri: /v1/bookRatings
- route:
- - destination:
- host: ratings.prod.svc.cluster.local
- subset: v1
-Describes match conditions and actions for routing HTTP/1.1, HTTP2, and -gRPC traffic. See VirtualService for usage examples.
- - -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”.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: reviews-route
-spec:
- hosts:
- - reviews.prod.svc.cluster.local
- http:
- - route:
- - destination:
- host: reviews.prod.svc.cluster.local
- subset: v2
- weight: 25
- - destination:
- host: reviews.prod.svc.cluster.local
- subset: v1
- weight: 75
-And the associated DestinationRule
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: reviews-destination
-spec:
- host: reviews.prod.svc.cluster.local
- subsets:
- - name: v1
- labels:
- version: v1
- - name: v2
- labels:
- version: v2
-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
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: reviews-route-two-domains
-spec:
- hosts:
- - reviews.com
- http:
- - route:
- - destination:
- host: dev.reviews.com
- weight: 25
- - destination:
- host: reviews.com
- weight: 75
-Header manipulation rules
- - -HeaderOperations Describes the header manipulations to apply
- - -IstioEgressListener specifies the properties of an outbound traffic -listener on the sidecar proxy attached to a workload.
- - -IstioIngressListener specifies the properties of an inbound -traffic listener on the sidecar proxy attached to a workload.
- - -L4 connection match attributes. Note that L4 connection matching support -is incomplete.
- - -Load balancing policies to apply for a specific destination. See Envoy’s -load balancing -documentation -for more details.
- -For example, the following rule uses a round robin load balancing policy -for all traffic going to the ratings service.
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: bookinfo-ratings
-spec:
- host: ratings.prod.svc.cluster.local
- trafficPolicy:
- loadBalancer:
- simple: ROUND_ROBIN
-The following example sets up sticky sessions for the ratings service -hashing-based load balancer for the same ratings service using the -the User cookie as the hash key.
- - apiVersion: networking.istio.io/v1alpha3
- kind: DestinationRule
- metadata:
- name: bookinfo-ratings
- spec:
- host: ratings.prod.svc.cluster.local
- trafficPolicy:
- loadBalancer:
- consistentHash:
- httpCookie:
- name: user
- ttl: 0s
-Consistent Hash-based load balancing can be used to provide soft -session affinity based on HTTP headers, cookies or other -properties. This load balancing policy is applicable only for HTTP -connections. The affinity to a particular destination host will be -lost when one or more hosts are added/removed from the destination -service.
- - -Describes a HTTP cookie that will be used as the hash key for the -Consistent Hash load balancer. If the cookie is not present, it will -be generated.
- - -Standard load balancing algorithms that require no tuning.
- -| Name | -Description | -
|---|---|
ROUND_ROBIN |
-
- Round Robin policy. Default - - |
-
LEAST_CONN |
-
- 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. - - |
-
RANDOM |
-
- 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. - - |
-
PASSTHROUGH |
-
- This option will forward the connection to the original IP address -requested by the caller without doing any form of load -balancing. This option must be used with care. It is meant for -advanced use cases. Refer to Original Destination load balancer in -Envoy for further details. - - |
-
A Circuit breaker implementation that tracks the status of each -individual host in the upstream service. Applicable to both HTTP and -TCP services. For HTTP services, hosts that continually return 5xx -errors for API calls are ejected from the pool for a pre-defined period -of time. For TCP services, connection timeouts or connection -failures to a given host counts as an error when measuring the -consecutive errors metric. See Envoy’s outlier -detection -for more details.
- -The following rule sets a connection pool size of 100 connections and -1000 concurrent HTTP2 requests, with no more than 10 req/connection to -“reviews” service. In addition, it configures upstream 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.
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: reviews-cb-policy
-spec:
- host: reviews.prod.svc.cluster.local
- trafficPolicy:
- connectionPool:
- tcp:
- maxConnections: 100
- http:
- http2MaxRequests: 1000
- maxRequestsPerConnection: 10
- outlierDetection:
- consecutiveErrors: 7
- interval: 5m
- baseEjectionTime: 15m
-Percent specifies a percentage in the range of [0.0, 100.0].
- - -Port describes the properties of a specific port of a service.
- - -PortSelector specifies the number of a port to be used for -matching or selection for final routing.
- - -L4 routing rule weighted destination.
- - -Server describes the properties of the proxy on a given load balancer
-port. For example,
apiVersion: networking.istio.io/v1alpha3
-kind: Gateway
-metadata:
- name: my-ingress
-spec:
- selector:
- app: my-ingress-gateway
- servers:
- - port:
- number: 80
- name: http2
- protocol: HTTP2
- hosts:
- - "*"
-Another example
- -apiVersion: networking.istio.io/v1alpha3
-kind: Gateway
-metadata:
- name: my-tcp-ingress
-spec:
- selector:
- app: my-tcp-ingress-gateway
- servers:
- - port:
- number: 27018
- name: mongo
- protocol: MONGO
- hosts:
- - "*"
-The following is an example of TLS configuration for port 443
- -apiVersion: networking.istio.io/v1alpha3
-kind: Gateway
-metadata:
- name: my-tls-ingress
-spec:
- selector:
- app: my-tls-ingress-gateway
- servers:
- - port:
- number: 443
- name: https
- protocol: HTTPS
- hosts:
- - "*"
- tls:
- mode: SIMPLE
- serverCertificate: /etc/certs/server.pem
- privateKey: /etc/certs/privatekey.pem
-TLS protocol versions.
- -| Name | -Description | -
|---|---|
TLS_AUTO |
-
- Automatically choose the optimal TLS version. - - |
-
TLSV1_0 |
-
- TLS version 1.0 - - |
-
TLSV1_1 |
-
- TLS version 1.1 - - |
-
TLSV1_2 |
-
- TLS version 1.2 - - |
-
TLSV1_3 |
-
- TLS version 1.3 - - |
-
TLS modes enforced by the proxy
- -| Name | -Description | -
|---|---|
PASSTHROUGH |
-
- The SNI string presented by the client will be used as the match -criterion in a VirtualService TLS route to determine the -destination service from the service registry. - - |
-
SIMPLE |
-
- Secure connections with standard TLS semantics. - - |
-
MUTUAL |
-
- Secure connections to the upstream using mutual TLS by presenting -client certificates for authentication. - - |
-
AUTO_PASSTHROUGH |
-
- Similar to the passthrough mode, except servers with this TLS mode -do not require an associated VirtualService to map from the SNI -value to service in the registry. The destination details such as -the service/subset/port are encoded in the SNI value. The proxy -will forward to the upstream (Envoy) cluster (a group of -endpoints) specified by the SNI value. This server is typically -used to provide connectivity between services in disparate L3 -networks that otherwise do not have direct connectivity between -their respective endpoints. Use of this mode assumes that both the -source and the destination are using Istio mTLS to secure traffic. - - |
-
ServiceEntry enables adding additional entries into Istio’s internal
-service registry, so that auto-discovered services in the mesh can
-access/route to these manually specified services. A service entry
-describes the properties of a service (DNS name, VIPs, ports, protocols,
-endpoints). These services could be external to the mesh (e.g., web
-APIs) or mesh-internal services that are not part of the platform’s
-service registry (e.g., a set of VMs talking to services in Kubernetes).
The following configuration adds a set of MongoDB instances running on -unmanaged VMs to Istio’s registry, so that these services can be treated -as any other service in the mesh. The associated DestinationRule is used -to initiate mTLS connections to the database instances.
- -apiVersion: networking.istio.io/v1alpha3
-kind: ServiceEntry
-metadata:
- name: external-svc-mongocluster
-spec:
- hosts:
- - mymongodb.somedomain # not used
- addresses:
- - 192.192.192.192/24 # VIPs
- ports:
- - number: 27018
- name: mongodb
- protocol: MONGO
- location: MESH_INTERNAL
- resolution: STATIC
- endpoints:
- - address: 2.2.2.2
- - address: 3.3.3.3
-and the associated DestinationRule
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: mtls-mongocluster
-spec:
- host: mymongodb.somedomain
- trafficPolicy:
- tls:
- mode: MUTUAL
- clientCertificate: /etc/certs/myclientcert.pem
- privateKey: /etc/certs/client_private_key.pem
- caCertificates: /etc/certs/rootcacerts.pem
-The following example uses a combination of service entry and TLS -routing in virtual service to demonstrate the use of SNI routing to -forward unterminated TLS traffic from the application to external -services via the sidecar. The sidecar inspects the SNI value in the -ClientHello message to route to the appropriate external service.
- -apiVersion: networking.istio.io/v1alpha3
-kind: ServiceEntry
-metadata:
- name: external-svc-https
-spec:
- hosts:
- - api.dropboxapi.com
- - www.googleapis.com
- - api.facebook.com
- location: MESH_EXTERNAL
- ports:
- - number: 443
- name: https
- protocol: TLS
- resolution: DNS
-And the associated VirtualService to route based on the SNI value.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: tls-routing
-spec:
- hosts:
- - api.dropboxapi.com
- - www.googleapis.com
- - api.facebook.com
- tls:
- - match:
- - port: 443
- sniHosts:
- - api.dropboxapi.com
- route:
- - destination:
- host: api.dropboxapi.com
- - match:
- - port: 443
- sniHosts:
- - www.googleapis.com
- route:
- - destination:
- host: www.googleapis.com
- - match:
- - port: 443
- sniHosts:
- - api.facebook.com
- route:
- - destination:
- host: api.facebook.com
-
-The following example demonstrates the use of a dedicated egress gateway -through which all external service traffic is forwarded. -The ‘exportTo’ field allows for control over the visibility of a service -declaration to other namespaces in the mesh. By default a service is exported -to all namespaces. The following example restricts the visibility to the -current namespace, represented by “.”, so that it cannot be used by other -namespaces.
- -apiVersion: networking.istio.io/v1alpha3
-kind: ServiceEntry
-metadata:
- name: external-svc-httpbin
- namespace : egress
-spec:
- hosts:
- - httpbin.com
- exportTo:
- - "."
- location: MESH_EXTERNAL
- ports:
- - number: 80
- name: http
- protocol: HTTP
- resolution: DNS
-Define a gateway to handle all egress traffic.
- -apiVersion: networking.istio.io/v1alpha3
-kind: Gateway
-metadata:
- name: istio-egressgateway
- namespace: egress
-spec:
- selector:
- istio: egressgateway
- servers:
- - port:
- number: 80
- name: http
- protocol: HTTP
- hosts:
- - "*"
-And the associated VirtualService to route from the sidecar to the -gateway service (istio-egressgateway.istio-system.svc.cluster.local), as -well as route from the gateway to the external service. Note that the -virtual service is exported to all namespaces enabling them to route traffic -through the gateway to the external service. Forcing traffic to go through -a managed middle proxy like this is a common practice.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: gateway-routing
- namespace: egress
-spec:
- hosts:
- - httpbin.com
- exportTo:
- - *
- gateways:
- - mesh
- - istio-egressgateway
- http:
- - match:
- - port: 80
- gateways:
- - mesh
- route:
- - destination:
- host: istio-egressgateway.istio-system.svc.cluster.local
- - match:
- - port: 80
- gateways:
- - istio-egressgateway
- route:
- - destination:
- host: httpbin.com
-The following example demonstrates the use of wildcards in the hosts for
-external services. If the connection has to be routed to the IP address
-requested by the application (i.e. application resolves DNS and attempts
-to connect to a specific IP), the discovery mode must be set to NONE.
apiVersion: networking.istio.io/v1alpha3
-kind: ServiceEntry
-metadata:
- name: external-svc-wildcard-example
-spec:
- hosts:
- - "*.bar.com"
- location: MESH_EXTERNAL
- ports:
- - number: 80
- name: http
- protocol: HTTP
- resolution: NONE
-The following example demonstrates a service that is available via a -Unix Domain Socket on the host of the client. The resolution must be -set to STATIC to use unix address endpoints.
- -apiVersion: networking.istio.io/v1alpha3
-kind: ServiceEntry
-metadata:
- name: unix-domain-socket-example
-spec:
- hosts:
- - "example.unix.local"
- location: MESH_EXTERNAL
- ports:
- - number: 80
- name: http
- protocol: HTTP
- resolution: STATIC
- endpoints:
- - address: unix:///var/run/example/socket
-For HTTP-based services, it is possible to create a VirtualService -backed by multiple DNS addressable endpoints. In such a scenario, the -application can use the HTTP_PROXY environment variable to transparently -reroute API calls for the VirtualService to a chosen backend. For -example, the following configuration creates a non-existent external -service called foo.bar.com backed by three domains: us.foo.bar.com:8080, -uk.foo.bar.com:9080, and in.foo.bar.com:7080
- -apiVersion: networking.istio.io/v1alpha3
-kind: ServiceEntry
-metadata:
- name: external-svc-dns
-spec:
- hosts:
- - foo.bar.com
- location: MESH_EXTERNAL
- ports:
- - number: 80
- name: http
- protocol: HTTP
- resolution: DNS
- endpoints:
- - address: us.foo.bar.com
- ports:
- https: 8080
- - address: uk.foo.bar.com
- ports:
- https: 9080
- - address: in.foo.bar.com
- ports:
- https: 7080
-With HTTP_PROXY=http://localhost/, calls from the application to
-http://foo.bar.com will be load balanced across the three domains
-specified above. In other words, a call to http://foo.bar.com/baz would
-be translated to http://uk.foo.bar.com/baz.
The following example illustrates the usage of a ServiceEntry -containing a subject alternate name -whose format conforms to the SPIFEE standard -https://github.com/spiffe/spiffe/blob/master/standards/SPIFFE-ID.md:
- -apiVersion: networking.istio.io/v1alpha3
-kind: ServiceEntry
-metadata:
- name: httpbin
- namespace : httpbin-ns
-spec:
- hosts:
- - httpbin.com
- location: MESH_INTERNAL
- ports:
- - number: 80
- name: http
- protocol: HTTP
- resolution: STATIC
- endpoints:
- - address: 2.2.2.2
- - address: 3.3.3.3
- subjectAltNames:
- - "spiffe://cluster.local/ns/httpbin-ns/sa/httpbin-service-account"
-Endpoint defines a network address (IP or hostname) associated with -the mesh service.
- - -Location specifies whether the service is part of Istio mesh or -outside the mesh. Location determines the behavior of several -features, such as service-to-service mTLS authentication, policy -enforcement, etc. When communicating with services outside the mesh, -Istio’s mTLS authentication is disabled, and policy enforcement is -performed on the client-side as opposed to server-side.
- -| Name | -Description | -
|---|---|
MESH_EXTERNAL |
-
- Signifies that the service is external to the mesh. Typically used -to indicate external services consumed through APIs. - - |
-
MESH_INTERNAL |
-
- Signifies that the service is part of the mesh. Typically used to -indicate services added explicitly as part of expanding the service -mesh to include unmanaged infrastructure (e.g., VMs added to a -Kubernetes based service mesh). - - |
-
Resolution determines how the proxy will resolve the IP addresses of -the network endpoints associated with the service, so that it can -route to one of them. The resolution mode specified here has no impact -on how the application resolves the IP address associated with the -service. The application may still have to use DNS to resolve the -service to an IP so that the outbound traffic can be captured by the -Proxy. Alternatively, for HTTP services, the application could -directly communicate with the proxy (e.g., by setting HTTP_PROXY) to -talk to these services.
- -| Name | -Description | -
|---|---|
NONE |
-
- Assume that incoming connections have already been resolved (to a -specific destination IP address). Such connections are typically -routed via the proxy using mechanisms such as IP table REDIRECT/ -eBPF. After performing any routing related transformations, the -proxy will forward the connection to the IP address to which the -connection was bound. - - |
-
STATIC |
-
- Use the static IP addresses specified in endpoints (see below) as the -backing instances associated with the service. - - |
-
DNS |
-
- Attempt to resolve the IP address by querying the ambient DNS, -during request processing. If no endpoints are specified, the proxy -will resolve the DNS address specified in the hosts field, if -wildcards are not used. If endpoints are specified, the DNS -addresses specified in the endpoints will be resolved to determine -the destination IP address. DNS resolution cannot be used with unix -domain socket endpoints. - - |
-
Sidecar describes the configuration of the sidecar proxy that mediates
-inbound and outbound communication to the workload it is attached to. By
-default, Istio will program all sidecar proxies in the mesh with the
-necessary configuration required to reach every workload in the mesh, as
-well as accept traffic on all the ports associated with the
-workload. The Sidecar resource provides a way to fine tune the set of
-ports, protocols that the proxy will accept when forwarding traffic to
-and from the workload. In addition, it is possible to restrict the set
-of services that the proxy can reach when forwarding outbound traffic
-from the workload.
Services and configuration in a mesh are organized into one or more -namespaces (e.g., a Kubernetes namespace or a CF org/space). A Sidecar -resource in a namespace will apply to one or more workloads in the same -namespace, selected using the workloadSelector. In the absence of a -workloadSelector, it will apply to all workloads in the same -namespace. When determining the Sidecar resource to be applied to a -workload, preference will be given to the resource with a -workloadSelector that selects this workload, over a Sidecar resource -without any workloadSelector.
- -NOTE: Each namespace can have only one Sidecar resource without any -workload selector. The behavior of the system is undefined if more -than one selector-less Sidecar resources exist in a given namespace. The -behavior of the system is undefined if two or more Sidecar resources -with a workload selector select the same workload.
- -The example below declares a Sidecar resource in the prod-us1 namespace -that configures the sidecars in the namespace to allow egress traffic to -public services in the prod-us1, prod-apis, and the istio-system -namespaces.
- -apiVersion: networking.istio.io/v1alpha3
-kind: Sidecar
-metadata:
- name: default
- namespace: prod-us1
-spec:
- egress:
- - hosts:
- - "prod-us1/*"
- - "prod-apis/*"
- - "istio-system/*"
-The example below declares a Sidecar resource in the prod-us1 namespace -that accepts inbound HTTP traffic on port 9080 and forwards -it to the attached workload listening on a unix domain socket. In the -egress direction, in addition to the istio-system namespace, the sidecar -proxies only HTTP traffic bound for port 9080 for services in the -prod-us1 namespace.
- -apiVersion: networking.istio.io/v1alpha3
-kind: Sidecar
-metadata:
- name: default
- namespace: prod-us1
-spec:
- ingress:
- - port:
- number: 9080
- protocol: HTTP
- name: somename
- defaultEndpoint: unix:///var/run/someuds.sock
- egress:
- - hosts:
- - "istio-system/*"
- - port:
- number: 9080
- protocol: HTTP
- name: egresshttp
- hosts:
- - "prod-us1/*"
-Describes how to match a given string in HTTP headers. Match is -case-sensitive.
- - -A subset of endpoints of a service. Subsets can be used for scenarios -like A/B testing, or routing to a specific version of a service. Refer -to VirtualService documentation for examples of using -subsets in these scenarios. In addition, traffic policies defined at the -service-level can be overridden at a subset-level. The following rule -uses a round robin load balancing policy for all traffic going to a -subset named testversion that is composed of endpoints (e.g., pods) with -labels (version:v3).
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: bookinfo-ratings
-spec:
- host: ratings.prod.svc.cluster.local
- trafficPolicy:
- loadBalancer:
- simple: LEAST_CONN
- subsets:
- - name: testversion
- labels:
- version: v3
- trafficPolicy:
- loadBalancer:
- simple: ROUND_ROBIN
-Note: Policies specified for subsets will not take effect until -a route rule explicitly sends traffic to this subset.
- -One or more labels are typically required to identify the subset destination, -however, when the corresponding DestinationRule represents a host that -supports multiple SNI hosts (e.g., an egress gateway), a subset without labels -may be meaningful. In this case a traffic policy with TLSSettings -can be used to identify a specific SNI host corresponding to the named subset.
- - -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.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: bookinfo-Mongo
-spec:
- hosts:
- - mongo.prod.svc.cluster.local
- tcp:
- - match:
- - port: 27017
- route:
- - destination:
- host: mongo.backup.svc.cluster.local
- port:
- number: 5555
-TLS connection match attributes.
- - -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.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: bookinfo-sni
-spec:
- hosts:
- - "*.bookinfo.com"
- gateways:
- - mygateway
- tls:
- - match:
- - port: 443
- sniHosts:
- - login.bookinfo.com
- route:
- - destination:
- host: login.prod.svc.cluster.local
- - match:
- - port: 443
- sniHosts:
- - reviews.bookinfo.com
- route:
- - destination:
- host: reviews.prod.svc.cluster.local
-SSL/TLS related settings for upstream connections. See Envoy’s TLS -context -for more details. These settings are common to both HTTP and TCP upstreams.
- -For example, the following rule configures a client to use mutual TLS -for connections to upstream database cluster.
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: db-mtls
-spec:
- host: mydbserver.prod.svc.cluster.local
- trafficPolicy:
- tls:
- mode: MUTUAL
- clientCertificate: /etc/certs/myclientcert.pem
- privateKey: /etc/certs/client_private_key.pem
- caCertificates: /etc/certs/rootcacerts.pem
-The following rule configures a client to use TLS when talking to a -foreign service whose domain matches *.foo.com.
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: tls-foo
-spec:
- host: "*.foo.com"
- trafficPolicy:
- tls:
- mode: SIMPLE
-The following rule configures a client to use Istio mutual TLS when talking -to rating services.
- -apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: ratings-istio-mtls
-spec:
- host: ratings.prod.svc.cluster.local
- trafficPolicy:
- tls:
- mode: ISTIO_MUTUAL
-TLS connection mode
- -| Name | -Description | -
|---|---|
DISABLE |
-
- Do not setup a TLS connection to the upstream endpoint. - - |
-
SIMPLE |
-
- Originate a TLS connection to the upstream endpoint. - - |
-
MUTUAL |
-
- Secure connections to the upstream using mutual TLS by presenting -client certificates for authentication. - - |
-
ISTIO_MUTUAL |
-
- Secure connections to the upstream using mutual TLS by presenting
-client certificates for authentication.
-Compared to Mutual mode, this mode uses certificates generated
-automatically by Istio for mTLS authentication. When this mode is
-used, all other fields in |
-
Traffic policies to apply for a specific destination, across all -destination ports. See DestinationRule for examples.
- - -Traffic policies that apply to specific ports of the service
- - -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”.
- -apiVersion: networking.istio.io/v1alpha3
-kind: VirtualService
-metadata:
- name: reviews-route
-spec:
- hosts:
- - reviews.prod.svc.cluster.local
- http:
- - match:
- - uri:
- prefix: "/wpcatalog"
- - uri:
- prefix: "/consumercatalog"
- rewrite:
- uri: "/newcatalog"
- route:
- - destination:
- host: reviews.prod.svc.cluster.local
- subset: v2
- - route:
- - destination:
- host: reviews.prod.svc.cluster.local
- subset: v1
-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.
apiVersion: networking.istio.io/v1alpha3
-kind: DestinationRule
-metadata:
- name: reviews-destination
-spec:
- host: reviews.prod.svc.cluster.local
- subsets:
- - name: v1
- labels:
- version: v1
- - name: v2
- labels:
- version: v2
-WorkloadSelector specifies the criteria used to determine if the Gateway -or Sidecar resource can be applied to a proxy. The matching criteria -includes the metadata associated with a proxy, workload info such as -labels attached to the pod/VM, or any other info that the proxy provides -to Istio during the initial handshake. If multiple conditions are -specified, all conditions need to match in order for the workload to be -selected. Currently, only label based selection mechanism is supported.
- - -