diff options
Diffstat (limited to 'grpc/src/proto')
26 files changed, 1902 insertions, 72 deletions
diff --git a/grpc/src/proto/grpc/testing/echo.proto b/grpc/src/proto/grpc/testing/echo.proto index db583a13..c4233035 100644 --- a/grpc/src/proto/grpc/testing/echo.proto +++ b/grpc/src/proto/grpc/testing/echo.proto @@ -15,15 +15,17 @@ syntax = "proto3"; +package grpc.testing; + import "src/proto/grpc/testing/echo_messages.proto"; import "src/proto/grpc/testing/simple_messages.proto"; -package grpc.testing; - service EchoTestService { rpc Echo(EchoRequest) returns (EchoResponse); rpc Echo1(EchoRequest) returns (EchoResponse); rpc Echo2(EchoRequest) returns (EchoResponse); + rpc CheckDeadlineUpperBound(SimpleRequest) returns (StringValue); + rpc CheckDeadlineSet(SimpleRequest) returns (StringValue); // A service which checks that the initial metadata sent over contains some // expected key value pair rpc CheckClientInitialMetadata(SimpleRequest) returns (SimpleResponse); @@ -64,5 +66,4 @@ service UnimplementedEchoService { } // A service without any rpc defined to test coverage. -service NoRpcService { -} +service NoRpcService {} diff --git a/grpc/src/proto/grpc/testing/messages.proto b/grpc/src/proto/grpc/testing/messages.proto index 5993bc6b..70e34277 100644 --- a/grpc/src/proto/grpc/testing/messages.proto +++ b/grpc/src/proto/grpc/testing/messages.proto @@ -202,8 +202,13 @@ message LoadBalancerStatsRequest { } message LoadBalancerStatsResponse { + message RpcsByPeer { + // The number of completed RPCs for each peer. + map<string, int32> rpcs_by_peer = 1; + } // The number of completed RPCs for each peer. map<string, int32> rpcs_by_peer = 1; // The number of RPCs that failed to record a remote peer. int32 num_failures = 2; + map<string, RpcsByPeer> rpcs_by_method = 3; } diff --git a/grpc/src/proto/grpc/testing/simple_messages.proto b/grpc/src/proto/grpc/testing/simple_messages.proto index 4b65d189..3afe236b 100644 --- a/grpc/src/proto/grpc/testing/simple_messages.proto +++ b/grpc/src/proto/grpc/testing/simple_messages.proto @@ -17,8 +17,10 @@ syntax = "proto3"; package grpc.testing; -message SimpleRequest { -} +message SimpleRequest {} + +message SimpleResponse {} -message SimpleResponse { +message StringValue { + string message = 1; } diff --git a/grpc/src/proto/grpc/testing/test.proto b/grpc/src/proto/grpc/testing/test.proto index 0b198d8c..1da43f48 100644 --- a/grpc/src/proto/grpc/testing/test.proto +++ b/grpc/src/proto/grpc/testing/test.proto @@ -84,3 +84,9 @@ service LoadBalancerStatsService { rpc GetClientStats(LoadBalancerStatsRequest) returns (LoadBalancerStatsResponse) {} } + +// A service to remotely control health status of an xDS test server. +service XdsUpdateHealthService { + rpc SetServing(grpc.testing.Empty) returns (grpc.testing.Empty); + rpc SetNotServing(grpc.testing.Empty) returns (grpc.testing.Empty); +} diff --git a/grpc/src/proto/grpc/testing/xds/BUILD b/grpc/src/proto/grpc/testing/xds/BUILD index b0d69f8e..5dd57959 100644 --- a/grpc/src/proto/grpc/testing/xds/BUILD +++ b/grpc/src/proto/grpc/testing/xds/BUILD @@ -35,6 +35,7 @@ grpc_proto_library( srcs = [ "cds_for_test.proto", ], + well_known_protos = True, ) grpc_proto_library( @@ -53,7 +54,10 @@ grpc_proto_library( ], has_services = True, well_known_protos = True, - deps = ["cds_for_test_proto"], + deps = [ + "cds_for_test_proto", + "eds_for_test_proto", + ], ) grpc_proto_library( diff --git a/grpc/src/proto/grpc/testing/xds/cds_for_test.proto b/grpc/src/proto/grpc/testing/xds/cds_for_test.proto index a4ee4b3b..8ea198d0 100644 --- a/grpc/src/proto/grpc/testing/xds/cds_for_test.proto +++ b/grpc/src/proto/grpc/testing/xds/cds_for_test.proto @@ -27,6 +27,8 @@ syntax = "proto3"; package envoy.api.v2; +import "google/protobuf/wrappers.proto"; + // Aggregated Discovery Service (ADS) options. This is currently empty, but when // set in :ref:`ConfigSource <envoy_api_msg_core.ConfigSource>` can be used to // specify that ADS is to be used. @@ -57,6 +59,19 @@ message ConfigSource { } } +enum RoutingPriority { + DEFAULT = 0; + HIGH = 1; +} + +message CircuitBreakers { + message Thresholds { + RoutingPriority priority = 1; + google.protobuf.UInt32Value max_requests = 4; + } + repeated Thresholds thresholds = 1; +} + message Cluster { // Refer to :ref:`service discovery type <arch_overview_service_discovery_types>` // for an explanation on each type. @@ -153,5 +168,7 @@ message Cluster { // Configuration to use for EDS updates for the Cluster. EdsClusterConfig eds_cluster_config = 3; + CircuitBreakers circuit_breakers = 10; + ConfigSource lrs_server = 42; } diff --git a/grpc/src/proto/grpc/testing/xds/eds_for_test.proto b/grpc/src/proto/grpc/testing/xds/eds_for_test.proto index ece658da..3b8ce66f 100644 --- a/grpc/src/proto/grpc/testing/xds/eds_for_test.proto +++ b/grpc/src/proto/grpc/testing/xds/eds_for_test.proto @@ -28,11 +28,8 @@ syntax = "proto3"; package envoy.api.v2; import "google/protobuf/any.proto"; - -message UInt32Value { - // The uint32 value. - uint32 value = 1; -} +import "google/protobuf/struct.proto"; +import "google/protobuf/wrappers.proto"; message Status { // The status code, which should be an enum value of [google.rpc.Code][]. @@ -48,60 +45,6 @@ message Status { repeated google.protobuf.Any details = 3; } -// `Struct` represents a structured data value, consisting of fields -// which map to dynamically typed values. In some languages, `Struct` -// might be supported by a native representation. For example, in -// scripting languages like JS a struct is represented as an -// object. The details of that representation are described together -// with the proto support for the language. -// -// The JSON representation for `Struct` is JSON object. -message Struct { - // Unordered map of dynamically typed values. - map<string, Value> fields = 1; -} - -// `Value` represents a dynamically typed value which can be either -// null, a number, a string, a boolean, a recursive struct value, or a -// list of values. A producer of value is expected to set one of that -// variants, absence of any variant indicates an error. -// -// The JSON representation for `Value` is JSON value. -message Value { - // The kind of value. - oneof kind { - // Represents a null value. - NullValue null_value = 1; - // Represents a double value. - double number_value = 2; - // Represents a string value. - string string_value = 3; - // Represents a boolean value. - bool bool_value = 4; - // Represents a structured value. - Struct struct_value = 5; - // Represents a repeated `Value`. - ListValue list_value = 6; - } -} - -// `NullValue` is a singleton enumeration to represent the null value for the -// `Value` type union. -// -// The JSON representation for `NullValue` is JSON `null`. -enum NullValue { - // Null value. - NULL_VALUE = 0; -} - -// `ListValue` is a wrapper around a repeated field of values. -// -// The JSON representation for `ListValue` is JSON array. -message ListValue { - // Repeated field of dynamically typed values. - repeated Value values = 1; -} - /////////////////////////////////////////////////////////////////////////////// // Identifies location of where either Envoy runs or where upstream hosts run. @@ -152,7 +95,7 @@ message Node { // Opaque metadata extending the node identifier. Envoy will pass this // directly to the management server. - Struct metadata = 3; + google.protobuf.Struct metadata = 3; // Locality specifying where the Envoy instance is running. Locality locality = 4; @@ -328,7 +271,7 @@ message Address { message Metadata { // Key is the reverse DNS filter name, e.g. com.acme.widget. The envoy.* // namespace is reserved for Envoy's built-in filters. - map<string, Struct> filter_metadata = 1; + map<string, google.protobuf.Struct> filter_metadata = 1; } /////////////////////////////////////////////////////////////////////////////// @@ -423,7 +366,7 @@ message LbEndpoint { // The limit of 128 is somewhat arbitrary, but is applied due to performance // concerns with the current implementation and can be removed when // `this issue <https://github.com/envoyproxy/envoy/issues/1285>`_ is fixed. - UInt32Value load_balancing_weight = 4; + google.protobuf.UInt32Value load_balancing_weight = 4; } // A group of endpoints belonging to a Locality. @@ -453,7 +396,7 @@ message LocalityLbEndpoints { // The limit of 128 is somewhat arbitrary, but is applied due to performance // concerns with the current implementation and can be removed when // `this issue <https://github.com/envoyproxy/envoy/issues/1285>`_ is fixed. - UInt32Value load_balancing_weight = 3; + google.protobuf.UInt32Value load_balancing_weight = 3; // Optional: the priority for this LocalityLbEndpoints. If unspecified this will // default to the highest priority (0). @@ -566,7 +509,7 @@ message ClusterLoadAssignment { // below 72%. // Read more at :ref:`priority levels <arch_overview_load_balancing_priority_levels>` and // :ref:`localities <arch_overview_load_balancing_locality_weighted_lb>`. - UInt32Value overprovisioning_factor = 3; + google.protobuf.UInt32Value overprovisioning_factor = 3; } // Load balancing policy settings. diff --git a/grpc/src/proto/grpc/testing/xds/lds_rds_for_test.proto b/grpc/src/proto/grpc/testing/xds/lds_rds_for_test.proto index acf21861..d5ba5bd3 100644 --- a/grpc/src/proto/grpc/testing/xds/lds_rds_for_test.proto +++ b/grpc/src/proto/grpc/testing/xds/lds_rds_for_test.proto @@ -26,8 +26,53 @@ syntax = "proto3"; package envoy.api.v2; import "google/protobuf/any.proto"; +import "google/protobuf/wrappers.proto"; import "src/proto/grpc/testing/xds/cds_for_test.proto"; +import "src/proto/grpc/testing/xds/eds_for_test.proto"; +message RegexMatcher { + message GoogleRE2 { + google.protobuf.UInt32Value max_program_size = 1; + } + oneof engine_type { + GoogleRE2 google_re2 = 1; + } + string regex = 2; +} + +message Int64Range { + // start of the range (inclusive) + int64 start = 1; + + // end of the range (exclusive) + int64 end = 2; +} + +message BoolValue { + // The bool value. + bool value = 1; +} + +message HeaderMatcher { + string name = 1; + oneof header_match_specifier { + string exact_match = 4; + RegexMatcher safe_regex_match = 11; + Int64Range range_match = 6; + bool present_match = 7; + string prefix_match = 9; + string suffix_match = 10; + } + bool invert_match = 8; +} + +message QueryParameterMatcher { + string name = 1; +} + +message RuntimeFractionalPercent { + FractionalPercent default_value = 1; +} message RouteMatch { oneof path_specifier { @@ -35,7 +80,21 @@ message RouteMatch { // match the beginning of the *:path* header. string prefix = 1; string path = 2; + RegexMatcher safe_regex = 10; + } + BoolValue case_sensitive = 4; + repeated QueryParameterMatcher query_parameters = 7; + RuntimeFractionalPercent runtime_fraction = 9; + repeated HeaderMatcher headers = 6; +} + +message WeightedCluster { + message ClusterWeight { + string name = 1; + google.protobuf.UInt32Value weight = 2; } + repeated ClusterWeight clusters = 1; + google.protobuf.UInt32Value total_weight = 3; } message RouteAction { @@ -54,6 +113,12 @@ message RouteAction { // Internally, Envoy 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. string cluster_header = 2; + // Multiple upstream clusters can be specified for a given route. The + // request is routed to one of the upstream clusters based on weights + // assigned to each cluster. See + // :ref:`traffic splitting <config_http_conn_man_route_table_traffic_splitting_split>` + // for additional documentation. + WeightedCluster weighted_clusters = 3; } } diff --git a/grpc/src/proto/grpc/testing/xds/lrs_for_test.proto b/grpc/src/proto/grpc/testing/xds/lrs_for_test.proto index 9d8ae267..d46d5e2c 100644 --- a/grpc/src/proto/grpc/testing/xds/lrs_for_test.proto +++ b/grpc/src/proto/grpc/testing/xds/lrs_for_test.proto @@ -166,8 +166,14 @@ message LoadStatsRequest { // [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. message LoadStatsResponse { // Clusters to report stats for. + // Not populated if *send_all_clusters* is true. repeated string clusters = 1; + // If true, the client should send all clusters it knows about. + // Only clients that advertise the "envoy.lrs.supports_send_all_clusters" capability in their + // :ref:`client_features<envoy_api_field_core.Node.client_features>` field will honor this field. + bool send_all_clusters = 4; + // The minimum interval of time to collect stats over. This is only a minimum for two reasons: // 1. There may be some delay from when the timer fires until stats sampling occurs. // 2. For clusters that were already feature in the previous *LoadStatsResponse*, any traffic diff --git a/grpc/src/proto/grpc/testing/xds/v3/BUILD b/grpc/src/proto/grpc/testing/xds/v3/BUILD new file mode 100644 index 00000000..ea828230 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/BUILD @@ -0,0 +1,180 @@ +# Copyright 2020 gRPC authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +licenses(["notice"]) # Apache v2 + +load("//bazel:grpc_build_system.bzl", "grpc_package", "grpc_proto_library") + +grpc_package( + name = "xds_v3", + visibility = "public", +) + +grpc_proto_library( + name = "address_proto", + srcs = [ + "address.proto", + ], +) + +grpc_proto_library( + name = "percent_proto", + srcs = [ + "percent.proto", + ], +) + +grpc_proto_library( + name = "base_proto", + srcs = [ + "base.proto", + ], + well_known_protos = True, + deps = [ + "percent_proto", + ], +) + +grpc_proto_library( + name = "discovery_proto", + srcs = [ + "discovery.proto", + ], + well_known_protos = True, + deps = [ + "base_proto", + ], +) + +grpc_proto_library( + name = "ads_proto", + srcs = [ + "ads.proto", + ], + has_services = True, + well_known_protos = True, + deps = [ + "discovery_proto", + ], +) + +grpc_proto_library( + name = "config_source_proto", + srcs = [ + "config_source.proto", + ], +) + +grpc_proto_library( + name = "cluster_proto", + srcs = [ + "cluster.proto", + ], + well_known_protos = True, + deps = [ + "config_source_proto", + ], +) + +grpc_proto_library( + name = "endpoint_proto", + srcs = [ + "endpoint.proto", + ], + well_known_protos = True, + deps = [ + "address_proto", + "base_proto", + "percent_proto", + ], +) + +grpc_proto_library( + name = "listener_proto", + srcs = [ + "listener.proto", + ], + well_known_protos = True, +) + +grpc_proto_library( + name = "load_report_proto", + srcs = [ + "load_report.proto", + ], + well_known_protos = True, + deps = [ + "address_proto", + "base_proto", + ], +) + +grpc_proto_library( + name = "lrs_proto", + srcs = [ + "lrs.proto", + ], + has_services = True, + well_known_protos = True, + deps = [ + "base_proto", + "load_report_proto", + ], +) + +grpc_proto_library( + name = "orca_load_report_proto", + srcs = [ + "orca_load_report.proto", + ], +) + +grpc_proto_library( + name = "range_proto", + srcs = [ + "range.proto", + ], +) + +grpc_proto_library( + name = "regex_proto", + srcs = [ + "regex.proto", + ], +) + +grpc_proto_library( + name = "route_proto", + srcs = [ + "route.proto", + ], + well_known_protos = True, + deps = [ + "base_proto", + "percent_proto", + "range_proto", + "regex_proto", + ], +) + +grpc_proto_library( + name = "http_connection_manager_proto", + srcs = [ + "http_connection_manager.proto", + ], + deps = [ + "config_source_proto", + "route_proto", + ], +) diff --git a/grpc/src/proto/grpc/testing/xds/v3/address.proto b/grpc/src/proto/grpc/testing/xds/v3/address.proto new file mode 100644 index 00000000..abea8bf6 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/address.proto @@ -0,0 +1,50 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.config.core.v3; + +// [#protodoc-title: Network addresses] + +// [#next-free-field: 7] +message SocketAddress { + // The address for this socket. :ref:`Listeners <config_listeners>` will bind + // to the address. An empty address is not allowed. Specify ``0.0.0.0`` or ``::`` + // to bind to any address. [#comment:TODO(zuercher) reinstate when implemented: + // It is possible to distinguish a Listener address via the prefix/suffix matching + // in :ref:`FilterChainMatch <envoy_api_msg_config.listener.v3.FilterChainMatch>`.] When used + // within an upstream :ref:`BindConfig <envoy_api_msg_config.core.v3.BindConfig>`, the address + // controls the source address of outbound connections. For :ref:`clusters + // <envoy_api_msg_config.cluster.v3.Cluster>`, the cluster type determines whether the + // address must be an IP (*STATIC* or *EDS* clusters) or a hostname resolved by DNS + // (*STRICT_DNS* or *LOGICAL_DNS* clusters). Address resolution can be customized + // via :ref:`resolver_name <envoy_api_field_config.core.v3.SocketAddress.resolver_name>`. + string address = 2; + + oneof port_specifier { + uint32 port_value = 3; + } +} + +// Addresses specify either a logical or physical address and port, which are +// used to tell Envoy where to bind/listen, connect to upstream and find +// management servers. +message Address { + oneof address { + SocketAddress socket_address = 1; + } +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/ads.proto b/grpc/src/proto/grpc/testing/xds/v3/ads.proto new file mode 100644 index 00000000..aea815d0 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/ads.proto @@ -0,0 +1,45 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.service.discovery.v3; + +import "src/proto/grpc/testing/xds/v3/discovery.proto"; + +// [#protodoc-title: Aggregated Discovery Service (ADS)] + +// [#not-implemented-hide:] Discovery services for endpoints, clusters, routes, +// and listeners are retained in the package `envoy.api.v2` for backwards +// compatibility with existing management servers. New development in discovery +// services should proceed in the package `envoy.service.discovery.v2`. + +// See https://github.com/lyft/envoy-api#apis for a description of the role of +// ADS and how it is intended to be used by a management server. ADS requests +// have the same structure as their singleton xDS counterparts, but can +// multiplex many resource types on a single stream. The type_url in the +// DiscoveryRequest/DiscoveryResponse provides sufficient information to recover +// the multiplexed singleton APIs at the Envoy instance and management server. +service AggregatedDiscoveryService { + // This is a gRPC-only API. + rpc StreamAggregatedResources(stream DiscoveryRequest) returns (stream DiscoveryResponse) { + } +} + +// [#not-implemented-hide:] Not configuration. Workaround c++ protobuf issue with importing +// services: https://github.com/google/protobuf/issues/4221 +message AdsDummy { +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/base.proto b/grpc/src/proto/grpc/testing/xds/v3/base.proto new file mode 100644 index 00000000..acecdda8 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/base.proto @@ -0,0 +1,111 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.config.core.v3; + +import "src/proto/grpc/testing/xds/v3/percent.proto"; + +import "google/protobuf/struct.proto"; + +// Identifies location of where either Envoy runs or where upstream hosts run. +message Locality { + // Region this :ref:`zone <envoy_api_field_config.core.v3.Locality.zone>` belongs to. + string region = 1; + + // Defines the local service zone where Envoy is running. Though optional, it + // should be set if discovery service routing is used and the discovery + // service exposes :ref:`zone data <envoy_api_field_config.endpoint.v3.LocalityLbEndpoints.locality>`, + // either in this message or via :option:`--service-zone`. The meaning of zone + // is context dependent, e.g. `Availability Zone (AZ) + // <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html>`_ + // on AWS, `Zone <https://cloud.google.com/compute/docs/regions-zones/>`_ on + // GCP, etc. + string zone = 2; + + // When used for locality of upstream hosts, this field further splits zone + // into smaller chunks of sub-zones so they can be load balanced + // independently. + string sub_zone = 3; +} + +// Identifies a specific Envoy instance. The node identifier is presented to the +// management server, which may use this identifier to distinguish per Envoy +// configuration for serving. +// [#next-free-field: 12] +message Node { + // An opaque node identifier for the Envoy node. This also provides the local + // service node name. It should be set if any of the following features are + // used: :ref:`statsd <arch_overview_statistics>`, :ref:`CDS + // <config_cluster_manager_cds>`, and :ref:`HTTP tracing + // <arch_overview_tracing>`, either in this message or via + // :option:`--service-node`. + string id = 1; + + // Defines the local service cluster name where Envoy is running. Though + // optional, it should be set if any of the following features are used: + // :ref:`statsd <arch_overview_statistics>`, :ref:`health check cluster + // verification + // <envoy_api_field_config.core.v3.HealthCheck.HttpHealthCheck.service_name_matcher>`, + // :ref:`runtime override directory <envoy_api_msg_config.bootstrap.v3.Runtime>`, + // :ref:`user agent addition + // <envoy_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.add_user_agent>`, + // :ref:`HTTP global rate limiting <config_http_filters_rate_limit>`, + // :ref:`CDS <config_cluster_manager_cds>`, and :ref:`HTTP tracing + // <arch_overview_tracing>`, either in this message or via + // :option:`--service-cluster`. + string cluster = 2; + + // Opaque metadata extending the node identifier. Envoy will pass this + // directly to the management server. + google.protobuf.Struct metadata = 3; + + // Locality specifying where the Envoy instance is running. + Locality locality = 4; + + // Free-form string that identifies the entity requesting config. + // E.g. "envoy" or "grpc" + string user_agent_name = 6; + + oneof user_agent_version_type { + // Free-form string that identifies the version of the entity requesting config. + // E.g. "1.12.2" or "abcd1234", or "SpecialEnvoyBuild" + string user_agent_version = 7; + } + + // Client feature support list. These are well known features described + // in the Envoy API repository for a given major version of an API. Client features + // use reverse DNS naming scheme, for example `com.acme.feature`. + // See :ref:`the list of features <client_features>` that xDS client may + // support. + repeated string client_features = 10; +} + +// Runtime derived FractionalPercent with defaults for when the numerator or denominator is not +// specified via a runtime key. +// +// .. note:: +// +// Parsing of the runtime key's data is implemented such that it may be represented as a +// :ref:`FractionalPercent <envoy_api_msg_type.v3.FractionalPercent>` proto represented as JSON/YAML +// and may also be represented as an integer with the assumption that the value is an integral +// percentage out of 100. For instance, a runtime key lookup returning the value "42" would parse +// as a `FractionalPercent` whose numerator is 42 and denominator is HUNDRED. +message RuntimeFractionalPercent { + // Default value if the runtime value's for the numerator/denominator keys are not available. + type.v3.FractionalPercent default_value = 1; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/cluster.proto b/grpc/src/proto/grpc/testing/xds/v3/cluster.proto new file mode 100644 index 00000000..c20d887b --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/cluster.proto @@ -0,0 +1,162 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.config.cluster.v3; + +import "src/proto/grpc/testing/xds/v3/config_source.proto"; + +import "google/protobuf/wrappers.proto"; + +enum RoutingPriority { + DEFAULT = 0; + HIGH = 1; +} + +message CircuitBreakers { + message Thresholds { + RoutingPriority priority = 1; + google.protobuf.UInt32Value max_requests = 4; + } + repeated Thresholds thresholds = 1; +} + +// [#protodoc-title: Cluster configuration] + +// Configuration for a single upstream cluster. +// [#next-free-field: 48] +message Cluster { + // Refer to :ref:`service discovery type <arch_overview_service_discovery_types>` + // for an explanation on each type. + enum DiscoveryType { + // Refer to the :ref:`static discovery type<arch_overview_service_discovery_types_static>` + // for an explanation. + STATIC = 0; + + // Refer to the :ref:`strict DNS discovery + // type<arch_overview_service_discovery_types_strict_dns>` + // for an explanation. + STRICT_DNS = 1; + + // Refer to the :ref:`logical DNS discovery + // type<arch_overview_service_discovery_types_logical_dns>` + // for an explanation. + LOGICAL_DNS = 2; + + // Refer to the :ref:`service discovery type<arch_overview_service_discovery_types_eds>` + // for an explanation. + EDS = 3; + + // Refer to the :ref:`original destination discovery + // type<arch_overview_service_discovery_types_original_destination>` + // for an explanation. + ORIGINAL_DST = 4; + } + + // Refer to :ref:`load balancer type <arch_overview_load_balancing_types>` architecture + // overview section for information on each type. + enum LbPolicy { + reserved 4; + + reserved "ORIGINAL_DST_LB"; + + // Refer to the :ref:`round robin load balancing + // policy<arch_overview_load_balancing_types_round_robin>` + // for an explanation. + ROUND_ROBIN = 0; + + // Refer to the :ref:`least request load balancing + // policy<arch_overview_load_balancing_types_least_request>` + // for an explanation. + LEAST_REQUEST = 1; + + // Refer to the :ref:`ring hash load balancing + // policy<arch_overview_load_balancing_types_ring_hash>` + // for an explanation. + RING_HASH = 2; + + // Refer to the :ref:`random load balancing + // policy<arch_overview_load_balancing_types_random>` + // for an explanation. + RANDOM = 3; + + // Refer to the :ref:`Maglev load balancing policy<arch_overview_load_balancing_types_maglev>` + // for an explanation. + MAGLEV = 5; + + // This load balancer type must be specified if the configured cluster provides a cluster + // specific load balancer. Consult the configured cluster's documentation for whether to set + // this option or not. + CLUSTER_PROVIDED = 6; + + // [#not-implemented-hide:] Use the new :ref:`load_balancing_policy + // <envoy_api_field_config.cluster.v3.Cluster.load_balancing_policy>` field to determine the LB policy. + // [#next-major-version: In the v3 API, we should consider deprecating the lb_policy field + // and instead using the new load_balancing_policy field as the one and only mechanism for + // configuring this.] + LOAD_BALANCING_POLICY_CONFIG = 7; + } + + // Only valid when discovery type is EDS. + message EdsClusterConfig { + // Configuration for the source of EDS updates for this Cluster. + core.v3.ConfigSource eds_config = 1; + + // Optional alternative to cluster name to present to EDS. This does not + // have the same restrictions as cluster name, i.e. it may be arbitrary + // length. + string service_name = 2; + } + + // Supplies the name of the cluster which must be unique across all clusters. + // The cluster name is used when emitting + // :ref:`statistics <config_cluster_manager_cluster_stats>` if :ref:`alt_stat_name + // <envoy_api_field_config.cluster.v3.Cluster.alt_stat_name>` is not provided. + // Any ``:`` in the cluster name will be converted to ``_`` when emitting statistics. + string name = 1; + + oneof cluster_discovery_type { + // The :ref:`service discovery type <arch_overview_service_discovery_types>` + // to use for resolving the cluster. + DiscoveryType type = 2; + } + + // Configuration to use for EDS updates for the Cluster. + EdsClusterConfig eds_cluster_config = 3; + + // The :ref:`load balancer type <arch_overview_load_balancing_types>` to use + // when picking a host in the cluster. + LbPolicy lb_policy = 6; + + CircuitBreakers circuit_breakers = 10; + + // [#not-implemented-hide:] + // If present, tells the client where to send load reports via LRS. If not present, the + // client will fall back to a client-side default, which may be either (a) don't send any + // load reports or (b) send load reports for all clusters to a single default server + // (which may be configured in the bootstrap file). + // + // Note that if multiple clusters point to the same LRS server, the client may choose to + // create a separate stream for each cluster or it may choose to coalesce the data for + // multiple clusters onto a single stream. Either way, the client must make sure to send + // the data for any given cluster on no more than one stream. + // + // [#next-major-version: In the v3 API, we should consider restructuring this somehow, + // maybe by allowing LRS to go on the ADS stream, or maybe by moving some of the negotiation + // from the LRS stream here.] + core.v3.ConfigSource lrs_server = 42; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/config_source.proto b/grpc/src/proto/grpc/testing/xds/v3/config_source.proto new file mode 100644 index 00000000..487b79c0 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/config_source.proto @@ -0,0 +1,77 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.config.core.v3; + +// [#protodoc-title: Configuration sources] + +// Aggregated Discovery Service (ADS) options. This is currently empty, but when +// set in :ref:`ConfigSource <envoy_api_msg_config.core.v3.ConfigSource>` can be used to +// specify that ADS is to be used. +message AggregatedConfigSource { +} + +// [#not-implemented-hide:] +// Self-referencing config source options. This is currently empty, but when +// set in :ref:`ConfigSource <envoy_api_msg_config.core.v3.ConfigSource>` can be used to +// specify that other data can be obtained from the same server. +message SelfConfigSource { +} + +// Configuration for :ref:`listeners <config_listeners>`, :ref:`clusters +// <config_cluster_manager>`, :ref:`routes +// <envoy_api_msg_config.route.v3.RouteConfiguration>`, :ref:`endpoints +// <arch_overview_service_discovery>` etc. may either be sourced from the +// filesystem or from an xDS API source. Filesystem configs are watched with +// inotify for updates. +// [#next-free-field: 7] +message ConfigSource { + oneof config_source_specifier { + // Path on the filesystem to source and watch for configuration updates. + // When sourcing configuration for :ref:`secret <envoy_api_msg_extensions.transport_sockets.tls.v3.Secret>`, + // the certificate and key files are also watched for updates. + // + // .. note:: + // + // The path to the source must exist at config load time. + // + // .. note:: + // + // Envoy will only watch the file path for *moves.* This is because in general only moves + // are atomic. The same method of swapping files as is demonstrated in the + // :ref:`runtime documentation <config_runtime_symbolic_link_swap>` can be used here also. + string path = 1; + + // When set, ADS will be used to fetch resources. The ADS API configuration + // source in the bootstrap configuration is used. + AggregatedConfigSource ads = 3; + + // [#not-implemented-hide:] + // When set, the client will access the resources from the same server it got the + // ConfigSource from, although not necessarily from the same stream. This is similar to the + // :ref:`ads<envoy_api_field.ConfigSource.ads>` field, except that the client may use a + // different stream to the same server. As a result, this field can be used for things + // like LRS that cannot be sent on an ADS stream. It can also be used to link from (e.g.) + // LDS to RDS on the same server without requiring the management server to know its name + // or required credentials. + // [#next-major-version: In xDS v3, consider replacing the ads field with this one, since + // this field can implicitly mean to use the same stream in the case where the ConfigSource + // is provided via ADS and the specified data can also be obtained via ADS.] + SelfConfigSource self = 5; + } +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/discovery.proto b/grpc/src/proto/grpc/testing/xds/v3/discovery.proto new file mode 100644 index 00000000..2a697d96 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/discovery.proto @@ -0,0 +1,122 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.service.discovery.v3; + +import "src/proto/grpc/testing/xds/v3/base.proto"; + +import "google/protobuf/any.proto"; + +message Status { + // The status code, which should be an enum value of [google.rpc.Code][]. + int32 code = 1; + + // A developer-facing error message, which should be in English. Any + // user-facing error message should be localized and sent in the + // [google.rpc.Status.details][] field, or localized by the client. + string message = 2; + + // A list of messages that carry the error details. There is a common set of + // message types for APIs to use. + repeated google.protobuf.Any details = 3; +} + +// [#protodoc-title: Common discovery API components] + +// A DiscoveryRequest requests a set of versioned resources of the same type for +// a given Envoy node on some API. +// [#next-free-field: 7] +message DiscoveryRequest { + // The version_info provided in the request messages will be the version_info + // received with the most recent successfully processed response or empty on + // the first request. It is expected that no new request is sent after a + // response is received until the Envoy instance is ready to ACK/NACK the new + // configuration. ACK/NACK takes place by returning the new API config version + // as applied or the previous API config version respectively. Each type_url + // (see below) has an independent version associated with it. + string version_info = 1; + + // The node making the request. + config.core.v3.Node node = 2; + + // List of resources to subscribe to, e.g. list of cluster names or a route + // configuration name. If this is empty, all resources for the API are + // returned. LDS/CDS may have empty resource_names, which will cause all + // resources for the Envoy instance to be returned. The LDS and CDS responses + // will then imply a number of resources that need to be fetched via EDS/RDS, + // which will be explicitly enumerated in resource_names. + repeated string resource_names = 3; + + // Type of the resource that is being requested, e.g. + // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This is implicit + // in requests made via singleton xDS APIs such as CDS, LDS, etc. but is + // required for ADS. + string type_url = 4; + + // nonce corresponding to DiscoveryResponse being ACK/NACKed. See above + // discussion on version_info and the DiscoveryResponse nonce comment. This + // may be empty only if 1) this is a non-persistent-stream xDS such as HTTP, + // or 2) the client has not yet accepted an update in this xDS stream (unlike + // delta, where it is populated only for new explicit ACKs). + string response_nonce = 5; + + // This is populated when the previous :ref:`DiscoveryResponse <envoy_api_msg_service.discovery.v3.DiscoveryResponse>` + // failed to update configuration. The *message* field in *error_details* provides the Envoy + // internal exception related to the failure. It is only intended for consumption during manual + // debugging, the string provided is not guaranteed to be stable across Envoy versions. + Status error_detail = 6; +} + +// [#next-free-field: 7] +message DiscoveryResponse { + // The version of the response data. + string version_info = 1; + + // The response resources. These resources are typed and depend on the API being called. + repeated google.protobuf.Any resources = 2; + + // [#not-implemented-hide:] + // Canary is used to support two Envoy command line flags: + // + // * --terminate-on-canary-transition-failure. When set, Envoy is able to + // terminate if it detects that configuration is stuck at canary. Consider + // this example sequence of updates: + // - Management server applies a canary config successfully. + // - Management server rolls back to a production config. + // - Envoy rejects the new production config. + // Since there is no sensible way to continue receiving configuration + // updates, Envoy will then terminate and apply production config from a + // clean slate. + // * --dry-run-canary. When set, a canary response will never be applied, only + // validated via a dry run. + bool canary = 3; + + // Type URL for resources. Identifies the xDS API when muxing over ADS. + // Must be consistent with the type_url in the 'resources' repeated Any (if non-empty). + string type_url = 4; + + // For gRPC based subscriptions, the nonce provides a way to explicitly ack a + // specific DiscoveryResponse in a following DiscoveryRequest. Additional + // messages may have been sent by Envoy to the management server for the + // previous version on the stream prior to this DiscoveryResponse, that were + // unprocessed at response send time. The nonce allows the management server + // to ignore any further DiscoveryRequests for the previous version until a + // DiscoveryRequest bearing the nonce. The nonce is optional and is not + // required for non-stream based xDS implementations. + string nonce = 5; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/endpoint.proto b/grpc/src/proto/grpc/testing/xds/v3/endpoint.proto new file mode 100644 index 00000000..7cc1d40c --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/endpoint.proto @@ -0,0 +1,176 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.config.endpoint.v3; + +import "src/proto/grpc/testing/xds/v3/address.proto"; +import "src/proto/grpc/testing/xds/v3/base.proto"; +import "src/proto/grpc/testing/xds/v3/percent.proto"; + +import "google/protobuf/wrappers.proto"; + +// [#protodoc-title: Endpoints] + +// Endpoint health status. +enum HealthStatus { + // The health status is not known. This is interpreted by Envoy as *HEALTHY*. + UNKNOWN = 0; + + // Healthy. + HEALTHY = 1; + + // Unhealthy. + UNHEALTHY = 2; + + // Connection draining in progress. E.g., + // `<https://aws.amazon.com/blogs/aws/elb-connection-draining-remove-instances-from-service-with-care/>`_ + // or + // `<https://cloud.google.com/compute/docs/load-balancing/enabling-connection-draining>`_. + // This is interpreted by Envoy as *UNHEALTHY*. + DRAINING = 3; + + // Health check timed out. This is part of HDS and is interpreted by Envoy as + // *UNHEALTHY*. + TIMEOUT = 4; + + // Degraded. + DEGRADED = 5; +} + +// Upstream host identifier. +message Endpoint { + // The upstream host address. + // + // .. attention:: + // + // The form of host address depends on the given cluster type. For STATIC or EDS, + // it is expected to be a direct IP address (or something resolvable by the + // specified :ref:`resolver <envoy_api_field_config.core.v3.SocketAddress.resolver_name>` + // in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname, + // and will be resolved via DNS. + core.v3.Address address = 1; +} + +// An Endpoint that Envoy can route traffic to. +// [#next-free-field: 6] +message LbEndpoint { + // Upstream host identifier or a named reference. + oneof host_identifier { + Endpoint endpoint = 1; + } + + // Optional health status when known and supplied by EDS server. + HealthStatus health_status = 2; +} + +// A group of endpoints belonging to a Locality. +// One can have multiple LocalityLbEndpoints for a locality, but this is +// generally only done if the different groups need to have different load +// balancing weights or different priorities. +// [#next-free-field: 7] +message LocalityLbEndpoints { + // Identifies location of where the upstream hosts run. + core.v3.Locality locality = 1; + + // The group of endpoints belonging to the locality specified. + repeated LbEndpoint lb_endpoints = 2; + + // Optional: Per priority/region/zone/sub_zone weight; at least 1. The load + // balancing weight for a locality is divided by the sum of the weights of all + // localities at the same priority level to produce the effective percentage + // of traffic for the locality. The sum of the weights of all localities at + // the same priority level must not exceed uint32_t maximal value (4294967295). + // + // Locality weights are only considered when :ref:`locality weighted load + // balancing <arch_overview_load_balancing_locality_weighted_lb>` is + // configured. These weights are ignored otherwise. If no weights are + // specified when locality weighted load balancing is enabled, the locality is + // assigned no load. + google.protobuf.UInt32Value load_balancing_weight = 3; + + // Optional: the priority for this LocalityLbEndpoints. If unspecified this will + // default to the highest priority (0). + // + // Under usual circumstances, Envoy will only select endpoints for the highest + // priority (0). In the event all endpoints for a particular priority are + // unavailable/unhealthy, Envoy will fail over to selecting endpoints for the + // next highest priority group. + // + // Priorities should range from 0 (highest) to N (lowest) without skipping. + uint32 priority = 5; +} + +// [#protodoc-title: Endpoint configuration] +// Endpoint discovery :ref:`architecture overview <arch_overview_service_discovery_types_eds>` + +// Each route from RDS will map to a single cluster or traffic split across +// clusters using weights expressed in the RDS WeightedCluster. +// +// With EDS, each cluster is treated independently from a LB perspective, with +// LB taking place between the Localities within a cluster and at a finer +// granularity between the hosts within a locality. The percentage of traffic +// for each endpoint is determined by both its load_balancing_weight, and the +// load_balancing_weight of its locality. First, a locality will be selected, +// then an endpoint within that locality will be chose based on its weight. +// [#next-free-field: 6] +message ClusterLoadAssignment { + // Load balancing policy settings. + // [#next-free-field: 6] + message Policy { + message DropOverload { + // Identifier for the policy specifying the drop. + string category = 1; + + // Percentage of traffic that should be dropped for the category. + type.v3.FractionalPercent drop_percentage = 2; + } + + // Action to trim the overall incoming traffic to protect the upstream + // hosts. This action allows protection in case the hosts are unable to + // recover from an outage, or unable to autoscale or unable to handle + // incoming traffic volume for any reason. + // + // At the client each category is applied one after the other to generate + // the 'actual' drop percentage on all outgoing traffic. For example: + // + // .. code-block:: json + // + // { "drop_overloads": [ + // { "category": "throttle", "drop_percentage": 60 } + // { "category": "lb", "drop_percentage": 50 } + // ]} + // + // The actual drop percentages applied to the traffic at the clients will be + // "throttle"_drop = 60% + // "lb"_drop = 20% // 50% of the remaining 'actual' load, which is 40%. + // actual_outgoing_load = 20% // remaining after applying all categories. + repeated DropOverload drop_overloads = 2; + } + + // Name of the cluster. This will be the :ref:`service_name + // <envoy_api_field_config.cluster.v3.Cluster.EdsClusterConfig.service_name>` value if specified + // in the cluster :ref:`EdsClusterConfig + // <envoy_api_msg_config.cluster.v3.Cluster.EdsClusterConfig>`. + string cluster_name = 1; + + // List of endpoints to load balance to. + repeated LocalityLbEndpoints endpoints = 2; + + // Load balancing policy settings. + Policy policy = 4; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/http_connection_manager.proto b/grpc/src/proto/grpc/testing/xds/v3/http_connection_manager.proto new file mode 100644 index 00000000..998ad561 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/http_connection_manager.proto @@ -0,0 +1,56 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.extensions.filters.network.http_connection_manager.v3; + +import "src/proto/grpc/testing/xds/v3/config_source.proto"; +import "src/proto/grpc/testing/xds/v3/route.proto"; + +// [#protodoc-title: HTTP connection manager] +// HTTP connection manager :ref:`configuration overview <config_http_conn_man>`. +// [#extension: envoy.filters.network.http_connection_manager] + +// [#next-free-field: 38] +message HttpConnectionManager { + oneof route_specifier { + // The connection manager’s route table will be dynamically loaded via the RDS API. + Rds rds = 3; + + // The route table for the connection manager is static and is specified in this property. + config.route.v3.RouteConfiguration route_config = 4; + + // A route table will be dynamically assigned to each request based on request attributes + // (e.g., the value of a header). The "routing scopes" (i.e., route tables) and "scope keys" are + // specified in this message. + ScopedRoutes scoped_routes = 31; + } +} + +message Rds { + // Configuration source specifier for RDS. + config.core.v3.ConfigSource config_source = 1; + + // The name of the route configuration. This name will be passed to the RDS + // API. This allows an Envoy configuration with multiple HTTP listeners (and + // associated HTTP connection manager filters) to use different route + // configurations. + string route_config_name = 2; +} + +message ScopedRoutes { +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/listener.proto b/grpc/src/proto/grpc/testing/xds/v3/listener.proto new file mode 100644 index 00000000..e9160e03 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/listener.proto @@ -0,0 +1,64 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.config.listener.v3; + +import "google/protobuf/any.proto"; + +// [#protodoc-title: Listener configuration] +// Listener :ref:`configuration overview <config_listeners>` + +// Describes a type of API listener, which is used in non-proxy clients. The type of API +// exposed to the non-proxy application depends on the type of API listener. +message ApiListener { + // The type in this field determines the type of API listener. At present, the following + // types are supported: + // envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager (HTTP) + // [#next-major-version: In the v3 API, replace this Any field with a oneof containing the + // specific config message for each type of API listener. We could not do this in v2 because + // it would have caused circular dependencies for go protos: lds.proto depends on this file, + // and http_connection_manager.proto depends on rds.proto, which is in the same directory as + // lds.proto, so lds.proto cannot depend on this file.] + google.protobuf.Any api_listener = 1; +} + +// [#next-free-field: 23] +message Listener { + // The unique name by which this listener is known. If no name is provided, + // Envoy will allocate an internal UUID for the listener. If the listener is to be dynamically + // updated or removed via :ref:`LDS <config_listeners_lds>` a unique name must be provided. + string name = 1; + + // Used to represent an API listener, which is used in non-proxy clients. The type of API + // exposed to the non-proxy application depends on the type of API listener. + // When this field is set, no other field except for :ref:`name<envoy_api_field_config.listener.v3.Listener.name>` + // should be set. + // + // .. note:: + // + // Currently only one ApiListener can be installed; and it can only be done via bootstrap config, + // not LDS. + // + // [#next-major-version: In the v3 API, instead of this messy approach where the socket + // listener fields are directly in the top-level Listener message and the API listener types + // are in the ApiListener message, the socket listener messages should be in their own message, + // and the top-level Listener should essentially be a oneof that selects between the + // socket listener and the various types of API listener. That way, a given Listener message + // can structurally only contain the fields of the relevant type.] + ApiListener api_listener = 19; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/load_report.proto b/grpc/src/proto/grpc/testing/xds/v3/load_report.proto new file mode 100644 index 00000000..b8ee86fb --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/load_report.proto @@ -0,0 +1,162 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.config.endpoint.v3; + +import "src/proto/grpc/testing/xds/v3/address.proto"; +import "src/proto/grpc/testing/xds/v3/base.proto"; + +import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; + +// These are stats Envoy reports to GLB every so often. Report frequency is +// defined by +// :ref:`LoadStatsResponse.load_reporting_interval<envoy_api_field_service.load_stats.v3.LoadStatsResponse.load_reporting_interval>`. +// Stats per upstream region/zone and optionally per subzone. +// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. +// [#next-free-field: 9] +message UpstreamLocalityStats { + // Name of zone, region and optionally endpoint group these metrics were + // collected from. Zone and region names could be empty if unknown. + core.v3.Locality locality = 1; + + // The total number of requests successfully completed by the endpoints in the + // locality. + uint64 total_successful_requests = 2; + + // The total number of unfinished requests + uint64 total_requests_in_progress = 3; + + // The total number of requests that failed due to errors at the endpoint, + // aggregated over all endpoints in the locality. + uint64 total_error_requests = 4; + + // The total number of requests that were issued by this Envoy since + // the last report. This information is aggregated over all the + // upstream endpoints in the locality. + uint64 total_issued_requests = 8; + + // Stats for multi-dimensional load balancing. + repeated EndpointLoadMetricStats load_metric_stats = 5; + + // Endpoint granularity stats information for this locality. This information + // is populated if the Server requests it by setting + // :ref:`LoadStatsResponse.report_endpoint_granularity<envoy_api_field_service.load_stats.v3.LoadStatsResponse.report_endpoint_granularity>`. + repeated UpstreamEndpointStats upstream_endpoint_stats = 7; + + // [#not-implemented-hide:] The priority of the endpoint group these metrics + // were collected from. + uint32 priority = 6; +} + +// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. +// [#next-free-field: 8] +message UpstreamEndpointStats { + // Upstream host address. + core.v3.Address address = 1; + + // Opaque and implementation dependent metadata of the + // endpoint. Envoy will pass this directly to the management server. + google.protobuf.Struct metadata = 6; + + // The total number of requests successfully completed by the endpoints in the + // locality. These include non-5xx responses for HTTP, where errors + // originate at the client and the endpoint responded successfully. For gRPC, + // the grpc-status values are those not covered by total_error_requests below. + uint64 total_successful_requests = 2; + + // The total number of unfinished requests for this endpoint. + uint64 total_requests_in_progress = 3; + + // The total number of requests that failed due to errors at the endpoint. + // For HTTP these are responses with 5xx status codes and for gRPC the + // grpc-status values: + // + // - DeadlineExceeded + // - Unimplemented + // - Internal + // - Unavailable + // - Unknown + // - DataLoss + uint64 total_error_requests = 4; + + // The total number of requests that were issued to this endpoint + // since the last report. A single TCP connection, HTTP or gRPC + // request or stream is counted as one request. + uint64 total_issued_requests = 7; + + // Stats for multi-dimensional load balancing. + repeated EndpointLoadMetricStats load_metric_stats = 5; +} + +// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. +message EndpointLoadMetricStats { + // Name of the metric; may be empty. + string metric_name = 1; + + // Number of calls that finished and included this metric. + uint64 num_requests_finished_with_metric = 2; + + // Sum of metric values across all calls that finished with this metric for + // load_reporting_interval. + double total_metric_value = 3; +} + +// Per cluster load stats. Envoy reports these stats a management server in a +// :ref:`LoadStatsRequest<envoy_api_msg_service.load_stats.v3.LoadStatsRequest>` +// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. +// Next ID: 7 +// [#next-free-field: 7] +message ClusterStats { + message DroppedRequests { + // Identifier for the policy specifying the drop. + string category = 1; + + // Total number of deliberately dropped requests for the category. + uint64 dropped_count = 2; + } + + // The name of the cluster. + string cluster_name = 1; + + // The eds_cluster_config service_name of the cluster. + // It's possible that two clusters send the same service_name to EDS, + // in that case, the management server is supposed to do aggregation on the load reports. + string cluster_service_name = 6; + + // Need at least one. + repeated UpstreamLocalityStats upstream_locality_stats = 2; + + // Cluster-level stats such as total_successful_requests may be computed by + // summing upstream_locality_stats. In addition, below there are additional + // cluster-wide stats. + // + // The total number of dropped requests. This covers requests + // deliberately dropped by the drop_overload policy and circuit breaking. + uint64 total_dropped_requests = 3; + + // Information about deliberately dropped requests for each category specified + // in the DropOverload policy. + repeated DroppedRequests dropped_requests = 5; + + // Period over which the actual load report occurred. This will be guaranteed to include every + // request reported. Due to system load and delays between the *LoadStatsRequest* sent from Envoy + // and the *LoadStatsResponse* message sent from the management server, this may be longer than + // the requested load reporting interval in the *LoadStatsResponse*. + google.protobuf.Duration load_report_interval = 4; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/lrs.proto b/grpc/src/proto/grpc/testing/xds/v3/lrs.proto new file mode 100644 index 00000000..e118b7f9 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/lrs.proto @@ -0,0 +1,96 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.service.load_stats.v3; + +import "src/proto/grpc/testing/xds/v3/base.proto"; +import "src/proto/grpc/testing/xds/v3/load_report.proto"; + +import "google/protobuf/duration.proto"; + +// [#protodoc-title: Load reporting service] + +service LoadReportingService { + // Advanced API to allow for multi-dimensional load balancing by remote + // server. For receiving LB assignments, the steps are: + // 1, The management server is configured with per cluster/zone/load metric + // capacity configuration. The capacity configuration definition is + // outside of the scope of this document. + // 2. Envoy issues a standard {Stream,Fetch}Endpoints request for the clusters + // to balance. + // + // Independently, Envoy will initiate a StreamLoadStats bidi stream with a + // management server: + // 1. Once a connection establishes, the management server publishes a + // LoadStatsResponse for all clusters it is interested in learning load + // stats about. + // 2. For each cluster, Envoy load balances incoming traffic to upstream hosts + // based on per-zone weights and/or per-instance weights (if specified) + // based on intra-zone LbPolicy. This information comes from the above + // {Stream,Fetch}Endpoints. + // 3. When upstream hosts reply, they optionally add header <define header + // name> with ASCII representation of EndpointLoadMetricStats. + // 4. Envoy aggregates load reports over the period of time given to it in + // LoadStatsResponse.load_reporting_interval. This includes aggregation + // stats Envoy maintains by itself (total_requests, rpc_errors etc.) as + // well as load metrics from upstream hosts. + // 5. When the timer of load_reporting_interval expires, Envoy sends new + // LoadStatsRequest filled with load reports for each cluster. + // 6. The management server uses the load reports from all reported Envoys + // from around the world, computes global assignment and prepares traffic + // assignment destined for each zone Envoys are located in. Goto 2. + rpc StreamLoadStats(stream LoadStatsRequest) returns (stream LoadStatsResponse) { + } +} + +// A load report Envoy sends to the management server. +// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. +message LoadStatsRequest { + // Node identifier for Envoy instance. + config.core.v3.Node node = 1; + + // A list of load stats to report. + repeated config.endpoint.v3.ClusterStats cluster_stats = 2; +} + +// The management server sends envoy a LoadStatsResponse with all clusters it +// is interested in learning load stats about. +// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. +message LoadStatsResponse { + // Clusters to report stats for. + // Not populated if *send_all_clusters* is true. + repeated string clusters = 1; + + // If true, the client should send all clusters it knows about. + // Only clients that advertise the "envoy.lrs.supports_send_all_clusters" capability in their + // :ref:`client_features<envoy_api_field_config.core.v3.Node.client_features>` field will honor this field. + bool send_all_clusters = 4; + + // The minimum interval of time to collect stats over. This is only a minimum for two reasons: + // 1. There may be some delay from when the timer fires until stats sampling occurs. + // 2. For clusters that were already feature in the previous *LoadStatsResponse*, any traffic + // that is observed in between the corresponding previous *LoadStatsRequest* and this + // *LoadStatsResponse* will also be accumulated and billed to the cluster. This avoids a period + // of inobservability that might otherwise exists between the messages. New clusters are not + // subject to this consideration. + google.protobuf.Duration load_reporting_interval = 2; + + // Set to *true* if the management server supports endpoint granularity + // report. + bool report_endpoint_granularity = 3; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/orca_load_report.proto b/grpc/src/proto/grpc/testing/xds/v3/orca_load_report.proto new file mode 100644 index 00000000..0d6a1699 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/orca_load_report.proto @@ -0,0 +1,44 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package udpa.data.orca.v1; + +// See section `ORCA load report format` of the design document in +// :ref:`https://github.com/envoyproxy/envoy/issues/6614`. + +message OrcaLoadReport { + // CPU utilization expressed as a fraction of available CPU resources. This + // should be derived from the latest sample or measurement. + double cpu_utilization = 1; + + // Memory utilization expressed as a fraction of available memory + // resources. This should be derived from the latest sample or measurement. + double mem_utilization = 2; + + // Total RPS being served by an endpoint. This should cover all services that an endpoint is + // responsible for. + uint64 rps = 3; + + // Application specific requests costs. Each value is an absolute cost (e.g. 3487 bytes of + // storage) associated with the request. + map<string, double> request_cost = 4; + + // Resource utilization values. Each value is expressed as a fraction of total resources + // available, derived from the latest sample or measurement. + map<string, double> utilization = 5; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/percent.proto b/grpc/src/proto/grpc/testing/xds/v3/percent.proto new file mode 100644 index 00000000..dacc9749 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/percent.proto @@ -0,0 +1,52 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.type.v3; + +// A fractional percentage is used in cases in which for performance reasons performing floating +// point to integer conversions during randomness calculations is undesirable. The message includes +// both a numerator and denominator that together determine the final fractional value. +// +// * **Example**: 1/100 = 1%. +// * **Example**: 3/10000 = 0.03%. +message FractionalPercent { + // Fraction percentages support several fixed denominator values. + enum DenominatorType { + // 100. + // + // **Example**: 1/100 = 1%. + HUNDRED = 0; + + // 10,000. + // + // **Example**: 1/10000 = 0.01%. + TEN_THOUSAND = 1; + + // 1,000,000. + // + // **Example**: 1/1000000 = 0.0001%. + MILLION = 2; + } + + // Specifies the numerator. Defaults to 0. + uint32 numerator = 1; + + // Specifies the denominator. If the denominator specified is less than the numerator, the final + // fractional percentage is capped at 1 (100%). + DenominatorType denominator = 2; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/range.proto b/grpc/src/proto/grpc/testing/xds/v3/range.proto new file mode 100644 index 00000000..5fe5530e --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/range.proto @@ -0,0 +1,31 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.type.v3; + +// [#protodoc-title: Range] + +// Specifies the int64 start and end of the range using half-open interval semantics [start, +// end). +message Int64Range { + // start of the range (inclusive) + int64 start = 1; + + // end of the range (exclusive) + int64 end = 2; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/regex.proto b/grpc/src/proto/grpc/testing/xds/v3/regex.proto new file mode 100644 index 00000000..af904577 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/regex.proto @@ -0,0 +1,38 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.type.matcher.v3; + +// [#protodoc-title: Regex matcher] + +// A regex matcher designed for safety when used with untrusted input. +message RegexMatcher { + // Google's `RE2 <https://github.com/google/re2>`_ regex engine. The regex string must adhere to + // the documented `syntax <https://github.com/google/re2/wiki/Syntax>`_. The engine is designed + // to complete execution in linear time as well as limit the amount of memory used. + message GoogleRE2 { + } + + oneof engine_type { + // Google's RE2 regex engine. + GoogleRE2 google_re2 = 1; + } + + // The regex match string. The string must be supported by the configured engine. + string regex = 2; +} diff --git a/grpc/src/proto/grpc/testing/xds/v3/route.proto b/grpc/src/proto/grpc/testing/xds/v3/route.proto new file mode 100644 index 00000000..309f80a0 --- /dev/null +++ b/grpc/src/proto/grpc/testing/xds/v3/route.proto @@ -0,0 +1,315 @@ +// Copyright 2020 The gRPC Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Local copy of Envoy xDS proto file, used for testing only. + +syntax = "proto3"; + +package envoy.config.route.v3; + +import "src/proto/grpc/testing/xds/v3/base.proto"; +import "src/proto/grpc/testing/xds/v3/regex.proto"; +import "src/proto/grpc/testing/xds/v3/percent.proto"; +import "src/proto/grpc/testing/xds/v3/range.proto"; + +import "google/protobuf/wrappers.proto"; + +// [#protodoc-title: HTTP route components] +// * Routing :ref:`architecture overview <arch_overview_http_routing>` +// * HTTP :ref:`router filter <config_http_filters_router>` + +// The top level element in the routing configuration is a virtual host. Each virtual host has +// a logical name as well as a set of domains that get routed to it based on the incoming request's +// host header. This allows a single listener to service multiple top level domain path trees. Once +// a virtual host is selected based on the domain, the routes are processed in order to see which +// upstream cluster to route to or whether to perform a redirect. +// [#next-free-field: 21] +message VirtualHost { + // The logical name of the virtual host. This is used when emitting certain + // statistics but is not relevant for routing. + string name = 1; + + // A list of domains (host/authority header) that will be matched to this + // virtual host. Wildcard hosts are supported in the suffix or prefix form. + // + // Domain search order: + // 1. Exact domain names: ``www.foo.com``. + // 2. Suffix domain wildcards: ``*.foo.com`` or ``*-bar.foo.com``. + // 3. Prefix domain wildcards: ``foo.*`` or ``foo-*``. + // 4. Special wildcard ``*`` matching any domain. + // + // .. note:: + // + // The wildcard will not match the empty string. + // e.g. ``*-bar.foo.com`` will match ``baz-bar.foo.com`` but not ``-bar.foo.com``. + // The longest wildcards match first. + // 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 fail to load. + // + // Domains cannot contain control characters. This is validated by the well_known_regex HTTP_HEADER_VALUE. + repeated string domains = 2; + + // The list of routes that will be matched, in order, for incoming requests. + // The first route that matches will be used. + repeated Route routes = 3; +} + +// A route is both a specification of how to match a request as well as an indication of what to do +// next (e.g., redirect, forward, rewrite, etc.). +// +// .. attention:: +// +// Envoy supports routing on HTTP method via :ref:`header matching +// <envoy_api_msg_config.route.v3.HeaderMatcher>`. +// [#next-free-field: 18] +message Route { + // Name for the route. + string name = 14; + + // Route matching parameters. + RouteMatch match = 1; + + oneof action { + // Route request to some upstream cluster. + RouteAction route = 2; + + // Return a redirect. + RedirectAction redirect = 3; + } +} + +// Compared to the :ref:`cluster <envoy_api_field_config.route.v3.RouteAction.cluster>` field that specifies a +// single upstream cluster as the target of a request, the :ref:`weighted_clusters +// <envoy_api_field_config.route.v3.RouteAction.weighted_clusters>` option allows for specification of +// multiple upstream clusters along with weights that indicate the percentage of +// traffic to be forwarded to each cluster. The router selects an upstream cluster based on the +// weights. +message WeightedCluster { + // [#next-free-field: 11] + message ClusterWeight { + // Name of the upstream cluster. The cluster must exist in the + // :ref:`cluster manager configuration <config_cluster_manager>`. + string name = 1; + + // An integer between 0 and :ref:`total_weight + // <envoy_api_field_config.route.v3.WeightedCluster.total_weight>`. When a request matches the route, + // the choice of an upstream cluster is determined by its weight. The sum of weights across all + // entries in the clusters array must add up to the total_weight, which defaults to 100. + google.protobuf.UInt32Value weight = 2; + } + + // Specifies one or more upstream clusters associated with the route. + repeated ClusterWeight clusters = 1; + + // Specifies the total weight across all clusters. The sum of all cluster weights must equal this + // value, which must be greater than 0. Defaults to 100. + google.protobuf.UInt32Value total_weight = 3; +} + +// [#next-free-field: 13] +message RouteMatch { + oneof path_specifier { + // If specified, the route is a prefix rule meaning that the prefix must + // match the beginning of the *:path* header. + string prefix = 1; + + // 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. + string path = 2; + + // 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. + // + // [#next-major-version: In the v3 API we should redo how path specification works such + // that we utilize StringMatcher, and additionally have consistent options around whether we + // strip query strings, do a case sensitive match, etc. In the interim it will be too disruptive + // to deprecate the existing options. We should even consider whether we want to do away with + // path_specifier entirely and just rely on a set of header matchers which can already match + // on :path, etc. The issue with that is it is unclear how to generically deal with query string + // stripping. This needs more thought.] + type.matcher.v3.RegexMatcher safe_regex = 10; + } + + // Indicates that prefix/path matching should be case insensitive. The default + // is true. + google.protobuf.BoolValue case_sensitive = 4; + + // Indicates that the route should additionally match on a runtime key. Every time the route + // is considered for a match, it must also fall under the percentage of matches indicated by + // this field. For some fraction N/D, a random number in the range [0,D) is selected. If the + // number is <= the value of the numerator N, or if the key is not present, the default + // value, the router continues to evaluate the remaining match criteria. A runtime_fraction + // route configuration can be used to roll out route changes in a gradual manner without full + // code/config deploys. Refer to the :ref:`traffic shifting + // <config_http_conn_man_route_table_traffic_splitting_shift>` docs for additional documentation. + // + // .. note:: + // + // Parsing this field is implemented such that the runtime key's data may be represented + // as a FractionalPercent proto represented as JSON/YAML and may also be represented as an + // integer with the assumption that the value is an integral percentage out of 100. For + // instance, a runtime key lookup returning the value "42" would parse as a FractionalPercent + // whose numerator is 42 and denominator is HUNDRED. This preserves legacy semantics. + core.v3.RuntimeFractionalPercent runtime_fraction = 9; + + // 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). + repeated HeaderMatcher headers = 6; + + // 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. + repeated QueryParameterMatcher query_parameters = 7; +} + +// [#next-free-field: 34] +message RouteAction { + oneof cluster_specifier { + // Indicates the upstream cluster to which the request should be routed + // to. + string cluster = 1; + + // 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. + // + // .. attention:: + // + // Internally, Envoy 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. + string cluster_header = 2; + + // Multiple upstream clusters can be specified for a given route. The + // request is routed to one of the upstream clusters based on weights + // assigned to each cluster. See + // :ref:`traffic splitting <config_http_conn_man_route_table_traffic_splitting_split>` + // for additional documentation. + WeightedCluster weighted_clusters = 3; + } +} + +// .. attention:: +// +// Internally, Envoy 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. +// +// .. attention:: +// +// To route on HTTP method, use the special HTTP/2 *:method* header. This works for both +// HTTP/1 and HTTP/2 as Envoy normalizes headers. E.g., +// +// .. code-block:: json +// +// { +// "name": ":method", +// "exact_match": "POST" +// } +// +// .. attention:: +// In the absence of any header match specifier, match will default to :ref:`present_match +// <envoy_api_field_config.route.v3.HeaderMatcher.present_match>`. i.e, a request that has the :ref:`name +// <envoy_api_field_config.route.v3.HeaderMatcher.name>` header will match, regardless of the header's +// value. +// +// [#next-major-version: HeaderMatcher should be refactored to use StringMatcher.] +// [#next-free-field: 12] +message HeaderMatcher { + // Specifies the name of the header in the request. + string name = 1; + + // Specifies how the header match will be performed to route the request. + oneof header_match_specifier { + // If specified, header match will be performed based on the value of the header. + string exact_match = 4; + + // If specified, this regex string is a regular expression rule which implies the entire request + // header value must match the regex. The rule will not match if only a subsequence of the + // request header value matches the regex. + type.matcher.v3.RegexMatcher safe_regex_match = 11; + + // If specified, header match will be performed based on range. + // The rule will match if the request header value is within this range. + // The entire request header value must represent an integer in base 10 notation: consisting of + // an optional plus or minus sign followed by a sequence of digits. The rule will not match if + // the header value does not represent an integer. Match will fail for empty values, floating + // point numbers or if only a subsequence of the header value is an integer. + // + // Examples: + // + // * For range [-10,0), route will match for header value -1, but not for 0, "somestring", 10.9, + // "-1somestring" + type.v3.Int64Range range_match = 6; + + // If specified, header match will be performed based on whether the header is in the + // request. + bool present_match = 7; + + // If specified, header match will be performed based on the prefix of the header value. + // Note: empty prefix is not allowed, please use present_match instead. + // + // Examples: + // + // * The prefix *abcd* matches the value *abcdxyz*, but not for *abcxyz*. + string prefix_match = 9; + + // If specified, header match will be performed based on the suffix of the header value. + // Note: empty suffix is not allowed, please use present_match instead. + // + // Examples: + // + // * The suffix *abcd* matches the value *xyzabcd*, but not for *xyzbcd*. + string suffix_match = 10; + } + + // If specified, the match result will be inverted before checking. Defaults to false. + // + // Examples: + // + // * The regex ``\d{3}`` does not match the value *1234*, so it will match when inverted. + // * The range [-10,0) will match the value -1, so it will not match when inverted. + bool invert_match = 8; +} + +// 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. +// [#next-free-field: 7] +message QueryParameterMatcher { +} + +// [#protodoc-title: HTTP route configuration] +// * Routing :ref:`architecture overview <arch_overview_http_routing>` +// * HTTP :ref:`router filter <config_http_filters_router>` + +// [#next-free-field: 11] +message RouteConfiguration { + // The name of the route configuration. For example, it might match + // :ref:`route_config_name + // <envoy_api_field_extensions.filters.network.http_connection_manager.v3.Rds.route_config_name>` in + // :ref:`envoy_api_msg_extensions.filters.network.http_connection_manager.v3.Rds`. + string name = 1; + + // An array of virtual hosts that make up the route table. + repeated VirtualHost virtual_hosts = 2; +} + +message RedirectAction { +} |