Project: Gloo (Orchestration & Management / API Gateway)
File: virtual_service.proto.sk.md

title: "virtual_service.proto" weight: 5 <!-- Code generated by solo-kit. DO NOT EDIT. --> Top-Level Resource 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: ```yaml apiVersion: gateway.solo.io/v1 kind: VirtualService metadata: name: 'http' namespace: 'usernamespace' spec: virtualHost: domains: '*.mydomain.com' 'mydomain.com' routes: matchers: prefix: '/' delegateAction: ref: name: 'shared-routes' namespace: 'usernamespace' ``` ```yaml apiVersion: gateway.solo.io/v1 kind: VirtualService metadata: name: 'https' namespace: 'usernamespace' spec: virtualHost: domains: '*.mydomain.com' 'mydomain.com' routes: matchers: prefix: '/' delegateAction: ref: name: 'shared-routes' namespace: 'usernamespace' sslConfig: secretRef: name: gateway-tls namespace: gloo-system ``` ```yaml 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 ```yaml "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` | | 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` | | 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` | | NamespacedStatuses indicates the validation status of this resource. NamespacedStatuses is read-only by clients, and set by gateway during validation. | | `metadata` | | Metadata contains the object metadata for this resource. | Virtual Hosts serve an ordered list of routes for a set of

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 , Gateway Virtual Hosts can delegate their routes to `RouteTables`. ```yaml "domains": []string "routes": []gateway.solo.io.Route "options": .gloo.solo.io.VirtualHostOptions "optionsConfigRefs": .gateway.solo.io.DelegateOptionsRefs ``` | Field | Type | Description | | -- | - | -- | | `domains` | `. | | `routes` | | 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` | | 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` | | 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. | 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 resources DelegateActions can be used to delegate the behavior for a set out routes with a given prefix to top-level `RouteTable` resources. ```yaml "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 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` | | Whether this route as a child should inherit headers, methods, and query parameter matchers from the

Defaults to value of parent; for virtual services (no parent) defaults to false. | | `inheritablePathMatchers` | | 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` | | 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` | | 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` | | Return an arbitrary HTTP response directly, without proxying. Only one of `directResponseAction`, `routeAction`, `redirectAction`, `delegateAction`, or `graphqlApiRef` can be set. | | `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` | | 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` | | 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` | | 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. | ```yaml "delegateOptions": []core.solo.io.ResourceRef ``` | Field | Type | Description | | -- | - | -- | | `delegateOptions` | | List of resource refs to Option CRs. | DelegateActions are used to delegate routing decisions to Route

```yaml "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` | | Delegate to the Route Table resource with the given `name` and `namespace. Only one of `ref` or `selector` can be set. | | `selector` | | Delegate to the Route Tables that match the given selector. Only one of `selector` or `ref` can be set. | Select route tables for delegation by namespace, labels, or both. ```yaml "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` | | 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. | ```yaml "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` | | The operator can only be in, notin, =, ==, !=, exists, ! (DoesNotExist), gt (GreaterThan), lt (LessThan). | | `values` | `[]string` | | 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 | <!-- Start of HubSpot Embed Code --> <script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/5130874.js"></script> <!-- End of HubSpot Embed Code -->