data-plane-api/envoy/config/route/v3/scoped_route.proto

syntax = "proto3";

package envoy.config.route.v3;

import "envoy/config/route/v3/route.proto";

import "udpa/annotations/migrate.proto";
import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";
import "validate/validate.proto";

option java_package = "io.envoyproxy.envoy.config.route.v3";
option java_outer_classname = "ScopedRouteProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/route/v3;routev3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: HTTP scoped routing configuration]
// * Routing :ref:`architecture overview <arch_overview_http_routing>`

// Specifies a routing scope, which associates a
// :ref:`Key<envoy_v3_api_msg_config.route.v3.ScopedRouteConfiguration.Key>` to a
// :ref:`envoy_v3_api_msg_config.route.v3.RouteConfiguration`.
// The :ref:`envoy_v3_api_msg_config.route.v3.RouteConfiguration` can be obtained dynamically
// via RDS (:ref:`route_configuration_name<envoy_v3_api_field_config.route.v3.ScopedRouteConfiguration.route_configuration_name>`)
// or specified inline (:ref:`route_configuration<envoy_v3_api_field_config.route.v3.ScopedRouteConfiguration.route_configuration>`).
//
// The HTTP connection manager builds up a table consisting of these Key to
// RouteConfiguration mappings, and looks up the RouteConfiguration to use per
// request according to the algorithm specified in the
// :ref:`scope_key_builder<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.ScopedRoutes.scope_key_builder>`
// assigned to the HttpConnectionManager.
//
// For example, with the following configurations (in YAML):
//
// HttpConnectionManager config:
//
// .. code::
//
//   ...
//   scoped_routes:
//     name: foo-scoped-routes
//     scope_key_builder:
//       fragments:
//         - header_value_extractor:
//             name: X-Route-Selector
//             element_separator: ,
//             element:
//               separator: =
//               key: vip
//
// ScopedRouteConfiguration resources (specified statically via
// :ref:`scoped_route_configurations_list<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.ScopedRoutes.scoped_route_configurations_list>`
// or obtained dynamically via SRDS):
//
// .. code::
//
//  (1)
//   name: route-scope1
//   route_configuration_name: route-config1
//   key:
//      fragments:
//        - string_key: 172.10.10.20
//
//  (2)
//   name: route-scope2
//   route_configuration_name: route-config2
//   key:
//     fragments:
//       - string_key: 172.20.20.30
//
// A request from a client such as:
//
// .. code::
//
//     GET / HTTP/1.1
//     Host: foo.com
//     X-Route-Selector: vip=172.10.10.20
//
// would result in the routing table defined by the `route-config1`
// RouteConfiguration being assigned to the HTTP request/stream.
//
// [#next-free-field: 6]
message ScopedRouteConfiguration {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.api.v2.ScopedRouteConfiguration";

  // Specifies a key which is matched against the output of the
  // :ref:`scope_key_builder<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.ScopedRoutes.scope_key_builder>`
  // specified in the HttpConnectionManager. The matching is done per HTTP
  // request and is dependent on the order of the fragments contained in the
  // Key.
  message Key {
    option (udpa.annotations.versioning).previous_message_type =
        "envoy.api.v2.ScopedRouteConfiguration.Key";

    message Fragment {
      option (udpa.annotations.versioning).previous_message_type =
          "envoy.api.v2.ScopedRouteConfiguration.Key.Fragment";

      oneof type {
        option (validate.required) = true;

        // A string to match against.
        string string_key = 1;
      }
    }

    // The ordered set of fragments to match against. The order must match the
    // fragments in the corresponding
    // :ref:`scope_key_builder<envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.ScopedRoutes.scope_key_builder>`.
    repeated Fragment fragments = 1 [(validate.rules).repeated = {min_items: 1}];
  }

  // Whether the RouteConfiguration should be loaded on demand.
  bool on_demand = 4;

  // The name assigned to the routing scope.
  string name = 1 [(validate.rules).string = {min_len: 1}];

  // The resource name to use for a :ref:`envoy_v3_api_msg_service.discovery.v3.DiscoveryRequest` to an
  // RDS server to fetch the :ref:`envoy_v3_api_msg_config.route.v3.RouteConfiguration` associated
  // with this scope.
  string route_configuration_name = 2
      [(udpa.annotations.field_migrate).oneof_promotion = "route_config"];

  // The :ref:`envoy_v3_api_msg_config.route.v3.RouteConfiguration` associated with the scope.
  RouteConfiguration route_configuration = 5
      [(udpa.annotations.field_migrate).oneof_promotion = "route_config"];

  // The key to match against.
  Key key = 3 [(validate.rules).message = {required: true}];
}