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),
9443(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-443
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: 9443
name: https-9443
protocol: HTTPS
hosts:
- "bookinfo-namespace/*.bookinfo.com"
tls:
mode: SIMPLE # enables HTTPS on this port
credentialName: bookinfo-secret # fetches certs from Kubernetes secret
- 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:
- "*"
apiVersion: networking.istio.io/v1beta1
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-443
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: 9443
name: https-9443
protocol: HTTPS
hosts:
- "bookinfo-namespace/*.bookinfo.com"
tls:
mode: SIMPLE # enables HTTPS on this port
credentialName: bookinfo-secret # fetches certs from Kubernetes secret
- 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:
exact: "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 it's the only port for reviews
host: reviews.prod.svc.cluster.local
weight: 80
- destination:
host: reviews.qa.svc.cluster.local
weight: 20
apiVersion: networking.istio.io/v1beta1
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:
exact: "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 it's 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
apiVersion: networking.istio.io/v1beta1
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
It is possible to restrict the set of virtual services that can bind to a gateway server using the namespace/hostname syntax in the hosts field. For example, the following Gateway allows any virtual service in the ns1 namespace to bind to it, while restricting only the virtual service with foo.bar.com host in the ns2 namespace to bind to it.
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:
- "ns1/*"
- "ns2/foo.bar.com"
apiVersion: networking.istio.io/v1beta1
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:
- "ns1/*"
- "ns2/foo.bar.com"
Gateway
Gateway describes a load balancer operating at the edge of the mesh receiving incoming or outgoing HTTP/TCP connections.
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-ingressgateway
servers:
- port:
number: 80
name: http2
protocol: HTTP2
hosts:
- "*"
apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
name: my-ingress
spec:
selector:
app: my-ingressgateway
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-ingressgateway
servers:
- port:
number: 27018
name: mongo
protocol: MONGO
hosts:
- "*"
apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
name: my-tcp-ingress
spec:
selector:
app: my-tcp-ingressgateway
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-ingressgateway
servers:
- port:
number: 443
name: https
protocol: HTTPS
hosts:
- "*"
tls:
mode: SIMPLE
credentialName: tls-cert
apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
name: my-tls-ingress
spec:
selector:
app: my-tls-ingressgateway
servers:
- port:
number: 443
name: https
protocol: HTTPS
hosts:
- "*"
tls:
mode: SIMPLE
credentialName: tls-cert
Port
Port describes the properties of a specific port of a service.
ServerTLSSettings
ServerTLSSettings.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. In this mode client certificate is not requested during handshake. |
MUTUAL | Secure connections to the downstream using mutual TLS by presenting server certificates for authentication. A client certificate will also be requested during the handshake and at least one valid certificate is required to be sent by the client. |
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. |
ISTIO_MUTUAL | Secure connections from the downstream using mutual TLS by
presenting server certificates for authentication. Compared
to Mutual mode, this mode uses certificates, representing
gateway workload identity, generated automatically by Istio
for mTLS authentication. When this mode is used, all other
fields in |
OPTIONAL_MUTUAL | Similar to MUTUAL mode, except that the client certificate is optional. Unlike SIMPLE mode, A client certificate will still be explicitly requested during handshake, but the client is not required to send a certificate. If a client certificate is presented, it will be validated. ca_certificates should be specified for validating client certificates. |
ServerTLSSettings.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 |