proxy.proto
Package: gloo.solo.io
Types:
- Proxy Top-Level Resource
- Listener
- HttpListener
- VirtualHost
- Route
- Matcher
- HeaderMatcher
- QueryParameterMatcher
- RouteAction
- Destination
- UpstreamGroup Top-Level Resource
- MultiDestination
- WeightedDestination
- RedirectAction
- RedirectResponseCode
- DirectResponseAction
- CorsPolicy
Source File: github.com/solo-io/gloo/projects/gloo/api/v1/proxy.proto
Proxy
A Proxy is a container for the entire set of configuration that will to be applied to one or more Proxy instances. Proxies can be understood as a set of listeners, represents a different bind address/port where the proxy will listen for connections. Each listener has its own set of configuration.
If any of the sub-resources within a listener is declared invalid (e.g. due to invalid user configuration), the proxy will be marked invalid by Gloo.
Proxy instances that register with Gloo are assigned the proxy configuration corresponding with
a proxy-specific identifier.
In the case of Envoy, proxy instances are identified by their Node ID. Node IDs must match a existing Proxy
Node ID can be specified in Envoy with the --service-node flag, or in the Envoy instance’s bootstrap config.
"listeners": []gloo.solo.io.Listener
"status": .core.solo.io.Status
"metadata": .core.solo.io.Metadata| Field | Type | Description | Default |
|---|---|---|---|
listeners |
[]gloo.solo.io.Listener | Define here each listener the proxy should create. Listeners define the a set of behaviors for a single bind address/port where the proxy will listen If no listeners are specified, the instances configured with the proxy resource will not accept connections. | |
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 |
Listener
Listeners define the address:port where the proxy will listen for incoming connections A Listener accepts connections (currently only HTTP is supported) and apply user-defined behavior for those connections, e.g. performing SSL termination, HTTP retries, and rate limiting.
"name": string
"bindAddress": string
"bindPort": int
"httpListener": .gloo.solo.io.HttpListener
"sslConfiguations": []gloo.solo.io.SslConfig
"useProxyProto": .google.protobuf.BoolValue| Field | Type | Description | Default |
|---|---|---|---|
name |
string |
the name of the listener. names must be unique for each listener within a proxy | |
bindAddress |
string |
the bind address for the listener. both ipv4 and ipv6 formats are supported | |
bindPort |
int |
the port to bind on ports numbers must be unique for listeners within a proxy | |
httpListener |
.gloo.solo.io.HttpListener | The HTTP Listener is currently the only supported listener type. It contains configuration options for GLoo’s HTTP-level features including request-based routing | |
sslConfiguations |
[]gloo.solo.io.SslConfig | SSL Config is optional for the listener. If provided, the listener will serve TLS for connections on this port Multiple SslConfigs are supported for the pupose of SNI. Be aware that the SNI domain provided in the SSL Config must match a domain in virtual host TODO(ilackarms): ensure that ssl configs without a matching virtual host are errored | |
useProxyProto |
.google.protobuf.BoolValue | Enable ProxyProtocol support for this listener |
HttpListener
Use this listener to configure proxy behavior for any HTTP-level features including defining routes (via virtualservices). HttpListeners also contain plugin configuration that applies globally across all virtaul hosts on the listener. Some plugins can be configured to work both on the listener and virtual host level (such as the rate limit plugin)
"virtualHosts": []gloo.solo.io.VirtualHost
"listenerPlugins": .gloo.solo.io.ListenerPlugins| Field | Type | Description | Default |
|---|---|---|---|
virtualHosts |
[]gloo.solo.io.VirtualHost | the set of virtual hosts that will be accessible by clients connecting to this listener. at least one virtual host must be specified for this listener to be active (else connections will be refused) the set of domains for each virtual host must be unique, or the config will be considered invalid | |
listenerPlugins |
.gloo.solo.io.ListenerPlugins | Plugins contains top-level plugin configuration to be applied to a listener Listener config is applied to all HTTP traffic that connects to this listener. Some configuration here can be overridden in Virtual Host Plugin configuration or Route Plugin configuration Plugins should be specified here in the form of "plugin_name": {..//plugin_config...} to allow specifying multiple plugins. |
VirtualHost
Virtual Hosts group an ordered list of routes under one or more domains. Each Virtual Host has a logical name, which must be unique for the listener. 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.
"name": string
"domains": []string
"routes": []gloo.solo.io.Route
"virtualHostPlugins": .gloo.solo.io.VirtualHostPlugins
"corsPolicy": .gloo.solo.io.CorsPolicy| Field | Type | Description | Default |
|---|---|---|---|
name |
string |
the logical name of the virtual host. names must be unique for each virtual host within a listener | |
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 in the entire route configuration can match on “*”. A domain must be unique across all virtual hosts or the config will be invalidated by Gloo Domains on virtual hosts obey the same rules as Envoy Virtual Hosts |
|
routes |
[]gloo.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 | Plugins contains top-level plugin configuration to be applied to a listener Listener config is applied to all HTTP traffic that connects to this listener. Some configuration here can be overridden in Virtual Host Plugin configuration or Route Plugin configuration Plugins should be specified here in the form of "plugin_name": {..//plugin_config...} to allow specifying multiple plugins. |
|
corsPolicy |
.gloo.solo.io.CorsPolicy | CorsPolicy defines Cross-Origin Resource Sharing for a virtual service. |
Route
* Routes declare the entrypoints on virtual hosts and the action to take for matched requests.
"matcher": .gloo.solo.io.Matcher
"routeAction": .gloo.solo.io.RouteAction
"redirectAction": .gloo.solo.io.RedirectAction
"directResponseAction": .gloo.solo.io.DirectResponseAction
"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.) | |
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. | |
redirectAction |
.gloo.solo.io.RedirectAction | Redirect actions tell the proxy to return a redirect response to the downstream client | |
directResponseAction |
.gloo.solo.io.DirectResponseAction | Return an arbitrary HTTP response directly, without proxying. | |
routePlugins |
.gloo.solo.io.RoutePlugins | Route Plugins extend the behavior of routes. Route plugins include configuration such as retries, rate limiting, and request/resonse transformation. Plugins should be specified here in the form of "plugin_name": {..//plugin_config...} to allow specifying multiple plugins. |
Matcher
Parameters for matching routes to requests received by a Gloo-managed proxy
"prefix": string
"exact": string
"regex": string
"headers": []gloo.solo.io.HeaderMatcher
"queryParameters": []gloo.solo.io.QueryParameterMatcher
"methods": []string| Field | Type | Description | Default |
|---|---|---|---|
prefix |
string |
If specified, the route is a prefix rule meaning that the prefix must match the beginning of the :path header. | |
exact |
string |
If specified, the route is an exact path rule meaning that the path must exactly match the :path header once the query string is removed. | |
regex |
string |
If specified, the route is a regular expression rule meaning that the regex must match the :path header once the query string is removed. The entire path (without the query string) must match the regex. The rule will not match if only a subsequence of the :path header matches the regex. The regex grammar is defined here <http://en.cppreference.com/w/cpp/regex/ecmascript>_. Examples: * The regex /b[io]t matches the path /bit * The regex /b[io]t matches the path /bot * The regex /b[io]t does not match the path /bite * The regex /b[io]t does not match the path /bit/bot |
|
headers |
[]gloo.solo.io.HeaderMatcher | Specifies a set of headers that the route should match on. The router will check the request’s headers against all the specified headers in the route config. A match will happen if all the headers in the route are present in the request with the same values (or based on presence if the value field is not in the config). | |
queryParameters |
[]gloo.solo.io.QueryParameterMatcher | Specifies a set of URL query parameters on which the route should match. The router will check the query string from the path header against all the specified query parameters. If the number of specified query parameters is nonzero, they all must match the path header’s query string for a match to occur. | |
methods |
[]string |
HTTP Method/Verb(s) to match on. If none specified, the matcher will ignore the HTTP Method |
HeaderMatcher
Internally, Gloo always uses the HTTP/2 :authority header to represent the HTTP/1 Host header. Thus, if attempting to match on Host, match on :authority instead.
In the absence of any header match specifier, match will default to present_match
i.e, a request that has the name header will match, regardless of the header’s
value.
"name": string
"value": string
"regex": bool| Field | Type | Description | Default |
|---|---|---|---|
name |
string |
Specifies the name of the header in the request. | |
value |
string |
Specifies the value of the header. If the value is absent a request that has the name header will match, regardless of the header’s value. | |
regex |
bool |
Specifies whether the header value should be treated as regex or not. |
QueryParameterMatcher
Query parameter matching treats the query string of a request’s :path header as an ampersand-separated list of keys and/or key=value elements.
"name": string
"value": string
"regex": bool| Field | Type | Description | Default |
|---|---|---|---|
name |
string |
Specifies the name of a key that must be present in the requested path’s query string. | |
value |
string |
Specifies the value of the key. If the value is absent, a request that contains the key in its query string will match, whether the key appears with a value (e.g., “?debug=true”) or not (e.g., “?debug”) | |
regex |
bool |
Specifies whether the query parameter value is a regular expression. Defaults to false. The entire query parameter value (i.e., the part to the right of the equals sign in “key=value”) must match the regex. E.g., the regex “\d+$” will match “123” but not “a123” or “123a”. |
RouteAction
RouteActions are used to route matched requests to upstreams.
"single": .gloo.solo.io.Destination
"multi": .gloo.solo.io.MultiDestination
"upstreamGroup": .core.solo.io.ResourceRef| Field | Type | Description | Default |
|---|---|---|---|
single |
.gloo.solo.io.Destination | Use SingleDestination to route to a single upstream | |
multi |
.gloo.solo.io.MultiDestination | Use MultiDestination to load balance requests between multiple upstreams (by weight) | |
upstreamGroup |
.core.solo.io.ResourceRef | Use a reference to an upstream group for routing. |
Destination
Destinations define routable destinations for proxied requests
"upstream": .core.solo.io.ResourceRef
"destinationSpec": .gloo.solo.io.DestinationSpec
"subset": .gloo.solo.io.Subset| Field | Type | Description | Default |
|---|---|---|---|
upstream |
.core.solo.io.ResourceRef | The upstream to route requests to | |
destinationSpec |
.gloo.solo.io.DestinationSpec | Some upstreams utilize plugins which require or permit additional configuration on routes targeting them. gRPC upstreams, for example, allow specifying REST-style parameters for JSON-to-gRPC transcoding in the destination config. If the destination config is required for the upstream and not provided by the user, Gloo will invalidate the destination and its parent resources. | |
subset |
.gloo.solo.io.Subset | If specified, traffic will only be routed to a subset of the upstream. If upstream doesn’t contain the specified subset, we will fallback to normal upstream routing. |
UpstreamGroup
"destinations": []gloo.solo.io.WeightedDestination
"status": .core.solo.io.Status
"metadata": .core.solo.io.Metadata| Field | Type | Description | Default |
|---|---|---|---|
destinations |
[]gloo.solo.io.WeightedDestination | The destinations that are part of this upstream group. | |
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 |
MultiDestination
MultiDestination is a container for a set of weighted destinations. Gloo will load balance traffic for a single route across multiple destinations according to their specified weights.
"destinations": []gloo.solo.io.WeightedDestination| Field | Type | Description | Default |
|---|---|---|---|
destinations |
[]gloo.solo.io.WeightedDestination | This list must contain at least one destination or the listener housing this route will be invalid, causing Gloo to error the parent proxy resource. |
WeightedDestination
WeightedDestination attaches a weight to a single destination.
"destination": .gloo.solo.io.Destination
"weight": int| Field | Type | Description | Default |
|---|---|---|---|
destination |
.gloo.solo.io.Destination | ||
weight |
int |
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 |
RedirectAction
TODO(ilackarms): evaluate how much to differentiate (or if even to include) RedirectAction Notice: RedirectAction is copioed directly from https://github.com/envoyproxy/envoy/blob/master/api/envoy/api/v2/route/route.proto
"hostRedirect": string
"pathRedirect": string
"prefixRewrite": string
"responseCode": .gloo.solo.io.RedirectAction.RedirectResponseCode
"httpsRedirect": bool
"stripQuery": bool| Field | Type | Description | Default |
|---|---|---|---|
hostRedirect |
string |
The host portion of the URL will be swapped with this value. | |
pathRedirect |
string |
The path portion of the URL will be swapped with this value. | |
prefixRewrite |
string |
Indicates that during redirection, the matched prefix (or path) should be swapped with this value. This option allows redirect URLs be dynamically created based on the request. Pay attention to the use of trailing slashes as mentioned in RouteAction’s prefix_rewrite. |
|
responseCode |
.gloo.solo.io.RedirectAction.RedirectResponseCode | The HTTP status code to use in the redirect response. The default response code is MOVED_PERMANENTLY (301). | |
httpsRedirect |
bool |
The scheme portion of the URL will be swapped with “https”. | |
stripQuery |
bool |
Indicates that during redirection, the query portion of the URL will be removed. Default value is false. |
RedirectResponseCode
| Name | Description |
|---|---|
MOVED_PERMANENTLY |
Moved Permanently HTTP Status Code - 301. |
FOUND |
Found HTTP Status Code - 302. |
SEE_OTHER |
See Other HTTP Status Code - 303. |
TEMPORARY_REDIRECT |
Temporary Redirect HTTP Status Code - 307. |
PERMANENT_REDIRECT |
Permanent Redirect HTTP Status Code - 308. |
DirectResponseAction
TODO(ilackarms): evaluate how much to differentiate (or if even to include) DirectResponseAction DirectResponseAction is copied directly from https://github.com/envoyproxy/envoy/blob/master/api/envoy/api/v2/route/route.proto
"status": int
"body": string| Field | Type | Description | Default |
|---|---|---|---|
status |
int |
Specifies the HTTP response status to be returned. | |
body |
string |
Specifies the content of the response body. If this setting is omitted, no body is included in the generated response. Note: Headers can be specified using the Header Modification plugin in the enclosing Route, Virtual Host, or Listener. |
CorsPolicy
CorsPolicy defines Cross-Origin Resource Sharing for a virtual service.
"allowOrigin": []string
"allowOriginRegex": []string
"allowMethods": []string
"allowHeaders": []string
"exposeHeaders": []string
"maxAge": string
"allowCredentials": bool| Field | Type | Description | Default |
|---|---|---|---|
allowOrigin |
[]string |
Specifies the origins that will be allowed to make CORS requests. An origin is allowed if either allow_origin or allow_origin_regex match. | |
allowOriginRegex |
[]string |
Specifies regex patterns that match origins that will be allowed to make CORS requests. An origin is allowed if either allow_origin or allow_origin_regex match. | |
allowMethods |
[]string |
Specifies the content for the access-control-allow-methods header. | |
allowHeaders |
[]string |
Specifies the content for the access-control-allow-headers header. | |
exposeHeaders |
[]string |
Specifies the content for the access-control-expose-headers header. | |
maxAge |
string |
Specifies the content for the access-control-max-age header. | |
allowCredentials |
bool |
Specifies whether the resource allows credentials. |