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
"namespacedStatuses": .core.solo.io.NamespacedStatuses
"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.
namespacedStatuses .core.solo.io.NamespacedStatuses NamespacedStatuses indicates the validation status of this resource. NamespacedStatuses is read-only by clients, and set by gateway 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
"optionsConfigRefs": .gateway.solo.io.DelegateOptionsRefs

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.
optionsConfigRefs .gateway.solo.io.DelegateOptionsRefs Delegate the VirtualHost options to an external VirtualHostOption Resource. Any options configured in the VirtualHost’s options field will override all delegated options. If multiple VirtualHostOption CRs are delegated to, configuration will be taken from prior VirtualHostOption CRs over later ones. For example if headerManipulation is specified on the VirtualHost options, a delegated VirtualHostOption vhost-opt-1, and a second delegated VirtualHostOption vhost-opt-2, the headerManipulation config from only the VirtualHost-level options will be applied. If the config is removed from the VirtualHost-level options field, then the config from the first delegated VirtualHostOption, vhost-opt-1, is applied.

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
"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
"graphqlApiRef": .core.solo.io.ResourceRef
"options": .gloo.solo.io.RouteOptions
"name": string
"optionsConfigRefs": .gateway.solo.io.DelegateOptionsRefs

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, directResponseAction, delegateAction, or graphqlApiRef 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, directResponseAction, delegateAction, or graphqlApiRef can be set.
directResponseAction .gloo.solo.io.DirectResponseAction Return an arbitrary HTTP response directly, without proxying. Only one of directResponseAction, routeAction, redirectAction, delegateAction, or graphqlApiRef 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, redirectAction, directResponseAction, or graphqlApiRef can be set.
graphqlApiRef .core.solo.io.ResourceRef Enterprise-Only: THIS FEATURE IS IN TECH PREVIEW. APIs are versioned as alpha and subject to change. A reference to a GraphQLApi CR. Resolution of the client request to upstream(s) will be delegated to the resolution policies defined in the GraphQLApi CR. If configured, the graphql filter will operate instead of the envoy router filter, so configuration (such as retries) that applies to the router filter will not be applied. Only one of graphqlApiRef, routeAction, redirectAction, directResponseAction, or delegateAction 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.
optionsConfigRefs .gateway.solo.io.DelegateOptionsRefs Delegate the Route options to an external RouteOption Resource. Any options configured in the Route’s options field will override all delegated options. If multiple RouteOption CRs are delegated to, configuration will be taken from prior RouteOption CRs over later ones. For example if headerManipulation is specified on the route options, a delegated RouteOption route-opt-1, and a second delegated RouteOption route-opt-2, the headerManipulation config from only the Route-level options will be applied. If the config is removed from the Route-level options field, then the config from the first delegated RouteOption, route-opt-1, is applied.

DelegateOptionsRefs

"delegateOptions": []core.solo.io.ResourceRef

Field Type Description
delegateOptions []core.solo.io.ResourceRef List of resource refs to Option CRs.

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 ref field. If name and/or namespace have been specified, Gloo will ignore ref 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 ref field. If name and/or namespace have been specified, Gloo will ignore ref 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>
"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