VirtualGateway
VirtualGateway API reference.
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.
Field | Description |
---|---|
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.
Field | Description |
---|---|
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:
|
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.
Field | Description |
---|---|
serverCert | (string )The path to the file that contains the server-side TLS certificate. Configuration constraints:
|
privateKey | (string )The path to the file that contains the server’s private key. Configuration constraints:
|
caCerts | (string )The path to the file that contains the certificate authority (CA) certificates for validating the client cert. Configuration constraints:
|
TLSConfig.Parameters
General TLS parameters. For more information about these values, see the Envoy docs.
Field | Description |
---|---|
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:
|
VirtualGatewayReport
The resources that the VirtualGateway selects after it is successfully applied.
Field | Description |
---|---|
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
Field | Description |
---|---|
key | (string ) |
value | (common.gloo.solo.io.Report ) |
VirtualGatewaySpec
Specifications for the VirtualGateway
resource.
Field | Description |
---|---|
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:
|
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
Field | Description |
---|---|
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:
|
tls | (TLSConfig )Configure TLS settings for a virtual host or listener. Configuration constraints:
|
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:
|
VirtualGatewaySpec.Listener.ExternalServiceFilter
Filter ExternalServices that can attach to this VirtualGateway by hostname.
Field | Description |
---|---|
host | (string )Required: The hostname to select. You can use * to match hostname patterns in multiple objects.Configuration constraints:
|
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.
Field | Description |
---|---|
host | (string )Required: The hostname to select. You can use * to match hostname patterns in multiple objects.Configuration constraints:
|
selector | (common.gloo.solo.io.ObjectSelector )Optional: Filter out RouteTables that do not match the selector. Implementation notes:
|
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.
Field | Description |
---|---|
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
Name | Number | Description |
---|---|---|
TLS_AUTO | 0 | Automatically choose the optimal TLS version. |
TLSv1_0 | 1 | TLS 1.0 |
TLSv1_1 | 2 | TLS 1.1 |
TLSv1_2 | 3 | TLS 1.2 |
TLSv1_3 | 4 | TLS 1.3 |
TLSConfig.TLSMode
TLS modes enforced by the gateway proxy.
Name | Number | Description |
---|---|---|
PASSTHROUGH | 0 | No 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. |
SIMPLE | 1 | Secure 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 . |
MUTUAL | 2 | Secure 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_PASSTHROUGH | 3 | Similar 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_MUTUAL | 4 | Secure 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. |