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:

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:

"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 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.

"domains": []string
"routes": []gateway.solo.io.Route
"options": .gloo.solo.io.VirtualHostOptions

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

"matchers": []matchers.core.gloo.solo.io.Matcher
"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 Default
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, 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 .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 Default
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 reforselector` 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>

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