proxy.proto

Package: gloo.solo.io

Types:

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
"tcpListener": .gloo.solo.io.TcpListener
"sslConfigurations": []gloo.solo.io.SslConfig
"useProxyProto": .google.protobuf.BoolValue
"options": .gloo.solo.io.ListenerOptions
"metadata": .google.protobuf.Struct
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. Only one of httpListener or tcpListener can be set.
tcpListener .gloo.solo.io.TcpListener The HTTP Listener is currently the only supported listener type. It contains configuration options for GLoo’s HTTP-level features including request-based routing. Only one of tcpListener or httpListener can be set.
sslConfigurations []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 purpose of SNI. Be aware that the SNI domain provided in the SSL Config.
useProxyProto .google.protobuf.BoolValue Enable ProxyProtocol support for this listener.
options .gloo.solo.io.ListenerOptions top level options.
metadata .google.protobuf.Struct Metadata for the individual listener This data is opaque to Gloo, used by controllers to track ownership of listeners within a proxy as they are typically generated by a controller (such as the gateway).

TcpListener

"tcpHosts": []gloo.solo.io.TcpHost
"options": .gloo.solo.io.TcpListenerOptions
"statPrefix": string
Field Type Description Default
tcpHosts []gloo.solo.io.TcpHost List of filter chains to match on for this listener.
options .gloo.solo.io.TcpListenerOptions 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.

TcpHost

"name": string
"destination": .gloo.solo.io.RouteAction
"sslConfig": .gloo.solo.io.SslConfig
Field Type Description Default
name string the logical name of the tcp host. names must be unique for each tcp host within a listener.
destination .gloo.solo.io.RouteAction Name of the destinations the gateway can route to. Note: the destination spec and subsets are not supported in this context and will be ignored.
sslConfig .gloo.solo.io.SslConfig If provided, the Gateway will serve TLS/SSL traffic for this set of routes.

HttpListener

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)

"virtualHosts": []gloo.solo.io.VirtualHost
"options": .gloo.solo.io.HttpListenerOptions
"statPrefix": string
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.
options .gloo.solo.io.HttpListenerOptions 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.

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
"options": .gloo.solo.io.VirtualHostOptions
"metadata": .google.protobuf.Struct
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.
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.
metadata .google.protobuf.Struct Metadata for the individual virtual host This data is opaque to Gloo, used by controllers to track ownership of virtual hosts within a proxy as they are typically generated by a controller (such as the gateway).

Route

* Routes declare the entry points on virtual hosts and the action to take for matched requests.

"matchers": []matchers.core.gloo.solo.io.Matcher
"routeAction": .gloo.solo.io.RouteAction
"redirectAction": .gloo.solo.io.RedirectAction
"directResponseAction": .gloo.solo.io.DirectResponseAction
"options": .gloo.solo.io.RouteOptions
"metadata": .google.protobuf.Struct
Field Type Description Default
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).
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, or directResponseAction 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, or directResponseAction can be set.
directResponseAction .gloo.solo.io.DirectResponseAction Return an arbitrary HTTP response directly, without proxying. Only one of directResponseAction, or redirectAction 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.
metadata .google.protobuf.Struct 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).

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. Only one of single, or upstreamGroup can be set.
multi .gloo.solo.io.MultiDestination Use MultiDestination to load balance requests between multiple upstreams (by weight). Only one of multi, or upstreamGroup can be set.
upstreamGroup .core.solo.io.ResourceRef Use a reference to an upstream group for routing. Only one of upstreamGroup, or multi can be set.

Destination

Destinations define routable destinations for proxied requests.

"upstream": .core.solo.io.ResourceRef
"kube": .gloo.solo.io.KubernetesServiceDestination
"consul": .gloo.solo.io.ConsulServiceDestination
"destinationSpec": .gloo.solo.io.DestinationSpec
"subset": .gloo.solo.io.Subset
Field Type Description Default
upstream .core.solo.io.ResourceRef Route requests to a Gloo upstream. Only one of upstream, or consul can be set.
kube .gloo.solo.io.KubernetesServiceDestination Route requests to a kubernetes service. Only one of kube, or consul can be set.
consul .gloo.solo.io.ConsulServiceDestination Route requests to a consul service. Only one of consul, or kube can be set.
destinationSpec .gloo.solo.io.DestinationSpec 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.
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.

KubernetesServiceDestination

Identifies a port on a kubernetes service to route traffic to.

"ref": .core.solo.io.ResourceRef
"port": int
Field Type Description Default
ref .core.solo.io.ResourceRef The target service.
port int The port attribute of the service.

ConsulServiceDestination

Identifies a Consul service 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.

"serviceName": string
"tags": []string
"dataCenters": []string
Field Type Description Default
serviceName string The name of the target service. This field is required.
tags []string If provided, load balance traffic only between services matching all the given tags.
dataCenters []string If provided, load balance traffic only between services running in the given data centers.

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
"options": .gloo.solo.io.WeightedDestinationOptions
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.
options .gloo.solo.io.WeightedDestinationOptions Apply configuration to traffic that is sent to this weighted destination.

RedirectAction

Notice: RedirectAction is copied 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. Only one of pathRedirect or prefixRewrite 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 or pathRedirect can be set.
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

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 feature in the enclosing Route, Virtual Host, or Listener options.