Proto: virtual_gateway.proto

Package: networking.gloo.solo.io

A VirtualGateway custom resource represents a logical gateway configuration for one or more Istio ingress, egress, or east-west gateway workloads within the same workspace. The specification describes a set of ports that the VirtualGateway listens for incoming or outgoing HTTP/TCP connections, the type of protocol to use, SNI configuration, and more.

For more information, see the gateway listener overview in the Gloo Mesh Gateway docs.

Examples

HTTP: This resource configures the gateway to listen for incoming HTTP requests on port 80, and delegate traffic requests for the *.bookinfo.com hostname. The VirtualGateway is applied to a specific set of gateway pods with the istio:ingressgateway label within the same workspace as the VirtualGateway resource.

  apiVersion: networking.gloo.solo.io/v2
kind: VirtualGateway
metadata:
  name: istio-ingressgateway
  namespace: bookinfo
spec:
  listeners:
    - http: {}
      port:
        number: 80
      allowedRouteTables:
        - host: '*.bookinfo.com'
  workloads:
    - selector:
        labels:
          istio: ingressgateway
  

HTTP with multiple hosts: This resource configures the gateway to listen for incoming HTTP requests on port 80, and delegate any *.foo.com requests to the RouteTable resource(s) provided by the foo-ws workspace. Further, on the same port 80, it also delegates any *.bar.com requests to the RouteTable resource(s) provided by the bar-ws workspace.

  apiVersion: networking.gloo.solo.io/v2
kind: VirtualGateway
metadata:
  name: my-gateway
  namespace: some-config-namespace
spec:
  listeners:
    - http: {}
      port:
        number: 80
      allowedRouteTables:
        - host: '*.foo.com'
          selector:
            workspace: foo-ws
        - host: '*.bar.com'
          selector:
            workspace: bar-ws
  workloads:
    - selector:
        labels:
          app: my-gateway-controller
  

Simple HTTPS/TLS: This resource configures the gateway to act as a load balancer listening on port 80 and 9080 (http), 443 (https), and 9443 (https) for ingress traffic. The VirtualGateway is applied to a specific set of gateway pods with the istio:ingressgateway label within the same workspace as the VirtualGateway resource. The RouteTable(s) associated with each port 80, 9443, and 443 must be provided by the foo-ws workspace, with hosts that match *.foo.com. The RouteTable(s) for port 9080 must be provided by the bar-ws workspace with hosts that match *.bar.com.

  apiVersion: networking.gloo.solo.io/v2
kind: VirtualGateway
metadata:
  name: istio-ingressgateway
  namespace: some-config-namespace
spec:
  listeners:
    - http: {}
      port:
        number: 80
      httpsRedirect: true
      allowedRouteTables:
        - host: '*.foo.com'
          selector:
            workspace: foo-ws
    - http: {}
      port:
        number: 443
      tls:
        mode: SIMPLE
        files:
          privateKey: /etc/certs/privatekey.pem
          serverCert: /etc/certs/servercert.pem
      allowedRouteTables:
        - host: '*.foo.com'
          selector:
            workspace: foo-ws
    - http: {}
      port:
        number: 9443
      tls:
        mode: SIMPLE
        secretName: my-secret
      allowedRouteTables:
        - host: '*.foo.com'
          selector:
            workspace: foo-ws
    - http: {}
      port:
        number: 9080
      allowedRouteTables:
        - host: '*.bar.com'
          selector:
            workspace: foo-ws
  workloads:
    - selector:
        labels:
          istio: ingressgateway
  

ListenerRouteTable

A list of listener/RouteTable combinations showing which RouteTables are attached to which listeners.

FieldDescription
listenerIdx(uint32)

The index of the listener in the list of listeners on the VirtualGateway.
routeTableRef(common.gloo.solo.io.ObjectReference)

A reference to a RouteTable.

TLSConfig

Configure TLS settings for a virtual host or listener.


Configuration constraints:

  • This field is required if `appProtocol` is `HTTPS` or `TLS`.
  • This field is optional if `appProtocol` is unset.
  • This field must be empty otherwise.
FieldDescription
secretName(string)

The name of the Kubernetes secret that contains the SSL secret. Each gateway checks for a secret with this name in its own namespace on the cluster.

