From 42c055026b46d141ce728fd653859e8629d91118 Mon Sep 17 00:00:00 2001 From: Shriram Rajagopalan Date: Mon, 25 Feb 2019 17:21:51 -0500 Subject: [PATCH] Revert "Revert "Generate separate HTML page per proto under networking (#811)"" This reverts commit 11e69f5b2af887f22a5cf9e7e484d61109271581. --- Makefile | 11 +- mesh/v1alpha1/istio.mesh.v1alpha1.pb.html | 4 +- networking/v1alpha3/destination_rule.pb.go | 145 +- networking/v1alpha3/destination_rule.pb.html | 1021 ++++ networking/v1alpha3/destination_rule.proto | 14 +- networking/v1alpha3/envoy_filter.pb.go | 75 +- networking/v1alpha3/envoy_filter.pb.html | 400 ++ networking/v1alpha3/envoy_filter.proto | 12 +- networking/v1alpha3/gateway.pb.go | 221 +- networking/v1alpha3/gateway.pb.html | 563 ++ networking/v1alpha3/gateway.proto | 14 +- .../istio.networking.v1alpha3.pb.html | 4665 ----------------- networking/v1alpha3/service_entry.pb.go | 221 +- networking/v1alpha3/service_entry.pb.html | 612 +++ networking/v1alpha3/service_entry.proto | 12 +- networking/v1alpha3/sidecar.pb.go | 115 +- networking/v1alpha3/sidecar.pb.html | 348 ++ networking/v1alpha3/sidecar.proto | 10 +- networking/v1alpha3/virtual_service.pb.go | 51 +- networking/v1alpha3/virtual_service.pb.html | 1759 +++++++ networking/v1alpha3/virtual_service.proto | 21 +- 21 files changed, 5179 insertions(+), 5115 deletions(-) create mode 100644 networking/v1alpha3/destination_rule.pb.html create mode 100644 networking/v1alpha3/envoy_filter.pb.html create mode 100644 networking/v1alpha3/gateway.pb.html delete mode 100644 networking/v1alpha3/istio.networking.v1alpha3.pb.html create mode 100644 networking/v1alpha3/service_entry.pb.html create mode 100644 networking/v1alpha3/sidecar.pb.html create mode 100644 networking/v1alpha3/virtual_service.pb.html diff --git a/Makefile b/Makefile index 8066ab8f06d..46ee9261cc3 100644 --- a/Makefile +++ b/Makefile @@ -70,6 +70,7 @@ gogoslick_plugin := $(gogoslick_plugin_prefix)$(gogo_mapping):$(out_path) ######################## protoc_gen_docs_plugin := --docs_out=warnings=true,mode=html_fragment_with_front_matter:$(repo_dir)/ +protoc_gen_docs_plugin_for_networking := --docs_out=warnings=true,per_file=true,mode=html_fragment_with_front_matter:$(repo_dir)/ ##################### # Generation Rules @@ -239,14 +240,14 @@ routing_v1alpha3_path := networking/v1alpha3 routing_v1alpha3_protos := $(shell find networking/v1alpha3 -type f -name '*.proto' | sort) routing_v1alpha3_pb_gos := $(routing_v1alpha3_protos:.proto=.pb.go) routing_v1alpha3_pb_pythons := $(routing_v1alpha3_protos:.proto=_pb2.py) -routing_v1alpha3_pb_doc := $(routing_v1alpha3_path)/istio.routing.v1alpha3.pb.html +routing_v1alpha3_pb_docs := $(routing_v1alpha3_protos:.proto=.pb.html) -generate-routing-go: $(routing_v1alpha3_pb_gos) $(routing_v1alpha3_pb_doc) +generate-routing-go: $(routing_v1alpha3_pb_gos) $(routing_v1alpha3_pb_docs) -$(routing_v1alpha3_pb_gos) $(routing_v1alpha3_pb_doc): $(routing_v1alpha3_protos) +$(routing_v1alpha3_pb_gos) $(routing_v1alpha3_pb_docs): $(routing_v1alpha3_protos) ## Generate networking/v1alpha3/*.pb.go @$(docker_lock) status - @$(docker_gen) $(gogofast_plugin) $(protoc_gen_docs_plugin)$(routing_v1alpha3_path) $^ + @$(docker_gen) $(gogofast_plugin) $(protoc_gen_docs_plugin_for_networking)$(routing_v1alpha3_path) $^ generate-routing-python: $(routing_v1alpha3_pb_pythons) @@ -257,7 +258,7 @@ $(routing_v1alpha3_pb_pythons): $(routing_v1alpha3_protos) clean-routing: rm -f $(routing_v1alpha3_pb_gos) - rm -f $(routing_v1alpha3_pb_doc) + rm -f $(routing_v1alpha3_pb_docs) ##################### # rbac/... diff --git a/mesh/v1alpha1/istio.mesh.v1alpha1.pb.html b/mesh/v1alpha1/istio.mesh.v1alpha1.pb.html index e4c5546a3fb..9eb2845c92f 100644 --- a/mesh/v1alpha1/istio.mesh.v1alpha1.pb.html +++ b/mesh/v1alpha1/istio.mesh.v1alpha1.pb.html @@ -75,7 +75,7 @@

ConfigSource

tlsSettings -istio.networking.v1alpha3.TLSSettings +istio.networking.v1alpha3.TLSSettings

Use the tlssettings to specify the tls mode to use. If the MCP server uses Istio MTLS and shares the root CA with Pilot, specify the TLS @@ -348,7 +348,7 @@

MeshConfig

tcpKeepalive -istio.networking.v1alpha3.ConnectionPoolSettings.TCPSettings.TcpKeepalive +istio.networking.v1alpha3.ConnectionPoolSettings.TCPSettings.TcpKeepalive

If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.

diff --git a/networking/v1alpha3/destination_rule.pb.go b/networking/v1alpha3/destination_rule.pb.go index 9a0d61a14ea..b3daf123578 100644 --- a/networking/v1alpha3/destination_rule.pb.go +++ b/networking/v1alpha3/destination_rule.pb.go @@ -1,6 +1,77 @@ // Code generated by protoc-gen-gogo. DO NOT EDIT. // source: networking/v1alpha3/destination_rule.proto +// `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: +// +// ```yaml +// 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). +// +// ```yaml +// 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. +// +// ```yaml +// 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 +// ``` + package v1alpha3 import ( @@ -111,81 +182,11 @@ func (TLSSettings_TLSmode) EnumDescriptor() ([]byte, []int) { return fileDescriptor_12899beb695152c8, []int{6, 0} } -// `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: -// -// ```yaml -// 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). -// -// ```yaml -// 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. -// -// ```yaml -// 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 -// ``` type DestinationRule struct { // REQUIRED. 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 [ServiceEntries](#ServiceEntry). Rules defined for + // declared by [ServiceEntries](/docs/reference/config/networking/v1alpha3/service-entry/#ServiceEntry). Rules defined for // services that do not exist in the service registry will be ignored. // // *Note for Kubernetes users*: When short names are used (e.g. "reviews" @@ -458,7 +459,7 @@ func (m *TrafficPolicy_PortTrafficPolicy) GetTls() *TLSSettings { // 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](#VirtualService) documentation for examples of using +// to [VirtualService](/docs/reference/config/networking/v1alpha3/virtual-service/#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 diff --git a/networking/v1alpha3/destination_rule.pb.html b/networking/v1alpha3/destination_rule.pb.html new file mode 100644 index 00000000000..47bb4d3e92d --- /dev/null +++ b/networking/v1alpha3/destination_rule.pb.html @@ -0,0 +1,1021 @@ +--- +title: Destination Rule +description: Configuration affecting load balancing, outlier detection, etc. +location: https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule.html +layout: protoc-gen-docs +generator: protoc-gen-docs +number_of_entries: 15 +--- +

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
+
+ +

ConnectionPoolSettings

+
+

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
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
tcpConnectionPoolSettings.TCPSettings +

Settings common to both HTTP and TCP upstream connections.

+ +
httpConnectionPoolSettings.HTTPSettings +

HTTP connection pool settings.

+ +
+
+

ConnectionPoolSettings.HTTPSettings

+
+

Settings applicable to HTTP1.1/HTTP2/GRPC connections.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
http1MaxPendingRequestsint32 +

Maximum number of pending HTTP requests to a destination. Default 1024.

+ +
http2MaxRequestsint32 +

Maximum number of requests to a backend. Default 1024.

+ +
maxRequestsPerConnectionint32 +

Maximum number of requests per connection to a backend. Setting this +parameter to 1 disables keep alive.

+ +
maxRetriesint32 +

Maximum number of retries that can be outstanding to all hosts in a +cluster at a given time. Defaults to 3.

+ +
+
+

ConnectionPoolSettings.TCPSettings

+
+

Settings common to both HTTP and TCP upstream connections.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
maxConnectionsint32 +

Maximum number of HTTP1 /TCP connections to a destination host.

+ +
connectTimeoutgoogle.protobuf.Duration +

TCP connection timeout.

+ +
tcpKeepaliveConnectionPoolSettings.TCPSettings.TcpKeepalive +

If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.

+ +
+
+

ConnectionPoolSettings.TCPSettings.TcpKeepalive

+
+

TCP keepalive.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
probesuint32 +

Maximum number of keepalive probes to send without response before +deciding the connection is dead. Default is to use the OS level configuration +(unless overridden, Linux defaults to 9.)

+ +
timegoogle.protobuf.Duration +

The time duration a connection needs to be idle before keep-alive +probes start being sent. Default is to use the OS level configuration +(unless overridden, Linux defaults to 7200s (ie 2 hours.)

+ +
intervalgoogle.protobuf.Duration +

The time duration between keep-alive probes. +Default is to use the OS level configuration +(unless overridden, Linux defaults to 75s.)

+ +
+
+

DestinationRule

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
hoststring +

REQUIRED. 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 ServiceEntries. Rules defined for +services that do not exist in the service registry will be ignored.

+ +

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.

+ +

Note that the host field applies to both HTTP and TCP services.

+ +
trafficPolicyTrafficPolicy +

Traffic policies to apply (load balancing policy, connection pool +sizes, outlier detection).

+ +
subsetsSubset[] +

One or more named sets that represent individual versions of a +service. Traffic policies can be overridden at subset level.

+ +
exportTostring[] +

The resolution of a DestinationRule to apply to a service occurs in the +context of a hierarchy of namespaces. This rule controls whether those +namespaces are allowed to select this rule.

+ +
+
+

LoadBalancerSettings

+
+

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
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
simpleLoadBalancerSettings.SimpleLB (oneof) +
consistentHashLoadBalancerSettings.ConsistentHashLB (oneof) +
+
+

LoadBalancerSettings.ConsistentHashLB

+
+

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
httpHeaderNamestring (oneof) +

Hash based on a specific HTTP header.

+ +
useSourceIpbool (oneof) +

Hash based on the source IP address.

+ +
minimumRingSizeuint64 +

The minimum number of virtual nodes to use for the hash +ring. Defaults to 1024. Larger ring sizes result in more granular +load distributions. If the number of hosts in the load balancing +pool is larger than the ring size, each host will be assigned a +single virtual node.

+ +
+
+

LoadBalancerSettings.ConsistentHashLB.HTTPCookie

+
+

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestring +

REQUIRED. Name of the cookie.

+ +
pathstring +

Path to set for the cookie.

+ +
ttlgoogle.protobuf.Duration +

REQUIRED. Lifetime of the cookie.

+ +
+
+

LoadBalancerSettings.SimpleLB

+
+

Standard load balancing algorithms that require no tuning.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
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.

+ +
+
+

OutlierDetection

+
+

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
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
consecutiveErrorsint32 +

Number of errors before a host is ejected from the connection +pool. Defaults to 5. When the upstream host is accessed over HTTP, a +502, 503 or 504 return code qualifies as an error. When the upstream host +is accessed over an opaque TCP connection, connect timeouts and +connection error/failure events qualify as an error.

+ +
intervalgoogle.protobuf.Duration +

Time interval between ejection sweep analysis. format: +1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.

+ +
baseEjectionTimegoogle.protobuf.Duration +

Minimum ejection duration. A host will remain ejected for a period +equal to the product of minimum ejection duration and the number of +times the host has been ejected. This technique allows the system to +automatically increase the ejection period for unhealthy upstream +servers. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 30s.

+ +
maxEjectionPercentint32 +

Maximum % of hosts in the load balancing pool for the upstream +service that can be ejected. Defaults to 10%.

+ +
minHealthPercentint32 +

Outlier detection will be enabled as long as the associated load balancing +pool has at least minhealthpercent hosts in healthy mode. When the +percentage of healthy hosts in the load balancing pool drops below this +threshold, outlier detection will be disabled and the proxy will load balance +across all hosts in the pool (healthy and unhealthy). The default is 50%.

+ +
+
+

Subset

+
+

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestring +

REQUIRED. Name of the subset. The service name and the subset name can +be used for traffic splitting in a route rule.

+ +
labelsmap<string, string> +

Labels apply a filter over the endpoints of a service in the +service registry. See route rules for examples of usage.

+ +
trafficPolicyTrafficPolicy +

Traffic policies that apply to this subset. Subsets inherit the +traffic policies specified at the DestinationRule level. Settings +specified at the subset level will override the corresponding settings +specified at the DestinationRule level.

+ +
+
+

TLSSettings

+
+

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
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
modeTLSSettings.TLSmode +

REQUIRED: Indicates whether connections to this port should be secured +using TLS. The value of this field determines how TLS is enforced.

+ +
clientCertificatestring +

REQUIRED if mode is MUTUAL. The path to the file holding the +client-side TLS certificate to use. +Should be empty if mode is ISTIO_MUTUAL.

+ +
privateKeystring +

REQUIRED if mode is MUTUAL. The path to the file holding the +client’s private key. +Should be empty if mode is ISTIO_MUTUAL.

+ +
caCertificatesstring +

OPTIONAL: The path to the file containing certificate authority +certificates to use in verifying a presented server certificate. If +omitted, the proxy will not verify the server’s certificate. +Should be empty if mode is ISTIO_MUTUAL.

+ +
subjectAltNamesstring[] +

A list of alternate names to verify the subject identity in the +certificate. If specified, the proxy will verify that the server +certificate’s subject alt name matches one of the specified values. +If specified, this list overrides the value of subjectaltnames +from the ServiceEntry.

+ +
snistring +

SNI string to present to the server during TLS handshake.

+ +
+
+

TLSSettings.TLSmode

+
+

TLS connection mode

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
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 TLSSettings should be empty.

+ +
+
+

TrafficPolicy

+
+

Traffic policies to apply for a specific destination, across all +destination ports. See DestinationRule for examples.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
loadBalancerLoadBalancerSettings +

Settings controlling the load balancer algorithms.

+ +
connectionPoolConnectionPoolSettings +

Settings controlling the volume of connections to an upstream service

+ +
outlierDetectionOutlierDetection +

Settings controlling eviction of unhealthy hosts from the load balancing pool

+ +
tlsTLSSettings +

TLS related settings for connections to the upstream service.

+ +
portLevelSettingsTrafficPolicy.PortTrafficPolicy[] +

Traffic policies specific to individual ports. Note that port level +settings will override the destination-level settings. Traffic +settings specified at the destination-level will not be inherited when +overridden by port-level settings, i.e. default values will be applied +to fields omitted in port-level traffic policies.

+ +
+
+

TrafficPolicy.PortTrafficPolicy

+
+

Traffic policies that apply to specific ports of the service

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
portPortSelector +

Specifies the port name or number of a port on the destination service +on which this policy is being applied.

+ +

Names must comply with DNS label syntax (rfc1035) and therefore cannot +collide with numbers. If there are multiple ports on a service with +the same protocol the names should be of the form -.

+ +
loadBalancerLoadBalancerSettings +

Settings controlling the load balancer algorithms.

+ +
connectionPoolConnectionPoolSettings +

Settings controlling the volume of connections to an upstream service

+ +
outlierDetectionOutlierDetection +

Settings controlling eviction of unhealthy hosts from the load balancing pool

+ +
tlsTLSSettings +

TLS related settings for connections to the upstream service.

+ +
+
diff --git a/networking/v1alpha3/destination_rule.proto b/networking/v1alpha3/destination_rule.proto index 1c340f8bbf6..5759ff50958 100644 --- a/networking/v1alpha3/destination_rule.proto +++ b/networking/v1alpha3/destination_rule.proto @@ -17,9 +17,9 @@ import "google/protobuf/duration.proto"; import "networking/v1alpha3/virtual_service.proto"; import "gogoproto/gogo.proto"; -package istio.networking.v1alpha3; - -option go_package = "istio.io/api/networking/v1alpha3"; +// $title: Destination Rule +// $description: Configuration affecting load balancing, outlier detection, etc. +// $location: https://istio.io/docs/reference/config/networking/v1alpha3/destination-rule.html // `DestinationRule` defines policies that apply to traffic intended for a // service after routing has occurred. These rules specify configuration @@ -91,11 +91,15 @@ option go_package = "istio.io/api/networking/v1alpha3"; // loadBalancer: // simple: ROUND_ROBIN // ``` +package istio.networking.v1alpha3; + +option go_package = "istio.io/api/networking/v1alpha3"; + message DestinationRule { // REQUIRED. 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 [ServiceEntries](#ServiceEntry). Rules defined for + // declared by [ServiceEntries](/docs/reference/config/networking/v1alpha3/service-entry/#ServiceEntry). Rules defined for // services that do not exist in the service registry will be ignored. // // *Note for Kubernetes users*: When short names are used (e.g. "reviews" @@ -173,7 +177,7 @@ message TrafficPolicy { // 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](#VirtualService) documentation for examples of using +// to [VirtualService](/docs/reference/config/networking/v1alpha3/virtual-service/#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 diff --git a/networking/v1alpha3/envoy_filter.pb.go b/networking/v1alpha3/envoy_filter.pb.go index 3d3c9450534..bbe92a378f3 100644 --- a/networking/v1alpha3/envoy_filter.pb.go +++ b/networking/v1alpha3/envoy_filter.pb.go @@ -1,6 +1,44 @@ // Code generated by protoc-gen-gogo. DO NOT EDIT. // source: networking/v1alpha3/envoy_filter.proto +// `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". +// +// ```yaml +// 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 ... +// ``` + package v1alpha3 import ( @@ -155,43 +193,6 @@ func (EnvoyFilter_Filter_FilterType) EnumDescriptor() ([]byte, []int) { return fileDescriptor_16d9b2922bd3e4a9, []int{0, 3, 0} } -// `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". -// -// ```yaml -// 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 ... -// ``` type EnvoyFilter struct { // One or more labels that indicate a specific set of pods/VMs whose // proxies should be configured to use these additional filters. The diff --git a/networking/v1alpha3/envoy_filter.pb.html b/networking/v1alpha3/envoy_filter.pb.html new file mode 100644 index 00000000000..d9a36cb8523 --- /dev/null +++ b/networking/v1alpha3/envoy_filter.pb.html @@ -0,0 +1,400 @@ +--- +title: Envoy Filter +description: Configuration affecting insertion of custom envoy filters. +location: https://istio.io/docs/reference/config/networking/v1alpha3/envoy-filter.html +layout: protoc-gen-docs +generator: protoc-gen-docs +number_of_entries: 8 +--- +

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 ...
+
+ +

EnvoyFilter

+
+ + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
workloadLabelsmap<string, string> +

One or more labels that indicate a specific set of pods/VMs whose +proxies should be configured to use these additional filters. The +scope of label search is platform dependent. On Kubernetes, for +example, the scope includes pods running in all reachable +namespaces. Omitting the selector applies the filter to all proxies in +the mesh. +NOTE: There can be only one EnvoyFilter bound to a specific workload. +The behavior is undefined if multiple EnvoyFilter configurations are +specified for the same workload.

+ +
filtersEnvoyFilter.Filter[] +

REQUIRED: Envoy network filters/http filters to be added to matching +listeners. When adding network filters to http connections, care +should be taken to ensure that the filter is added before +envoy.httpconnectionmanager.

+ +
+
+

EnvoyFilter.Filter

+
+

Envoy filters to be added to a network or http filter chain.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
listenerMatchEnvoyFilter.ListenerMatch +

Filter will be added to the listener only if the match conditions are true. +If not specified, the filters will be applied to all listeners.

+ +
insertPositionEnvoyFilter.InsertPosition +

Insert position in the filter chain. Defaults to FIRST

+ +
filterTypeEnvoyFilter.Filter.FilterType +

REQUIRED: The type of filter to instantiate.

+ +
filterNamestring +

REQUIRED: The name of the filter to instantiate. The name must match a supported +filter compiled into Envoy.

+ +
filterConfiggoogle.protobuf.Struct +

REQUIRED: Filter specific configuration which depends on the filter being +instantiated.

+ +
+
+

EnvoyFilter.Filter.FilterType

+
+ + + + + + + + + + + + + + + + + + + + + +
NameDescription
INVALID +

placeholder

+ +
HTTP +

Http filter

+ +
NETWORK +

Network filter

+ +
+
+

EnvoyFilter.InsertPosition

+
+

Indicates the relative index in the filter chain where the filter should be inserted.

+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
indexEnvoyFilter.InsertPosition.Index +

Position of this filter in the filter chain.

+ +
relativeTostring +

If BEFORE or AFTER position is specified, specify the name of the +filter relative to which this filter should be inserted.

+ +
+
+

EnvoyFilter.InsertPosition.Index

+
+

Index/position in the filter chain.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
FIRST +

Insert first

+ +
LAST +

Insert last

+ +
BEFORE +

Insert before the named filter.

+ +
AFTER +

Insert after the named filter.

+ +
+
+

EnvoyFilter.ListenerMatch

+
+

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
portNumberuint32 +

The service port/gateway port to which traffic is being +sent/received. If not specified, matches all listeners. Even though +inbound listeners are generated for the instance/pod ports, only +service ports should be used to match listeners.

+ +
portNamePrefixstring +

Instead of using specific port numbers, a set of ports matching a +given port name prefix can be selected. E.g., “mongo” selects ports +named mongo-port, mongo, mongoDB, MONGO, etc. Matching is case +insensitive.

+ +
listenerTypeEnvoyFilter.ListenerMatch.ListenerType +

Inbound vs outbound sidecar listener or gateway listener. If not specified, +matches all listeners.

+ +
listenerProtocolEnvoyFilter.ListenerMatch.ListenerProtocol +

Selects a class of listeners for the same protocol. If not +specified, applies to listeners on all protocols. Use the protocol +selection to select all HTTP listeners (includes HTTP2/gRPC/HTTPS +where Envoy terminates TLS) or all TCP listeners (includes HTTPS +passthrough using SNI).

+ +
addressstring[] +

One or more IP addresses to which the listener is bound. If +specified, should match at least one address in the list.

+ +
+
+

EnvoyFilter.ListenerMatch.ListenerProtocol

+
+ + + + + + + + + + + + + + + + + + + + + +
NameDescription
ALL +

All protocols

+ +
HTTP +

HTTP or HTTPS (with termination) / HTTP2/gRPC

+ +
TCP +

Any non-HTTP listener

+ +
+
+

EnvoyFilter.ListenerMatch.ListenerType

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
ANY +

All listeners

+ +
SIDECAR_INBOUND +

Inbound listener in sidecar

+ +
SIDECAR_OUTBOUND +

Outbound listener in sidecar

+ +
GATEWAY +

Gateway listener

+ +
+
diff --git a/networking/v1alpha3/envoy_filter.proto b/networking/v1alpha3/envoy_filter.proto index c944675e558..4b9d040c11e 100644 --- a/networking/v1alpha3/envoy_filter.proto +++ b/networking/v1alpha3/envoy_filter.proto @@ -16,9 +16,9 @@ syntax = "proto3"; import "google/protobuf/struct.proto"; -package istio.networking.v1alpha3; - -option go_package = "istio.io/api/networking/v1alpha3"; +// $title: Envoy Filter +// $description: Configuration affecting insertion of custom envoy filters. +// $location: https://istio.io/docs/reference/config/networking/v1alpha3/envoy-filter.html // `EnvoyFilter` describes Envoy proxy-specific filters that can be used to // customize the Envoy proxy configuration generated by Istio networking @@ -50,13 +50,17 @@ option go_package = "istio.io/api/networking/v1alpha3"; // filters: // - listenerMatch: // portNumber: 8080 -// listenerType: SIDECAR_INBOUND #will match with the inbound listener for reviews:8080 +// listenerType: SIDECAR_INBOUND # will match with the inbound listener for reviews:8080 // filterName: envoy.lua // filterType: HTTP // filterConfig: // inlineCode: | // ... lua code ... // ``` +package istio.networking.v1alpha3; + +option go_package = "istio.io/api/networking/v1alpha3"; + message EnvoyFilter { // One or more labels that indicate a specific set of pods/VMs whose // proxies should be configured to use these additional filters. The diff --git a/networking/v1alpha3/gateway.pb.go b/networking/v1alpha3/gateway.pb.go index 62fc8b17826..77785897fac 100644 --- a/networking/v1alpha3/gateway.pb.go +++ b/networking/v1alpha3/gateway.pb.go @@ -1,114 +1,6 @@ // Code generated by protoc-gen-gogo. DO NOT EDIT. // source: networking/v1alpha3/gateway.proto -package v1alpha3 - -import ( - fmt "fmt" - proto "github.com/gogo/protobuf/proto" - io "io" - math "math" -) - -// Reference imports to suppress errors if they are not otherwise used. -var _ = proto.Marshal -var _ = fmt.Errorf -var _ = math.Inf - -// This is a compile-time assertion to ensure that this generated file -// is compatible with the proto package it is being compiled against. -// A compilation error at this line likely means your copy of the -// proto package needs to be updated. -const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package - -// TLS modes enforced by the proxy -type Server_TLSOptions_TLSmode int32 - -const ( - // 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. - Server_TLSOptions_PASSTHROUGH Server_TLSOptions_TLSmode = 0 - // Secure connections with standard TLS semantics. - Server_TLSOptions_SIMPLE Server_TLSOptions_TLSmode = 1 - // Secure connections to the upstream using mutual TLS by presenting - // client certificates for authentication. - Server_TLSOptions_MUTUAL Server_TLSOptions_TLSmode = 2 - // 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. - Server_TLSOptions_AUTO_PASSTHROUGH Server_TLSOptions_TLSmode = 3 -) - -var Server_TLSOptions_TLSmode_name = map[int32]string{ - 0: "PASSTHROUGH", - 1: "SIMPLE", - 2: "MUTUAL", - 3: "AUTO_PASSTHROUGH", -} - -var Server_TLSOptions_TLSmode_value = map[string]int32{ - "PASSTHROUGH": 0, - "SIMPLE": 1, - "MUTUAL": 2, - "AUTO_PASSTHROUGH": 3, -} - -func (x Server_TLSOptions_TLSmode) String() string { - return proto.EnumName(Server_TLSOptions_TLSmode_name, int32(x)) -} - -func (Server_TLSOptions_TLSmode) EnumDescriptor() ([]byte, []int) { - return fileDescriptor_067d98d02f84cc0b, []int{1, 0, 0} -} - -// TLS protocol versions. -type Server_TLSOptions_TLSProtocol int32 - -const ( - // Automatically choose the optimal TLS version. - Server_TLSOptions_TLS_AUTO Server_TLSOptions_TLSProtocol = 0 - // TLS version 1.0 - Server_TLSOptions_TLSV1_0 Server_TLSOptions_TLSProtocol = 1 - // TLS version 1.1 - Server_TLSOptions_TLSV1_1 Server_TLSOptions_TLSProtocol = 2 - // TLS version 1.2 - Server_TLSOptions_TLSV1_2 Server_TLSOptions_TLSProtocol = 3 - // TLS version 1.3 - Server_TLSOptions_TLSV1_3 Server_TLSOptions_TLSProtocol = 4 -) - -var Server_TLSOptions_TLSProtocol_name = map[int32]string{ - 0: "TLS_AUTO", - 1: "TLSV1_0", - 2: "TLSV1_1", - 3: "TLSV1_2", - 4: "TLSV1_3", -} - -var Server_TLSOptions_TLSProtocol_value = map[string]int32{ - "TLS_AUTO": 0, - "TLSV1_0": 1, - "TLSV1_1": 2, - "TLSV1_2": 3, - "TLSV1_3": 4, -} - -func (x Server_TLSOptions_TLSProtocol) String() string { - return proto.EnumName(Server_TLSOptions_TLSProtocol_name, int32(x)) -} - -func (Server_TLSOptions_TLSProtocol) EnumDescriptor() ([]byte, []int) { - return fileDescriptor_067d98d02f84cc0b, []int{1, 0, 1} -} - // `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 @@ -149,7 +41,7 @@ func (Server_TLSOptions_TLSProtocol) EnumDescriptor() ([]byte, []int) { // - uk.bookinfo.com // - eu.bookinfo.com // tls: -// mode: SIMPLE #enables HTTPS on this port +// mode: SIMPLE # enables HTTPS on this port // serverCertificate: /etc/certs/servercert.pem // privateKey: /etc/certs/privatekey.pem // - port: @@ -231,7 +123,7 @@ func (Server_TLSOptions_TLSProtocol) EnumDescriptor() ([]byte, []int) { // namespace: bookinfo-namespace // spec: // hosts: -// - mongosvr.prod.svc.cluster.local #name of internal Mongo service +// - 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. @@ -244,6 +136,115 @@ func (Server_TLSOptions_TLSProtocol) EnumDescriptor() ([]byte, []int) { // port: // number: 5555 // ``` + +package v1alpha3 + +import ( + fmt "fmt" + proto "github.com/gogo/protobuf/proto" + io "io" + math "math" +) + +// Reference imports to suppress errors if they are not otherwise used. +var _ = proto.Marshal +var _ = fmt.Errorf +var _ = math.Inf + +// This is a compile-time assertion to ensure that this generated file +// is compatible with the proto package it is being compiled against. +// A compilation error at this line likely means your copy of the +// proto package needs to be updated. +const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package + +// TLS modes enforced by the proxy +type Server_TLSOptions_TLSmode int32 + +const ( + // 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. + Server_TLSOptions_PASSTHROUGH Server_TLSOptions_TLSmode = 0 + // Secure connections with standard TLS semantics. + Server_TLSOptions_SIMPLE Server_TLSOptions_TLSmode = 1 + // Secure connections to the upstream using mutual TLS by presenting + // client certificates for authentication. + Server_TLSOptions_MUTUAL Server_TLSOptions_TLSmode = 2 + // 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. + Server_TLSOptions_AUTO_PASSTHROUGH Server_TLSOptions_TLSmode = 3 +) + +var Server_TLSOptions_TLSmode_name = map[int32]string{ + 0: "PASSTHROUGH", + 1: "SIMPLE", + 2: "MUTUAL", + 3: "AUTO_PASSTHROUGH", +} + +var Server_TLSOptions_TLSmode_value = map[string]int32{ + "PASSTHROUGH": 0, + "SIMPLE": 1, + "MUTUAL": 2, + "AUTO_PASSTHROUGH": 3, +} + +func (x Server_TLSOptions_TLSmode) String() string { + return proto.EnumName(Server_TLSOptions_TLSmode_name, int32(x)) +} + +func (Server_TLSOptions_TLSmode) EnumDescriptor() ([]byte, []int) { + return fileDescriptor_067d98d02f84cc0b, []int{1, 0, 0} +} + +// TLS protocol versions. +type Server_TLSOptions_TLSProtocol int32 + +const ( + // Automatically choose the optimal TLS version. + Server_TLSOptions_TLS_AUTO Server_TLSOptions_TLSProtocol = 0 + // TLS version 1.0 + Server_TLSOptions_TLSV1_0 Server_TLSOptions_TLSProtocol = 1 + // TLS version 1.1 + Server_TLSOptions_TLSV1_1 Server_TLSOptions_TLSProtocol = 2 + // TLS version 1.2 + Server_TLSOptions_TLSV1_2 Server_TLSOptions_TLSProtocol = 3 + // TLS version 1.3 + Server_TLSOptions_TLSV1_3 Server_TLSOptions_TLSProtocol = 4 +) + +var Server_TLSOptions_TLSProtocol_name = map[int32]string{ + 0: "TLS_AUTO", + 1: "TLSV1_0", + 2: "TLSV1_1", + 3: "TLSV1_2", + 4: "TLSV1_3", +} + +var Server_TLSOptions_TLSProtocol_value = map[string]int32{ + "TLS_AUTO": 0, + "TLSV1_0": 1, + "TLSV1_1": 2, + "TLSV1_2": 3, + "TLSV1_3": 4, +} + +func (x Server_TLSOptions_TLSProtocol) String() string { + return proto.EnumName(Server_TLSOptions_TLSProtocol_name, int32(x)) +} + +func (Server_TLSOptions_TLSProtocol) EnumDescriptor() ([]byte, []int) { + return fileDescriptor_067d98d02f84cc0b, []int{1, 0, 1} +} + type Gateway struct { // REQUIRED: A list of server specifications. Servers []*Server `protobuf:"bytes,1,rep,name=servers,proto3" json:"servers,omitempty"` diff --git a/networking/v1alpha3/gateway.pb.html b/networking/v1alpha3/gateway.pb.html new file mode 100644 index 00000000000..b5cc69a3885 --- /dev/null +++ b/networking/v1alpha3/gateway.pb.html @@ -0,0 +1,563 @@ +--- +title: Gateway +description: Configuration affecting edge load balancer. +location: https://istio.io/docs/reference/config/networking/v1alpha3/gateway.html +layout: protoc-gen-docs +generator: protoc-gen-docs +number_of_entries: 6 +--- +

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
+
+ +

Gateway

+
+ + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
serversServer[] +

REQUIRED: A list of server specifications.

+ +
selectormap<string, string> +

REQUIRED: One or more labels that indicate a specific set of pods/VMs +on which this gateway configuration should be applied. The scope of +label search is restricted to the configuration namespace in which the +the resource is present. In other words, the Gateway resource must +reside in the same namespace as the gateway workload.

+ +
+
+

Port

+
+

Port describes the properties of a specific port of a service.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
numberuint32 +

REQUIRED: A valid non-negative integer port number.

+ +
protocolstring +

REQUIRED: The protocol exposed on the port. +MUST BE one of HTTP|HTTPS|GRPC|HTTP2|MONGO|TCP|TLS. +TLS implies the connection will be routed based on the SNI header to +the destination without terminating the TLS connection.

+ +
namestring +

Label assigned to the port.

+ +
+
+

Server

+
+

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
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
portPort +

REQUIRED: The Port on which the proxy should listen for incoming +connections. If using unix domain socket, use 0 as the port number, +with a valid protocol and port name, along with the bind parameter.

+ +
hostsstring[] +

REQUIRED. A list of hosts exposed by this gateway. At least one +host is required. While typically applicable to +HTTP services, it can also be used for TCP services using TLS with +SNI. May contain a wildcard prefix for the bottom-level component of +a domain name. For example *.foo.com matches bar.foo.com +and *.com matches bar.foo.com, example.com, and so on.

+ +

Note: A VirtualService that is bound to a gateway must have one +or more hosts that match the hosts specified in a server. The match +could be an exact match or a suffix match with the server’s hosts. For +example, if the server’s hosts specifies “*.example.com”, +VirtualServices with hosts dev.example.com, prod.example.com will +match. However, VirtualServices with hosts example.com or +newexample.com will not match.

+ +
tlsServer.TLSOptions +

Set of TLS related options that govern the server’s behavior. Use +these options to control if all http requests should be redirected to +https, and the TLS modes to use.

+ +
defaultEndpointstring +

The loopback IP endpoint or unix domain socket to which traffic should +be forwarded to by default. Format should be 127.0.0.1:PORT or +unix:///path/to/socket or unix://@foobar (Linux abstract namespace).

+ +
+
+

Server.TLSOptions

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
httpsRedirectbool +

If set to true, the load balancer will send a 301 redirect for all +http connections, asking the clients to use HTTPS.

+ +
modeServer.TLSOptions.TLSmode +

Optional: Indicates whether connections to this port should be +secured using TLS. The value of this field determines how TLS is +enforced.

+ +
serverCertificatestring +

REQUIRED if mode is SIMPLE or MUTUAL. The path to the file +holding the server-side TLS certificate to use.

+ +
privateKeystring +

REQUIRED if mode is SIMPLE or MUTUAL. The path to the file +holding the server’s private key.

+ +
caCertificatesstring +

REQUIRED if mode is MUTUAL. The path to a file containing +certificate authority certificates to use in verifying a presented +client side certificate.

+ +
credentialNamestring +

The credentialName stands for a unique identifier that can be used +to identify the serverCertificate and the privateKey. The credentialName +appended with suffix “-cacert” is used to identify the CaCertificates +associated with this server. Gateway workloads capable of fetching +credentials from a remote credential store will be configured to retrieve +the serverCertificate and the privateKey using credentialName, instead of +using the file system paths specified above. If using mutual TLS, +gateway workloads will retrieve the CaCertificates using +credentialName-cacert. The semantics of the name are platform dependent. +In Kubernetes, the default Istio supplied credential server expects the +credentialName to match the name of the Kubernetes secret that holds the +server certificate, the private key, and the CA certificate +(if using mutual TLS).

+ +
subjectAltNamesstring[] +

A list of alternate names to verify the subject identity in the +certificate presented by the client.

+ +
minProtocolVersionServer.TLSOptions.TLSProtocol +

Optional: Minimum TLS protocol version.

+ +
maxProtocolVersionServer.TLSOptions.TLSProtocol +

Optional: Maximum TLS protocol version.

+ +
cipherSuitesstring[] +

Optional: If specified, only support the specified cipher list. +Otherwise default to the default cipher list supported by Envoy.

+ +
+
+

Server.TLSOptions.TLSProtocol

+
+

TLS protocol versions.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
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

+ +
+
+

Server.TLSOptions.TLSmode

+
+

TLS modes enforced by the proxy

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
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.

+ +
+
diff --git a/networking/v1alpha3/gateway.proto b/networking/v1alpha3/gateway.proto index bc567376bdf..4a5877cb952 100644 --- a/networking/v1alpha3/gateway.proto +++ b/networking/v1alpha3/gateway.proto @@ -14,9 +14,9 @@ syntax = "proto3"; -package istio.networking.v1alpha3; - -option go_package = "istio.io/api/networking/v1alpha3"; +// $title: Gateway +// $description: Configuration affecting edge load balancer. +// $location: https://istio.io/docs/reference/config/networking/v1alpha3/gateway.html // `Gateway` describes a load balancer operating at the edge of the mesh // receiving incoming or outgoing HTTP/TCP connections. The specification @@ -58,7 +58,7 @@ option go_package = "istio.io/api/networking/v1alpha3"; // - uk.bookinfo.com // - eu.bookinfo.com // tls: -// mode: SIMPLE #enables HTTPS on this port +// mode: SIMPLE # enables HTTPS on this port // serverCertificate: /etc/certs/servercert.pem // privateKey: /etc/certs/privatekey.pem // - port: @@ -140,7 +140,7 @@ option go_package = "istio.io/api/networking/v1alpha3"; // namespace: bookinfo-namespace // spec: // hosts: -// - mongosvr.prod.svc.cluster.local #name of internal Mongo service +// - 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. @@ -153,6 +153,10 @@ option go_package = "istio.io/api/networking/v1alpha3"; // port: // number: 5555 // ``` +package istio.networking.v1alpha3; + +option go_package = "istio.io/api/networking/v1alpha3"; + message Gateway { // REQUIRED: A list of server specifications. repeated Server servers = 1; diff --git a/networking/v1alpha3/istio.networking.v1alpha3.pb.html b/networking/v1alpha3/istio.networking.v1alpha3.pb.html deleted file mode 100644 index 665bf24c100..00000000000 --- a/networking/v1alpha3/istio.networking.v1alpha3.pb.html +++ /dev/null @@ -1,4665 +0,0 @@ ---- -title: Traffic Routing -description: Configuration affecting traffic routing. -location: https://istio.io/docs/reference/config/istio.networking.v1alpha3.html -layout: protoc-gen-docs -generator: protoc-gen-docs -aliases: - - /docs/reference/config/istio.routing.v1alpha1/ -number_of_entries: 60 ---- -

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

-
-

CaptureMode describes how traffic to a listener is expected to be -captured. Applicable only when the listener is bound to an IP.

- - - - - - - - - - - - - - - - - - - - - - -
NameDescription
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.

- -
-
-

ConnectionPoolSettings

-
-

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
-
- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
tcpConnectionPoolSettings.TCPSettings -

Settings common to both HTTP and TCP upstream connections.

- -
httpConnectionPoolSettings.HTTPSettings -

HTTP connection pool settings.

- -
-
-

ConnectionPoolSettings.HTTPSettings

-
-

Settings applicable to HTTP1.1/HTTP2/GRPC connections.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
http1MaxPendingRequestsint32 -

Maximum number of pending HTTP requests to a destination. Default 1024.

- -
http2MaxRequestsint32 -

Maximum number of requests to a backend. Default 1024.

- -
maxRequestsPerConnectionint32 -

Maximum number of requests per connection to a backend. Setting this -parameter to 1 disables keep alive.

- -
maxRetriesint32 -

Maximum number of retries that can be outstanding to all hosts in a -cluster at a given time. Defaults to 3.

- -
-
-

ConnectionPoolSettings.TCPSettings

-
-

Settings common to both HTTP and TCP upstream connections.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
maxConnectionsint32 -

Maximum number of HTTP1 /TCP connections to a destination host.

- -
connectTimeoutgoogle.protobuf.Duration -

TCP connection timeout.

- -
tcpKeepaliveConnectionPoolSettings.TCPSettings.TcpKeepalive -

If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.

- -
-
-

ConnectionPoolSettings.TCPSettings.TcpKeepalive

-
-

TCP keepalive.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
probesuint32 -

Maximum number of keepalive probes to send without response before -deciding the connection is dead. Default is to use the OS level configuration -(unless overridden, Linux defaults to 9.)

- -
timegoogle.protobuf.Duration -

The time duration a connection needs to be idle before keep-alive -probes start being sent. Default is to use the OS level configuration -(unless overridden, Linux defaults to 7200s (ie 2 hours.)

- -
intervalgoogle.protobuf.Duration -

The time duration between keep-alive probes. -Default is to use the OS level configuration -(unless overridden, Linux defaults to 75s.)

- -
-
-

CorsPolicy

-
-

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"
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
allowOriginstring[] -

The list of origins that are allowed to perform CORS requests. The -content will be serialized into the Access-Control-Allow-Origin -header. Wildcard * will allow all origins.

- -
allowMethodsstring[] -

List of HTTP methods allowed to access the resource. The content will -be serialized into the Access-Control-Allow-Methods header.

- -
allowHeadersstring[] -

List of HTTP headers that can be used when requesting the -resource. Serialized to Access-Control-Allow-Headers header.

- -
exposeHeadersstring[] -

A white list of HTTP headers that the browsers are allowed to -access. Serialized into Access-Control-Expose-Headers header.

- -
maxAgegoogle.protobuf.Duration -

Specifies how long the results of a preflight request can be -cached. Translates to the Access-Control-Max-Age header.

- -
allowCredentialsgoogle.protobuf.BoolValue -

Indicates whether the caller is allowed to send the actual request -(not the preflight) using credentials. Translates to -Access-Control-Allow-Credentials header.

- -
-
-

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/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
-
- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
hoststring -

REQUIRED. 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 misconfigurations, it is recommended to always use fully -qualified domain names over short names.

- -
subsetstring -

The name of a subset within the service. Applicable only to services -within the mesh. The subset must be defined in a corresponding -DestinationRule.

- -
portPortSelector -

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.

- -
-
-

DestinationRule

-
-

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
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
hoststring -

REQUIRED. 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 ServiceEntries. Rules defined for -services that do not exist in the service registry will be ignored.

- -

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.

- -

Note that the host field applies to both HTTP and TCP services.

- -
trafficPolicyTrafficPolicy -

Traffic policies to apply (load balancing policy, connection pool -sizes, outlier detection).

- -
subsetsSubset[] -

One or more named sets that represent individual versions of a -service. Traffic policies can be overridden at subset level.

- -
exportTostring[] -

The resolution of a DestinationRule to apply to a service occurs in the -context of a hierarchy of namespaces. This rule controls whether those -namespaces are allowed to select this rule.

- -
-
-

EnvoyFilter

-
-

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 ...
-
- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
workloadLabelsmap<string, string> -

One or more labels that indicate a specific set of pods/VMs whose -proxies should be configured to use these additional filters. The -scope of label search is platform dependent. On Kubernetes, for -example, the scope includes pods running in all reachable -namespaces. Omitting the selector applies the filter to all proxies in -the mesh. -NOTE: There can be only one EnvoyFilter bound to a specific workload. -The behavior is undefined if multiple EnvoyFilter configurations are -specified for the same workload.

- -
filtersEnvoyFilter.Filter[] -

REQUIRED: Envoy network filters/http filters to be added to matching -listeners. When adding network filters to http connections, care -should be taken to ensure that the filter is added before -envoy.httpconnectionmanager.

- -
-
-

EnvoyFilter.Filter

-
-

Envoy filters to be added to a network or http filter chain.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
listenerMatchEnvoyFilter.ListenerMatch -

Filter will be added to the listener only if the match conditions are true. -If not specified, the filters will be applied to all listeners.

- -
insertPositionEnvoyFilter.InsertPosition -

Insert position in the filter chain. Defaults to FIRST

- -
filterTypeEnvoyFilter.Filter.FilterType -

REQUIRED: The type of filter to instantiate.

- -
filterNamestring -

REQUIRED: The name of the filter to instantiate. The name must match a supported -filter compiled into Envoy.

- -
filterConfiggoogle.protobuf.Struct -

REQUIRED: Filter specific configuration which depends on the filter being -instantiated.

- -
-
-

EnvoyFilter.Filter.FilterType

-
- - - - - - - - - - - - - - - - - - - - - -
NameDescription
INVALID -

placeholder

- -
HTTP -

Http filter

- -
NETWORK -

Network filter

- -
-
-

EnvoyFilter.InsertPosition

-
-

Indicates the relative index in the filter chain where the filter should be inserted.

- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
indexEnvoyFilter.InsertPosition.Index -

Position of this filter in the filter chain.

- -
relativeTostring -

If BEFORE or AFTER position is specified, specify the name of the -filter relative to which this filter should be inserted.

- -
-
-

EnvoyFilter.InsertPosition.Index

-
-

Index/position in the filter chain.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
NameDescription
FIRST -

Insert first

- -
LAST -

Insert last

- -
BEFORE -

Insert before the named filter.

- -
AFTER -

Insert after the named filter.

- -
-
-

EnvoyFilter.ListenerMatch

-
-

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
portNumberuint32 -

The service port/gateway port to which traffic is being -sent/received. If not specified, matches all listeners. Even though -inbound listeners are generated for the instance/pod ports, only -service ports should be used to match listeners.

- -
portNamePrefixstring -

Instead of using specific port numbers, a set of ports matching a -given port name prefix can be selected. E.g., “mongo” selects ports -named mongo-port, mongo, mongoDB, MONGO, etc. Matching is case -insensitive.

- -
listenerTypeEnvoyFilter.ListenerMatch.ListenerType -

Inbound vs outbound sidecar listener or gateway listener. If not specified, -matches all listeners.

- -
listenerProtocolEnvoyFilter.ListenerMatch.ListenerProtocol -

Selects a class of listeners for the same protocol. If not -specified, applies to listeners on all protocols. Use the protocol -selection to select all HTTP listeners (includes HTTP2/gRPC/HTTPS -where Envoy terminates TLS) or all TCP listeners (includes HTTPS -passthrough using SNI).

- -
addressstring[] -

One or more IP addresses to which the listener is bound. If -specified, should match at least one address in the list.

- -
-
-

EnvoyFilter.ListenerMatch.ListenerProtocol

-
- - - - - - - - - - - - - - - - - - - - - -
NameDescription
ALL -

All protocols

- -
HTTP -

HTTP or HTTPS (with termination) / HTTP2/gRPC

- -
TCP -

Any non-HTTP listener

- -
-
-

EnvoyFilter.ListenerMatch.ListenerType

-
- - - - - - - - - - - - - - - - - - - - - - - - - -
NameDescription
ANY -

All listeners

- -
SIDECAR_INBOUND -

Inbound listener in sidecar

- -
SIDECAR_OUTBOUND -

Outbound listener in sidecar

- -
GATEWAY -

Gateway listener

- -
-
-

Gateway

-
-

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
-
- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
serversServer[] -

REQUIRED: A list of server specifications.

- -
selectormap<string, string> -

REQUIRED: One or more labels that indicate a specific set of pods/VMs -on which this gateway configuration should be applied. The scope of -label search is restricted to the configuration namespace in which the -the resource is present. In other words, the Gateway resource must -reside in the same namespace as the gateway workload.

- -
-
-

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.

- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
delayHTTPFaultInjection.Delay -

Delay requests before forwarding, emulating various failures such as -network issues, overloaded upstream service, etc.

- -
abortHTTPFaultInjection.Abort -

Abort Http request attempts and return error codes back to downstream -service, giving the impression that the upstream service is faulty.

- -
-
-

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”.

- -
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.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
percentint32 -

Percentage of requests to be aborted with the error code provided (0-100). -Use of integer percent value is deprecated. Use the double percentage -field instead.

- -
httpStatusint32 (oneof) -

REQUIRED. HTTP status code to use to abort the Http request.

- -
percentagePercent -

Percentage of requests to be aborted with the error code provided.

- -
-
-

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

- -
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.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
percentint32 -

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.

- -
fixedDelaygoogle.protobuf.Duration (oneof) -

REQUIRED. Add a fixed delay before forwarding the request. Format: -1h/1m/1s/1ms. MUST be >=1ms.

- -
percentagePercent -

Percentage of requests on which the delay will be injected.

- -
-
-

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.

- -
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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
uriStringMatch -

URI to match -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

    • -
- -
schemeStringMatch -

URI Scheme -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

    • -
- -
methodStringMatch -

HTTP Method -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

    • -
- -
authorityStringMatch -

HTTP Authority -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

    • -
- -
headersmap<string, StringMatch> -

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.

- -
portuint32 -

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.

- -
sourceLabelsmap<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 at the top, it should include the reserved gateway -mesh in order for this field to be applicable.

- -
gatewaysstring[] -

Names of gateways where the rule should be applied to. Gateway names -at the top of the VirtualService (if any) are overridden. The gateway match is -independent of sourceLabels.

- -
-
-

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.

- -
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
-  ...
-
- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
uristring -

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.

- -
authoritystring -

On a redirect, overwrite the Authority/Host portion of the URL with -this value.

- -
-
-

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.

- -
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
-
- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
attemptsint32 -

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.

- -
perTryTimeoutgoogle.protobuf.Duration -

Timeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.

- -
retryOnstring -

Specifies the conditions under which retry takes place. -One or more policies can be specified using a ‘,’ delimited list. -The supported policies can be found in -https://www.envoyproxy.io/docs/envoy/latest/configuration/http_filters/router_filter#x-envoy-retry-on -and https://www.envoyproxy.io/docs/envoy/latest/configuration/http_filters/router_filter#x-envoy-retry-grpc-on

- -
-
-

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.

- -
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
-
- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
uristring -

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.

- -
authoritystring -

rewrite the Authority/Host header with this value.

- -
-
-

HTTPRoute

-
-

Describes match conditions and actions for routing HTTP/1.1, HTTP2, and -gRPC traffic. See VirtualService for usage examples.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
matchHTTPMatchRequest[] -

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.

- -
routeHTTPRouteDestination[] -

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.

- -
redirectHTTPRedirect -

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.

- -
rewriteHTTPRewrite -

Rewrite HTTP URIs and Authority headers. Rewrite cannot be used with -Redirect primitive. Rewrite will be performed before forwarding.

- -
timeoutgoogle.protobuf.Duration -

Timeout for HTTP requests.

- -
retriesHTTPRetry -

Retry policy for HTTP requests.

- -
faultHTTPFaultInjection -

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.

- -
mirrorDestination -

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.

- -
corsPolicyCorsPolicy -

Cross-Origin Resource Sharing policy (CORS). Refer to -CORS -for further details about cross origin resource sharing.

- -
appendHeadersmap<string, string> -

Use of append_headers is deprecated. Use the headers -field instead.

- -
removeResponseHeadersstring[] -

Use of remove_response_header is deprecated. Use the headers -field instead.

- -
appendResponseHeadersmap<string, string> -

Use of append_response_headers is deprecated. Use the headers -field instead.

- -
removeRequestHeadersstring[] -

Use of remove_request_headers is deprecated. Use the headers -field instead.

- -
appendRequestHeadersmap<string, string> -

Use of append_request_headers is deprecated. Use the headers -field instead.

- -
headersHeaders -

Header manipulation rules

- -
-
-

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”.

- -
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
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
destinationDestination -

REQUIRED. Destination uniquely identifies the instances of a service -to which the request/connection should be forwarded to.

- -
weightint32 -

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 one destination in a rule, the weight value is assumed to -be 100.

- -
removeResponseHeadersstring[] -

Use of remove_response_header is deprecated. Use the headers -field instead.

- -
appendResponseHeadersmap<string, string> -

Use of append_response_headers is deprecated. Use the headers -field instead.

- -
removeRequestHeadersstring[] -

Use of remove_request_headers is deprecated. Use the headers -field instead.

- -
appendRequestHeadersmap<string, string> -

Use of append_request_headers is deprecated. Use the headers -field instead.

- -
headersHeaders -

Header manipulation rules

- -
-
-

Headers

-
-

Header manipulation rules

- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
requestHeaders.HeaderOperations -

Header manipulation rules to apply before forwarding a request -to the destination service

- -
responseHeaders.HeaderOperations -

Header manipulation rules to apply before returning a response -to the caller

- -
-
-

Headers.HeaderOperations

-
-

HeaderOperations Describes the header manipulations to apply

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
setmap<string, string> -

Overwrite the headers specified by key with the given values

- -
addmap<string, string> -

Append the given values to the headers specified by keys -(will create a comma-separated list of values)

- -
removestring[] -

Remove a the specified headers

- -
-
-

IstioEgressListener

-
-

IstioEgressListener specifies the properties of an outbound traffic -listener on the sidecar proxy attached to a workload.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
portPort -

The port associated with the listener. If using unix domain socket, -use 0 as the port number, with a valid protocol. The port if -specified, will be used as the default destination port associated -with the imported hosts. If the port is omitted, Istio will infer the -listener ports based on the imported hosts. Note that when multiple -egress listeners are specified, where one or more listeners have -specific ports while others have no port, the hosts exposed on a -listener port will be based on the listener with the most specific -port.

- -
bindstring -

The ip or the unix domain socket to which the listener should be bound -to. Port MUST be specified if bind is not empty. Format: x.x.x.x or -unix:///path/to/uds or unix://@foobar (Linux abstract namespace). If -omitted, Istio will autoconfigure the defaults based on imported -services, the workload to which this configuration is applied to and -the captureMode. If captureMode is NONE, bind will default to -127.0.0.1.

- -
captureModeCaptureMode -

When the bind address is an IP, the captureMode option dictates -how traffic to the listener is expected to be captured (or not). -captureMode must be DEFAULT or NONE for unix domain socket binds.

- -
hostsstring[] -

REQUIRED: One or more services/virtualServices exposed by the listener -in namespace/dnsName format. Publicly scoped services and -VirtualServices from remote namespaces corresponding to the specified -hosts will be imported. The service in a namespace can be a service in -the service registry (e.g., a kubernetes or cloud foundry service) or -a service specified via ServiceEntry configuration. In addition, any -publicly scoped DestinationRule associated with the imported services -will also be imported.

- -

Set the namespace to * to import a particular service from any -available namespace (e.g., “*/foo.example.com”). Set the dnsName field -to * to import all services from the specified namespace (e.g., -“prod/*”). The services should be specified using FQDN format.

- -

NOTE: Only exported services and configuration artifacts from a -namespace can be imported. Private services/configuration will not be -imported. Refer to the scope setting associated with VirtualService, -DestinationRule, ServiceEntry, etc. for details.

- -
-
-

IstioIngressListener

-
-

IstioIngressListener specifies the properties of an inbound -traffic listener on the sidecar proxy attached to a workload.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
portPort -

REQUIRED. The port associated with the listener. If using -unix domain socket, use 0 as the port number, with a valid -protocol.

- -
bindstring -

The ip or the unix domain socket to which the listener should be bound -to. Format: x.x.x.x or unix:///path/to/uds or unix://@foobar (Linux -abstract namespace). If omitted, Istio will autoconfigure the defaults -based on imported services and the workload to which this -configuration is applied to.

- -
captureModeCaptureMode -

When the bind address is an IP, the captureMode option dictates -how traffic to the listener is expected to be captured (or not). -captureMode must be DEFAULT or NONE for unix domain socket binds.

- -
defaultEndpointstring -

REQUIRED: The loopback IP endpoint or unix domain socket to which -traffic should be forwarded to. This configuration can be used to -redirect traffic arriving at the bind point on the sidecar to a port -or unix domain socket where the application workload is listening for -connections. Format should be 127.0.0.1:PORT or unix:///path/to/socket

- -
-
-

L4MatchAttributes

-
-

L4 connection match attributes. Note that L4 connection matching support -is incomplete.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
destinationSubnetsstring[] -

IPv4 or IPv6 ip addresses of destination with optional subnet. E.g., -a.b.c.d/xx form or just a.b.c.d.

- -
portuint32 -

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.

- -
sourceLabelsmap<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 at the top, it should include the reserved gateway -mesh in order for this field to be applicable.

- -
gatewaysstring[] -

Names of gateways where the rule should be applied to. Gateway names -at the top of the VirtualService (if any) are overridden. The gateway -match is independent of sourceLabels.

- -
-
-

LoadBalancerSettings

-
-

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
-
- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
simpleLoadBalancerSettings.SimpleLB (oneof) -
consistentHashLoadBalancerSettings.ConsistentHashLB (oneof) -
-
-

LoadBalancerSettings.ConsistentHashLB

-
-

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
httpHeaderNamestring (oneof) -

Hash based on a specific HTTP header.

- -
useSourceIpbool (oneof) -

Hash based on the source IP address.

- -
minimumRingSizeuint64 -

The minimum number of virtual nodes to use for the hash -ring. Defaults to 1024. Larger ring sizes result in more granular -load distributions. If the number of hosts in the load balancing -pool is larger than the ring size, each host will be assigned a -single virtual node.

- -
-
-

LoadBalancerSettings.ConsistentHashLB.HTTPCookie

-
-

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
namestring -

REQUIRED. Name of the cookie.

- -
pathstring -

Path to set for the cookie.

- -
ttlgoogle.protobuf.Duration -

REQUIRED. Lifetime of the cookie.

- -
-
-

LoadBalancerSettings.SimpleLB

-
-

Standard load balancing algorithms that require no tuning.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
NameDescription
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.

- -
-
-

OutlierDetection

-
-

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
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
consecutiveErrorsint32 -

Number of errors before a host is ejected from the connection -pool. Defaults to 5. When the upstream host is accessed over HTTP, a -502, 503 or 504 return code qualifies as an error. When the upstream host -is accessed over an opaque TCP connection, connect timeouts and -connection error/failure events qualify as an error.

- -
intervalgoogle.protobuf.Duration -

Time interval between ejection sweep analysis. format: -1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.

- -
baseEjectionTimegoogle.protobuf.Duration -

Minimum ejection duration. A host will remain ejected for a period -equal to the product of minimum ejection duration and the number of -times the host has been ejected. This technique allows the system to -automatically increase the ejection period for unhealthy upstream -servers. format: 1h/1m/1s/1ms. MUST BE >=1ms. Default is 30s.

- -
maxEjectionPercentint32 -

Maximum % of hosts in the load balancing pool for the upstream -service that can be ejected. Defaults to 10%.

- -
minHealthPercentint32 -

Outlier detection will be enabled as long as the associated load balancing -pool has at least minhealthpercent hosts in healthy mode. When the -percentage of healthy hosts in the load balancing pool drops below this -threshold, outlier detection will be disabled and the proxy will load balance -across all hosts in the pool (healthy and unhealthy). The default is 50%.

- -
-
-

Percent

-
-

Percent specifies a percentage in the range of [0.0, 100.0].

- - - - - - - - - - - - - - - - -
FieldTypeDescription
valuedouble -
-
-

Port

-
-

Port describes the properties of a specific port of a service.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
numberuint32 -

REQUIRED: A valid non-negative integer port number.

- -
protocolstring -

REQUIRED: The protocol exposed on the port. -MUST BE one of HTTP|HTTPS|GRPC|HTTP2|MONGO|TCP|TLS. -TLS implies the connection will be routed based on the SNI header to -the destination without terminating the TLS connection.

- -
namestring -

Label assigned to the port.

- -
-
-

PortSelector

-
-

PortSelector specifies the number of a port to be used for -matching or selection for final routing.

- - - - - - - - - - - - - - - - -
FieldTypeDescription
numberuint32 (oneof) -

Valid port number

- -
-
-

RouteDestination

-
-

L4 routing rule weighted destination.

- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
destinationDestination -

REQUIRED. Destination uniquely identifies the instances of a service -to which the request/connection should be forwarded to.

- -
weightint32 -

REQUIRED. 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.

- -
-
-

Server

-
-

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
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
portPort -

REQUIRED: The Port on which the proxy should listen for incoming -connections. If using unix domain socket, use 0 as the port number, -with a valid protocol and port name, along with the bind parameter.

- -
hostsstring[] -

REQUIRED. A list of hosts exposed by this gateway. At least one -host is required. While typically applicable to -HTTP services, it can also be used for TCP services using TLS with -SNI. May contain a wildcard prefix for the bottom-level component of -a domain name. For example *.foo.com matches bar.foo.com -and *.com matches bar.foo.com, example.com, and so on.

- -

Note: A VirtualService that is bound to a gateway must have one -or more hosts that match the hosts specified in a server. The match -could be an exact match or a suffix match with the server’s hosts. For -example, if the server’s hosts specifies “*.example.com”, -VirtualServices with hosts dev.example.com, prod.example.com will -match. However, VirtualServices with hosts example.com or -newexample.com will not match.

- -
tlsServer.TLSOptions -

Set of TLS related options that govern the server’s behavior. Use -these options to control if all http requests should be redirected to -https, and the TLS modes to use.

- -
defaultEndpointstring -

The loopback IP endpoint or unix domain socket to which traffic should -be forwarded to by default. Format should be 127.0.0.1:PORT or -unix:///path/to/socket or unix://@foobar (Linux abstract namespace).

- -
-
-

Server.TLSOptions

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
httpsRedirectbool -

If set to true, the load balancer will send a 301 redirect for all -http connections, asking the clients to use HTTPS.

- -
modeServer.TLSOptions.TLSmode -

Optional: Indicates whether connections to this port should be -secured using TLS. The value of this field determines how TLS is -enforced.

- -
serverCertificatestring -

REQUIRED if mode is SIMPLE or MUTUAL. The path to the file -holding the server-side TLS certificate to use.

- -
privateKeystring -

REQUIRED if mode is SIMPLE or MUTUAL. The path to the file -holding the server’s private key.

- -
caCertificatesstring -

REQUIRED if mode is MUTUAL. The path to a file containing -certificate authority certificates to use in verifying a presented -client side certificate.

- -
credentialNamestring -

The credentialName stands for a unique identifier that can be used -to identify the serverCertificate and the privateKey. The credentialName -appended with suffix “-cacert” is used to identify the CaCertificates -associated with this server. Gateway workloads capable of fetching -credentials from a remote credential store will be configured to retrieve -the serverCertificate and the privateKey using credentialName, instead of -using the file system paths specified above. If using mutual TLS, -gateway workloads will retrieve the CaCertificates using -credentialName-cacert. The semantics of the name are platform dependent. -In Kubernetes, the default Istio supplied credential server expects the -credentialName to match the name of the Kubernetes secret that holds the -server certificate, the private key, and the CA certificate -(if using mutual TLS).

- -
subjectAltNamesstring[] -

A list of alternate names to verify the subject identity in the -certificate presented by the client.

- -
minProtocolVersionServer.TLSOptions.TLSProtocol -

Optional: Minimum TLS protocol version.

- -
maxProtocolVersionServer.TLSOptions.TLSProtocol -

Optional: Maximum TLS protocol version.

- -
cipherSuitesstring[] -

Optional: If specified, only support the specified cipher list. -Otherwise default to the default cipher list supported by Envoy.

- -
-
-

Server.TLSOptions.TLSProtocol

-
-

TLS protocol versions.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameDescription
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

- -
-
-

Server.TLSOptions.TLSmode

-
-

TLS modes enforced by the proxy

- - - - - - - - - - - - - - - - - - - - - - - - - - -
NameDescription
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

-
-

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
-      gateway:
-      - 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"
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
hostsstring[] -

REQUIRED. The hosts associated with the ServiceEntry. Could be a DNS -name with wildcard prefix (external services only). DNS names in hosts -will be ignored if the application accesses the service over non-HTTP -protocols such as mongo/opaque TCP/HTTPS. In such scenarios, the -IP addresses specified in the Addresses field or the port will be used -to uniquely identify the destination.

- -
addressesstring[] -

The virtual IP addresses associated with the service. Could be CIDR -prefix. For HTTP services, the addresses field will be ignored and -the destination will be identified based on the HTTP Host/Authority -header. For non-HTTP protocols such as mongo/opaque TCP/HTTPS, -the hosts will be ignored. If one or more IP addresses are specified, -the incoming traffic will be identified as belonging to this service -if the destination IP matches the IP/CIDRs specified in the addresses -field. If the Addresses field is empty, traffic will be identified -solely based on the destination port. In such scenarios, the port on -which the service is being accessed must not be shared by any other -service in the mesh. In other words, the sidecar will behave as a -simple TCP proxy, forwarding incoming traffic on a specified port to -the specified destination endpoint IP/host. Unix domain socket -addresses are not supported in this field.

- -
portsPort[] -

REQUIRED. The ports associated with the external service. If the -Endpoints are unix domain socket addresses, there must be exactly one -port.

- -
locationServiceEntry.Location -

Specify whether the service should be considered external to the mesh -or part of the mesh.

- -
resolutionServiceEntry.Resolution -

REQUIRED: Service discovery mode for the hosts. Care must be taken -when setting the resolution mode to NONE for a TCP port without -accompanying IP addresses. In such cases, traffic to any IP on -said port will be allowed (i.e. 0.0.0.0:).

- -
endpointsServiceEntry.Endpoint[] -

One or more endpoints associated with the service.

- -
exportTostring[] -

A list of namespaces to which this service is exported. Exporting a service -allows it to used by sidecars, gateways and virtual services defined in -other namespaces. This feature provides a mechanism for service owners -and mesh administrators to control the visibility of services across -namespace boundaries.

- -

If no namespaces are specified then the service is exported to all -namespaces by default.

- -

The value “.” is reserved and defines an export to the same namespace that -the service is declared in, similarly the value “*” is reserved and -defines an export to all namespaces.

- -

For a Kubernetes Service the equivalent effect can be achieved by setting -the annotation “networking.istio.io/exportTo” to a comma-separated list -of namespace names.

- -
subjectAltNamesstring[] -

The list of subject alternate names allowed for workloads that -implement this service. This information is used to enforce -secure-naming https://istio.io/docs/concepts/security/#secure-naming. -If specified, the proxy will verify that the server -certificate’s subject alternate name matches one of the specified values.

- -
-
-

ServiceEntry.Endpoint

-
-

Endpoint defines a network address (IP or hostname) associated with -the mesh service.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
addressstring -

REQUIRED: Address associated with the network endpoint without the -port. Domain names can be used if and only if the resolution is set -to DNS, and must be fully-qualified without wildcards. Use the form -unix:///absolute/path/to/socket for unix domain socket endpoints.

- -
portsmap<string, uint32> -

Set of ports associated with the endpoint. The ports must be -associated with a port name that was declared as part of the -service. Do not use for unix:// addresses.

- -
labelsmap<string, string> -

One or more labels associated with the endpoint.

- -
networkstring -

Network enables Istio to group endpoints resident in the same L3 -domain/network. All endpoints in the same network are assumed to be -directly reachable from one another. When endpoints in different -networks cannot reach each other directly, an Istio Gateway can be -used to establish connectivity (usually using the -AUTO_PASSTHROUGH mode in a Gateway Server). This is -an advanced configuration used typically for spanning an Istio mesh -over multiple clusters.

- -
localitystring -

The locality associated with the endpoint. A locality corresponds -to a failure domain (e.g., country/region/zone). Arbitrary failure -domain hierarchies can be represented by separating each -encapsulating failure domain by /. For example, the locality of an -an endpoint in US, in US-East-1 region, within availability zone -az-1, in data center rack r11 can be represented as -us/us-east-1/az-1/r11. Istio will configure the sidecar to route to -endpoints within the same locality as the sidecar. If none of the -endpoints in the locality are available, endpoints parent locality -(but within the same network ID) will be chosen. For example, if -there are two endpoints in same network (networkID “n1”), say e1 -with locality us/us-east-1/az-1/r11 and e2 with locality -us/us-east-1/az-2/r12, a sidecar from us/us-east-1/az-1/r11 locality -will prefer e1 from the same locality over e2 from a different -locality. Endpoint e2 could be the IP associated with a gateway -(that bridges networks n1 and n2), or the IP associated with a -standard service endpoint.

- -
weightuint32 -

The load balancing weight associated with the endpoint. Endpoints -with higher weights will receive proportionally higher traffic.

- -
-
-

ServiceEntry.Location

-
-

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.

- - - - - - - - - - - - - - - - - - -
NameDescription
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).

- -
-
-

ServiceEntry.Resolution

-
-

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.

- - - - - - - - - - - - - - - - - - - - - - -
NameDescription
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

-
-

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/*"
-
- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
workloadSelectorWorkloadSelector -

Criteria used to select the specific set of pods/VMs on which this -sidecar configuration should be applied. If omitted, the sidecar -configuration will be applied to all workloads in the same config -namespace.

- -
ingressIstioIngressListener[] -

Ingress specifies the configuration of the sidecar for processing -inbound traffic to the attached workload. If omitted, Istio will -autoconfigure the sidecar based on the information about the workload -obtained from the orchestration platform (e.g., exposed ports, services, -etc.).

- -
egressIstioEgressListener[] -

Egress specifies the configuration of the sidecar for processing -outbound traffic from the attached workload to other services in the -mesh. If omitted, Istio will autoconfigure the sidecar to be able to -reach every service in the mesh that is visible to this namespace.

- -
-
-

StringMatch

-
-

Describes how to match a given string in HTTP headers. Match is -case-sensitive.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
exactstring (oneof) -

exact string match

- -
prefixstring (oneof) -

prefix-based match

- -
regexstring (oneof) -

ECMAscript style regex-based match

- -
-
-

Subset

-
-

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
namestring -

REQUIRED. Name of the subset. The service name and the subset name can -be used for traffic splitting in a route rule.

- -
labelsmap<string, string> -

Labels apply a filter over the endpoints of a service in the -service registry. See route rules for examples of usage.

- -
trafficPolicyTrafficPolicy -

Traffic policies that apply to this subset. Subsets inherit the -traffic policies specified at the DestinationRule level. Settings -specified at the subset level will override the corresponding settings -specified at the DestinationRule level.

- -
-
-

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.

- -
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
-
- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
matchL4MatchAttributes[] -

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.

- -
routeRouteDestination[] -

The destination to which the connection should be forwarded to.

- -
-
-

TLSMatchAttributes

-
-

TLS connection match attributes.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
sniHostsstring[] -

REQUIRED. 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.

- -
destinationSubnetsstring[] -

IPv4 or IPv6 ip addresses of destination with optional subnet. E.g., -a.b.c.d/xx form or just a.b.c.d.

- -
portuint32 -

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.

- -
sourceLabelsmap<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 at the top, it should include the reserved gateway -mesh in order for this field to be applicable.

- -
gatewaysstring[] -

Names of gateways where the rule should be applied to. Gateway names -at the top of the VirtualService (if any) are overridden. The gateway -match is independent of sourceLabels.

- -
-
-

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.

- -
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
-
- - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
matchTLSMatchAttributes[] -

REQUIRED. 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.

- -
routeRouteDestination[] -

The destination to which the connection should be forwarded to.

- -
-
-

TLSSettings

-
-

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
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
modeTLSSettings.TLSmode -

REQUIRED: Indicates whether connections to this port should be secured -using TLS. The value of this field determines how TLS is enforced.

- -
clientCertificatestring -

REQUIRED if mode is MUTUAL. The path to the file holding the -client-side TLS certificate to use. -Should be empty if mode is ISTIO_MUTUAL.

- -
privateKeystring -

REQUIRED if mode is MUTUAL. The path to the file holding the -client’s private key. -Should be empty if mode is ISTIO_MUTUAL.

- -
caCertificatesstring -

OPTIONAL: The path to the file containing certificate authority -certificates to use in verifying a presented server certificate. If -omitted, the proxy will not verify the server’s certificate. -Should be empty if mode is ISTIO_MUTUAL.

- -
subjectAltNamesstring[] -

A list of alternate names to verify the subject identity in the -certificate. If specified, the proxy will verify that the server -certificate’s subject alt name matches one of the specified values. -If specified, this list overrides the value of subjectaltnames -from the ServiceEntry.

- -
snistring -

SNI string to present to the server during TLS handshake.

- -
-
-

TLSSettings.TLSmode

-
-

TLS connection mode

- - - - - - - - - - - - - - - - - - - - - - - - - - -
NameDescription
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 TLSSettings should be empty.

- -
-
-

TrafficPolicy

-
-

Traffic policies to apply for a specific destination, across all -destination ports. See DestinationRule for examples.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
loadBalancerLoadBalancerSettings -

Settings controlling the load balancer algorithms.

- -
connectionPoolConnectionPoolSettings -

Settings controlling the volume of connections to an upstream service

- -
outlierDetectionOutlierDetection -

Settings controlling eviction of unhealthy hosts from the load balancing pool

- -
tlsTLSSettings -

TLS related settings for connections to the upstream service.

- -
portLevelSettingsTrafficPolicy.PortTrafficPolicy[] -

Traffic policies specific to individual ports. Note that port level -settings will override the destination-level settings. Traffic -settings specified at the destination-level will not be inherited when -overridden by port-level settings, i.e. default values will be applied -to fields omitted in port-level traffic policies.

- -
-
-

TrafficPolicy.PortTrafficPolicy

-
-

Traffic policies that apply to specific ports of the service

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
portPortSelector -

Specifies the port name or number of a port on the destination service -on which this policy is being applied.

- -

Names must comply with DNS label syntax (rfc1035) and therefore cannot -collide with numbers. If there are multiple ports on a service with -the same protocol the names should be of the form -.

- -
loadBalancerLoadBalancerSettings -

Settings controlling the load balancer algorithms.

- -
connectionPoolConnectionPoolSettings -

Settings controlling the volume of connections to an upstream service

- -
outlierDetectionOutlierDetection -

Settings controlling eviction of unhealthy hosts from the load balancing pool

- -
tlsTLSSettings -

TLS related settings for connections to the upstream service.

- -
-
-

VirtualService

-
-

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
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
hostsstring[] -

REQUIRED. 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 host name can be defined by only one VirtualService. A single -VirtualService can be used to describe traffic properties for multiple -HTTP and TCP ports.

- -

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.

- -
gatewaysstring[] -

The names of gateways and sidecars that should apply these routes. 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.

- -
httpHTTPRoute[] -

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.

- -
tlsTLSRoute[] -

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.

- -
tcpTCPRoute[] -

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.

- -
exportTostring[] -

A list of namespaces to which this virtual service is exported. Exporting a -virtual service allows it to 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.

- -
-
-

WorkloadSelector

-
-

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.

- - - - - - - - - - - - - - - - -
FieldTypeDescription
labelsmap<string, string> -

REQUIRED: One or more labels that indicate a specific set of pods/VMs -on which this sidecar configuration should be applied. The scope of -label search is restricted to the configuration namespace in which the -the resource is present.

- -
-
diff --git a/networking/v1alpha3/service_entry.pb.go b/networking/v1alpha3/service_entry.pb.go index d34c55bc909..b6923884133 100644 --- a/networking/v1alpha3/service_entry.pb.go +++ b/networking/v1alpha3/service_entry.pb.go @@ -1,115 +1,6 @@ // Code generated by protoc-gen-gogo. DO NOT EDIT. // source: networking/v1alpha3/service_entry.proto -package v1alpha3 - -import ( - fmt "fmt" - proto "github.com/gogo/protobuf/proto" - io "io" - math "math" -) - -// Reference imports to suppress errors if they are not otherwise used. -var _ = proto.Marshal -var _ = fmt.Errorf -var _ = math.Inf - -// This is a compile-time assertion to ensure that this generated file -// is compatible with the proto package it is being compiled against. -// A compilation error at this line likely means your copy of the -// proto package needs to be updated. -const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package - -// 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. -type ServiceEntry_Location int32 - -const ( - // Signifies that the service is external to the mesh. Typically used - // to indicate external services consumed through APIs. - ServiceEntry_MESH_EXTERNAL ServiceEntry_Location = 0 - // 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). - ServiceEntry_MESH_INTERNAL ServiceEntry_Location = 1 -) - -var ServiceEntry_Location_name = map[int32]string{ - 0: "MESH_EXTERNAL", - 1: "MESH_INTERNAL", -} - -var ServiceEntry_Location_value = map[string]int32{ - "MESH_EXTERNAL": 0, - "MESH_INTERNAL": 1, -} - -func (x ServiceEntry_Location) String() string { - return proto.EnumName(ServiceEntry_Location_name, int32(x)) -} - -func (ServiceEntry_Location) EnumDescriptor() ([]byte, []int) { - return fileDescriptor_9220e0fa673c4bf8, []int{0, 0} -} - -// 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. -type ServiceEntry_Resolution int32 - -const ( - // 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. - ServiceEntry_NONE ServiceEntry_Resolution = 0 - // Use the static IP addresses specified in endpoints (see below) as the - // backing instances associated with the service. - ServiceEntry_STATIC ServiceEntry_Resolution = 1 - // 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. - ServiceEntry_DNS ServiceEntry_Resolution = 2 -) - -var ServiceEntry_Resolution_name = map[int32]string{ - 0: "NONE", - 1: "STATIC", - 2: "DNS", -} - -var ServiceEntry_Resolution_value = map[string]int32{ - "NONE": 0, - "STATIC": 1, - "DNS": 2, -} - -func (x ServiceEntry_Resolution) String() string { - return proto.EnumName(ServiceEntry_Resolution_name, int32(x)) -} - -func (ServiceEntry_Resolution) EnumDescriptor() ([]byte, []int) { - return fileDescriptor_9220e0fa673c4bf8, []int{0, 1} -} - // `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 @@ -416,6 +307,116 @@ func (ServiceEntry_Resolution) EnumDescriptor() ([]byte, []int) { // - "spiffe://cluster.local/ns/httpbin-ns/sa/httpbin-service-account" // ``` // + +package v1alpha3 + +import ( + fmt "fmt" + proto "github.com/gogo/protobuf/proto" + io "io" + math "math" +) + +// Reference imports to suppress errors if they are not otherwise used. +var _ = proto.Marshal +var _ = fmt.Errorf +var _ = math.Inf + +// This is a compile-time assertion to ensure that this generated file +// is compatible with the proto package it is being compiled against. +// A compilation error at this line likely means your copy of the +// proto package needs to be updated. +const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package + +// 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. +type ServiceEntry_Location int32 + +const ( + // Signifies that the service is external to the mesh. Typically used + // to indicate external services consumed through APIs. + ServiceEntry_MESH_EXTERNAL ServiceEntry_Location = 0 + // 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). + ServiceEntry_MESH_INTERNAL ServiceEntry_Location = 1 +) + +var ServiceEntry_Location_name = map[int32]string{ + 0: "MESH_EXTERNAL", + 1: "MESH_INTERNAL", +} + +var ServiceEntry_Location_value = map[string]int32{ + "MESH_EXTERNAL": 0, + "MESH_INTERNAL": 1, +} + +func (x ServiceEntry_Location) String() string { + return proto.EnumName(ServiceEntry_Location_name, int32(x)) +} + +func (ServiceEntry_Location) EnumDescriptor() ([]byte, []int) { + return fileDescriptor_9220e0fa673c4bf8, []int{0, 0} +} + +// 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. +type ServiceEntry_Resolution int32 + +const ( + // 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. + ServiceEntry_NONE ServiceEntry_Resolution = 0 + // Use the static IP addresses specified in endpoints (see below) as the + // backing instances associated with the service. + ServiceEntry_STATIC ServiceEntry_Resolution = 1 + // 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. + ServiceEntry_DNS ServiceEntry_Resolution = 2 +) + +var ServiceEntry_Resolution_name = map[int32]string{ + 0: "NONE", + 1: "STATIC", + 2: "DNS", +} + +var ServiceEntry_Resolution_value = map[string]int32{ + "NONE": 0, + "STATIC": 1, + "DNS": 2, +} + +func (x ServiceEntry_Resolution) String() string { + return proto.EnumName(ServiceEntry_Resolution_name, int32(x)) +} + +func (ServiceEntry_Resolution) EnumDescriptor() ([]byte, []int) { + return fileDescriptor_9220e0fa673c4bf8, []int{0, 1} +} + type ServiceEntry struct { // REQUIRED. The hosts associated with the ServiceEntry. Could be a DNS // name with wildcard prefix (external services only). DNS names in hosts @@ -472,7 +473,7 @@ type ServiceEntry struct { ExportTo []string `protobuf:"bytes,7,rep,name=export_to,json=exportTo,proto3" json:"export_to,omitempty"` // The list of subject alternate names allowed for workloads that // implement this service. This information is used to enforce - // secure-naming . + // [secure-naming](/docs/concepts/security/#secure-naming). // If specified, the proxy will verify that the server // certificate's subject alternate name matches one of the specified values. SubjectAltNames []string `protobuf:"bytes,8,rep,name=subject_alt_names,json=subjectAltNames,proto3" json:"subject_alt_names,omitempty"` diff --git a/networking/v1alpha3/service_entry.pb.html b/networking/v1alpha3/service_entry.pb.html new file mode 100644 index 00000000000..a53b377df89 --- /dev/null +++ b/networking/v1alpha3/service_entry.pb.html @@ -0,0 +1,612 @@ +--- +title: Service Entry +description: Configuration affecting service registry. +location: https://istio.io/docs/reference/config/networking/v1alpha3/service-entry.html +layout: protoc-gen-docs +generator: protoc-gen-docs +number_of_entries: 4 +--- +

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
+      gateway:
+      - 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"
+
+ +

ServiceEntry

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
hostsstring[] +

REQUIRED. The hosts associated with the ServiceEntry. Could be a DNS +name with wildcard prefix (external services only). DNS names in hosts +will be ignored if the application accesses the service over non-HTTP +protocols such as mongo/opaque TCP/HTTPS. In such scenarios, the +IP addresses specified in the Addresses field or the port will be used +to uniquely identify the destination.

+ +
addressesstring[] +

The virtual IP addresses associated with the service. Could be CIDR +prefix. For HTTP services, the addresses field will be ignored and +the destination will be identified based on the HTTP Host/Authority +header. For non-HTTP protocols such as mongo/opaque TCP/HTTPS, +the hosts will be ignored. If one or more IP addresses are specified, +the incoming traffic will be identified as belonging to this service +if the destination IP matches the IP/CIDRs specified in the addresses +field. If the Addresses field is empty, traffic will be identified +solely based on the destination port. In such scenarios, the port on +which the service is being accessed must not be shared by any other +service in the mesh. In other words, the sidecar will behave as a +simple TCP proxy, forwarding incoming traffic on a specified port to +the specified destination endpoint IP/host. Unix domain socket +addresses are not supported in this field.

+ +
portsPort[] +

REQUIRED. The ports associated with the external service. If the +Endpoints are unix domain socket addresses, there must be exactly one +port.

+ +
locationServiceEntry.Location +

Specify whether the service should be considered external to the mesh +or part of the mesh.

+ +
resolutionServiceEntry.Resolution +

REQUIRED: Service discovery mode for the hosts. Care must be taken +when setting the resolution mode to NONE for a TCP port without +accompanying IP addresses. In such cases, traffic to any IP on +said port will be allowed (i.e. 0.0.0.0:).

+ +
endpointsServiceEntry.Endpoint[] +

One or more endpoints associated with the service.

+ +
exportTostring[] +

A list of namespaces to which this service is exported. Exporting a service +allows it to used by sidecars, gateways and virtual services defined in +other namespaces. This feature provides a mechanism for service owners +and mesh administrators to control the visibility of services across +namespace boundaries.

+ +

If no namespaces are specified then the service is exported to all +namespaces by default.

+ +

The value “.” is reserved and defines an export to the same namespace that +the service is declared in, similarly the value “*” is reserved and +defines an export to all namespaces.

+ +

For a Kubernetes Service the equivalent effect can be achieved by setting +the annotation “networking.istio.io/exportTo” to a comma-separated list +of namespace names.

+ +
subjectAltNamesstring[] +

The list of subject alternate names allowed for workloads that +implement this service. This information is used to enforce +secure-naming. +If specified, the proxy will verify that the server +certificate’s subject alternate name matches one of the specified values.

+ +
+
+

ServiceEntry.Endpoint

+
+

Endpoint defines a network address (IP or hostname) associated with +the mesh service.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
addressstring +

REQUIRED: Address associated with the network endpoint without the +port. Domain names can be used if and only if the resolution is set +to DNS, and must be fully-qualified without wildcards. Use the form +unix:///absolute/path/to/socket for unix domain socket endpoints.

+ +
portsmap<string, uint32> +

Set of ports associated with the endpoint. The ports must be +associated with a port name that was declared as part of the +service. Do not use for unix:// addresses.

+ +
labelsmap<string, string> +

One or more labels associated with the endpoint.

+ +
networkstring +

Network enables Istio to group endpoints resident in the same L3 +domain/network. All endpoints in the same network are assumed to be +directly reachable from one another. When endpoints in different +networks cannot reach each other directly, an Istio Gateway can be +used to establish connectivity (usually using the +AUTO_PASSTHROUGH mode in a Gateway Server). This is +an advanced configuration used typically for spanning an Istio mesh +over multiple clusters.

+ +
localitystring +

The locality associated with the endpoint. A locality corresponds +to a failure domain (e.g., country/region/zone). Arbitrary failure +domain hierarchies can be represented by separating each +encapsulating failure domain by /. For example, the locality of an +an endpoint in US, in US-East-1 region, within availability zone +az-1, in data center rack r11 can be represented as +us/us-east-1/az-1/r11. Istio will configure the sidecar to route to +endpoints within the same locality as the sidecar. If none of the +endpoints in the locality are available, endpoints parent locality +(but within the same network ID) will be chosen. For example, if +there are two endpoints in same network (networkID “n1”), say e1 +with locality us/us-east-1/az-1/r11 and e2 with locality +us/us-east-1/az-2/r12, a sidecar from us/us-east-1/az-1/r11 locality +will prefer e1 from the same locality over e2 from a different +locality. Endpoint e2 could be the IP associated with a gateway +(that bridges networks n1 and n2), or the IP associated with a +standard service endpoint.

+ +
weightuint32 +

The load balancing weight associated with the endpoint. Endpoints +with higher weights will receive proportionally higher traffic.

+ +
+
+

ServiceEntry.Location

+
+

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.

+ + + + + + + + + + + + + + + + + + +
NameDescription
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).

+ +
+
+

ServiceEntry.Resolution

+
+

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.

+ + + + + + + + + + + + + + + + + + + + + + +
NameDescription
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.

+ +
+
diff --git a/networking/v1alpha3/service_entry.proto b/networking/v1alpha3/service_entry.proto index 1527586f479..0964ead5073 100644 --- a/networking/v1alpha3/service_entry.proto +++ b/networking/v1alpha3/service_entry.proto @@ -16,9 +16,9 @@ syntax = "proto3"; import "networking/v1alpha3/gateway.proto"; -package istio.networking.v1alpha3; - -option go_package = "istio.io/api/networking/v1alpha3"; +// $title: Service Entry +// $description: Configuration affecting service registry. +// $location: https://istio.io/docs/reference/config/networking/v1alpha3/service-entry.html // `ServiceEntry` enables adding additional entries into Istio's internal // service registry, so that auto-discovered services in the mesh can @@ -326,6 +326,10 @@ option go_package = "istio.io/api/networking/v1alpha3"; // - "spiffe://cluster.local/ns/httpbin-ns/sa/httpbin-service-account" // ``` // +package istio.networking.v1alpha3; + +option go_package = "istio.io/api/networking/v1alpha3"; + message ServiceEntry { // REQUIRED. The hosts associated with the ServiceEntry. Could be a DNS // name with wildcard prefix (external services only). DNS names in hosts @@ -490,7 +494,7 @@ message ServiceEntry { // The list of subject alternate names allowed for workloads that // implement this service. This information is used to enforce - // secure-naming . + // [secure-naming](/docs/concepts/security/#secure-naming). // If specified, the proxy will verify that the server // certificate's subject alternate name matches one of the specified values. repeated string subject_alt_names = 8; diff --git a/networking/v1alpha3/sidecar.pb.go b/networking/v1alpha3/sidecar.pb.go index 70b52cdf959..e520774c021 100644 --- a/networking/v1alpha3/sidecar.pb.go +++ b/networking/v1alpha3/sidecar.pb.go @@ -1,63 +1,6 @@ // Code generated by protoc-gen-gogo. DO NOT EDIT. // source: networking/v1alpha3/sidecar.proto -package v1alpha3 - -import ( - fmt "fmt" - proto "github.com/gogo/protobuf/proto" - io "io" - math "math" -) - -// Reference imports to suppress errors if they are not otherwise used. -var _ = proto.Marshal -var _ = fmt.Errorf -var _ = math.Inf - -// This is a compile-time assertion to ensure that this generated file -// is compatible with the proto package it is being compiled against. -// A compilation error at this line likely means your copy of the -// proto package needs to be updated. -const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package - -// CaptureMode describes how traffic to a listener is expected to be -// captured. Applicable only when the listener is bound to an IP. -type CaptureMode int32 - -const ( - // The default capture mode defined by the environment - CaptureMode_DEFAULT CaptureMode = 0 - // Capture traffic using IPtables redirection - CaptureMode_IPTABLES CaptureMode = 1 - // 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. - CaptureMode_NONE CaptureMode = 2 -) - -var CaptureMode_name = map[int32]string{ - 0: "DEFAULT", - 1: "IPTABLES", - 2: "NONE", -} - -var CaptureMode_value = map[string]int32{ - "DEFAULT": 0, - "IPTABLES": 1, - "NONE": 2, -} - -func (x CaptureMode) String() string { - return proto.EnumName(CaptureMode_name, int32(x)) -} - -func (CaptureMode) EnumDescriptor() ([]byte, []int) { - return fileDescriptor_b5c11342f04ad3d1, []int{0} -} - // `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 @@ -135,6 +78,64 @@ func (CaptureMode) EnumDescriptor() ([]byte, []int) { // - "prod-us1/*" // ``` // + +package v1alpha3 + +import ( + fmt "fmt" + proto "github.com/gogo/protobuf/proto" + io "io" + math "math" +) + +// Reference imports to suppress errors if they are not otherwise used. +var _ = proto.Marshal +var _ = fmt.Errorf +var _ = math.Inf + +// This is a compile-time assertion to ensure that this generated file +// is compatible with the proto package it is being compiled against. +// A compilation error at this line likely means your copy of the +// proto package needs to be updated. +const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package + +// CaptureMode describes how traffic to a listener is expected to be +// captured. Applicable only when the listener is bound to an IP. +type CaptureMode int32 + +const ( + // The default capture mode defined by the environment + CaptureMode_DEFAULT CaptureMode = 0 + // Capture traffic using IPtables redirection + CaptureMode_IPTABLES CaptureMode = 1 + // 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. + CaptureMode_NONE CaptureMode = 2 +) + +var CaptureMode_name = map[int32]string{ + 0: "DEFAULT", + 1: "IPTABLES", + 2: "NONE", +} + +var CaptureMode_value = map[string]int32{ + "DEFAULT": 0, + "IPTABLES": 1, + "NONE": 2, +} + +func (x CaptureMode) String() string { + return proto.EnumName(CaptureMode_name, int32(x)) +} + +func (CaptureMode) EnumDescriptor() ([]byte, []int) { + return fileDescriptor_b5c11342f04ad3d1, []int{0} +} + type Sidecar struct { // Criteria used to select the specific set of pods/VMs on which this // sidecar configuration should be applied. If omitted, the sidecar diff --git a/networking/v1alpha3/sidecar.pb.html b/networking/v1alpha3/sidecar.pb.html new file mode 100644 index 00000000000..172162066fd --- /dev/null +++ b/networking/v1alpha3/sidecar.pb.html @@ -0,0 +1,348 @@ +--- +title: Sidecar +description: Configuration affecting network reachability of a sidecar. +location: https://istio.io/docs/reference/config/networking/v1alpha3/sidecar.html +layout: protoc-gen-docs +generator: protoc-gen-docs +number_of_entries: 5 +--- +

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/*"
+
+ +

CaptureMode

+
+

CaptureMode describes how traffic to a listener is expected to be +captured. Applicable only when the listener is bound to an IP.

+ + + + + + + + + + + + + + + + + + + + + + +
NameDescription
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.

+ +
+
+

IstioEgressListener

+
+

IstioEgressListener specifies the properties of an outbound traffic +listener on the sidecar proxy attached to a workload.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
portPort +

The port associated with the listener. If using unix domain socket, +use 0 as the port number, with a valid protocol. The port if +specified, will be used as the default destination port associated +with the imported hosts. If the port is omitted, Istio will infer the +listener ports based on the imported hosts. Note that when multiple +egress listeners are specified, where one or more listeners have +specific ports while others have no port, the hosts exposed on a +listener port will be based on the listener with the most specific +port.

+ +
bindstring +

The ip or the unix domain socket to which the listener should be bound +to. Port MUST be specified if bind is not empty. Format: x.x.x.x or +unix:///path/to/uds or unix://@foobar (Linux abstract namespace). If +omitted, Istio will autoconfigure the defaults based on imported +services, the workload to which this configuration is applied to and +the captureMode. If captureMode is NONE, bind will default to +127.0.0.1.

+ +
captureModeCaptureMode +

When the bind address is an IP, the captureMode option dictates +how traffic to the listener is expected to be captured (or not). +captureMode must be DEFAULT or NONE for unix domain socket binds.

+ +
hostsstring[] +

REQUIRED: One or more services/virtualServices exposed by the listener +in namespace/dnsName format. Publicly scoped services and +VirtualServices from remote namespaces corresponding to the specified +hosts will be imported. The service in a namespace can be a service in +the service registry (e.g., a kubernetes or cloud foundry service) or +a service specified via ServiceEntry configuration. In addition, any +publicly scoped DestinationRule associated with the imported services +will also be imported.

+ +

Set the namespace to * to import a particular service from any +available namespace (e.g., “*/foo.example.com”). Set the dnsName field +to * to import all services from the specified namespace (e.g., +“prod/*”). The services should be specified using FQDN format.

+ +

NOTE: Only exported services and configuration artifacts from a +namespace can be imported. Private services/configuration will not be +imported. Refer to the scope setting associated with VirtualService, +DestinationRule, ServiceEntry, etc. for details.

+ +
+
+

IstioIngressListener

+
+

IstioIngressListener specifies the properties of an inbound +traffic listener on the sidecar proxy attached to a workload.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
portPort +

REQUIRED. The port associated with the listener. If using +unix domain socket, use 0 as the port number, with a valid +protocol.

+ +
bindstring +

The ip or the unix domain socket to which the listener should be bound +to. Format: x.x.x.x or unix:///path/to/uds or unix://@foobar (Linux +abstract namespace). If omitted, Istio will autoconfigure the defaults +based on imported services and the workload to which this +configuration is applied to.

+ +
captureModeCaptureMode +

When the bind address is an IP, the captureMode option dictates +how traffic to the listener is expected to be captured (or not). +captureMode must be DEFAULT or NONE for unix domain socket binds.

+ +
defaultEndpointstring +

REQUIRED: The loopback IP endpoint or unix domain socket to which +traffic should be forwarded to. This configuration can be used to +redirect traffic arriving at the bind point on the sidecar to a port +or unix domain socket where the application workload is listening for +connections. Format should be 127.0.0.1:PORT or unix:///path/to/socket

+ +
+
+

Sidecar

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
workloadSelectorWorkloadSelector +

Criteria used to select the specific set of pods/VMs on which this +sidecar configuration should be applied. If omitted, the sidecar +configuration will be applied to all workloads in the same config +namespace.

+ +
ingressIstioIngressListener[] +

Ingress specifies the configuration of the sidecar for processing +inbound traffic to the attached workload. If omitted, Istio will +autoconfigure the sidecar based on the information about the workload +obtained from the orchestration platform (e.g., exposed ports, services, +etc.).

+ +
egressIstioEgressListener[] +

Egress specifies the configuration of the sidecar for processing +outbound traffic from the attached workload to other services in the +mesh. If omitted, Istio will autoconfigure the sidecar to be able to +reach every service in the mesh that is visible to this namespace.

+ +
+
+

WorkloadSelector

+
+

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.

+ + + + + + + + + + + + + + + + +
FieldTypeDescription
labelsmap<string, string> +

REQUIRED: One or more labels that indicate a specific set of pods/VMs +on which this sidecar configuration should be applied. The scope of +label search is restricted to the configuration namespace in which the +the resource is present.

+ +
+
diff --git a/networking/v1alpha3/sidecar.proto b/networking/v1alpha3/sidecar.proto index d2e2776513c..2db96f12a93 100644 --- a/networking/v1alpha3/sidecar.proto +++ b/networking/v1alpha3/sidecar.proto @@ -16,9 +16,9 @@ syntax = "proto3"; import "networking/v1alpha3/gateway.proto"; -package istio.networking.v1alpha3; - -option go_package = "istio.io/api/networking/v1alpha3"; +// $title: Sidecar +// $description: Configuration affecting network reachability of a sidecar. +// $location: https://istio.io/docs/reference/config/networking/v1alpha3/sidecar.html // `Sidecar` describes the configuration of the sidecar proxy that mediates // inbound and outbound communication to the workload it is attached to. By @@ -97,6 +97,10 @@ option go_package = "istio.io/api/networking/v1alpha3"; // - "prod-us1/*" // ``` // +package istio.networking.v1alpha3; + +option go_package = "istio.io/api/networking/v1alpha3"; + message Sidecar { // Criteria used to select the specific set of pods/VMs on which this // sidecar configuration should be applied. If omitted, the sidecar diff --git a/networking/v1alpha3/virtual_service.pb.go b/networking/v1alpha3/virtual_service.pb.go index 7ccda22babb..5426007e362 100644 --- a/networking/v1alpha3/virtual_service.pb.go +++ b/networking/v1alpha3/virtual_service.pb.go @@ -29,29 +29,7 @@ // actual choice of the version is determined by the proxy/sidecar, enabling the // application code to decouple itself from the evolution of dependent // services. - -package v1alpha3 - -import ( - encoding_binary "encoding/binary" - fmt "fmt" - proto "github.com/gogo/protobuf/proto" - types "github.com/gogo/protobuf/types" - io "io" - math "math" -) - -// Reference imports to suppress errors if they are not otherwise used. -var _ = proto.Marshal -var _ = fmt.Errorf -var _ = math.Inf - -// This is a compile-time assertion to ensure that this generated file -// is compatible with the proto package it is being compiled against. -// A compilation error at this line likely means your copy of the -// proto package needs to be updated. -const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package - +// // 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 @@ -112,6 +90,29 @@ const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package // version: v2 // ``` // + +package v1alpha3 + +import ( + encoding_binary "encoding/binary" + fmt "fmt" + proto "github.com/gogo/protobuf/proto" + types "github.com/gogo/protobuf/types" + io "io" + math "math" +) + +// Reference imports to suppress errors if they are not otherwise used. +var _ = proto.Marshal +var _ = fmt.Errorf +var _ = math.Inf + +// This is a compile-time assertion to ensure that this generated file +// is compatible with the proto package it is being compiled against. +// A compilation error at this line likely means your copy of the +// proto package needs to be updated. +const _ = proto.GoGoProtoPackageIsVersion2 // please upgrade the proto package + type VirtualService struct { // REQUIRED. The destination hosts to which traffic is being sent. Could // be a DNS name with wildcard prefix or an IP address. Depending on the @@ -267,7 +268,7 @@ func (m *VirtualService) GetExportTo() []string { // 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](#ServiceEntry) resource. +// [ServiceEntry](/docs/reference/config/networking/v1alpha3/service-entry/#ServiceEntry) resource. // // *Note for Kubernetes users*: When short names are used (e.g. "reviews" // instead of "reviews.default.svc.cluster.local"), Istio will interpret @@ -392,7 +393,7 @@ type Destination struct { // REQUIRED. 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](#ServiceEntry). Traffic forwarded to + // declared by [ServiceEntry](/docs/reference/config/networking/v1alpha3/service-entry/#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" diff --git a/networking/v1alpha3/virtual_service.pb.html b/networking/v1alpha3/virtual_service.pb.html new file mode 100644 index 00000000000..c70eea2f091 --- /dev/null +++ b/networking/v1alpha3/virtual_service.pb.html @@ -0,0 +1,1759 @@ +--- +title: Virtual Service +description: Configuration affecting label/content routing, sni routing, etc. +location: https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service.html +layout: protoc-gen-docs +generator: protoc-gen-docs +number_of_entries: 22 +--- +

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”.

+ +
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
+
+ +

CorsPolicy

+
+

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"
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
allowOriginstring[] +

The list of origins that are allowed to perform CORS requests. The +content will be serialized into the Access-Control-Allow-Origin +header. Wildcard * will allow all origins.

+ +
allowMethodsstring[] +

List of HTTP methods allowed to access the resource. The content will +be serialized into the Access-Control-Allow-Methods header.

+ +
allowHeadersstring[] +

List of HTTP headers that can be used when requesting the +resource. Serialized to Access-Control-Allow-Headers header.

+ +
exposeHeadersstring[] +

A white list of HTTP headers that the browsers are allowed to +access. Serialized into Access-Control-Expose-Headers header.

+ +
maxAgegoogle.protobuf.Duration +

Specifies how long the results of a preflight request can be +cached. Translates to the Access-Control-Max-Age header.

+ +
allowCredentialsgoogle.protobuf.BoolValue +

Indicates whether the caller is allowed to send the actual request +(not the preflight) using credentials. Translates to +Access-Control-Allow-Credentials header.

+ +
+
+

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/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
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
hoststring +

REQUIRED. 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 misconfigurations, it is recommended to always use fully +qualified domain names over short names.

+ +
subsetstring +

The name of a subset within the service. Applicable only to services +within the mesh. The subset must be defined in a corresponding +DestinationRule.

+ +
portPortSelector +

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.

+ +
+
+

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.

+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
delayHTTPFaultInjection.Delay +

Delay requests before forwarding, emulating various failures such as +network issues, overloaded upstream service, etc.

+ +
abortHTTPFaultInjection.Abort +

Abort Http request attempts and return error codes back to downstream +service, giving the impression that the upstream service is faulty.

+ +
+
+

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”.

+ +
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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentint32 +

Percentage of requests to be aborted with the error code provided (0-100). +Use of integer percent value is deprecated. Use the double percentage +field instead.

+ +
httpStatusint32 (oneof) +

REQUIRED. HTTP status code to use to abort the Http request.

+ +
percentagePercent +

Percentage of requests to be aborted with the error code provided.

+ +
+
+

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

+ +
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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
percentint32 +

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.

+ +
fixedDelaygoogle.protobuf.Duration (oneof) +

REQUIRED. Add a fixed delay before forwarding the request. Format: +1h/1m/1s/1ms. MUST be >=1ms.

+ +
percentagePercent +

Percentage of requests on which the delay will be injected.

+ +
+
+

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.

+ +
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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uriStringMatch +

URI to match +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

    • +
+ +
schemeStringMatch +

URI Scheme +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

    • +
+ +
methodStringMatch +

HTTP Method +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

    • +
+ +
authorityStringMatch +

HTTP Authority +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

    • +
+ +
headersmap<string, StringMatch> +

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.

+ +
portuint32 +

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.

+ +
sourceLabelsmap<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 at the top, it should include the reserved gateway +mesh in order for this field to be applicable.

+ +
gatewaysstring[] +

Names of gateways where the rule should be applied to. Gateway names +at the top of the VirtualService (if any) are overridden. The gateway match is +independent of sourceLabels.

+ +
+
+

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.

+ +
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
+  ...
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uristring +

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.

+ +
authoritystring +

On a redirect, overwrite the Authority/Host portion of the URL with +this value.

+ +
+
+

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.

+ +
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
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
attemptsint32 +

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.

+ +
perTryTimeoutgoogle.protobuf.Duration +

Timeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.

+ +
retryOnstring +

Specifies the conditions under which retry takes place. +One or more policies can be specified using a ‘,’ delimited list. +The supported policies can be found in +https://www.envoyproxy.io/docs/envoy/latest/configuration/http_filters/router_filter#x-envoy-retry-on +and https://www.envoyproxy.io/docs/envoy/latest/configuration/http_filters/router_filter#x-envoy-retry-grpc-on

+ +
+
+

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.

+ +
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
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
uristring +

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.

+ +
authoritystring +

rewrite the Authority/Host header with this value.

+ +
+
+

HTTPRoute

+
+

Describes match conditions and actions for routing HTTP/1.1, HTTP2, and +gRPC traffic. See VirtualService for usage examples.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
matchHTTPMatchRequest[] +

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.

+ +
routeHTTPRouteDestination[] +

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.

+ +
redirectHTTPRedirect +

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.

+ +
rewriteHTTPRewrite +

Rewrite HTTP URIs and Authority headers. Rewrite cannot be used with +Redirect primitive. Rewrite will be performed before forwarding.

+ +
timeoutgoogle.protobuf.Duration +

Timeout for HTTP requests.

+ +
retriesHTTPRetry +

Retry policy for HTTP requests.

+ +
faultHTTPFaultInjection +

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.

+ +
mirrorDestination +

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.

+ +
corsPolicyCorsPolicy +

Cross-Origin Resource Sharing policy (CORS). Refer to +CORS +for further details about cross origin resource sharing.

+ +
appendHeadersmap<string, string> +

Use of append_headers is deprecated. Use the headers +field instead.

+ +
removeResponseHeadersstring[] +

Use of remove_response_header is deprecated. Use the headers +field instead.

+ +
appendResponseHeadersmap<string, string> +

Use of append_response_headers is deprecated. Use the headers +field instead.

+ +
removeRequestHeadersstring[] +

Use of remove_request_headers is deprecated. Use the headers +field instead.

+ +
appendRequestHeadersmap<string, string> +

Use of append_request_headers is deprecated. Use the headers +field instead.

+ +
headersHeaders +

Header manipulation rules

+ +
+
+

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”.

+ +
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
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationDestination +

REQUIRED. Destination uniquely identifies the instances of a service +to which the request/connection should be forwarded to.

+ +
weightint32 +

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 one destination in a rule, the weight value is assumed to +be 100.

+ +
removeResponseHeadersstring[] +

Use of remove_response_header is deprecated. Use the headers +field instead.

+ +
appendResponseHeadersmap<string, string> +

Use of append_response_headers is deprecated. Use the headers +field instead.

+ +
removeRequestHeadersstring[] +

Use of remove_request_headers is deprecated. Use the headers +field instead.

+ +
appendRequestHeadersmap<string, string> +

Use of append_request_headers is deprecated. Use the headers +field instead.

+ +
headersHeaders +

Header manipulation rules

+ +
+
+

Headers

+
+

Header manipulation rules

+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
requestHeaders.HeaderOperations +

Header manipulation rules to apply before forwarding a request +to the destination service

+ +
responseHeaders.HeaderOperations +

Header manipulation rules to apply before returning a response +to the caller

+ +
+
+

Headers.HeaderOperations

+
+

HeaderOperations Describes the header manipulations to apply

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
setmap<string, string> +

Overwrite the headers specified by key with the given values

+ +
addmap<string, string> +

Append the given values to the headers specified by keys +(will create a comma-separated list of values)

+ +
removestring[] +

Remove a the specified headers

+ +
+
+

L4MatchAttributes

+
+

L4 connection match attributes. Note that L4 connection matching support +is incomplete.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationSubnetsstring[] +

IPv4 or IPv6 ip addresses of destination with optional subnet. E.g., +a.b.c.d/xx form or just a.b.c.d.

+ +
portuint32 +

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.

+ +
sourceLabelsmap<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 at the top, it should include the reserved gateway +mesh in order for this field to be applicable.

+ +
gatewaysstring[] +

Names of gateways where the rule should be applied to. Gateway names +at the top of the VirtualService (if any) are overridden. The gateway +match is independent of sourceLabels.

+ +
+
+

Percent

+
+

Percent specifies a percentage in the range of [0.0, 100.0].

+ + + + + + + + + + + + + + + + +
FieldTypeDescription
valuedouble +
+
+

PortSelector

+
+

PortSelector specifies the number of a port to be used for +matching or selection for final routing.

+ + + + + + + + + + + + + + + + +
FieldTypeDescription
numberuint32 (oneof) +

Valid port number

+ +
+
+

RouteDestination

+
+

L4 routing rule weighted destination.

+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
destinationDestination +

REQUIRED. Destination uniquely identifies the instances of a service +to which the request/connection should be forwarded to.

+ +
weightint32 +

REQUIRED. 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.

+ +
+
+

StringMatch

+
+

Describes how to match a given string in HTTP headers. Match is +case-sensitive.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
exactstring (oneof) +

exact string match

+ +
prefixstring (oneof) +

prefix-based match

+ +
regexstring (oneof) +

ECMAscript style regex-based match

+ +
+
+

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.

+ +
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
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
matchL4MatchAttributes[] +

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.

+ +
routeRouteDestination[] +

The destination to which the connection should be forwarded to.

+ +
+
+

TLSMatchAttributes

+
+

TLS connection match attributes.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
sniHostsstring[] +

REQUIRED. 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.

+ +
destinationSubnetsstring[] +

IPv4 or IPv6 ip addresses of destination with optional subnet. E.g., +a.b.c.d/xx form or just a.b.c.d.

+ +
portuint32 +

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.

+ +
sourceLabelsmap<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 at the top, it should include the reserved gateway +mesh in order for this field to be applicable.

+ +
gatewaysstring[] +

Names of gateways where the rule should be applied to. Gateway names +at the top of the VirtualService (if any) are overridden. The gateway +match is independent of sourceLabels.

+ +
+
+

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.

+ +
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
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
matchTLSMatchAttributes[] +

REQUIRED. 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.

+ +
routeRouteDestination[] +

The destination to which the connection should be forwarded to.

+ +
+
+

VirtualService

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
hostsstring[] +

REQUIRED. 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 host name can be defined by only one VirtualService. A single +VirtualService can be used to describe traffic properties for multiple +HTTP and TCP ports.

+ +

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.

+ +
gatewaysstring[] +

The names of gateways and sidecars that should apply these routes. 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.

+ +
httpHTTPRoute[] +

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.

+ +
tlsTLSRoute[] +

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.

+ +
tcpTCPRoute[] +

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.

+ +
exportTostring[] +

A list of namespaces to which this virtual service is exported. Exporting a +virtual service allows it to 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.

+ +
+
diff --git a/networking/v1alpha3/virtual_service.proto b/networking/v1alpha3/virtual_service.proto index f9465aeaaa6..823adc02bac 100644 --- a/networking/v1alpha3/virtual_service.proto +++ b/networking/v1alpha3/virtual_service.proto @@ -17,11 +17,9 @@ syntax = "proto3"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; -// $title: Traffic Routing -// $description: Configuration affecting traffic routing. -// $location: https://istio.io/docs/reference/config/istio.networking.v1alpha3.html -// $aliases: -// $ - /docs/reference/config/istio.routing.v1alpha1/ +// $title: Virtual Service +// $description: Configuration affecting label/content routing, sni routing, etc. +// $location: https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service.html // Configuration affecting traffic routing. Here are a few terms useful to define // in the context of traffic routing. @@ -51,10 +49,7 @@ import "google/protobuf/wrappers.proto"; // actual choice of the version is determined by the proxy/sidecar, enabling the // application code to decouple itself from the evolution of dependent // services. -package istio.networking.v1alpha3; - -option go_package = "istio.io/api/networking/v1alpha3"; - +// // 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 @@ -115,6 +110,10 @@ option go_package = "istio.io/api/networking/v1alpha3"; // version: v2 // ``` // +package istio.networking.v1alpha3; + +option go_package = "istio.io/api/networking/v1alpha3"; + message VirtualService { // REQUIRED. The destination hosts to which traffic is being sent. Could // be a DNS name with wildcard prefix or an IP address. Depending on the @@ -197,7 +196,7 @@ message VirtualService { // 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](#ServiceEntry) resource. +// [ServiceEntry](/docs/reference/config/networking/v1alpha3/service-entry/#ServiceEntry) resource. // // *Note for Kubernetes users*: When short names are used (e.g. "reviews" // instead of "reviews.default.svc.cluster.local"), Istio will interpret @@ -322,7 +321,7 @@ message Destination { // REQUIRED. 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](#ServiceEntry). Traffic forwarded to + // declared by [ServiceEntry](/docs/reference/config/networking/v1alpha3/service-entry/#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"