Gateway

Gateway describes a load balancer operating at the edge of the meshreceiving incoming or outgoing HTTP/TCP connections. The specificationdescribes a set of ports that should be exposed, the type of protocol touse, SNI configuration for the load balancer, etc.

For example, the following Gateway configuration sets up a proxy to actas a load balancer exposing port 80 and 9080 (http), 443 (https),9443(https) and port 2379 (TCP) for ingress. The gateway will beapplied to the proxy running on a pod with labels app:
my-gateway-controller
. While Istio will configure the proxy to listenon these ports, it is the responsibility of the user to ensure thatexternal traffic to these ports are allowed into the mesh.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Gateway
  3. metadata:
  4. name: my-gateway
  5. namespace: some-config-namespace
  6. spec:
  7. selector:
  8. app: my-gateway-controller
  9. servers:
  10. - port:
  11. number: 80
  12. name: http
  13. protocol: HTTP
  14. hosts:
  15. - uk.bookinfo.com
  16. - eu.bookinfo.com
  17. tls:
  18. httpsRedirect: true # sends 301 redirect for http requests
  19. - port:
  20. number: 443
  21. name: https-443
  22. protocol: HTTPS
  23. hosts:
  24. - uk.bookinfo.com
  25. - eu.bookinfo.com
  26. tls:
  27. mode: SIMPLE # enables HTTPS on this port
  28. serverCertificate: /etc/certs/servercert.pem
  29. privateKey: /etc/certs/privatekey.pem
  30. - port:
  31. number: 9443
  32. name: https-9443
  33. protocol: HTTPS
  34. hosts:
  35. - "bookinfo-namespace/*.bookinfo.com"
  36. tls:
  37. mode: SIMPLE # enables HTTPS on this port
  38. credentialName: bookinfo-secret # fetches certs from Kubernetes secret
  39. - port:
  40. number: 9080
  41. name: http-wildcard
  42. protocol: HTTP
  43. hosts:
  44. - "*"
  45. - port:
  46. number: 2379 # to expose internal service via external port 2379
  47. name: mongo
  48. protocol: MONGO
  49. hosts:
  50. - "*"

The Gateway specification above describes the L4-L6 properties of a loadbalancer. A VirtualService can then be bound to a gateway to controlthe forwarding of traffic arriving at a particular host or gateway port.

For example, the following VirtualService splits traffic forhttps://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) ofan internal reviews service on port 9080. In addition, requestscontaining the cookie “user: dev-123” will be sent to special port 7777in the qa version. The same rule is also applicable inside the mesh forrequests to the “reviews.prod.svc.cluster.local” service. This rule isapplicable across ports 443, 9080. Note that http://uk.bookinfo.comgets redirected to https://uk.bookinfo.com (i.e. 80 redirects to 443).

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: VirtualService
  3. metadata:
  4. name: bookinfo-rule
  5. namespace: bookinfo-namespace
  6. spec:
  7. hosts:
  8. - reviews.prod.svc.cluster.local
  9. - uk.bookinfo.com
  10. - eu.bookinfo.com
  11. gateways:
  12. - some-config-namespace/my-gateway
  13. - mesh # applies to all the sidecars in the mesh
  14. http:
  15. - match:
  16. - headers:
  17. cookie:
  18. exact: "user=dev-123"
  19. route:
  20. - destination:
  21. port:
  22. number: 7777
  23. host: reviews.qa.svc.cluster.local
  24. - match:
  25. - uri:
  26. prefix: /reviews/
  27. route:
  28. - destination:
  29. port:
  30. number: 9080 # can be omitted if it's the only port for reviews
  31. host: reviews.prod.svc.cluster.local
  32. weight: 80
  33. - destination:
  34. host: reviews.qa.svc.cluster.local
  35. weight: 20

The following VirtualService forwards traffic arriving at (external)port 27017 to internal Mongo server on port 5555. This rule is notapplicable internally in the mesh as the gateway list omits thereserved name mesh.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: VirtualService
  3. metadata:
  4. name: bookinfo-Mongo
  5. namespace: bookinfo-namespace
  6. spec:
  7. hosts:
  8. - mongosvr.prod.svc.cluster.local # name of internal Mongo service
  9. gateways:
  10. - some-config-namespace/my-gateway # can omit the namespace if gateway is in same
  11. namespace as virtual service.
  12. tcp:
  13. - match:
  14. - port: 27017
  15. route:
  16. - destination:
  17. host: mongo.prod.svc.cluster.local
  18. port:
  19. number: 5555