Configuration constraints:
  • This field must be empty if the mode is ISTIO_MUTUAL.
  • This field is ignored if the mode is PASSTHROUGH or AUTO_PASSTHROUGH.
  • The value must name a real secret in the given namespace and cluster.
  • An Opaque secret must contain either tls.key: <privateKey> and tls.crt: <serverCert>, or key: <privateKey> and cert: <serverCert>. For mutual TLS, you can provide cacert: <CACertificate> and crl: <CertificateRevocationList> in the same secret, or a separate secret named <secret>-cacert. You can also provide a TLS secret for server certificates with an additional tls.ocsp-staple key for OCSP staple information, ca.crt key for CA certificates, and ca.crl for a certificate revocation list.
files(TLSConfig.Files)

Paths to certificates that can be read by the gateway proxy from its local filesystem.
verifySubjectAltName(repeated string)

Verify that the Subject Alternative Name in the peer certificate is one of the specified values.

Configuration constraints: If you set this field, you must also set files.caCerts.
parameters(TLSConfig.Parameters)

General TLS parameters.
mode(TLSConfig.TLSMode)

TLS modes enforced by the gateway proxy.

TLSConfig.Files

Paths to certificates that can be read by the gateway proxy from its local filesystem.

Implementation notes: These files must be present on the filesystem.

FieldDescription
serverCert(string)

The path to the file that contains the server-side TLS certificate.

Configuration constraints:
  • This field must be empty if tlsMode is ISTIO_MUTUAL.
  • This field is required if tlsMode is SIMPLE or MUTUAL, and secretName is not set.
  • This field is ignored if tlsMode is PASSTHROUGH or AUTO_PASSTHROUGH.
privateKey(string)

The path to the file that contains the server’s private key.

Configuration constraints:
  • This field must be empty if tlsMode is ISTIO_MUTUAL.
  • This field is required if tlsMode is SIMPLE or MUTUAL, and secretName is not set.
  • This field is ignored if tlsMode is PASSTHROUGH or AUTO_PASSTHROUGH.
caCerts(string)

The path to the file that contains the certificate authority (CA) certificates for validating the client cert.

Configuration constraints:
  • This field must be empty if tlsMode is ISTIO_MUTUAL.
  • This field is required if tlsMode is MUTUAL, and secretName is not set.
  • This field is ignored if tlsMode is PASSTHROUGH or AUTO_PASSTHROUGH.

TLSConfig.Parameters

General TLS parameters. For more information about these values, see the Envoy docs.

FieldDescription
minimumProtocolVersion(TLSConfig.Parameters.ProtocolVersion)

The minimum TLS version. Defaults to TLSV1_2. Warning: Using TLS protocol versions below TLSV1_2 can pose serious security risks.
maximumProtocolVersion(TLSConfig.Parameters.ProtocolVersion)

The maximum TLS version.
cipherSuites(repeated string)

The TLS cipher suites to secure the connection.

Configuration constraints:
  • This field is required if minimumProtocolVersion is TLSv1_0 or TLSv1_1. TLS protocol versions below TLSV1_2 require setting compatible ciphers with this setting, because they no longer include compatible ciphers.
  • This field is ignored if minimumProtocolVersion is TLSv1_3.
  • Invalid or duplicate values are ignored.
  • The following cipher values are supported:
    • 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

VirtualGatewayReport

The resources that the VirtualGateway selects after it is successfully applied.

FieldDescription
workspaces(repeated VirtualGatewayReport.WorkspacesEntry)

A list of workspaces in which the virtal gateway can be applied.
allowedRouteTables(repeated common.gloo.solo.io.ObjectReference)

A list of RouteTables allowed to bind to this VirtualGateway.
selectedWorkloads(repeated common.gloo.solo.io.ObjectReference)

A list of workloads selected by this VirtualGateway.
exposedExternalServices(repeated common.gloo.solo.io.ObjectReference)

A list of external services exposed by this VirtualGateway.
listenerRouteTables(repeated ListenerRouteTable)

A list of listener/RouteTable combinations showing which RouteTables are attached to which listeners.

VirtualGatewayReport.WorkspacesEntry

FieldDescription
key(string)

value(common.gloo.solo.io.Report)

VirtualGatewaySpec

Specifications for the VirtualGateway resource.

FieldDescription
workloads(repeated common.gloo.solo.io.WorkloadSelector)

Optional: Select the gateway workloads that implement this VirtualGateway in the same workspace. A gateway workload is selected if it matches any of the provided selectors. For selector.name, specify the gateway service’s name. For selector.labels, specify the gateway service’s spec.selector label.

