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.
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.
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.
contains configuration options for Gloo’s HTTP-level features including request-based routing. Only one of httpListener, tcpListener, hybridListener, or aggregateListener can be set.
contains any number of configuration options for Gloo’s HTTP and/or TCP-level features. Only one of hybridListener, httpListener, tcpListener, or aggregateListener can be set.
contains any number of configuration options for Gloo’s HTTP and/or TCP-level features avoids duplicating definitions by separating resources and relationships between resources. Only one of aggregateListener, httpListener, tcpListener, or hybridListener can be set.
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 purpose of SNI. Be aware that the SNI domain provided in the SSL Config. This is set to the aggregated list of SslConfigs that are defined on the selected VirtualServices.
Enable ProxyProtocol support for this listener. Deprecated: prefer setting the listener option. If configured, the listener option (filter config) overrides any setting here.
Metadata for the individual route This data is opaque to Gloo, used by controllers to track ownership of routes within a proxy as they are typically generated by a controller (such as the gateway) Deprecated: prefer the any field below. Only one of metadata or metadataStatic can be set.
Options contains top-level configuration to be applied to a listener. Listener config is applied to traffic for the given listener. Some configuration here can be overridden in Virtual Host Options configuration or Route Options configuration.
statPrefix
string
prefix for addressing envoy stats for the tcp proxy.
Use MultiDestination to load balance requests between multiple upstreams (by weight). Only one of multi, single, upstreamGroup, or forwardSniClusterName can be set.
Use this listener to configure proxy behavior for any HTTP-level features including defining routes (via virtual services).
HttpListeners also contain optional configuration that applies globally across all virtual hosts on the listener.
Some traffic policies can be configured to work both on the listener and virtual host level (e.g., the rate limit feature)
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.
HttpListenerOptions contains optional top-level configuration to be applied to a listener. Listener config is applied to traffic for the given listener. Some configuration here can be overridden in VirtualHostOptions configuration, RouteOptions configuration, or WeightedDestinationOptions configuration.
statPrefix
string
prefix for addressing envoy stats for the http connection manager.
Matchers are used to define unique matching criteria for each MatchedListener Each MatchedListener within a HybridListener must have a unique Matcher If multiple matchers in a HybridListener are identical, the HybridListener will not be accepted Empty Matchers are effectively catch-alls, and there can be no more than one empty Matcher per HybridListener.
SSL Config is optional for the MatchedListener. If provided, the listener will serve TLS for connections. Multiple SslConfigs are supported for the purpose of SNI. Be aware that the SNI domain provided in the SSL Config. This is set to the aggregated list of SslConfigs that are defined on the selected VirtualServices.
Matching criteria used to generate both the FilterChainMatch and TransportSocket for the Envoy FilterChain.
httpOptionsRef
string
The ref pointing to HttpListenerOptions which are used to configure the HCM on this HttpFilterChain Corresponds to an entry in the HttpResources.HttpOptions map.
virtualHostRefs
[]string
The set of refs pointing to VirtualHosts which are available on this HttpFilterChain Each ref corresponds to an entry in the HttpResources.VirtualHosts map.
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 http 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.
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.
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.
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.
Metadata for the individual route This data is opaque to Gloo, used by controllers to track ownership of routes within a proxy as they are typically generated by a controller (such as the gateway) Deprecated: prefer the any field below. Only one of metadata or metadataStatic can be set.
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).
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, or graphqlApiRef can be set.
Redirect actions tell the proxy to return a redirect response to the downstream client. Only one of redirectAction, routeAction, directResponseAction, or graphqlApiRef can be set.
Return an arbitrary HTTP response directly, without proxying. Only one of directResponseAction, routeAction, redirectAction, or graphqlApiRef can be set.
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, or directResponseAction can be set.
Metadata for the individual route This data is opaque to Gloo, used by controllers to track ownership of routes within a proxy as they are typically generated by a controller (such as the gateway) Deprecated: prefer the any field below. Only one of metadata or metadataStatic can be set.
Inline metadata used by gloo controller to track ownership. Only one of metadataStatic or metadata can be set.
name
string
The name provides a convenience for users to be able to refer to a route by name. It includes names of vs, route, and route table ancestors of the route.
RouteAction
RouteActions are used to route matched requests to upstreams.
Use MultiDestination to load balance requests between multiple upstreams (by weight). Only one of multi, single, upstreamGroup, clusterHeader, or dynamicForwardProxy can be set.
Use a reference to an upstream group for routing. Only one of upstreamGroup, single, multi, clusterHeader, or dynamicForwardProxy can be set.
clusterHeader
string
Envoy will determine the cluster to route to by reading the value of the HTTP header named by cluster_header from the request headers. If the header is not found or the referenced cluster does not exist, Envoy will return a 404 response. Avoid using this whenever possible, it does not allow for custom filter configuration based on Virtual Host. Only one of clusterHeader, single, multi, upstreamGroup, or dynamicForwardProxy can be set.
Route requests to a custom dynamic forward proxy envoy cluster. Envoy will route based on the DNS response (cached) or pause requests (for a configurable amount of time on the listener) until DNS has resolved for the host header rewrite as provided here. For more, see https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/http/http_proxy. Only one of dynamicForwardProxy, single, multi, upstreamGroup, or clusterHeader can be set.
Destination
Destinations define routable destinations for proxied requests.
Some upstreams utilize options 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.
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.
KubernetesServiceDestination
Identifies a port on a kubernetes service to route traffic to.
Identifies a Consulservice to route traffic to.
Multiple Consul services with the same name can present distinct sets of tags, listen of different ports, and live in
multiple data centers (see an example here).
You can target the desired subset of services via the fields in this configuration. Gloo will detect the correspondent
IP addresses and ports and load balance traffic between them.
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.
This list must contain at least one destination with a weight greater than 0. Otherwise, the listener for this route becomes invalid, which causes an error for the parent proxy resource.
WeightedDestination
WeightedDestination attaches a weight to a single destination.
Weight must be zero or greater -if no weight is passed it will default to 0 - Routing to each destination is balanced according to the ratio of the destination’s weight to the total weight on a route. For example, if the weight for one destination is 2, and the total weight of all destinations on the route is 6, the destination receives 2/6 of the traffic. Note that a weight of 0 routes no traffic to the destination.
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. Only one of pathRedirect, prefixRewrite, or regexRewrite can be set.
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. Only one of prefixRewrite, pathRedirect, or regexRewrite can be set.
Indicates that during forwarding, portions of the path that match the pattern should be rewritten, even allowing the substitution of capture groups from the pattern into the new path as specified by the rewrite substitution string. This is useful to allow application paths to be rewritten in a way that is aware of segments with variable content like identifiers. The router filter will place the original path as it was before the rewrite into the :ref:x-envoy-original-path <config_http_filters_router_x-envoy-original-path> header. Only one of :ref:prefix_rewrite <envoy_api_field_config.route.v3.RouteAction.prefix_rewrite> or regex_rewrite may be specified. Examples using Google’s RE2 <https://github.com/google/re2>_ engine: * The path pattern ^/service/([^/]+)(/.*)$ paired with a substitution string of \2/instance/\1 would transform /service/foo/v1/api into /v1/api/instance/foo. * The pattern one paired with a substitution string of two would transform /xxx/one/yyy/one/zzz into /xxx/two/yyy/two/zzz. * The pattern ^(.*?)one(.*)$ paired with a substitution string of \1two\2 would replace only the first occurrence of one, transforming path /xxx/one/yyy/one/zzz into /xxx/two/yyy/one/zzz. * The pattern (?i)/xxx/ paired with a substitution string of /yyy/ would do a case-insensitive match and transform path /aaa/XxX/bbb to /aaa/yyy/bbb. Only one of regexRewrite, pathRedirect, or prefixRewrite can be set.
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 feature in the enclosing Route, Virtual Host, or Listener options.
SourceMetadata
SourceMetadata is an internal message used to track ownership of nested proxy objects:
