syntax = "proto3"; package gloo.solo.io; option go_package = "github.com/solo-io/gloo/projects/gloo/pkg/api/v1"; import "google/protobuf/wrappers.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/struct.proto"; import "google/protobuf/any.proto"; import "extproto/ext.proto"; option (extproto.equal_all) = true; option (extproto.hash_all) = true; option (extproto.clone_all) = true; import "github.com/solo-io/solo-kit/api/v1/metadata.proto"; import "github.com/solo-io/solo-kit/api/v1/status.proto"; import "github.com/solo-io/solo-kit/api/v1/ref.proto"; import "github.com/solo-io/solo-kit/api/v1/solo-kit.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/listener_options.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/http_listener_options.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/tcp_listener_options.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/virtual_host_options.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/route_options.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/route_configuration_options.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/weighted_destination_options.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/ssl/ssl.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/subset.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/destination_spec.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/filters/stages.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/core/matchers/matchers.proto"; import "github.com/solo-io/gloo/projects/gloo/api/external/envoy/config/core/v3/address.proto"; import "github.com/solo-io/gloo/projects/gloo/api/v1/options/dynamic_forward_proxy/dynamic_forward_proxy.proto"; import "github.com/solo-io/gloo/projects/gloo/api/external/envoy/type/matcher/v3/regex.proto"; /* 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. */ message Proxy { option (core.solo.io.resource).short_name = "px"; option (core.solo.io.resource).plural_name = "proxies"; // This field is populated when the proxy compression is turned on. string compressedSpec = 3; // 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. repeated Listener listeners = 2; reserved 6; // NamespacedStatuses indicates the validation status of this resource. // NamespacedStatuses is read-only by clients, and set by gloo during validation core.solo.io.NamespacedStatuses namespaced_statuses = 8 [(extproto.skip_hashing) = true]; // Metadata contains the object metadata for this resource core.solo.io.Metadata metadata = 7; } // 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. message Listener { // the name of the listener. names must be unique for each listener within a proxy string name = 1; // the bind address for the listener. // both ipv4 and ipv6 formats are supported string bind_address = 2; // the port to bind on // ports numbers must be unique for listeners within a proxy uint32 bind_port = 3; // Listeners can listen for HTTP, TCP (unsupported), and UDP (unsupported) connections oneof ListenerType { // contains configuration options for Gloo's HTTP-level features including request-based routing HttpListener http_listener = 4; // contains configuration options for Gloo's TCP-level features TcpListener tcp_listener = 5; // contains any number of configuration options for Gloo's HTTP and/or TCP-level features HybridListener hybrid_listener = 11; // 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 AggregateListener aggregate_listener = 13; } // 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 repeated SslConfig ssl_configurations = 6; // Enable ProxyProtocol support for this listener. // Deprecated: prefer setting the listener option. // If configured, the listener option (filter config) overrides any setting here. google.protobuf.BoolValue use_proxy_proto = 7 [deprecated=true]; // top level options ListenerOptions options = 8; oneof opaque_metadata { // 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 google.protobuf.Struct metadata = 9 [(extproto.skip_hashing) = true]; // Inline metadata used by gloo controller to track ownership. // See [uses of static metadata](https://github.com/solo-io/gloo/tree/main/devel/architecture/static_metadata.md) for specific uses SourceMetadata metadata_static = 12 [(extproto.skip_hashing) = true]; } // Route Configuration Options RouteConfigurationOptions route_options = 10; } message TcpListener { // List of filter chains to match on for this listener repeated TcpHost tcp_hosts = 1; // 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 TcpListenerOptions options = 8; // prefix for addressing envoy stats for the tcp proxy string stat_prefix = 3; // Additional arbitrary network Filters that will be inserted directly into xDS. repeated CustomEnvoyFilter custom_network_filters = 4; } message TcpHost { // the logical name of the tcp host. names must be unique for each tcp host within a listener string name = 1; reserved 2; // If provided, the Gateway will serve TLS/SSL traffic for this set of routes gloo.solo.io.SslConfig ssl_config = 3; // 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. message TcpAction { oneof destination { // Use SingleDestination to route to a single upstream Destination single = 1; // Use MultiDestination to load balance requests between multiple upstreams (by weight) MultiDestination multi = 2; // Use a reference to an upstream group for routing. core.solo.io.ResourceRef upstream_group = 3; // Forwards the request to a cluster name matching the TLS SNI name // https://www.envoyproxy.io/docs/envoy/latest/api-v2/config/filter/network/sni_cluster/empty/sni_cluster // Note: This filter will only work properly with TLS connections in which the upstream SNI domain is specified google.protobuf.Empty forward_sni_cluster_name = 4; }; } TcpAction destination = 4; } // 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) message HttpListener { // 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 repeated VirtualHost virtual_hosts = 1; // 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. HttpListenerOptions options = 2; // prefix for addressing envoy stats for the http connection manager string stat_prefix = 3; // Additional arbitrary HTTPFilters that will be inserted directly into xDS. repeated CustomEnvoyFilter custom_http_filters = 4; // Additional arbitrary network Filters that will be inserted directly into xDS. repeated CustomEnvoyFilter custom_network_filters = 5; oneof opaque_metadata { // 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 google.protobuf.Struct metadata = 6 [(extproto.skip_hashing) = true]; // Inline metadata used by gloo controller to track ownership. // See [uses of static metadata](https://github.com/solo-io/gloo/tree/main/devel/architecture/static_metadata.md) for specific uses SourceMetadata metadata_static = 7 [(extproto.skip_hashing) = true]; } } message HybridListener { repeated MatchedListener matched_listeners = 1; } message MatchedListener { // 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 Matcher matcher = 1; oneof ListenerType { HttpListener http_listener = 2; TcpListener tcp_listener = 3; } // 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 repeated SslConfig ssl_configurations = 4; } message MatchedTcpListener { // Matchers are used to define unique matching criteria for each MatchedListener // These are overridden by tcphost sni mutators Matcher matcher = 1; // The actual tcp listener to be used for this matcher in the aggregate listener TcpListener tcp_listener = 2; } message Matcher { // Gloo use SNI domains as matching criteria for Gateway selection // The other ssl_config properties will be applied to the outputFilterChain's transport socket // SslConfig from VirtualServices will be ignored in a MatchedGateway gloo.solo.io.SslConfig ssl_config = 1; // Source addresses to match. This value is either the actual addresses used to connect, // or addresses that are overridden by using PROXY protocol or original_src. repeated .solo.io.envoy.config.core.v3.CidrRange source_prefix_ranges = 2; // Destination addresses to match. This value is either the actual addresses used to connect, // or addresses that are overridden by using PROXY protocol or original_dst. repeated .solo.io.envoy.config.core.v3.CidrRange prefix_ranges = 4; // Optional destination port to consider in determining a filter chain match. // Filter chains that specify the destination port of incoming traffic are the most specific match. // If no filter chain specifies the exact destination port, // the filter chains which do not specify ports are the most specific match. google.protobuf.UInt32Value destination_port = 5; repeated string passthrough_cipher_suites = 3; } // An AggregateListener defines a set of Gloo configuration which will map to a unique set of FilterChains on a Listener message AggregateListener { message HttpResources { // Set of VirtualHosts available on this Listener, indexed by name map virtual_hosts = 1; // Set of HttpListenerOptions available on this Listener, indexed by hash map http_options = 2; } message HttpFilterChain { // Matching criteria used to generate both the FilterChainMatch and TransportSocket for the Envoy FilterChain Matcher matcher = 1; // The ref pointing to HttpListenerOptions which are used to configure the HCM on this HttpFilterChain // Corresponds to an entry in the HttpResources.HttpOptions map string http_options_ref = 2; // The set of refs pointing to VirtualHosts which are available on this HttpFilterChain // Each ref corresponds to an entry in the HttpResources.VirtualHosts map repeated string virtual_host_refs = 3; // Additional arbitrary HTTPFilters that will be inserted directly into xDS. repeated CustomEnvoyFilter custom_http_filters = 37; // Additional arbitrary network Filters that will be inserted directly into xDS. repeated CustomEnvoyFilter custom_network_filters = 38; } // The aggregate set of resources available on this listener HttpResources http_resources = 1; // The set of HttpFilterChains to create on this listener repeated HttpFilterChain http_filter_chains = 2; // The set of TcpListeners to create on this listener repeated MatchedTcpListener tcp_listeners = 3; } /* * 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. */ message VirtualHost { // the logical name of the virtual host. names must be unique for each virtual host within a listener string name = 1; // 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](https://github.com/envoyproxy/envoy/blob/main/api/envoy/api/v2/route/route.proto) repeated string domains = 2; // 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. repeated Route routes = 3; // 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. VirtualHostOptions options = 4; oneof opaque_metadata { // 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 google.protobuf.Struct metadata = 6 [(extproto.skip_hashing) = true]; // Inline metadata used by gloo controller to track ownership SourceMetadata metadata_static = 7 [(extproto.skip_hashing) = true]; } } /** * Routes declare the entry points on virtual hosts and the action to take for matched requests. */ message Route { // 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) repeated matchers.core.gloo.solo.io.Matcher matchers = 1; // The Route Action Defines what action the proxy should take when a request matches the route. oneof action { // This action is the primary action to be selected for most routes. The RouteAction tells the proxy to // route requests to an upstream. RouteAction route_action = 2; // Redirect actions tell the proxy to return a redirect response to the downstream client RedirectAction redirect_action = 3; // Return an arbitrary HTTP response directly, without proxying. DirectResponseAction direct_response_action = 4; } reserved 8; reserved "graphql_api_ref"; // Route Options extend the behavior of routes. // Route options include configuration such as retries, rate limiting, and request/response transformation. RouteOptions options = 5; oneof opaque_metadata { // 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 google.protobuf.Struct metadata = 6 [(extproto.skip_hashing) = true]; // Inline metadata used by gloo controller to track ownership SourceMetadata metadata_static = 9 [(extproto.skip_hashing) = true]; } // 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. string name = 7; } // RouteActions are used to route matched requests to upstreams. message RouteAction { // Defines the destination upstream for routing // Some destinations require additional configuration for the route (e.g. AWS upstreams require a function name // to be specified). oneof destination { // Use SingleDestination to route to a single upstream Destination single = 1; // Use MultiDestination to load balance requests between multiple upstreams (by weight) MultiDestination multi = 2; // Use a reference to an upstream group for routing. core.solo.io.ResourceRef upstream_group = 3; // 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. string cluster_header = 4; // 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 dfp.options.gloo.solo.io.PerRouteConfig dynamic_forward_proxy = 5; }; } // Destinations define routable destinations for proxied requests. message Destination { // The type of the destination oneof destination_type { // Route requests to a Gloo upstream core.solo.io.ResourceRef upstream = 10; // Route requests to a kubernetes service KubernetesServiceDestination kube = 11; // Route requests to a consul service ConsulServiceDestination consul = 12; } // Note: When in the context of a TCP gateway the below 2 fields will be ignored // 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. DestinationSpec destination_spec = 2; // 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. Subset subset = 3; } // Identifies a port on a kubernetes service to route traffic to. message KubernetesServiceDestination { // The target service core.solo.io.ResourceRef ref = 1; // The port attribute of the service uint32 port = 2; } // Identifies a [Consul](https://www.consul.io/) [service](https://www.consul.io/docs/agent/services.html) 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](https://www.consul.io/docs/agent/services.html#multiple-service-definitions)). // 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. message ConsulServiceDestination { // The name of the target service. This field is required. string service_name = 1; // If provided, load balance traffic only between services matching all the given tags. repeated string tags = 2; // If provided, load balance traffic only between services running in the given // [data centers](https://www.consul.io/docs/internals/architecture.html). repeated string data_centers = 3; } message UpstreamGroup { option (core.solo.io.resource).short_name = "ug"; option (core.solo.io.resource).plural_name = "upstream_groups"; // The destinations that are part of this upstream group. repeated WeightedDestination destinations = 1; reserved 6; // NamespacedStatuses indicates the validation status of this resource. // NamespacedStatuses is read-only by clients, and set by gloo during validation core.solo.io.NamespacedStatuses namespaced_statuses = 8 [(extproto.skip_hashing) = true]; // Metadata contains the object metadata for this resource core.solo.io.Metadata metadata = 7; } // 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. message MultiDestination { // 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. repeated WeightedDestination destinations = 1; } // WeightedDestination attaches a weight to a single destination. message WeightedDestination { Destination destination = 1; // 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. google.protobuf.UInt32Value weight = 2; // Apply configuration to traffic that is sent to this weighted destination WeightedDestinationOptions options = 3; } // Notice: RedirectAction is copied directly from https://github.com/envoyproxy/envoy/blob/main/api/envoy/api/v2/route/route.proto message RedirectAction { // The host portion of the URL will be swapped with this value. string host_redirect = 1; oneof path_rewrite_specifier { // The path portion of the URL will be swapped with this value. string path_redirect = 2; // 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`. string prefix_rewrite = 5; // 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 // ` header. // // Only one of :ref:`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`. .solo.io.envoy.type.matcher.v3.RegexMatchAndSubstitute regex_rewrite = 32; } enum RedirectResponseCode { // Moved Permanently HTTP Status Code - 301. MOVED_PERMANENTLY = 0; // Found HTTP Status Code - 302. FOUND = 1; // See Other HTTP Status Code - 303. SEE_OTHER = 2; // Temporary Redirect HTTP Status Code - 307. TEMPORARY_REDIRECT = 3; // Permanent Redirect HTTP Status Code - 308. PERMANENT_REDIRECT = 4; } // The HTTP status code to use in the redirect response. The default response // code is MOVED_PERMANENTLY (301). RedirectResponseCode response_code = 3; // The scheme portion of the URL will be swapped with "https". bool https_redirect = 4; // Indicates that during redirection, the query portion of the URL will // be removed. Default value is false. bool strip_query = 6; // Which port to redirect to if different than original. google.protobuf.UInt32Value port_redirect = 7; } // DirectResponseAction is copied directly from https://github.com/envoyproxy/envoy/blob/main/api/envoy/api/v2/route/route.proto message DirectResponseAction { // Specifies the HTTP response status to be returned. uint32 status = 1; // 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. string body = 2; } // SourceMetadata is an internal message used to track ownership of nested proxy objects: // - Listener // - VirtualHost // - Route message SourceMetadata { message SourceRef { // The resource being referenced core.solo.io.ResourceRef resource_ref = 1; // The resource Kind string resource_kind = 2; // The observed generation of the resource int64 observed_generation = 3; } // A list of sources repeated SourceRef sources = 1; } // CustomEnvoyFilter contains an arbitrary filter. // These may be HTTPFilters or NetworkFilters, depending on the context they're used. message CustomEnvoyFilter { // Determines filter ordering. .filters.gloo.solo.io.FilterStage filter_stage = 1; // The name of the filter configuration. string name = 2; // Filter specific configuration. google.protobuf.Any config = 3; }