networking/v1alpha3/gateway.pb.html

--- title: Gateway description: Configuration affecting edge load balancer. location: https://istio.io/docs/reference/config/networking/gateway.html layout: protoc-gen-docs generator: protoc-gen-docs schema: istio.networking.v1alpha3.Gateway aliases: [/docs/reference/config/networking/v1alpha3/gateway] number_of_entries: 6 --- <p><code>Gateway</code> 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.</p> <p>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 <code>app: my-gateway-controller</code>. 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.</p> <pre><code class="language-yaml">apiVersion: networking.istio.io/v1 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: - "*" </code></pre> <p>The Gateway specification above describes the L4-L6 properties of a load balancer. A <code>VirtualService</code> can then be bound to a gateway to control the forwarding of traffic arriving at a particular host or gateway port.</p> <p>For example, the following VirtualService splits traffic for <code>https://uk.bookinfo.com/reviews</code>, <code>https://eu.bookinfo.com/reviews</code>, <code>http://uk.bookinfo.com:9080/reviews</code>, <code>http://eu.bookinfo.com:9080/reviews</code> 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 <code>http://uk.bookinfo.com</code> gets redirected to <code>https://uk.bookinfo.com</code> (i.e. 80 redirects to 443).</p> <pre><code class="language-yaml">apiVersion: networking.istio.io/v1 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 </code></pre> <p>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 <code>mesh</code>.</p> <pre><code class="language-yaml">apiVersion: networking.istio.io/v1 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 </code></pre> <p>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.</p> <pre><code class="language-yaml">apiVersion: networking.istio.io/v1 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" </code></pre> <h2 id="Gateway">Gateway</h2> <section> <p>Gateway describes a load balancer operating at the edge of the mesh receiving incoming or outgoing HTTP/TCP connections.</p> <table class="message-fields"> <thead> <tr> <th>Field</th> <th>Type</th> <th>Description</th> <th>Required</th> </tr> </thead> <tbody> <tr id="Gateway-servers"> <td><code><a href="#Gateway-servers">servers</a></code></td> <td><code><a href="#Server">Server[]</a></code></td> <td> <p>A list of server specifications.</p> </td> <td> No </td> </tr> <tr id="Gateway-selector"> <td><code><a href="#Gateway-selector">selector</a></code></td> <td><code>map<string, string></code></td> <td> <p>One or more labels that indicate a specific set of pods/VMs on 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 in the namespace “bar” based on labels. This behavior can be controlled via the <code>PILOT_SCOPE_GATEWAY_TO_NAMESPACE</code> environment variable in istiod. If this variable is set to true, 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 instance. If selector is nil, the Gateway will be applied to all workloads.</p> </td> <td> No </td> </tr> </tbody> </table> </section> <h2 id="Server">Server</h2> <section> <p><code>Server</code> describes the properties of the proxy on a given load balancer port. For example,</p> <pre><code class="language-yaml">apiVersion: networking.istio.io/v1 kind: Gateway metadata: name: my-ingress spec: selector: app: my-ingressgateway servers: - port: number: 80 name: http2 protocol: HTTP2 hosts: - "*" </code></pre> <p>Another example</p> <pre><code class="language-yaml">apiVersion: networking.istio.io/v1 kind: Gateway metadata: name: my-tcp-ingress spec: selector: app: my-tcp-ingressgateway servers: - port: number: 27018 name: mongo protocol: MONGO hosts: - "*" </code></pre> <p>The following is an example of TLS configuration for port 443</p> <pre><code class="language-yaml">apiVersion: networking.istio.io/v1 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 </code></pre> <table class="message-fields"> <thead> <tr> <th>Field</th> <th>Type</th> <th>Description</th> <th>Required</th> </tr> </thead> <tbody> <tr id="Server-port"> <td><code><a href="#Server-port">port</a></code></td> <td><code><a href="#Port">Port</a></code></td> <td> <p>The Port on which the proxy should listen for incoming connections.</p> </td> <td> Yes </td> </tr> <tr id="Server-bind"> <td><code><a href="#Server-bind">bind</a></code></td> <td><code>string</code></td> <td> <p>The ip or the Unix domain socket to which the listener should be bound to. Format: <code>x.x.x.x</code> or <code>unix:///path/to/uds</code> or <code>unix://@foobar</code> (Linux abstract namespace). When using Unix domain sockets, the port number 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 service e.g. publishing metrics. In such case, the server created with the specified bind will not be available to external gateway clients.</p> </td> <td> No </td> </tr> <tr id="Server-hosts"> <td><code><a href="#Server-hosts">hosts</a></code></td> <td><code>string[]</code></td> <td> <p>One or more hosts exposed by this gateway. While typically applicable to HTTP services, it can also be used for TCP services using TLS with SNI. A host is specified as a <code>dnsName</code> with an optional <code>namespace/</code> prefix. The <code>dnsName</code> should be specified using FQDN format, optionally including a wildcard character in the left-most component (e.g., <code>prod/*.example.com</code>). Set the <code>dnsName</code> to <code>*</code> to select all <code>VirtualService</code> hosts from the specified namespace (e.g.,<code>prod/*</code>).</p> <p>The <code>namespace</code> can be set to <code>*</code> or <code>.</code>, representing any or the current namespace, respectively. For example, <code>*/foo.example.com</code> selects the service from any available namespace while <code>./foo.example.com</code> only selects the service from the namespace of the sidecar. The default, if no <code>namespace/</code> is specified, is <code>*/</code>, that is, select services from any namespace. Any associated <code>DestinationRule</code> in the selected namespace will also be used.</p> <p>A <code>VirtualService</code> must be bound to the gateway and 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 <code>*.example.com</code>, a <code>VirtualService</code> with hosts <code>dev.example.com</code> or <code>prod.example.com</code> will match. However, a <code>VirtualService</code> with host <code>example.com</code> or <code>newexample.com</code> will not match.</p> <p>NOTE: Only virtual services exported to the gateway’s namespace (e.g., <code>exportTo</code> value of <code>*</code>) can be referenced. Private configurations (e.g., <code>exportTo</code> set to <code>.</code>) will not be available. Refer to the <code>exportTo</code> setting in <code>VirtualService</code>, <code>DestinationRule</code>, and <code>ServiceEntry</code> configurations for details.</p> </td> <td> Yes </td> </tr> <tr id="Server-tls"> <td><code><a href="#Server-tls">tls</a></code></td> <td><code><a href="#ServerTLSSettings">ServerTLSSettings</a></code></td> <td> <p>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.</p> </td> <td> No </td> </tr> <tr id="Server-name"> <td><code><a href="#Server-name">name</a></code></td> <td><code>string</code></td> <td> <p>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 with this name etc.</p> </td> <td> No </td> </tr> </tbody> </table> </section> <h2 id="Port">Port</h2> <section> <p>Port describes the properties of a specific port of a service.</p> <table class="message-fields"> <thead> <tr> <th>Field</th> <th>Type</th> <th>Description</th> <th>Required</th> </tr> </thead> <tbody> <tr id="Port-number"> <td><code><a href="#Port-number">number</a></code></td> <td><code>uint32</code></td> <td> <p>A valid non-negative integer port number.</p> </td> <td> Yes </td> </tr> <tr id="Port-protocol"> <td><code><a href="#Port-protocol">protocol</a></code></td> <td><code>string</code></td> <td> <p>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 port or to route traffic based on SNI header to the destination without terminating the TLS connection.</p> </td> <td> Yes </td> </tr> <tr id="Port-name"> <td><code><a href="#Port-name">name</a></code></td> <td><code>string</code></td> <td> <p>Label assigned to the port.</p> </td> <td> Yes </td> </tr> </tbody> </table> </section> <h2 id="ServerTLSSettings">ServerTLSSettings</h2> <section> <table class="message-fields"> <thead> <tr> <th>Field</th> <th>Type</th> <th>Description</th> <th>Required</th> </tr> </thead> <tbody> <tr id="ServerTLSSettings-https_redirect"> <td><code><a href="#ServerTLSSettings-https_redirect">httpsRedirect</a></code></td> <td><code>bool</code></td> <td> <p>If set to true, the load balancer will send a 301 redirect for all http connections, asking the clients to use HTTPS.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-mode"> <td><code><a href="#ServerTLSSettings-mode">mode</a></code></td> <td><code><a href="#ServerTLSSettings-TLSmode">TLSmode</a></code></td> <td> <p>Optional: Indicates whether connections to this port should be secured using TLS. The value of this field determines how TLS is enforced.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-server_certificate"> <td><code><a href="#ServerTLSSettings-server_certificate">serverCertificate</a></code></td> <td><code>string</code></td> <td> <p>REQUIRED if mode is <code>SIMPLE</code> or <code>MUTUAL</code>. The path to the file holding the server-side TLS certificate to use.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-private_key"> <td><code><a href="#ServerTLSSettings-private_key">privateKey</a></code></td> <td><code>string</code></td> <td> <p>REQUIRED if mode is <code>SIMPLE</code> or <code>MUTUAL</code>. The path to the file holding the server’s private key.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-ca_certificates"> <td><code><a href="#ServerTLSSettings-ca_certificates">caCertificates</a></code></td> <td><code>string</code></td> <td> <p>REQUIRED if mode is <code>MUTUAL</code> or <code>OPTIONAL_MUTUAL</code>. The path to a file containing certificate authority certificates to use in verifying a presented client side certificate.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-ca_crl"> <td><code><a href="#ServerTLSSettings-ca_crl">caCrl</a></code></td> <td><code>string</code></td> <td> <p>OPTIONAL: The path to the file containing the certificate revocation list (CRL) to use in verifying a presented client side certificate. <code>CRL</code> is a list of certificates that 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 <code>crl</code>.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-credential_name"> <td><code><a href="#ServerTLSSettings-credential_name">credentialName</a></code></td> <td><code>string</code></td> <td> <p>For gateways running on Kubernetes, the name of the secret that holds the TLS certs including the CA certificates. Applicable only on Kubernetes. An Opaque secret should contain the following keys and values: <code>tls.key: <privateKey></code> and <code>tls.crt: <serverCert></code> or <code>key: <privateKey></code> and <code>cert: <serverCert></code>. For mutual TLS, <code>cacert: <CACertificate></code> and <code>crl: <CertificateRevocationList></code> can be provided in the same secret or a separate secret named <code><secret>-cacert</code>. A TLS secret for server certificates with an additional <code>tls.ocsp-staple</code> key for specifying OCSP staple information, <code>ca.crt</code> key for CA certificates and <code>ca.crl</code> for certificate revocation list is also supported. Only one of server certificates and CA certificate or credentialName can be specified.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-subject_alt_names"> <td><code><a href="#ServerTLSSettings-subject_alt_names">subjectAltNames</a></code></td> <td><code>string[]</code></td> <td> <p>A list of alternate names to verify the subject identity in the certificate presented by the client.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-verify_certificate_spki"> <td><code><a href="#ServerTLSSettings-verify_certificate_spki">verifyCertificateSpki</a></code></td> <td><code>string[]</code></td> <td> <p>An optional list of base64-encoded SHA-256 hashes of the SPKIs of authorized client certificates. Note: When both verify_certificate_hash and verify_certificate_spki are specified, a hash matching either value will result in the certificate being accepted.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-verify_certificate_hash"> <td><code><a href="#ServerTLSSettings-verify_certificate_hash">verifyCertificateHash</a></code></td> <td><code>string[]</code></td> <td> <p>An optional list of hex-encoded SHA-256 hashes of the authorized client certificates. Both simple and colon separated formats are acceptable. Note: When both verify_certificate_hash and verify_certificate_spki are specified, a hash matching either value will result in the certificate being accepted.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-min_protocol_version"> <td><code><a href="#ServerTLSSettings-min_protocol_version">minProtocolVersion</a></code></td> <td><code><a href="#ServerTLSSettings-TLSProtocol">TLSProtocol</a></code></td> <td> <p>Optional: Minimum TLS protocol version. By default, it is <code>TLSV1_2</code>. TLS protocol versions below TLSV1_2 require setting compatible ciphers with the <code>cipherSuites</code> setting as they no longer include compatible ciphers.</p> <p>Note: Using TLS protocol versions below TLSV1_2 has serious security risks.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-max_protocol_version"> <td><code><a href="#ServerTLSSettings-max_protocol_version">maxProtocolVersion</a></code></td> <td><code><a href="#ServerTLSSettings-TLSProtocol">TLSProtocol</a></code></td> <td> <p>Optional: Maximum TLS protocol version.</p> </td> <td> No </td> </tr> <tr id="ServerTLSSettings-cipher_suites"> <td><code><a href="#ServerTLSSettings-cipher_suites">cipherSuites</a></code></td> <td><code>string[]</code></td> <td> <p>Optional: If specified, only support the specified cipher list. Otherwise default to the default cipher list supported by Envoy as specified <a href="https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto">here</a>. The supported list of ciphers are:</p> <ul> <li><code>ECDHE-ECDSA-AES128-GCM-SHA256</code></li> <li><code>ECDHE-RSA-AES128-GCM-SHA256</code></li> <li><code>ECDHE-ECDSA-AES256-GCM-SHA384</code></li> <li><code>ECDHE-RSA-AES256-GCM-SHA384</code></li> <li><code>ECDHE-ECDSA-CHACHA20-POLY1305</code></li> <li><code>ECDHE-RSA-CHACHA20-POLY1305</code></li> <li><code>ECDHE-ECDSA-AES128-SHA</code></li> <li><code>ECDHE-RSA-AES128-SHA</code></li> <li><code>ECDHE-ECDSA-AES256-SHA</code></li> <li><code>ECDHE-RSA-AES256-SHA</code></li> <li><code>AES128-GCM-SHA256</code></li> <li><code>AES256-GCM-SHA384</code></li> <li><code>AES128-SHA</code></li> <li><code>AES256-SHA</code></li> <li><code>DES-CBC3-SHA</code></li> </ul> </td> <td> No </td> </tr> </tbody> </table> </section> <h2 id="ServerTLSSettings-TLSmode">ServerTLSSettings.TLSmode</h2> <section> <p>TLS modes enforced by the proxy</p> <table class="enum-values"> <thead> <tr> <th>Name</th> <th>Description</th> </tr> </thead> <tbody> <tr id="ServerTLSSettings-TLSmode-PASSTHROUGH"> <td><code><a href="#ServerTLSSettings-TLSmode-PASSTHROUGH">PASSTHROUGH</a></code></td> <td> <p>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.</p> </td> </tr> <tr id="ServerTLSSettings-TLSmode-SIMPLE"> <td><code><a href="#ServerTLSSettings-TLSmode-SIMPLE">SIMPLE</a></code></td> <td> <p>Secure connections with standard TLS semantics. In this mode client certificate is not requested during handshake.</p> </td> </tr> <tr id="ServerTLSSettings-TLSmode-MUTUAL"> <td><code><a href="#ServerTLSSettings-TLSmode-MUTUAL">MUTUAL</a></code></td> <td> <p>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.</p> </td> </tr> <tr id="ServerTLSSettings-TLSmode-AUTO_PASSTHROUGH"> <td><code><a href="#ServerTLSSettings-TLSmode-AUTO_PASSTHROUGH">AUTO_PASSTHROUGH</a></code></td> <td> <p>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.</p> </td> </tr> <tr id="ServerTLSSettings-TLSmode-ISTIO_MUTUAL"> <td><code><a href="#ServerTLSSettings-TLSmode-ISTIO_MUTUAL">ISTIO_MUTUAL</a></code></td> <td> <p>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 <code>TLSOptions</code> should be empty.</p> </td> </tr> <tr id="ServerTLSSettings-TLSmode-OPTIONAL_MUTUAL"> <td><code><a href="#ServerTLSSettings-TLSmode-OPTIONAL_MUTUAL">OPTIONAL_MUTUAL</a></code></td> <td> <p>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.</p> </td> </tr> </tbody> </table> </section> <h2 id="ServerTLSSettings-TLSProtocol">ServerTLSSettings.TLSProtocol</h2> <section> <p>TLS protocol versions.</p> <table class="enum-values"> <thead> <tr> <th>Name</th> <th>Description</th> </tr> </thead> <tbody> <tr id="ServerTLSSettings-TLSProtocol-TLS_AUTO"> <td><code><a href="#ServerTLSSettings-TLSProtocol-TLS_AUTO">TLS_AUTO</a></code></td> <td> <p>Automatically choose the optimal TLS version.</p> </td> </tr> <tr id="ServerTLSSettings-TLSProtocol-TLSV1_0"> <td><code><a href="#ServerTLSSettings-TLSProtocol-TLSV1_0">TLSV1_0</a></code></td> <td> <p>TLS version 1.0</p> </td> </tr> <tr id="ServerTLSSettings-TLSProtocol-TLSV1_1"> <td><code><a href="#ServerTLSSettings-TLSProtocol-TLSV1_1">TLSV1_1</a></code></td> <td> <p>TLS version 1.1</p> </td> </tr> <tr id="ServerTLSSettings-TLSProtocol-TLSV1_2"> <td><code><a href="#ServerTLSSettings-TLSProtocol-TLSV1_2">TLSV1_2</a></code></td> <td> <p>TLS version 1.2</p> </td> </tr> <tr id="ServerTLSSettings-TLSProtocol-TLSV1_3"> <td><code><a href="#ServerTLSSettings-TLSProtocol-TLSV1_3">TLSV1_3</a></code></td> <td> <p>TLS version 1.3</p> </td> </tr> </tbody> </table> </section>

networking/v1alpha3/gateway.pb.html (736 lines of code) (raw):