Gateway

11 minute read

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

apiVersion: networking.istio.io/v1kind: Gatewaymetadata:  name: my-gateway  namespace: some-config-namespacespec:  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 loadbalancer. AVirtualService 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 thathttp://uk.bookinfo.comgets redirected tohttps://uk.bookinfo.com (i.e. 80 redirects to 443).

apiVersion: networking.istio.io/v1kind: VirtualServicemetadata:  name: bookinfo-rule  namespace: bookinfo-namespacespec:  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 notapplicable internally in the mesh as the gateway list omits thereserved namemesh.

apiVersion: networking.istio.io/v1kind: VirtualServicemetadata:  name: bookinfo-mongo  namespace: bookinfo-namespacespec:  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 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.

apiVersion: networking.istio.io/v1kind: Gatewaymetadata:  name: my-gateway  namespace: some-config-namespacespec:  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 meshreceiving incoming or outgoing HTTP/TCP connections.

Field Description

Field	Description
`servers` Server[]	A list of server specifications.
`selector` map<string, string>	One or more labels that indicate a specific set of pods/VMson which this gateway configuration should be applied.By default workloads are searched across all namespaces based on label selectors.This implies that a gateway resource in the namespace “foo” can select pods inthe namespace “bar” based on labels.This behavior can be controlled via the`PILOT_SCOPE_GATEWAY_TO_NAMESPACE`environment variable in istiod. If this variable is setto true, the scope of label search is restricted to the configurationnamespace in which the the resource is present. In other words, the Gatewayresource must reside in the same namespace as the gateway workloadinstance.If selector is nil, the Gateway will be applied to all workloads.

servers

Server[]

A list of server specifications.

selector

map<string, string>

One or more labels that indicate a specific set of pods/VMson which this gateway configuration should be applied.By default workloads are searched across all namespaces based on label selectors.This implies that a gateway resource in the namespace “foo” can select pods inthe namespace “bar” based on labels.This behavior can be controlled via thePILOT_SCOPE_GATEWAY_TO_NAMESPACEenvironment variable in istiod. If this variable is setto true, the scope of label search is restricted to the configurationnamespace in which the the resource is present. In other words, the Gatewayresource must reside in the same namespace as the gateway workloadinstance.If selector is nil, the Gateway will be applied to all workloads.

Server

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

apiVersion: networking.istio.io/v1kind: Gatewaymetadata:  name: my-ingressspec:  selector:    app: my-ingressgateway  servers:  - port:      number: 80      name: http2      protocol: HTTP2    hosts:    - "*"

Another example

apiVersion: networking.istio.io/v1kind: Gatewaymetadata:  name: my-tcp-ingressspec:  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/v1kind: Gatewaymetadata:  name: my-tls-ingressspec:  selector:    app: my-tls-ingressgateway  servers:  - port:      number: 443      name: https      protocol: HTTPS    hosts:    - "*"    tls:      mode: SIMPLE      credentialName: tls-cert

Field	Description
`port` Port Required	The Port on which the proxy should listen for incomingconnections.
`bind` string	The ip or the Unix domain socket to which the listener should be boundto. Format:`x.x.x.x` or`unix:///path/to/uds` or`unix://@foobar`(Linux abstract namespace). When using Unix domain sockets, the portnumber should be 0.This can be used to restrict the reachability of this server to be gateway internal only.This is typically used when a gateway needs to communicate to another mesh servicee.g. publishing metrics. In such case, the server created with thespecified bind will not be available to external gateway clients.
`hosts` string[] Required	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`, a`VirtualService` with hosts`dev.example.com` or`prod.example.com` willmatch. However, a`VirtualService` with host`example.com` or`newexample.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.
`tls` ServerTLSSettings	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.
`name` string	An optional name of the server, when set must be unique across all servers.This will be used for variety of purposes like prefixing stats generated withthis name etc.

Port

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

Field	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\|GRPC-WEB\|HTTP2\|MONGO\|TCP\|TLS.TLS can be either used to terminate non-HTTP based connections on a specific portor to route traffic based on SNI header to the destination without terminating the TLS connection.
`name` string Required	Label assigned to the port.

ServerTLSSettings