Implementation notes:
  • If this field is nil, it is applied to all gateway workloads.
  • If one of the selectors is nil, that selector selects nothing.
  • If one of the selectors is {}, it selects everything.
listeners(repeated VirtualGatewaySpec.Listener)

Required: One or more listeners for the VirtualGateway. Each listener specifies a port and virtual host(s) on which traffic can be received.

Configuration constraints: This field is required and must define at least one listener.

VirtualGatewaySpec.Listener

FieldDescription
port(common.gloo.solo.io.PortSelector)

Required: The port on the backing gateway service, on which the gateway listens for connections to route.

Configuration constraints:
  • This field is required and must define either a port number or name.
  • The value must match a port on the backing gateway service.
  • The port on the backing gateway service must not have a targetPort that is specified by name.
  • The port on the backing gateway service must be in the range 1 - 65535, or its targetPort number, if specified, must be in that range.
  • The port on the backing gateway service must not match the port of another listener with the same appProtocol and same first host. The first host is the host on the first allowedRouteTables entry. If no allowedRouteTables are set, then the first host is the host on the first exposedExternalServices entry. If no allowedRouteTables and no exposedExternalServices are set, then the first host is the wildcard ‘*’.
tls(TLSConfig)

Configure TLS settings for a virtual host or listener.

Configuration constraints:
  • This field is required if appProtocol is HTTPS or TLS.
  • This field is optional if appProtocol is unset.
  • This field must be empty otherwise.
httpsRedirect(bool)

If set to true, the load balancer returns a 301 HTTP response code for all incoming HTTP connections with an HTTPS redirect location for the client to use.

Configuration constraints: This field must be unset if the listener type is tcp (tcp is set, or neither tcp nor http is set).
http(VirtualGatewaySpec.Listener.HTTPServer)

Serves HTTP requests on the hosts specified for a listener. The listener routes traffic based on the RouteTable resource that is attached to the VirtualGateway.
tcp(VirtualGatewaySpec.Listener.TCPServer)

The TCP listener configuration. If you want to use TCP routes that route via SNI server name, a TLS configuration is required.
allowedRouteTables(repeated VirtualGatewaySpec.Listener.RouteTableFilter)

Optional: Filter RouteTables that can bind to this listener by the hostnames and object metadata. Wildcard matching for hostnames is supported. If omitted, any RouteTable can bind to this VirtualGateway.
exposedExternalServices(repeated VirtualGatewaySpec.Listener.ExternalServiceFilter)

Optional: A list of ExternalServices exposed by this VirtualGateway, for configuring egress traffic. If empty or omitted, any ExternalService is exposed by this VirtualGateway.
appProtocol(string)

Optional: Application protocol to use when adding capabilities, such as routing and rich metrics, to the gateway. If no protocol is selected, the protocol is inferred from the listener type and its TLS settings. For example, for an http listener, appProtocol defaults to HTTP if no TLS settings are defined, and HTTPS if TLS settings are defined. For a tcp listener, appProtocol defaults to TCP or TLS, depending on the presence of TLS settings.

Configuration constraints:
  • The following values are supported: GRPC, GRPC-WEB, HTTP, HTTPS, HTTP_PROXY, HTTP2, MONGO, MYSQL, TCP, TLS, REDIS
  • The value must be the same for multiple listeners that specify the same port. This includes cases when the protocol is inferred from the listener type and TLS settings.
  • If the listener type is http (http is set) and tls is set, appProtocol must be empty or set to HTTPS.
  • If the listener type is http (http is set) and tls is unset, appProtocol must be empty or set to GRPC, GRPC-WEB, HTTP, HTTP_PROXY, or HTTP2.
  • If the listener type is tcp (tcp is set, or neither tcp nor http is set) and tls is set, appProtocol must be empty or set to TLS.
  • If the listener type is tcp (tcp is set, or neither tcp nor http is set) and tls is unset, appProtocol must be empty or set to TCP, MONGO, REDIS, or MYSQL.

VirtualGatewaySpec.Listener.ExternalServiceFilter

Filter ExternalServices that can attach to this VirtualGateway by hostname.

FieldDescription
host(string)

Required: The hostname to select. You can use * to match hostname patterns in multiple objects.