It is possible to restrict the set of virtual services that can bind toa gateway server using the namespace/hostname syntax in the hosts field.For example, the following Gateway allows any virtual service in the ns1namespace to bind to it, while restricting only the virtual service withfoo.bar.com host in the ns2 namespace to bind to it.

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Gateway
  3. metadata:
  4. name: my-gateway
  5. namespace: some-config-namespace
  6. spec:
  7. selector:
  8. app: my-gateway-controller
  9. servers:
  10. - port:
  11. number: 80
  12. name: http
  13. protocol: HTTP
  14. hosts:
  15. - "ns1/*"
  16. - "ns2/foo.bar.com"

Gateway

Gateway describes a load balancer operating at the edge of the meshreceiving incoming or outgoing HTTP/TCP connections.

FieldTypeDescriptionRequired
serversServer[]
A list of server specifications.
Yes
selectormap<string, string>
One or more labels that indicate a specific set of pods/VMson which this gateway configuration should be applied. The scope oflabel search is restricted to the configuration namespace in which thethe resource is present. In other words, the Gateway resource mustreside in the same namespace as the gateway workload instance.
Yes

Port

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

FieldTypeDescriptionRequired
numberuint32
A valid non-negative integer port number.
Yes
protocolstring
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 tothe destination without terminating the TLS connection.
Yes
namestring
Label assigned to the port.
No

Server

Server describes the properties of the proxy on a given load balancerport. For example,

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Gateway
  3. metadata:
  4. name: my-ingress
  5. spec:
  6. selector:
  7. app: my-ingress-gateway
  8. servers:
  9. - port:
  10. number: 80
  11. name: http2
  12. protocol: HTTP2
  13. hosts:
  14. - "*"

Another example

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Gateway
  3. metadata:
  4. name: my-tcp-ingress
  5. spec:
  6. selector:
  7. app: my-tcp-ingress-gateway
  8. servers:
  9. - port:
  10. number: 27018
  11. name: mongo
  12. protocol: MONGO
  13. hosts:
  14. - "*"

The following is an example of TLS configuration for port 443

  1. apiVersion: networking.istio.io/v1alpha3
  2. kind: Gateway
  3. metadata:
  4. name: my-tls-ingress
  5. spec:
  6. selector:
  7. app: my-tls-ingress-gateway
  8. servers:
  9. - port:
  10. number: 443
  11. name: https
  12. protocol: HTTPS
  13. hosts:
  14. - "*"
  15. tls:
  16. mode: SIMPLE
  17. serverCertificate: /etc/certs/server.pem
  18. privateKey: /etc/certs/privatekey.pem
FieldTypeDescriptionRequired
portPort
The Port on which the proxy should listen for incomingconnections.
Yes
hostsstring[]
One or more hosts exposed by this gateway.While typically applicable toHTTP services, it can also be used for TCP services using TLS with SNI.A host is specified as a dnsName with an optional namespace/ prefix.The dnsName should be specified using FQDN format, optionally includinga wildcard character in the left-most component (e.g., prod/.example.com).Set the dnsName to to select all VirtualService hosts from thespecified namespace (e.g.,prod/).

The namespace can be set to
or ., representing any or the currentnamespace, respectively. For example, /foo.example.com selects theservice from any available namespace while ./foo.example.com only selectsthe service from the namespace of the sidecar. The default, if no namespace/is specified, is /, that is, select services from any namespace.Any associated DestinationRule in the selected namespace will also be used.

A VirtualService must be bound to the gateway and must have one ormore hosts that match the hosts specified in a server. The matchcould be an exact match or a suffix match with the server’s hosts. Forexample, if the server’s hosts specifies .example.com, aVirtualService with hosts dev.example.com or prod.example.com willmatch. However, a VirtualService with host example.com ornewexample.com will not match.

NOTE: Only virtual services exported to the gateway’s namespace(e.g., exportTo value of
) can be referenced.Private configurations (e.g., exportTo set to .) will not beavailable. Refer to the exportTo setting in VirtualService,DestinationRule, and ServiceEntry configurations for details.
Yes
tlsTLSOptions
Set of TLS related options that govern the server’s behavior. Usethese options to control if all http requests should be redirected tohttps, and the TLS modes to use.
No
defaultEndpointstring
The loopback IP endpoint or Unix domain socket to which traffic shouldbe forwarded to by default. Format should be 127.0.0.1:PORT orunix:///path/to/socket or unix://@foobar (Linux abstract namespace).
No

