virtual_service.proto
Package: gateway.solo.io
Types:
- VirtualService Top-Level Resource
- VirtualHost
- Route
- DelegateAction
- RouteTableSelector
- Expression
- Operator
Source File: github.com/solo-io/gloo/projects/gateway/api/v1/virtual_service.proto
VirtualService
The VirtualService is the root routing object for the Gloo Gateway. A virtual service describes the set of routes to match for a set of domains.
It defines:
- a set of domains
- the root set of routes for those domains
- an optional SSL configuration for server TLS Termination
- VirtualHostOptions that will apply configuration to all routes that live on the VirtualService.
Domains must be unique across all virtual services within a gateway (i.e. no overlap between sets).
VirtualServices can delegate routing behavior to the RouteTable resource by using the delegateAction
on routes.
An example configuration using two VirtualServices (one with TLS termination and one without) which share a RouteTable looks as follows:
# HTTP VirtualService:
apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
name: 'http'
namespace: 'usernamespace'
spec:
virtualHost:
domains:
- '*.mydomain.com'
- 'mydomain.com'
routes:
- matchers:
- prefix: '/'
# delegate all traffic to the `shared-routes` RouteTable
delegateAction:
ref:
name: 'shared-routes'
namespace: 'usernamespace'
# HTTPS VirtualService:
apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
name: 'https'
namespace: 'usernamespace'
spec:
virtualHost:
domains:
- '*.mydomain.com'
- 'mydomain.com'
routes:
- matchers:
- prefix: '/'
# delegate all traffic to the `shared-routes` RouteTable
delegateAction:
ref:
name: 'shared-routes'
namespace: 'usernamespace'
sslConfig:
secretRef:
name: gateway-tls
namespace: gloo-system
# the RouteTable shared by both VirtualServices:
apiVersion: gateway.solo.io/v1
kind: RouteTable
metadata:
name: 'shared-routes'
namespace: 'usernamespace'
spec:
routes:
- matchers:
- prefix: '/some-route'
routeAction:
single:
upstream:
name: 'some-upstream'
...
Delegated Routes are routes that use the delegateAction
routing action. Delegated Routes obey the following
constraints:
- delegate routes must use
prefix
path matchers - delegated routes cannot specify header, query, or methods portion of the normal route matcher.
routeOptions
configuration will be inherited from parent routes, but can be overridden by the child
"virtualHost": .gateway.solo.io.VirtualHost
"sslConfig": .gloo.solo.io.SslConfig
"displayName": string
"status": .core.solo.io.Status
"metadata": .core.solo.io.Metadata
Field | Type | Description |
---|---|---|
virtualHost |
.gateway.solo.io.VirtualHost | The VirtualHost contains the The list of HTTP routes define routing actions to be taken for incoming HTTP requests whose host header matches this virtual host. If the request matches more than one route in the list, the first route matched will be selected. If the list of routes is empty, the virtual host will be ignored by Gloo. |
sslConfig |
.gloo.solo.io.SslConfig | If provided, the Gateway will serve TLS/SSL traffic for this set of routes. |
displayName |
string |
Display only, optional descriptive name. Unlike metadata.name, DisplayName can be any string and can be changed after creating the resource. |
status |
.core.solo.io.Status | Status indicates the validation status of this resource. Status is read-only by clients, and set by gloo during validation. |
metadata |
.core.solo.io.Metadata | Metadata contains the object metadata for this resource. |
VirtualHost
Virtual Hosts serve an ordered list of routes for a set of domains.
An HTTP request is first matched to a virtual host based on its host header, then to a route within the virtual host.
If a request is not matched to any virtual host or a route therein, the target proxy will reply with a 404.
Unlike the Gloo Virtual Host,
Gateway* Virtual Hosts can **delegate** their routes to RouteTables
.
"domains": []string
"routes": []gateway.solo.io.Route
"options": .gloo.solo.io.VirtualHostOptions
Field | Type | Description |
---|---|---|
domains |
[]string |
The list of domains (i.e.: matching the Host header of a request) that belong to this virtual host. Note that the wildcard will not match the empty string. e.g. “-bar.foo.com” will match “baz-bar.foo.com” but not “-bar.foo.com”. Additionally, a special entry “” is allowed which will match any host/authority header. Only a single virtual host on a gateway can match on “*”. A domain must be unique across all virtual hosts on a gateway or the config will be invalidated by Gloo Domains on virtual hosts obey the same rules as Envoy Virtual Hosts. |
routes |
[]gateway.solo.io.Route | The list of HTTP routes define routing actions to be taken for incoming HTTP requests whose host header matches this virtual host. If the request matches more than one route in the list, the first route matched will be selected. If the list of routes is empty, the virtual host will be ignored by Gloo. |
options |
.gloo.solo.io.VirtualHostOptions | Virtual host options contain additional configuration to be applied to all traffic served by the Virtual Host. Some configuration here can be overridden by Route Options. |
Route
A route specifies how to match a request and what action to take when the request is matched.
When a request matches on a route, the route can perform one of the following actions:
- Route the request to a destination
- Reply with a Direct Response
- Send a Redirect response to the client
- Delegate the action for the request to one or more top-level
RouteTable
resources DelegateActions can be used to delegate the behavior for a set out routes with a given prefix to top-levelRouteTable
resources.
"matchers": []matchers.core.gloo.solo.io.Matcher
"inheritableMatchers": .google.protobuf.BoolValue
"inheritablePathMatchers": .google.protobuf.BoolValue
"routeAction": .gloo.solo.io.RouteAction
"redirectAction": .gloo.solo.io.RedirectAction
"directResponseAction": .gloo.solo.io.DirectResponseAction
"delegateAction": .gateway.solo.io.DelegateAction
"options": .gloo.solo.io.RouteOptions
"name": string
Field | Type | Description |
---|---|---|
matchers |
[]matchers.core.gloo.solo.io.Matcher | Matchers contain parameters for matching requests (i.e., based on HTTP path, headers, etc.). If empty, the route will match all requests (i.e, a single “/” path prefix matcher). For delegated routes, any parent matcher must have a prefix path matcher. |
inheritableMatchers |
.google.protobuf.BoolValue | Whether this route as a child should inherit headers, methods, and query parameter matchers from the parent. Defaults to value of parent; for virtual services (no parent) defaults to false. |
inheritablePathMatchers |
.google.protobuf.BoolValue | Whether this route as a child should inherit path matchers (i.e., path itself, case-sensitive setting) from the parent. Defaults to value of parent; for virtual services (no parent) defaults to false. |
routeAction |
.gloo.solo.io.RouteAction | This action is the primary action to be selected for most routes. The RouteAction tells the proxy to route requests to an upstream. Only one of routeAction , redirectAction , or delegateAction can be set. |
redirectAction |
.gloo.solo.io.RedirectAction | Redirect actions tell the proxy to return a redirect response to the downstream client. Only one of redirectAction , routeAction , or delegateAction can be set. |
directResponseAction |
.gloo.solo.io.DirectResponseAction | Return an arbitrary HTTP response directly, without proxying. Only one of directResponseAction , routeAction , or delegateAction can be set. |
delegateAction |
.gateway.solo.io.DelegateAction | Delegate routing actions for the given matcher to one or more RouteTables. Only one of delegateAction , routeAction , or directResponseAction can be set. |
options |
.gloo.solo.io.RouteOptions | Route Options extend the behavior of routes. Route options include configuration such as retries, rate limiting, and request/response transformation. RouteOption behavior will be inherited by delegated routes which do not specify their own options . |
name |
string |
The name provides a convenience for users to be able to refer to a route by name. |
DelegateAction
DelegateActions are used to delegate routing decisions to Route Tables.
"name": string
"namespace": string
"ref": .core.solo.io.ResourceRef
"selector": .gateway.solo.io.RouteTableSelector
Field | Type | Description |
---|---|---|
name |
string |
The name of the Route Table to delegate to. Deprecated: these fields have been added for backwards-compatibility. Please use the single field. If name and/or namespace have been specified, Gloo will ignore single and selector . |
namespace |
string |
The namespace of the Route Table to delegate to. Deprecated: these fields have been added for backwards-compatibility. Please use the single field. If name and/or namespace have been specified, Gloo will ignore single and selector . |
ref |
.core.solo.io.ResourceRef | Delegate to the Route Table resource with the given name and namespace. Only one of refor selector` can be set. | |
selector |
.gateway.solo.io.RouteTableSelector | Delegate to the Route Tables that match the given selector. Only one of selector or ref can be set. |
RouteTableSelector
Select route tables for delegation by namespace, labels, or both.
"namespaces": []string
"labels": map<string, string>
"expressions": []gateway.solo.io.RouteTableSelector.Expression
Field | Type | Description |
---|---|---|
namespaces |
[]string |
Delegate to Route Tables in these namespaces. If omitted, Gloo will only select Route Tables in the same namespace as the resource (Virtual Service or Route Table) that owns this selector. The reserved value “*” can be used to select Route Tables in all namespaces watched by Gloo. |
labels |
map<string, string> |
Delegate to Route Tables whose labels match the ones specified here. |
expressions |
[]gateway.solo.io.RouteTableSelector.Expression | Expressions allow for more flexible Route Tables label matching, such as equality-based requirements, set-based requirements, or a combination of both. https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#equality-based-requirement. |
Expression
"key": string
"operator": .gateway.solo.io.RouteTableSelector.Expression.Operator
"values": []string
Field | Type | Description |
---|---|---|
key |
string |
Kubernetes label key, must conform to Kubernetes syntax requirements https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set. |
operator |
.gateway.solo.io.RouteTableSelector.Expression.Operator | The operator can only be in, notin, =, ==, !=, exists, ! (DoesNotExist), gt (GreaterThan), lt (LessThan). |
values |
[]string |
Operator
Route Table Selector expression operator, while the set-based syntax differs from Kubernetes (kubernetes: key: !mylabel
, gloo: key: mylabel, operator: "!"
| kubernetes: key: mylabel
, gloo: key: mylabel, operator: exists
), the functionality remains the same.
Name | Description |
---|---|
Equals |
= |
DoubleEquals |
== |
NotEquals |
!= |
In |
in |
NotIn |
notin |
Exists |
exists |
DoesNotExist |
! |
GreaterThan |
gt |
LessThan |
lt |