virtual_service.proto

Package: gateway.solo.io

Types:

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 - VirtualHostPlugins 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:
    - matcher:
        prefix: '/'
      # delegate all traffic to the `shared-routes` RouteTable
      delegateAction:
        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:
    - matcher:
        prefix: '/'
      # delegate all traffic to the `shared-routes` RouteTable
      delegateAction:
        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:
    - matcher:
        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:

Field Type Description Default
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.

"name": string
"domains": []string
"routes": []gateway.solo.io.Route
"virtualHostPlugins": .gloo.solo.io.VirtualHostPlugins
"corsPolicy": .gloo.solo.io.CorsPolicy
Field Type Description Default
name string deprecated. this field is ignored.
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.
virtualHostPlugins .gloo.solo.io.VirtualHostPlugins Virtual host plugins contain additional configuration to be applied to all traffic served by the Virtual Host. Some configuration here can be overridden by Route Plugins.
corsPolicy .gloo.solo.io.CorsPolicy Defines a CORS policy for the virtual host If a CORS policy is also defined on the route matched by the request, the policies are merged. DEPRECATED set cors policy through the Virtual Host Plugin.

Route

Routes declare the entry points on virtual hosts and the action to take for matched requests.

DelegateActions can be used to delegate the behavior for a set out routes with a given prefix to a top-level RouteTable resource.

Routes specified in the RouteTable will have their paths prefixed by the prefix provided in the parent’s matcher.

For example, the following configuration:

virtualService: mydomain.com
match: /a
delegate: a-routes
---
routeTable: a-routes
match: /1
delegate: 1-routes
match: /2
delegate: 2-routes
---
routeTable: 1-routes
match: /foo
destination: foo-svc
match: /bar
destination: bar-svc
----
routeTable: 2-routes
match: /baz
destination: baz-svc
match: /qux
destination: qux-svc
apiVersion: gateway.solo.io/v1
kind: VirtualService
metadata:
  name: 'any'
  namespace: 'any'
spec:
  virtualHost:
    domains:
    - 'any.com'
    routes:
    - matcher:
        prefix: '/a'
      delegateAction:
        name: 'a-routes'
        namespace: 'a'
apiVersion: gateway.solo.io/v1
kind: RouteTable
metadata:
  name: 'a-routes'
  namespace: 'a'
spec:
  routes:
    - matcher:
        prefix: '/1'
      delegateAction:
        name: 'one-routes'
        namespace: 'one'
    - matcher:
        prefix: '/2'
      delegateAction:
        name: 'two-routes'
        namespace: 'two'
apiVersion: gateway.solo.io/v1
kind: RouteTable
metadata:
  name: 'one-routes'
  namespace: 'one'
spec:
  routes:
    - matcher:
        prefix: '/foo'
      routeAction:
        single:
          upstream:
            name: 'foo-upstream'
    - matcher:
        prefix: '/bar'
      routeAction:
        single:
          upstream:
            name: 'bar-upstream'
apiVersion: gateway.solo.io/v1
kind: RouteTable
metadata:
  name: 'two-routes'
  namespace: 'two'
spec:
  routes:
    - matcher:
        prefix: '/baz'
      routeAction:
        single:
          upstream:
            name: 'baz-upstream'
    - matcher:
        prefix: '/qux'
      routeAction:
        single:
          upstream:
            name: 'qux-upstream'

Would produce the following route config for mydomain.com:

/a/1/foo -> foo-svc
/a/1/bar -> bar-svc
/a/2/baz -> baz-svc
/a/2/qux -> qux-svc
"matcher": .gloo.solo.io.Matcher
"routeAction": .gloo.solo.io.RouteAction
"redirectAction": .gloo.solo.io.RedirectAction
"directResponseAction": .gloo.solo.io.DirectResponseAction
"delegateAction": .core.solo.io.ResourceRef
"routePlugins": .gloo.solo.io.RoutePlugins
Field Type Description Default
matcher .gloo.solo.io.Matcher The matcher contains parameters for matching requests (i.e.: based on HTTP path, headers, etc.) For delegated routes, the matcher must contain only a prefix path matcher and no other config.
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 .core.solo.io.ResourceRef delegate routing actions for the given matcher to a RouteTable the delegateAction config is simply the name and namespace of the delegated RouteTable resource. Only one of delegateAction, routeAction, or directResponseAction can be set.
routePlugins .gloo.solo.io.RoutePlugins Route Plugins extend the behavior of routes. Route plugins include configuration such as retries, rate limiting, and request/response transformation. RoutePlugin behavior will be inherited by delegated routes which do not specify their own routePlugins.