Server.TLSOptions

FieldTypeDescriptionRequired
httpsRedirectbool
If set to true, the load balancer will send a 301 redirect for allhttp connections, asking the clients to use HTTPS.
No
modeTLSmode
Optional: Indicates whether connections to this port should besecured using TLS. The value of this field determines how TLS isenforced.
No
serverCertificatestring
REQUIRED if mode is SIMPLE or MUTUAL. The path to the fileholding the server-side TLS certificate to use.
No
privateKeystring
REQUIRED if mode is SIMPLE or MUTUAL. The path to the fileholding the server’s private key.
No
caCertificatesstring
REQUIRED if mode is MUTUAL. The path to a file containingcertificate authority certificates to use in verifying a presentedclient side certificate.
No
credentialNamestring
The credentialName stands for a unique identifier that can be usedto identify the serverCertificate and the privateKey. ThecredentialName appended with suffix “-cacert” is used to identifythe CaCertificates associated with this server. Gateway workloadscapable of fetching credentials from a remote credential store suchas Kubernetes secrets, will be configured to retrieve theserverCertificate and the privateKey using credentialName, insteadof using the file system paths specified above. If using mutual TLS,gateway workload instances will retrieve the CaCertificates usingcredentialName-cacert. The semantics of the name are platformdependent. In Kubernetes, the default Istio supplied credentialserver expects the credentialName to match the name of theKubernetes secret that holds the server certificate, the privatekey, and the CA certificate (if using mutual TLS). Set theISTIO_META_USER_SDS metadata variable in the gateway’s proxy toenable the dynamic credential fetching feature.
No
subjectAltNamesstring[]
A list of alternate names to verify the subject identity in thecertificate presented by the client.
No
verifyCertificateSpkistring[]
An optional list of base64-encoded SHA-256 hashes of the SKPIs ofauthorized client certificates.Note: When both verify_certificate_hash and verify_certificate_spkiare specified, a hash matching either value will result in thecertificate being accepted.
No
verifyCertificateHashstring[]
An optional list of hex-encoded SHA-256 hashes of theauthorized client certificates. Both simple and colon separatedformats are acceptable.Note: When both verify_certificate_hash and verify_certificate_spkiare specified, a hash matching either value will result in thecertificate being accepted.
No
minProtocolVersionTLSProtocol
Optional: Minimum TLS protocol version.
No
maxProtocolVersionTLSProtocol
Optional: Maximum TLS protocol version.
No
cipherSuitesstring[]
Optional: If specified, only support the specified cipher list.Otherwise default to the default cipher list supported by Envoy.
No

Server.TLSOptions.TLSProtocol

TLS protocol versions.

NameDescription
TLS_AUTO
Automatically choose the optimal TLS version.
TLSV1_0
TLS version 1.0
TLSV1_1
TLS version 1.1
TLSV1_2
TLS version 1.2
TLSV1_3
TLS version 1.3

Server.TLSOptions.TLSmode

TLS modes enforced by the proxy

NameDescription
PASSTHROUGH
The SNI string presented by the client will be used as the matchcriterion in a VirtualService TLS route to determine thedestination service from the service registry.
SIMPLE
Secure connections with standard TLS semantics.
MUTUAL
Secure connections to the downstream using mutual TLS by presentingserver certificates for authentication.
AUTO_PASSTHROUGH
Similar to the passthrough mode, except servers with this TLS modedo not require an associated VirtualService to map from the SNIvalue to service in the registry. The destination details such asthe service/subset/port are encoded in the SNI value. The proxywill forward to the upstream (Envoy) cluster (a group ofendpoints) specified by the SNI value. This server is typicallyused to provide connectivity between services in disparate L3networks that otherwise do not have direct connectivity betweentheir respective endpoints. Use of this mode assumes that both thesource and the destination are using Istio mTLS to secure traffic.
ISTIO_MUTUAL
Secure connections from the downstream using mutual TLS by presentingserver certificates for authentication.Compared to Mutual mode, this mode uses certificates, representinggateway workload identity, generated automatically by Istio formTLS authentication. When this mode is used, all other fields inTLSOptions should be empty.