☰
Navigation :

gateway.proto

Package: istio.networking.v1alpha3

Copyright 2017 Istio Authors

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Types:

Source File: networking/v1alpha3/gateway.proto

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
"servers": []istio.networking.v1alpha3.Server
"selector": map<string, string>
Field Type Description Default
servers []istio.networking.v1alpha3.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.

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
"port": .istio.networking.v1alpha3.Port
"bind": string
"hosts": []string
"tls": .istio.networking.v1alpha3.Server.TLSOptions
"defaultEndpoint": string
Field Type Description Default
port .istio.networking.v1alpha3.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.
bind string $hide_from_docs 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).
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 .istio.networking.v1alpha3.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).

TLSOptions

"httpsRedirect": bool
"mode": .istio.networking.v1alpha3.Server.TLSOptions.TLSmode
"serverCertificate": string
"privateKey": string
"caCertificates": string
"subjectAltNames": []string
"minProtocolVersion": .istio.networking.v1alpha3.Server.TLSOptions.TLSProtocol
"maxProtocolVersion": .istio.networking.v1alpha3.Server.TLSOptions.TLSProtocol
"cipherSuites": []string
Field Type Description Default
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 .istio.networking.v1alpha3.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.
subjectAltNames []string A list of alternate names to verify the subject identity in the certificate presented by the client.
minProtocolVersion .istio.networking.v1alpha3.Server.TLSOptions.TLSProtocol Optional: Minimum TLS protocol version.
maxProtocolVersion .istio.networking.v1alpha3.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.

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.

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

Port

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

"number": int
"protocol": string
"name": string
Field Type Description Default
number int REQUIRED: A valid non-negative integer port number.
protocol string REQUIRED: The protocol exposed on the port. MUST BE one of HTTP HTTPS
name string Label assigned to the port.