Skip to content

Virtual Services

Contents

Top

VirtualService

Virtual Services represent a collection of routes for a set of domains. Gloo's Virtual Services can be compared to virtual hosts in Envoy terminology. A virtual service can be used to define "apps"; a collection of APIs that belong to a particular domain. The Virtual Service concept allows configuration of per-virtualservice SSL certificates

name: string
domains: [string]
routes: [{Route}]
ssl_config: {SSLConfig}
disable_for_gateways: bool
status: (read only)
metadata: {Metadata}

Field Type Label Description
name string Name of the virtual service. Names must be unique and follow the following syntax rules: One or more lowercase rfc1035/rfc1123 labels separated by '.' with a maximum length of 253 characters.
domains string repeated Domains represent the list of domains (host/authority header) that will match for all routes on this virtual service. As in Envoy: wildcard hosts are supported in the form of “.foo.com” or “-bar.foo.com”. If domains is empty, gloo will set the domain to "", making that virtual service the "default" virtualservice. The default virtualservice will be the fallback virtual service for all requests that do not match a domain on an existing virtual service. Only one default virtual service can be defined (either with an empty domain list, or a domain list that includes "")
routes Route repeated Routes define the list of routes that live on this virtual service.
ssl_config SSLConfig SSL Config is optional for the virtual service. If provided, the virtual service will listen on the envoy HTTPS listener port (default :8443) If left empty, the virtual service will listen on the HTTP listener port (default :8080)
disable_for_gateways bool indicates whether or not this virtual service should be assigned to gateway roles automatically TODO: eventually this flag will be deprecated; gateway roles will have to explicitly state the virtual services they have access to.
status Status Status indicates the validation status of the virtual service resource. Status is read-only by clients, and set by gloo during validation
metadata Metadata Metadata contains the resource metadata for the virtual service

Route

Routes declare the entrypoints on virtual services and the upstreams or functions they route requests to

request_matcher: {RequestMatcher}
event_matcher: {EventMatcher}
multiple_destinations: [{WeightedDestination}]
single_destination: {Destination}
prefix_rewrite: string
extensions: {google.protobuf.Struct}

Field Type Label Description
request_matcher RequestMatcher request_matcher indicates this route should match requests according to the specification in the provided RequestMatcher only one of request_matcher or event_matcher can be set
event_matcher EventMatcher eventt_matcher indicates this route should match requests according to the specification in the provided EventMatcher only one of request_matcher or event_matcher can be set
multiple_destinations WeightedDestination repeated A route is only allowed to specify one of multiple_destinations or single_destination. Setting both will result in an error Multiple Destinations is used when a user wants a route to balance requests between multiple destinations Balancing is done by probability, where weights are specified for each destination
single_destination Destination A single destination is specified when a route only routes to a single destination.
prefix_rewrite string PrefixRewrite can be specified to rewrite the matched path of the request path to a new prefix
extensions google.protobuf.Struct Extensions provides a way to extend the behavior of a route. In addition to the core route extensions<!--(TODO)-->, gloo provides the means for route plugins<!--(TODO)--> to be added to gloo which add new types of route extensions. <!--See the route extensions section for a more detailed explanation-->

RequestMatcher

Request Matcher is a route matcher for traditional http requests Request Matchers stand in juxtoposition to Event Matchers, which match "events" rather than HTTP Requests

path_prefix: string
path_regex: string
path_exact: string
headers: map<string,string>
query_params: map<string,string>
verbs: [string]

Field Type Label Description
path_prefix string Prefix will match any request whose path begins with this prefix Only one of path_prefix, path_regex, or path_exact can be set
path_regex string Regex will match any path that matches this regex string Only one of path_prefix, path_regex, or path_exact can be set
path_exact string Exact will match only requests with exactly this path Only one of path_prefix, path_regex, or path_exact can be set
headers map<string,string> Headers specify a list of request headers and their values the request must contain to match this route If a value is not specified (empty string) for a header, all values will match so long as the header is present on the request
query_params map<string,string> Query params work the same way as headers, but for query string parameters
verbs string repeated HTTP Verb(s) to match on. If none specified, the matcher will match all verbs

EventMatcher

Event matcher is a special kind of matcher for CloudEvents The CloudEvents API is described here: https://github.com/cloudevents/spec/blob/master/spec.md

event_type: string

Field Type Label Description
event_type string Event Type indicates the event type or topic to match

WeightedDestination

WeightedDestination attaches a weight to a destination For use in routes with multiple destinations

destination: {Destination}
weight: uint32

Field Type Label Description
destination Destination
weight uint32 Weight must be greater than zero Routing to each destination will be balanced by the ratio of the destination's weight to the total weight on a route

Destination

Destination is a destination that requests can be routed to.

function: {FunctionDestination}
upstream: {UpstreamDestination}

Field Type Label Description
function FunctionDestination function indicates requests sent to this destination will invoke a function Only one of funtion or upstream should be set
upstream UpstreamDestination upstream indicates requests sent to this destination will be routed to an upstream Only one of funtion or upstream should be set

FunctionDestination

FunctionDestination will route a request to a specific function defined for an upstream

upstream_name: string
function_name: string

Field Type Label Description
upstream_name string Upstream Name is the name of the upstream the function belongs to
function_name string Function Name is the name of the function as defined on the upstream

UpstreamDestination

Upstream Destination routes a request to an upstream

name: string

Field Type Label Description
name string Name of the upstream

SSLConfig

SSLConfig contains the options necessary to configure a virtualservice or listener to use TLS

secret_ref: string
ssl_files: {SSLFiles}
sni_domains: [string]

Field Type Label Description
secret_ref string SecretRef contains the secret ref to a gloo secret containing the following structure: { "tls.crt": <ca chain data...>, "tls.key": <private key data...> }
ssl_files SSLFiles SSLFiles reference paths to certificates which are local to the proxy
sni_domains string repeated optional. the SNI domains that should be considered for TLS connections

SSLFiles

SSLFiles reference paths to certificates which can be read by the proxy off of its local filesystem

tls_cert: string
tls_key: string
root_ca: string

Field Type Label Description
tls_cert string
tls_key string
root_ca string for client cert validation. optional