Configuration constraints:
  • This field is required.
  • The host must be specified as a dnsName, with an optional namespace/ prefix.
  • The namespace can optionally be set to *, for any namespace, or ., for the current namespace.
  • If no namespace/ prefix is specified, the default is */, which selects services from any namespace.
  • The dnsName must be in FQDN format, and can optionally include a wildcard character in the first segment, such as prod/*.example.com.
selector(common.gloo.solo.io.ObjectSelector)

Optional: Filter out ExternalServices that do not match the selector.

VirtualGatewaySpec.Listener.HTTPServer

Serve HTTP routes for RouteTables that select this gateway.

VirtualGatewaySpec.Listener.RouteTableFilter

Optional: Filter RouteTables that can bind to this listener by the hostnames and object metadata. Wildcard matching for hostnames is supported. If omitted, any RouteTable can bind to this VirtualGateway.

FieldDescription
host(string)

Required: The hostname to select. You can use * to match hostname patterns in multiple objects.

Configuration constraints:
  • This field is required.
  • The host must be specified as a dnsName, with an optional namespace/ prefix.
  • The namespace can optionally be set to *, for any namespace, or ., for the current namespace.
  • If no namespace/ prefix is specified, the default is */, which selects services from any namespace.
  • The dnsName must be in FQDN format, and can optionally include a wildcard character in the first segment, such as prod/*.example.com.
selector(common.gloo.solo.io.ObjectSelector)

Optional: Filter out RouteTables that do not match the selector.

Implementation notes:
  • If the selector is empty, then it matches all RouteTables in this workspace.
  • If the selector is nil, then it matches no RouteTables.
  • A RouteTable must match one of the selectors to be selected.
allowedRoutes(repeated common.gloo.solo.io.RouteFilter)

Optional: Restrict the routes that can be applied to this VirtualGateway to a set of route filter criteria. If empty, all the routes that belong to the matching RouteTables can bind to this VirtualGateway.

VirtualGatewayStatus

The status of the resource after it is applied to your Gloo environment.

FieldDescription
common(common.gloo.solo.io.Status)

The state and workspace conditions of the applied resource.
routeTablesCount(uint32)

The number of RouteTables allowed to bind to this VirtualGateway.
selectedWorkloadsCount(uint32)

The number of workloads selected by this VirtualGateway.
externalServicesCount(uint32)

The number of ExternalServices exposed by this VirtualGateway.

TLSConfig.Parameters.ProtocolVersion

NameNumberDescription
TLS_AUTO0Automatically choose the optimal TLS version.
TLSv1_01TLS 1.0
TLSv1_12TLS 1.1
TLSv1_23TLS 1.2
TLSv1_34TLS 1.3

TLSConfig.TLSMode

TLS modes enforced by the gateway proxy.

NameNumberDescription
PASSTHROUGH0No TLS traffic is terminated at the gateway. Instead, the SNI string presented by the client is used to find the matching TLS route and to determine the destination service from the service registry. Then, traffic is forwarded to the destination. Note that the destination must be capable of terminating TLS traffic.
SIMPLE1Secure connections with standard TLS semantics.

Configuration constraints: If mode is set to this value, you must set either tlsConfig.secretName or both tlsConfig.files.serverCert and tlsConfig.files.privateKey.
MUTUAL2Secure connections to the downstream using mutual TLS by presenting server certificates for authentication.

Implementation notes: At least one valid certificate must be sent by the client.

Configuration constraints: If mode is set to this value, you must either set tlsConfig.secretName or set tlsConfig.files and all its subfields.
AUTO_PASSTHROUGH3Similar to the PASSTHROUGH mode, except that gateways with this TLS mode do not require an associated VirtualService to map from the SNI value to a service in the registry. The destination details such as the service, subset, and port are encoded in the SNI value. The proxy forwards to the upstream Envoy cluster a group of endpoints specified by the SNI value. This mode is typically used to provide connectivity between services in disparate L3 networks that otherwise do not have direct connectivity between their respective endpoints.

Implementation notes: If mode is set to this value, the source and destination are assumed to use Istio mTLS to secure traffic.
ISTIO_MUTUAL4Secure connections from the downstream using mutual TLS by presenting server certificates for authentication. Compared to MUTUAL mode, this mode uses certificates that represent the gateway workload identity and are automatically generated by Istio for mTLS authentication.

Configuration constraints: If mode is set to this value, tlsConfig.secretName and tlsConfig.files must not be set.