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
+
+
+
+
+ConnectionPoolSettings.HTTPSettings
+
+Settings applicable to HTTP1.1/HTTP2/GRPC connections.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+http1MaxPendingRequests |
+int32 |
+
+ Maximum number of pending HTTP requests to a destination. Default 1024.
+
+ |
+
+
+http2MaxRequests |
+int32 |
+
+ Maximum number of requests to a backend. Default 1024.
+
+ |
+
+
+maxRequestsPerConnection |
+int32 |
+
+ Maximum number of requests per connection to a backend. Setting this
+parameter to 1 disables keep alive.
+
+ |
+
+
+maxRetries |
+int32 |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+maxConnections |
+int32 |
+
+ Maximum number of HTTP1 /TCP connections to a destination host.
+
+ |
+
+
+connectTimeout |
+google.protobuf.Duration |
+
+ TCP connection timeout.
+
+ |
+
+
+tcpKeepalive |
+ConnectionPoolSettings.TCPSettings.TcpKeepalive |
+
+ If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.
+
+ |
+
+
+
+
+ConnectionPoolSettings.TCPSettings.TcpKeepalive
+
+TCP keepalive.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+probes |
+uint32 |
+
+ 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.)
+
+ |
+
+
+time |
+google.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.)
+
+ |
+
+
+interval |
+google.protobuf.Duration |
+
+ The time duration between keep-alive probes.
+Default is to use the OS level configuration
+(unless overridden, Linux defaults to 75s.)
+
+ |
+
+
+
+
+DestinationRule
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+host |
+string |
+
+ 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.
+
+ |
+
+
+trafficPolicy |
+TrafficPolicy |
+
+ Traffic policies to apply (load balancing policy, connection pool
+sizes, outlier detection).
+
+ |
+
+
+subsets |
+Subset[] |
+
+ One or more named sets that represent individual versions of a
+service. Traffic policies can be overridden at subset level.
+
+ |
+
+
+exportTo |
+string[] |
+
+ 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
+
+
+
+
+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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+
+httpCookie |
+LoadBalancerSettings.ConsistentHashLB.HTTPCookie (oneof) |
+
+ Hash based on HTTP cookie.
+
+ |
+
+
+useSourceIp |
+bool (oneof) |
+
+ Hash based on the source IP address.
+
+ |
+
+
+minimumRingSize |
+uint64 |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+name |
+string |
+
+ REQUIRED. Name of the cookie.
+
+ |
+
+
+path |
+string |
+
+ Path to set for the cookie.
+
+ |
+
+
+ttl |
+google.protobuf.Duration |
+
+ REQUIRED. Lifetime of the cookie.
+
+ |
+
+
+
+
+LoadBalancerSettings.SimpleLB
+
+Standard load balancing algorithms that require no tuning.
+
+
+
+
+| Name |
+Description |
+
+
+
+
+ROUND_ROBIN |
+
+ Round Robin policy. Default
+
+ |
+
+
+LEAST_CONN |
+
+ The least request load balancer uses an O(1) algorithm which selects
+two random healthy hosts and picks the host which has fewer active
+requests.
+
+ |
+
+
+RANDOM |
+
+ The random load balancer selects a random healthy host. The random
+load balancer generally performs better than round robin if no health
+checking policy is configured.
+
+ |
+
+
+PASSTHROUGH |
+
+ This option will forward the connection to the original IP address
+requested by the caller without doing any form of load
+balancing. This option must be used with care. It is meant for
+advanced use cases. Refer to Original Destination load balancer in
+Envoy for further details.
+
+ |
+
+
+
+
+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
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+consecutiveErrors |
+int32 |
+
+ 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.
+
+ |
+
+
+interval |
+google.protobuf.Duration |
+
+ Time interval between ejection sweep analysis. format:
+1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.
+
+ |
+
+
+baseEjectionTime |
+google.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.
+
+ |
+
+
+maxEjectionPercent |
+int32 |
+
+ Maximum % of hosts in the load balancing pool for the upstream
+service that can be ejected. Defaults to 10%.
+
+ |
+
+
+minHealthPercent |
+int32 |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+name |
+string |
+
+ REQUIRED. Name of the subset. The service name and the subset name can
+be used for traffic splitting in a route rule.
+
+ |
+
+
+labels |
+map<string, string> |
+
+ Labels apply a filter over the endpoints of a service in the
+service registry. See route rules for examples of usage.
+
+ |
+
+
+trafficPolicy |
+TrafficPolicy |
+
+ 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
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+mode |
+TLSSettings.TLSmode |
+
+ REQUIRED: Indicates whether connections to this port should be secured
+using TLS. The value of this field determines how TLS is enforced.
+
+ |
+
+
+clientCertificate |
+string |
+
+ 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.
+
+ |
+
+
+privateKey |
+string |
+
+ REQUIRED if mode is MUTUAL. The path to the file holding the
+client’s private key.
+Should be empty if mode is ISTIO_MUTUAL.
+
+ |
+
+
+caCertificates |
+string |
+
+ 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.
+
+ |
+
+
+subjectAltNames |
+string[] |
+
+ 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.
+
+ |
+
+
+sni |
+string |
+
+ SNI string to present to the server during TLS handshake.
+
+ |
+
+
+
+
+TLSSettings.TLSmode
+
+TLS connection mode
+
+
+
+
+| Name |
+Description |
+
+
+
+
+DISABLE |
+
+ Do not setup a TLS connection to the upstream endpoint.
+
+ |
+
+
+SIMPLE |
+
+ Originate a TLS connection to the upstream endpoint.
+
+ |
+
+
+MUTUAL |
+
+ Secure connections to the upstream using mutual TLS by presenting
+client certificates for authentication.
+
+ |
+
+
+ISTIO_MUTUAL |
+
+ Secure connections to the upstream using mutual TLS by presenting
+client certificates for authentication.
+Compared to Mutual mode, this mode uses certificates generated
+automatically by Istio for mTLS authentication. When this mode is
+used, all other fields in TLSSettings should be empty.
+
+ |
+
+
+
+
+TrafficPolicy
+
+Traffic policies to apply for a specific destination, across all
+destination ports. See DestinationRule for examples.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+loadBalancer |
+LoadBalancerSettings |
+
+ Settings controlling the load balancer algorithms.
+
+ |
+
+
+connectionPool |
+ConnectionPoolSettings |
+
+ Settings controlling the volume of connections to an upstream service
+
+ |
+
+
+outlierDetection |
+OutlierDetection |
+
+ Settings controlling eviction of unhealthy hosts from the load balancing pool
+
+ |
+
+
+tls |
+TLSSettings |
+
+ TLS related settings for connections to the upstream service.
+
+ |
+
+
+portLevelSettings |
+TrafficPolicy.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
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+port |
+PortSelector |
+
+ 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 -.
+
+ |
+
+
+loadBalancer |
+LoadBalancerSettings |
+
+ Settings controlling the load balancer algorithms.
+
+ |
+
+
+connectionPool |
+ConnectionPoolSettings |
+
+ Settings controlling the volume of connections to an upstream service
+
+ |
+
+
+outlierDetection |
+OutlierDetection |
+
+ Settings controlling eviction of unhealthy hosts from the load balancing pool
+
+ |
+
+
+tls |
+TLSSettings |
+
+ 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
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+workloadLabels |
+map<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.
+
+ |
+
+
+filters |
+EnvoyFilter.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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+listenerMatch |
+EnvoyFilter.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.
+
+ |
+
+
+insertPosition |
+EnvoyFilter.InsertPosition |
+
+ Insert position in the filter chain. Defaults to FIRST
+
+ |
+
+
+filterType |
+EnvoyFilter.Filter.FilterType |
+
+ REQUIRED: The type of filter to instantiate.
+
+ |
+
+
+filterName |
+string |
+
+ REQUIRED: The name of the filter to instantiate. The name must match a supported
+filter compiled into Envoy.
+
+ |
+
+
+filterConfig |
+google.protobuf.Struct |
+
+ REQUIRED: Filter specific configuration which depends on the filter being
+instantiated.
+
+ |
+
+
+
+
+EnvoyFilter.Filter.FilterType
+
+
+
+
+| Name |
+Description |
+
+
+
+
+INVALID |
+
+ placeholder
+
+ |
+
+
+HTTP |
+
+ Http filter
+
+ |
+
+
+NETWORK |
+
+ Network filter
+
+ |
+
+
+
+
+EnvoyFilter.InsertPosition
+
+Indicates the relative index in the filter chain where the filter should be inserted.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+index |
+EnvoyFilter.InsertPosition.Index |
+
+ Position of this filter in the filter chain.
+
+ |
+
+
+relativeTo |
+string |
+
+ 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.
+
+
+
+
+| Name |
+Description |
+
+
+
+
+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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+portNumber |
+uint32 |
+
+ 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.
+
+ |
+
+
+portNamePrefix |
+string |
+
+ 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.
+
+ |
+
+
+listenerType |
+EnvoyFilter.ListenerMatch.ListenerType |
+
+ Inbound vs outbound sidecar listener or gateway listener. If not specified,
+matches all listeners.
+
+ |
+
+
+listenerProtocol |
+EnvoyFilter.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).
+
+ |
+
+
+address |
+string[] |
+
+ 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
+
+
+
+
+| Name |
+Description |
+
+
+
+
+ALL |
+
+ All protocols
+
+ |
+
+
+HTTP |
+
+ HTTP or HTTPS (with termination) / HTTP2/gRPC
+
+ |
+
+
+TCP |
+
+ Any non-HTTP listener
+
+ |
+
+
+
+
+EnvoyFilter.ListenerMatch.ListenerType
+
+
+
+
+| Name |
+Description |
+
+
+
+
+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
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+servers |
+Server[] |
+
+ REQUIRED: A list of server specifications.
+
+ |
+
+
+selector |
+map<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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+number |
+uint32 |
+
+ REQUIRED: A valid non-negative integer port number.
+
+ |
+
+
+protocol |
+string |
+
+ 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.
+
+ |
+
+
+name |
+string |
+
+ 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
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+port |
+Port |
+
+ 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.
+
+ |
+
+
+hosts |
+string[] |
+
+ 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.
+
+ |
+
+
+tls |
+Server.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.
+
+ |
+
+
+defaultEndpoint |
+string |
+
+ 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
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+httpsRedirect |
+bool |
+
+ If set to true, the load balancer will send a 301 redirect for all
+http connections, asking the clients to use HTTPS.
+
+ |
+
+
+mode |
+Server.TLSOptions.TLSmode |
+
+ Optional: Indicates whether connections to this port should be
+secured using TLS. The value of this field determines how TLS is
+enforced.
+
+ |
+
+
+serverCertificate |
+string |
+
+ REQUIRED if mode is SIMPLE or MUTUAL. The path to the file
+holding the server-side TLS certificate to use.
+
+ |
+
+
+privateKey |
+string |
+
+ REQUIRED if mode is SIMPLE or MUTUAL. The path to the file
+holding the server’s private key.
+
+ |
+
+
+caCertificates |
+string |
+
+ REQUIRED if mode is MUTUAL. The path to a file containing
+certificate authority certificates to use in verifying a presented
+client side certificate.
+
+ |
+
+
+credentialName |
+string |
+
+ 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).
+
+ |
+
+
+subjectAltNames |
+string[] |
+
+ A list of alternate names to verify the subject identity in the
+certificate presented by the client.
+
+ |
+
+
+minProtocolVersion |
+Server.TLSOptions.TLSProtocol |
+
+ Optional: Minimum TLS protocol version.
+
+ |
+
+
+maxProtocolVersion |
+Server.TLSOptions.TLSProtocol |
+
+ Optional: Maximum TLS protocol version.
+
+ |
+
+
+cipherSuites |
+string[] |
+
+ 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.
+
+
+
+
+| Name |
+Description |
+
+
+
+
+TLS_AUTO |
+
+ Automatically choose the optimal TLS version.
+
+ |
+
+
+TLSV1_0 |
+
+ TLS version 1.0
+
+ |
+
+
+TLSV1_1 |
+
+ TLS version 1.1
+
+ |
+
+
+TLSV1_2 |
+
+ TLS version 1.2
+
+ |
+
+
+TLSV1_3 |
+
+ TLS version 1.3
+
+ |
+
+
+
+
+Server.TLSOptions.TLSmode
+
+TLS modes enforced by the proxy
+
+
+
+
+| Name |
+Description |
+
+
+
+
+PASSTHROUGH |
+
+ The SNI string presented by the client will be used as the match
+criterion in a VirtualService TLS route to determine the
+destination service from the service registry.
+
+ |
+
+
+SIMPLE |
+
+ Secure connections with standard TLS semantics.
+
+ |
+
+
+MUTUAL |
+
+ Secure connections to the upstream using mutual TLS by presenting
+client certificates for authentication.
+
+ |
+
+
+AUTO_PASSTHROUGH |
+
+ Similar to the passthrough mode, except servers with this TLS mode
+do not require an associated VirtualService to map from the SNI
+value to service in the registry. The destination details such as
+the service/subset/port are encoded in the SNI value. The proxy
+will forward to the upstream (Envoy) cluster (a group of
+endpoints) specified by the SNI value. This server is typically
+used to provide connectivity between services in disparate L3
+networks that otherwise do not have direct connectivity between
+their respective endpoints. Use of this mode assumes that both the
+source and the destination are using Istio mTLS to secure traffic.
+
+ |
+
+
+
+
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.
-
-
-
-
-| Name |
-Description |
-
-
-
-
-DEFAULT |
-
- The default capture mode defined by the environment
-
- |
-
-
-IPTABLES |
-
- Capture traffic using IPtables redirection
-
- |
-
-
-NONE |
-
- No traffic capture. When used in egress listener, the application is
-expected to explicitly communicate with the listener port/unix
-domain socket. When used in ingress listener, care needs to be taken
-to ensure that the listener port is not in use by other processes on
-the host.
-
- |
-
-
-
-
-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
-
-
-
-
-ConnectionPoolSettings.HTTPSettings
-
-Settings applicable to HTTP1.1/HTTP2/GRPC connections.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-http1MaxPendingRequests |
-int32 |
-
- Maximum number of pending HTTP requests to a destination. Default 1024.
-
- |
-
-
-http2MaxRequests |
-int32 |
-
- Maximum number of requests to a backend. Default 1024.
-
- |
-
-
-maxRequestsPerConnection |
-int32 |
-
- Maximum number of requests per connection to a backend. Setting this
-parameter to 1 disables keep alive.
-
- |
-
-
-maxRetries |
-int32 |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-maxConnections |
-int32 |
-
- Maximum number of HTTP1 /TCP connections to a destination host.
-
- |
-
-
-connectTimeout |
-google.protobuf.Duration |
-
- TCP connection timeout.
-
- |
-
-
-tcpKeepalive |
-ConnectionPoolSettings.TCPSettings.TcpKeepalive |
-
- If set then set SO_KEEPALIVE on the socket to enable TCP Keepalives.
-
- |
-
-
-
-
-ConnectionPoolSettings.TCPSettings.TcpKeepalive
-
-TCP keepalive.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-probes |
-uint32 |
-
- 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.)
-
- |
-
-
-time |
-google.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.)
-
- |
-
-
-interval |
-google.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"
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-allowOrigin |
-string[] |
-
- 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.
-
- |
-
-
-allowMethods |
-string[] |
-
- List of HTTP methods allowed to access the resource. The content will
-be serialized into the Access-Control-Allow-Methods header.
-
- |
-
-
-
-
-maxAge |
-google.protobuf.Duration |
-
- Specifies how long the results of a preflight request can be
-cached. Translates to the Access-Control-Max-Age header.
-
- |
-
-
-allowCredentials |
-google.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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-host |
-string |
-
- 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.
-
- |
-
-
-subset |
-string |
-
- The name of a subset within the service. Applicable only to services
-within the mesh. The subset must be defined in a corresponding
-DestinationRule.
-
- |
-
-
-port |
-PortSelector |
-
- 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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-host |
-string |
-
- 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.
-
- |
-
-
-trafficPolicy |
-TrafficPolicy |
-
- Traffic policies to apply (load balancing policy, connection pool
-sizes, outlier detection).
-
- |
-
-
-subsets |
-Subset[] |
-
- One or more named sets that represent individual versions of a
-service. Traffic policies can be overridden at subset level.
-
- |
-
-
-exportTo |
-string[] |
-
- 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 ...
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-workloadLabels |
-map<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.
-
- |
-
-
-filters |
-EnvoyFilter.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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-listenerMatch |
-EnvoyFilter.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.
-
- |
-
-
-insertPosition |
-EnvoyFilter.InsertPosition |
-
- Insert position in the filter chain. Defaults to FIRST
-
- |
-
-
-filterType |
-EnvoyFilter.Filter.FilterType |
-
- REQUIRED: The type of filter to instantiate.
-
- |
-
-
-filterName |
-string |
-
- REQUIRED: The name of the filter to instantiate. The name must match a supported
-filter compiled into Envoy.
-
- |
-
-
-filterConfig |
-google.protobuf.Struct |
-
- REQUIRED: Filter specific configuration which depends on the filter being
-instantiated.
-
- |
-
-
-
-
-EnvoyFilter.Filter.FilterType
-
-
-
-
-| Name |
-Description |
-
-
-
-
-INVALID |
-
- placeholder
-
- |
-
-
-HTTP |
-
- Http filter
-
- |
-
-
-NETWORK |
-
- Network filter
-
- |
-
-
-
-
-EnvoyFilter.InsertPosition
-
-Indicates the relative index in the filter chain where the filter should be inserted.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-index |
-EnvoyFilter.InsertPosition.Index |
-
- Position of this filter in the filter chain.
-
- |
-
-
-relativeTo |
-string |
-
- 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.
-
-
-
-
-| Name |
-Description |
-
-
-
-
-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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-portNumber |
-uint32 |
-
- 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.
-
- |
-
-
-portNamePrefix |
-string |
-
- 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.
-
- |
-
-
-listenerType |
-EnvoyFilter.ListenerMatch.ListenerType |
-
- Inbound vs outbound sidecar listener or gateway listener. If not specified,
-matches all listeners.
-
- |
-
-
-listenerProtocol |
-EnvoyFilter.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).
-
- |
-
-
-address |
-string[] |
-
- 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
-
-
-
-
-| Name |
-Description |
-
-
-
-
-ALL |
-
- All protocols
-
- |
-
-
-HTTP |
-
- HTTP or HTTPS (with termination) / HTTP2/gRPC
-
- |
-
-
-TCP |
-
- Any non-HTTP listener
-
- |
-
-
-
-
-EnvoyFilter.ListenerMatch.ListenerType
-
-
-
-
-| Name |
-Description |
-
-
-
-
-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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-servers |
-Server[] |
-
- REQUIRED: A list of server specifications.
-
- |
-
-
-selector |
-map<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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-delay |
-HTTPFaultInjection.Delay |
-
- Delay requests before forwarding, emulating various failures such as
-network issues, overloaded upstream service, etc.
-
- |
-
-
-abort |
-HTTPFaultInjection.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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-percent |
-int32 |
-
- 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.
-
- |
-
-
-httpStatus |
-int32 (oneof) |
-
- REQUIRED. HTTP status code to use to abort the Http request.
-
- |
-
-
-percentage |
-Percent |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-percent |
-int32 |
-
- Percentage of requests on which the delay will be injected (0-100).
-Use of integer percent value is deprecated. Use the double percentage
-field instead.
-
- |
-
-
-fixedDelay |
-google.protobuf.Duration (oneof) |
-
- REQUIRED. Add a fixed delay before forwarding the request. Format:
-1h/1m/1s/1ms. MUST be >=1ms.
-
- |
-
-
-percentage |
-Percent |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-uri |
-StringMatch |
-
- 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
-
- |
-
-
-scheme |
-StringMatch |
-
- 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
-
- |
-
-
-method |
-StringMatch |
-
- 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
-
- |
-
-
-authority |
-StringMatch |
-
- 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
-
- |
-
-
-
-port |
-uint32 |
-
- Specifies the ports on the host that is being addressed. Many services
-only expose a single port or label ports with the protocols they support,
-in these cases it is not required to explicitly select the port.
-
- |
-
-
-sourceLabels |
-map<string, string> |
-
- One or more labels that constrain the applicability of a rule to
-workloads with the given labels. If the VirtualService has a list of
-gateways specified at the top, it should include the reserved gateway
-mesh in order for this field to be applicable.
-
- |
-
-
-gateways |
-string[] |
-
- 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
- ...
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-uri |
-string |
-
- 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.
-
- |
-
-
-authority |
-string |
-
- 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
-
-
-
-
-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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-uri |
-string |
-
- 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.
-
- |
-
-
-authority |
-string |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-match |
-HTTPMatchRequest[] |
-
- 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.
-
- |
-
-
-route |
-HTTPRouteDestination[] |
-
- 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.
-
- |
-
-
-redirect |
-HTTPRedirect |
-
- 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.
-
- |
-
-
-rewrite |
-HTTPRewrite |
-
- Rewrite HTTP URIs and Authority headers. Rewrite cannot be used with
-Redirect primitive. Rewrite will be performed before forwarding.
-
- |
-
-
-timeout |
-google.protobuf.Duration |
-
- Timeout for HTTP requests.
-
- |
-
-
-retries |
-HTTPRetry |
-
- Retry policy for HTTP requests.
-
- |
-
-
-fault |
-HTTPFaultInjection |
-
- Fault injection policy to apply on HTTP traffic at the client side.
-Note that timeouts or retries will not be enabled when faults are
-enabled on the client side.
-
- |
-
-
-mirror |
-Destination |
-
- 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.
-
- |
-
-
-corsPolicy |
-CorsPolicy |
-
- Cross-Origin Resource Sharing policy (CORS). Refer to
-CORS
-for further details about cross origin resource sharing.
-
- |
-
-
-
-
-
-
-
-
-
-
-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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-destination |
-Destination |
-
- REQUIRED. Destination uniquely identifies the instances of a service
-to which the request/connection should be forwarded to.
-
- |
-
-
-weight |
-int32 |
-
- 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.
-
- |
-
-
-
-
-
-
-
-
-
-
-
-Header manipulation rules
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-
-
-
-
-
-
-HeaderOperations Describes the header manipulations to apply
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-
-
-
-
-
-IstioEgressListener
-
-IstioEgressListener specifies the properties of an outbound traffic
-listener on the sidecar proxy attached to a workload.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-port |
-Port |
-
- 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.
-
- |
-
-
-bind |
-string |
-
- 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.
-
- |
-
-
-captureMode |
-CaptureMode |
-
- 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.
-
- |
-
-
-hosts |
-string[] |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-port |
-Port |
-
- REQUIRED. The port associated with the listener. If using
-unix domain socket, use 0 as the port number, with a valid
-protocol.
-
- |
-
-
-bind |
-string |
-
- 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.
-
- |
-
-
-captureMode |
-CaptureMode |
-
- 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.
-
- |
-
-
-defaultEndpoint |
-string |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-destinationSubnets |
-string[] |
-
- IPv4 or IPv6 ip addresses of destination with optional subnet. E.g.,
-a.b.c.d/xx form or just a.b.c.d.
-
- |
-
-
-port |
-uint32 |
-
- Specifies the port on the host that is being addressed. Many services
-only expose a single port or label ports with the protocols they support,
-in these cases it is not required to explicitly select the port.
-
- |
-
-
-sourceLabels |
-map<string, string> |
-
- One or more labels that constrain the applicability of a rule to
-workloads with the given labels. If the VirtualService has a list of
-gateways specified at the top, it should include the reserved gateway
-mesh in order for this field to be applicable.
-
- |
-
-
-gateways |
-string[] |
-
- 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
-
-
-
-
-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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-
-httpCookie |
-LoadBalancerSettings.ConsistentHashLB.HTTPCookie (oneof) |
-
- Hash based on HTTP cookie.
-
- |
-
-
-useSourceIp |
-bool (oneof) |
-
- Hash based on the source IP address.
-
- |
-
-
-minimumRingSize |
-uint64 |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-name |
-string |
-
- REQUIRED. Name of the cookie.
-
- |
-
-
-path |
-string |
-
- Path to set for the cookie.
-
- |
-
-
-ttl |
-google.protobuf.Duration |
-
- REQUIRED. Lifetime of the cookie.
-
- |
-
-
-
-
-LoadBalancerSettings.SimpleLB
-
-Standard load balancing algorithms that require no tuning.
-
-
-
-
-| Name |
-Description |
-
-
-
-
-ROUND_ROBIN |
-
- Round Robin policy. Default
-
- |
-
-
-LEAST_CONN |
-
- The least request load balancer uses an O(1) algorithm which selects
-two random healthy hosts and picks the host which has fewer active
-requests.
-
- |
-
-
-RANDOM |
-
- The random load balancer selects a random healthy host. The random
-load balancer generally performs better than round robin if no health
-checking policy is configured.
-
- |
-
-
-PASSTHROUGH |
-
- This option will forward the connection to the original IP address
-requested by the caller without doing any form of load
-balancing. This option must be used with care. It is meant for
-advanced use cases. Refer to Original Destination load balancer in
-Envoy for further details.
-
- |
-
-
-
-
-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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-consecutiveErrors |
-int32 |
-
- 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.
-
- |
-
-
-interval |
-google.protobuf.Duration |
-
- Time interval between ejection sweep analysis. format:
-1h/1m/1s/1ms. MUST BE >=1ms. Default is 10s.
-
- |
-
-
-baseEjectionTime |
-google.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.
-
- |
-
-
-maxEjectionPercent |
-int32 |
-
- Maximum % of hosts in the load balancing pool for the upstream
-service that can be ejected. Defaults to 10%.
-
- |
-
-
-minHealthPercent |
-int32 |
-
- 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].
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-value |
-double |
-
- |
-
-
-
-
-Port
-
-Port describes the properties of a specific port of a service.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-number |
-uint32 |
-
- REQUIRED: A valid non-negative integer port number.
-
- |
-
-
-protocol |
-string |
-
- 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.
-
- |
-
-
-name |
-string |
-
- Label assigned to the port.
-
- |
-
-
-
-
-PortSelector
-
-PortSelector specifies the number of a port to be used for
-matching or selection for final routing.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-number |
-uint32 (oneof) |
-
- Valid port number
-
- |
-
-
-
-
-RouteDestination
-
-L4 routing rule weighted destination.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-destination |
-Destination |
-
- REQUIRED. Destination uniquely identifies the instances of a service
-to which the request/connection should be forwarded to.
-
- |
-
-
-weight |
-int32 |
-
- 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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-port |
-Port |
-
- 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.
-
- |
-
-
-hosts |
-string[] |
-
- 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.
-
- |
-
-
-tls |
-Server.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.
-
- |
-
-
-defaultEndpoint |
-string |
-
- 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
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-httpsRedirect |
-bool |
-
- If set to true, the load balancer will send a 301 redirect for all
-http connections, asking the clients to use HTTPS.
-
- |
-
-
-mode |
-Server.TLSOptions.TLSmode |
-
- Optional: Indicates whether connections to this port should be
-secured using TLS. The value of this field determines how TLS is
-enforced.
-
- |
-
-
-serverCertificate |
-string |
-
- REQUIRED if mode is SIMPLE or MUTUAL. The path to the file
-holding the server-side TLS certificate to use.
-
- |
-
-
-privateKey |
-string |
-
- REQUIRED if mode is SIMPLE or MUTUAL. The path to the file
-holding the server’s private key.
-
- |
-
-
-caCertificates |
-string |
-
- REQUIRED if mode is MUTUAL. The path to a file containing
-certificate authority certificates to use in verifying a presented
-client side certificate.
-
- |
-
-
-credentialName |
-string |
-
- 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).
-
- |
-
-
-subjectAltNames |
-string[] |
-
- A list of alternate names to verify the subject identity in the
-certificate presented by the client.
-
- |
-
-
-minProtocolVersion |
-Server.TLSOptions.TLSProtocol |
-
- Optional: Minimum TLS protocol version.
-
- |
-
-
-maxProtocolVersion |
-Server.TLSOptions.TLSProtocol |
-
- Optional: Maximum TLS protocol version.
-
- |
-
-
-cipherSuites |
-string[] |
-
- 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.
-
-
-
-
-| Name |
-Description |
-
-
-
-
-TLS_AUTO |
-
- Automatically choose the optimal TLS version.
-
- |
-
-
-TLSV1_0 |
-
- TLS version 1.0
-
- |
-
-
-TLSV1_1 |
-
- TLS version 1.1
-
- |
-
-
-TLSV1_2 |
-
- TLS version 1.2
-
- |
-
-
-TLSV1_3 |
-
- TLS version 1.3
-
- |
-
-
-
-
-Server.TLSOptions.TLSmode
-
-TLS modes enforced by the proxy
-
-
-
-
-| Name |
-Description |
-
-
-
-
-PASSTHROUGH |
-
- The SNI string presented by the client will be used as the match
-criterion in a VirtualService TLS route to determine the
-destination service from the service registry.
-
- |
-
-
-SIMPLE |
-
- Secure connections with standard TLS semantics.
-
- |
-
-
-MUTUAL |
-
- Secure connections to the upstream using mutual TLS by presenting
-client certificates for authentication.
-
- |
-
-
-AUTO_PASSTHROUGH |
-
- Similar to the passthrough mode, except servers with this TLS mode
-do not require an associated VirtualService to map from the SNI
-value to service in the registry. The destination details such as
-the service/subset/port are encoded in the SNI value. The proxy
-will forward to the upstream (Envoy) cluster (a group of
-endpoints) specified by the SNI value. This server is typically
-used to provide connectivity between services in disparate L3
-networks that otherwise do not have direct connectivity between
-their respective endpoints. Use of this mode assumes that both the
-source and the destination are using Istio mTLS to secure traffic.
-
- |
-
-
-
-
-ServiceEntry
-
-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"
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-hosts |
-string[] |
-
- 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.
-
- |
-
-
-addresses |
-string[] |
-
- 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.
-
- |
-
-
-ports |
-Port[] |
-
- REQUIRED. The ports associated with the external service. If the
-Endpoints are unix domain socket addresses, there must be exactly one
-port.
-
- |
-
-
-location |
-ServiceEntry.Location |
-
- Specify whether the service should be considered external to the mesh
-or part of the mesh.
-
- |
-
-
-resolution |
-ServiceEntry.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:).
-
- |
-
-
-endpoints |
-ServiceEntry.Endpoint[] |
-
- One or more endpoints associated with the service.
-
- |
-
-
-exportTo |
-string[] |
-
- 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.
-
- |
-
-
-subjectAltNames |
-string[] |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-address |
-string |
-
- 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.
-
- |
-
-
-ports |
-map<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.
-
- |
-
-
-labels |
-map<string, string> |
-
- One or more labels associated with the endpoint.
-
- |
-
-
-network |
-string |
-
- 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.
-
- |
-
-
-locality |
-string |
-
- 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.
-
- |
-
-
-weight |
-uint32 |
-
- 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.
-
-
-
-
-| Name |
-Description |
-
-
-
-
-MESH_EXTERNAL |
-
- Signifies that the service is external to the mesh. Typically used
-to indicate external services consumed through APIs.
-
- |
-
-
-MESH_INTERNAL |
-
- Signifies that the service is part of the mesh. Typically used to
-indicate services added explicitly as part of expanding the service
-mesh to include unmanaged infrastructure (e.g., VMs added to a
-Kubernetes based service mesh).
-
- |
-
-
-
-
-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.
-
-
-
-
-| Name |
-Description |
-
-
-
-
-NONE |
-
- Assume that incoming connections have already been resolved (to a
-specific destination IP address). Such connections are typically
-routed via the proxy using mechanisms such as IP table REDIRECT/
-eBPF. After performing any routing related transformations, the
-proxy will forward the connection to the IP address to which the
-connection was bound.
-
- |
-
-
-STATIC |
-
- Use the static IP addresses specified in endpoints (see below) as the
-backing instances associated with the service.
-
- |
-
-
-DNS |
-
- Attempt to resolve the IP address by querying the ambient DNS,
-during request processing. If no endpoints are specified, the proxy
-will resolve the DNS address specified in the hosts field, if
-wildcards are not used. If endpoints are specified, the DNS
-addresses specified in the endpoints will be resolved to determine
-the destination IP address. DNS resolution cannot be used with unix
-domain socket endpoints.
-
- |
-
-
-
-
-Sidecar
-
-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/*"
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-workloadSelector |
-WorkloadSelector |
-
- 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.
-
- |
-
-
-ingress |
-IstioIngressListener[] |
-
- 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.).
-
- |
-
-
-egress |
-IstioEgressListener[] |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-exact |
-string (oneof) |
-
- exact string match
-
- |
-
-
-prefix |
-string (oneof) |
-
- prefix-based match
-
- |
-
-
-regex |
-string (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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-name |
-string |
-
- REQUIRED. Name of the subset. The service name and the subset name can
-be used for traffic splitting in a route rule.
-
- |
-
-
-labels |
-map<string, string> |
-
- Labels apply a filter over the endpoints of a service in the
-service registry. See route rules for examples of usage.
-
- |
-
-
-trafficPolicy |
-TrafficPolicy |
-
- 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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-match |
-L4MatchAttributes[] |
-
- 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.
-
- |
-
-
-route |
-RouteDestination[] |
-
- The destination to which the connection should be forwarded to.
-
- |
-
-
-
-
-TLSMatchAttributes
-
-TLS connection match attributes.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-sniHosts |
-string[] |
-
- 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.
-
- |
-
-
-destinationSubnets |
-string[] |
-
- IPv4 or IPv6 ip addresses of destination with optional subnet. E.g.,
-a.b.c.d/xx form or just a.b.c.d.
-
- |
-
-
-port |
-uint32 |
-
- Specifies the port on the host that is being addressed. Many services
-only expose a single port or label ports with the protocols they
-support, in these cases it is not required to explicitly select the
-port.
-
- |
-
-
-sourceLabels |
-map<string, string> |
-
- One or more labels that constrain the applicability of a rule to
-workloads with the given labels. If the VirtualService has a list of
-gateways specified at the top, it should include the reserved gateway
-mesh in order for this field to be applicable.
-
- |
-
-
-gateways |
-string[] |
-
- 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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-match |
-TLSMatchAttributes[] |
-
- 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.
-
- |
-
-
-route |
-RouteDestination[] |
-
- 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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-mode |
-TLSSettings.TLSmode |
-
- REQUIRED: Indicates whether connections to this port should be secured
-using TLS. The value of this field determines how TLS is enforced.
-
- |
-
-
-clientCertificate |
-string |
-
- 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.
-
- |
-
-
-privateKey |
-string |
-
- REQUIRED if mode is MUTUAL. The path to the file holding the
-client’s private key.
-Should be empty if mode is ISTIO_MUTUAL.
-
- |
-
-
-caCertificates |
-string |
-
- 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.
-
- |
-
-
-subjectAltNames |
-string[] |
-
- 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.
-
- |
-
-
-sni |
-string |
-
- SNI string to present to the server during TLS handshake.
-
- |
-
-
-
-
-TLSSettings.TLSmode
-
-TLS connection mode
-
-
-
-
-| Name |
-Description |
-
-
-
-
-DISABLE |
-
- Do not setup a TLS connection to the upstream endpoint.
-
- |
-
-
-SIMPLE |
-
- Originate a TLS connection to the upstream endpoint.
-
- |
-
-
-MUTUAL |
-
- Secure connections to the upstream using mutual TLS by presenting
-client certificates for authentication.
-
- |
-
-
-ISTIO_MUTUAL |
-
- Secure connections to the upstream using mutual TLS by presenting
-client certificates for authentication.
-Compared to Mutual mode, this mode uses certificates generated
-automatically by Istio for mTLS authentication. When this mode is
-used, all other fields in TLSSettings should be empty.
-
- |
-
-
-
-
-TrafficPolicy
-
-Traffic policies to apply for a specific destination, across all
-destination ports. See DestinationRule for examples.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-loadBalancer |
-LoadBalancerSettings |
-
- Settings controlling the load balancer algorithms.
-
- |
-
-
-connectionPool |
-ConnectionPoolSettings |
-
- Settings controlling the volume of connections to an upstream service
-
- |
-
-
-outlierDetection |
-OutlierDetection |
-
- Settings controlling eviction of unhealthy hosts from the load balancing pool
-
- |
-
-
-tls |
-TLSSettings |
-
- TLS related settings for connections to the upstream service.
-
- |
-
-
-portLevelSettings |
-TrafficPolicy.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
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-port |
-PortSelector |
-
- 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 -.
-
- |
-
-
-loadBalancer |
-LoadBalancerSettings |
-
- Settings controlling the load balancer algorithms.
-
- |
-
-
-connectionPool |
-ConnectionPoolSettings |
-
- Settings controlling the volume of connections to an upstream service
-
- |
-
-
-outlierDetection |
-OutlierDetection |
-
- Settings controlling eviction of unhealthy hosts from the load balancing pool
-
- |
-
-
-tls |
-TLSSettings |
-
- 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
-
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-hosts |
-string[] |
-
- 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.
-
- |
-
-
-gateways |
-string[] |
-
- 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.
-
- |
-
-
-http |
-HTTPRoute[] |
-
- 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.
-
- |
-
-
-tls |
-TLSRoute[] |
-
- 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.
-
- |
-
-
-tcp |
-TCPRoute[] |
-
- 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.
-
- |
-
-
-exportTo |
-string[] |
-
- 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.
-
-
-
-
-| Field |
-Type |
-Description |
-
-
-
-
-labels |
-map<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
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+hosts |
+string[] |
+
+ 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.
+
+ |
+
+
+addresses |
+string[] |
+
+ 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.
+
+ |
+
+
+ports |
+Port[] |
+
+ REQUIRED. The ports associated with the external service. If the
+Endpoints are unix domain socket addresses, there must be exactly one
+port.
+
+ |
+
+
+location |
+ServiceEntry.Location |
+
+ Specify whether the service should be considered external to the mesh
+or part of the mesh.
+
+ |
+
+
+resolution |
+ServiceEntry.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:).
+
+ |
+
+
+endpoints |
+ServiceEntry.Endpoint[] |
+
+ One or more endpoints associated with the service.
+
+ |
+
+
+exportTo |
+string[] |
+
+ 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.
+
+ |
+
+
+subjectAltNames |
+string[] |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+address |
+string |
+
+ 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.
+
+ |
+
+
+ports |
+map<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.
+
+ |
+
+
+labels |
+map<string, string> |
+
+ One or more labels associated with the endpoint.
+
+ |
+
+
+network |
+string |
+
+ 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.
+
+ |
+
+
+locality |
+string |
+
+ 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.
+
+ |
+
+
+weight |
+uint32 |
+
+ 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.
+
+
+
+
+| Name |
+Description |
+
+
+
+
+MESH_EXTERNAL |
+
+ Signifies that the service is external to the mesh. Typically used
+to indicate external services consumed through APIs.
+
+ |
+
+
+MESH_INTERNAL |
+
+ Signifies that the service is part of the mesh. Typically used to
+indicate services added explicitly as part of expanding the service
+mesh to include unmanaged infrastructure (e.g., VMs added to a
+Kubernetes based service mesh).
+
+ |
+
+
+
+
+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.
+
+
+
+
+| Name |
+Description |
+
+
+
+
+NONE |
+
+ Assume that incoming connections have already been resolved (to a
+specific destination IP address). Such connections are typically
+routed via the proxy using mechanisms such as IP table REDIRECT/
+eBPF. After performing any routing related transformations, the
+proxy will forward the connection to the IP address to which the
+connection was bound.
+
+ |
+
+
+STATIC |
+
+ Use the static IP addresses specified in endpoints (see below) as the
+backing instances associated with the service.
+
+ |
+
+
+DNS |
+
+ Attempt to resolve the IP address by querying the ambient DNS,
+during request processing. If no endpoints are specified, the proxy
+will resolve the DNS address specified in the hosts field, if
+wildcards are not used. If endpoints are specified, the DNS
+addresses specified in the endpoints will be resolved to determine
+the destination IP address. DNS resolution cannot be used with unix
+domain socket endpoints.
+
+ |
+
+
+
+
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.
+
+
+
+
+| Name |
+Description |
+
+
+
+
+DEFAULT |
+
+ The default capture mode defined by the environment
+
+ |
+
+
+IPTABLES |
+
+ Capture traffic using IPtables redirection
+
+ |
+
+
+NONE |
+
+ No traffic capture. When used in egress listener, the application is
+expected to explicitly communicate with the listener port/unix
+domain socket. When used in ingress listener, care needs to be taken
+to ensure that the listener port is not in use by other processes on
+the host.
+
+ |
+
+
+
+
+IstioEgressListener
+
+IstioEgressListener specifies the properties of an outbound traffic
+listener on the sidecar proxy attached to a workload.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+port |
+Port |
+
+ 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.
+
+ |
+
+
+bind |
+string |
+
+ 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.
+
+ |
+
+
+captureMode |
+CaptureMode |
+
+ 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.
+
+ |
+
+
+hosts |
+string[] |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+port |
+Port |
+
+ REQUIRED. The port associated with the listener. If using
+unix domain socket, use 0 as the port number, with a valid
+protocol.
+
+ |
+
+
+bind |
+string |
+
+ 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.
+
+ |
+
+
+captureMode |
+CaptureMode |
+
+ 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.
+
+ |
+
+
+defaultEndpoint |
+string |
+
+ 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
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+workloadSelector |
+WorkloadSelector |
+
+ 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.
+
+ |
+
+
+ingress |
+IstioIngressListener[] |
+
+ 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.).
+
+ |
+
+
+egress |
+IstioEgressListener[] |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+labels |
+map<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"
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+allowOrigin |
+string[] |
+
+ 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.
+
+ |
+
+
+allowMethods |
+string[] |
+
+ List of HTTP methods allowed to access the resource. The content will
+be serialized into the Access-Control-Allow-Methods header.
+
+ |
+
+
+
+
+maxAge |
+google.protobuf.Duration |
+
+ Specifies how long the results of a preflight request can be
+cached. Translates to the Access-Control-Max-Age header.
+
+ |
+
+
+allowCredentials |
+google.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
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+host |
+string |
+
+ 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.
+
+ |
+
+
+subset |
+string |
+
+ The name of a subset within the service. Applicable only to services
+within the mesh. The subset must be defined in a corresponding
+DestinationRule.
+
+ |
+
+
+port |
+PortSelector |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+delay |
+HTTPFaultInjection.Delay |
+
+ Delay requests before forwarding, emulating various failures such as
+network issues, overloaded upstream service, etc.
+
+ |
+
+
+abort |
+HTTPFaultInjection.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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+percent |
+int32 |
+
+ 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.
+
+ |
+
+
+httpStatus |
+int32 (oneof) |
+
+ REQUIRED. HTTP status code to use to abort the Http request.
+
+ |
+
+
+percentage |
+Percent |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+percent |
+int32 |
+
+ Percentage of requests on which the delay will be injected (0-100).
+Use of integer percent value is deprecated. Use the double percentage
+field instead.
+
+ |
+
+
+fixedDelay |
+google.protobuf.Duration (oneof) |
+
+ REQUIRED. Add a fixed delay before forwarding the request. Format:
+1h/1m/1s/1ms. MUST be >=1ms.
+
+ |
+
+
+percentage |
+Percent |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+uri |
+StringMatch |
+
+ 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
+
+ |
+
+
+scheme |
+StringMatch |
+
+ 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
+
+ |
+
+
+method |
+StringMatch |
+
+ 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
+
+ |
+
+
+authority |
+StringMatch |
+
+ 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
+
+ |
+
+
+
+port |
+uint32 |
+
+ Specifies the ports on the host that is being addressed. Many services
+only expose a single port or label ports with the protocols they support,
+in these cases it is not required to explicitly select the port.
+
+ |
+
+
+sourceLabels |
+map<string, string> |
+
+ One or more labels that constrain the applicability of a rule to
+workloads with the given labels. If the VirtualService has a list of
+gateways specified at the top, it should include the reserved gateway
+mesh in order for this field to be applicable.
+
+ |
+
+
+gateways |
+string[] |
+
+ 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
+ ...
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+uri |
+string |
+
+ 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.
+
+ |
+
+
+authority |
+string |
+
+ 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
+
+
+
+
+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
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+uri |
+string |
+
+ 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.
+
+ |
+
+
+authority |
+string |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+match |
+HTTPMatchRequest[] |
+
+ 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.
+
+ |
+
+
+route |
+HTTPRouteDestination[] |
+
+ 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.
+
+ |
+
+
+redirect |
+HTTPRedirect |
+
+ 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.
+
+ |
+
+
+rewrite |
+HTTPRewrite |
+
+ Rewrite HTTP URIs and Authority headers. Rewrite cannot be used with
+Redirect primitive. Rewrite will be performed before forwarding.
+
+ |
+
+
+timeout |
+google.protobuf.Duration |
+
+ Timeout for HTTP requests.
+
+ |
+
+
+retries |
+HTTPRetry |
+
+ Retry policy for HTTP requests.
+
+ |
+
+
+fault |
+HTTPFaultInjection |
+
+ Fault injection policy to apply on HTTP traffic at the client side.
+Note that timeouts or retries will not be enabled when faults are
+enabled on the client side.
+
+ |
+
+
+mirror |
+Destination |
+
+ 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.
+
+ |
+
+
+corsPolicy |
+CorsPolicy |
+
+ Cross-Origin Resource Sharing policy (CORS). Refer to
+CORS
+for further details about cross origin resource sharing.
+
+ |
+
+
+
+
+
+
+
+
+
+
+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
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+destination |
+Destination |
+
+ REQUIRED. Destination uniquely identifies the instances of a service
+to which the request/connection should be forwarded to.
+
+ |
+
+
+weight |
+int32 |
+
+ 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.
+
+ |
+
+
+
+
+
+
+
+
+
+
+
+Header manipulation rules
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+
+
+
+
+
+
+HeaderOperations Describes the header manipulations to apply
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+
+
+
+
+
+L4MatchAttributes
+
+L4 connection match attributes. Note that L4 connection matching support
+is incomplete.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+destinationSubnets |
+string[] |
+
+ IPv4 or IPv6 ip addresses of destination with optional subnet. E.g.,
+a.b.c.d/xx form or just a.b.c.d.
+
+ |
+
+
+port |
+uint32 |
+
+ Specifies the port on the host that is being addressed. Many services
+only expose a single port or label ports with the protocols they support,
+in these cases it is not required to explicitly select the port.
+
+ |
+
+
+sourceLabels |
+map<string, string> |
+
+ One or more labels that constrain the applicability of a rule to
+workloads with the given labels. If the VirtualService has a list of
+gateways specified at the top, it should include the reserved gateway
+mesh in order for this field to be applicable.
+
+ |
+
+
+gateways |
+string[] |
+
+ 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].
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+value |
+double |
+
+ |
+
+
+
+
+PortSelector
+
+PortSelector specifies the number of a port to be used for
+matching or selection for final routing.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+number |
+uint32 (oneof) |
+
+ Valid port number
+
+ |
+
+
+
+
+RouteDestination
+
+L4 routing rule weighted destination.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+destination |
+Destination |
+
+ REQUIRED. Destination uniquely identifies the instances of a service
+to which the request/connection should be forwarded to.
+
+ |
+
+
+weight |
+int32 |
+
+ 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.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+exact |
+string (oneof) |
+
+ exact string match
+
+ |
+
+
+prefix |
+string (oneof) |
+
+ prefix-based match
+
+ |
+
+
+regex |
+string (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
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+match |
+L4MatchAttributes[] |
+
+ 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.
+
+ |
+
+
+route |
+RouteDestination[] |
+
+ The destination to which the connection should be forwarded to.
+
+ |
+
+
+
+
+TLSMatchAttributes
+
+TLS connection match attributes.
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+sniHosts |
+string[] |
+
+ 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.
+
+ |
+
+
+destinationSubnets |
+string[] |
+
+ IPv4 or IPv6 ip addresses of destination with optional subnet. E.g.,
+a.b.c.d/xx form or just a.b.c.d.
+
+ |
+
+
+port |
+uint32 |
+
+ Specifies the port on the host that is being addressed. Many services
+only expose a single port or label ports with the protocols they
+support, in these cases it is not required to explicitly select the
+port.
+
+ |
+
+
+sourceLabels |
+map<string, string> |
+
+ One or more labels that constrain the applicability of a rule to
+workloads with the given labels. If the VirtualService has a list of
+gateways specified at the top, it should include the reserved gateway
+mesh in order for this field to be applicable.
+
+ |
+
+
+gateways |
+string[] |
+
+ 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
+
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+match |
+TLSMatchAttributes[] |
+
+ 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.
+
+ |
+
+
+route |
+RouteDestination[] |
+
+ The destination to which the connection should be forwarded to.
+
+ |
+
+
+
+
+VirtualService
+
+
+
+
+| Field |
+Type |
+Description |
+
+
+
+
+hosts |
+string[] |
+
+ 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.
+
+ |
+
+
+gateways |
+string[] |
+
+ 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.
+
+ |
+
+
+http |
+HTTPRoute[] |
+
+ 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.
+
+ |
+
+
+tls |
+TLSRoute[] |
+
+ 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.
+
+ |
+
+
+tcp |
+TCPRoute[] |
+
+ 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.
+
+ |
+
+
+exportTo |
+string[] |
+
+ 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"
|