Field	Description
`httpsRedirect` bool	If set to true, the load balancer will send a 301 redirect forall http connections, asking the clients to use HTTPS.
`mode` TLSmode	Indicates whether connections to this port should besecured using TLS. The value of this field determines how TLS isenforced.
`serverCertificate` string	REQUIRED if mode is`SIMPLE` or`MUTUAL`. The path to the fileholding the server-side TLS certificate to use.
`privateKey` string	REQUIRED if mode is`SIMPLE` or`MUTUAL`. The path to the fileholding the server’s private key.
`caCertificates` string	REQUIRED if mode is`MUTUAL` or`OPTIONAL_MUTUAL`. The path to a filecontaining certificate authority certificates to use in verifying a presentedclient side certificate.
`caCrl` string	OPTIONAL: The path to the file containing the certificate revocation list (CRL)to use in verifying a presented client side certificate.`CRL` is a list of certificatesthat have been revoked by the CA (Certificate Authority) before their scheduled expiration date.If specified, the proxy will verify if the presented certificate is part of the revoked list of certificates.If omitted, the proxy will not verify the certificate against the`crl`.
`credentialName` string	For gateways running on Kubernetes, the name of the secret thatholds the TLS certs including the CA certificates. Applicableonly on Kubernetes. An Opaque secret should contain the followingkeys and values:`tls.key: <privateKey>` and`tls.crt: <serverCert>` or`key: <privateKey>` and`cert: <serverCert>`.For mutual TLS,`cacert: <CACertificate>` and`crl: <CertificateRevocationList>`can be provided in the same secret or a separate secret named`<secret>-cacert`.A TLS secret for server certificates with an additional`tls.ocsp-staple` keyfor specifying OCSP staple information,`ca.crt` key for CA certificatesand`ca.crl` for certificate revocation list is also supported.Only one of server certificates and CA certificateor credentialName can be specified.
`credentialNames` string[]	Same as CredentialName but for multiple certificates. Mainly used for specifyingRSA and ECDSA certificates for the same server.
`caCertCredentialName` string	For mutual TLS, the name of the secret or the configmap that holds CA certificates.Takes precedence over CA certificates in the Secret referenced with`credentialName(s)`.
`tlsCertificates` TLSCertificate[]	Only one of`server_certificate`,`private_key` or`credential_name`or`credential_names` or`tls_certificates` should be specified.This is mainly used for specifying RSA and ECDSA certificates for the same server.
`subjectAltNames` string[]	A list of alternate names to verify the subject identity in thecertificate presented by the client.Requires TLS mode to be set to`MUTUAL`.When multiple certificates are provided via`credential_names` or`tls_certificates`,the subject alternate names are validated against the selected certificate.
`verifyCertificateSpki` string[]	An optional list of base64-encoded SHA-256 hashes of the SPKIs 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.
`verifyCertificateHash` string[]	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.
`minProtocolVersion` TLSProtocol	Minimum TLS protocol version. By default, it is`TLSV1_2`.TLS protocol versions below TLSV1_2 require setting compatible ciphers with the`cipherSuites` setting as they no longer include compatible ciphers. Note: Using TLS protocol versions below TLSV1_2 has serious security risks.
`maxProtocolVersion` TLSProtocol	Maximum TLS protocol version.
`cipherSuites` string[]	If specified, only support the specified cipher list.Otherwise default to the default cipher list supported by Envoyas specifiedhere.The supported list of ciphers are: `ECDHE-ECDSA-AES128-GCM-SHA256` `ECDHE-RSA-AES128-GCM-SHA256` `ECDHE-ECDSA-AES256-GCM-SHA384` `ECDHE-RSA-AES256-GCM-SHA384` `ECDHE-ECDSA-CHACHA20-POLY1305` `ECDHE-RSA-CHACHA20-POLY1305` `ECDHE-ECDSA-AES128-SHA` `ECDHE-RSA-AES128-SHA` `ECDHE-ECDSA-AES256-SHA` `ECDHE-RSA-AES256-SHA` `AES128-GCM-SHA256` `AES256-GCM-SHA384` `AES128-SHA` `AES256-SHA` `DES-CBC3-SHA`

TLSCertificate

TLSCertificate describes the server’s TLS certificate.

Field	Description
`serverCertificate` string	REQUIRED if mode is`SIMPLE` or`MUTUAL`. The path to the fileholding the server-side TLS certificate to use.
`privateKey` string	REQUIRED if mode is`SIMPLE` or`MUTUAL`. The path to the fileholding the server’s private key.

TLSmode

TLS modes enforced by the proxy

Name	Description
`PASSTHROUGH`	The SNI string presented by the client will be used as thematch criterion in a VirtualService TLS route to determinethe destination service from the service registry.
`SIMPLE`	Secure connections with standard TLS semantics. In this modeclient certificate is not requested during handshake.
`MUTUAL`	Secure connections to the downstream using mutual TLS bypresenting server certificates for authentication.A client certificate will also be requested during the handshake andat least one valid certificate is required to be sent by the client.
`AUTO_PASSTHROUGH`	Similar to the passthrough mode, except servers with this TLSmode do not require an associated VirtualService to map fromthe SNI value to service in the registry. The destinationdetails such as the service/subset/port are encoded in theSNI value. The proxy will forward to the upstream (Envoy)cluster (a group of endpoints) specified by the SNIvalue. This server is typically used to provide connectivitybetween services in disparate L3 networks that otherwise donot have direct connectivity between their respectiveendpoints. Use of this mode assumes that both the source andthe destination are using Istio mTLS to secure traffic.
`ISTIO_MUTUAL`	Secure connections from the downstream using mutual TLS bypresenting server certificates for authentication. Comparedto Mutual mode, this mode uses certificates, representinggateway workload identity, generated automatically by Istiofor mTLS authentication. When this mode is used, all otherfields in`TLSOptions` should be empty.
`OPTIONAL_MUTUAL`	Similar to MUTUAL mode, except that the client certificateis optional. Unlike SIMPLE mode, A client certificate willstill be explicitly requested during handshake, but the clientis not required to send a certificate. If a client certificateis presented, it will be validated. ca_certificates shouldbe specified for validating client certificates.

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

Was this information useful?

Do you have any suggestions for improvement?

Thanks for your feedback!

Movatterモバイル変換

Gateway

Gateway

Server

Port

ServerTLSSettings

TLSCertificate

TLSmode

TLSProtocol

Links