xds/v3/base.proto

// 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/any.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;
}

// Data source consisting of either a file or an inline value.
message DataSource {}

// 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;
}

// Configuration for transport socket in :ref:`listeners <config_listeners>` and
// :ref:`clusters <envoy_api_msg_config.cluster.v3.Cluster>`. If the configuration is
// empty, a default transport socket implementation and configuration will be
// chosen based on the platform and existence of tls_context.
message TransportSocket {
  // The name of the transport socket to instantiate. The name must match a supported transport
  // socket implementation.
  string name = 1;

  // Implementation specific configuration which depends on the implementation being instantiated.
  // See the supported transport socket implementations for further documentation.
  oneof config_type {
    google.protobuf.Any typed_config = 3;
  }
}

// Metadata provides additional inputs to filters based on matched listeners,
// filter chains, routes and endpoints. It is structured as a map, usually from
// filter name (in reverse DNS format) to metadata specific to the filter. Metadata
// key-values for a filter are merged as connection and request handling occurs,
// with later values for the same key overriding earlier values.
//
// An example use of metadata is providing additional values to
// http_connection_manager in the envoy.http_connection_manager.access_log
// namespace.
//
// Another example use of metadata is to per service config info in cluster metadata, which may get
// consumed by multiple filters.
//
// For load balancing, Metadata provides a means to subset cluster endpoints.
// Endpoints have a Metadata object associated and routes contain a Metadata
// object to match against. There are some well defined metadata used today for
// this purpose:
//
// * ``{"envoy.lb": {"canary": <bool> }}`` This indicates the canary status of an
//   endpoint and is also used during header processing
//   (x-envoy-upstream-canary) and for stats purposes.
// [#next-major-version: move to type/metadata/v2]
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.
  // If both ``filter_metadata`` and
  // :ref:`typed_filter_metadata <envoy_v3_api_field_config.core.v3.Metadata.typed_filter_metadata>`
  // fields are present in the metadata with same keys,
  // only ``typed_filter_metadata`` field will be parsed.
  map<string, google.protobuf.Struct> filter_metadata = 1;

  // Key is the reverse DNS filter name, e.g. com.acme.widget. The ``envoy.*``
  // namespace is reserved for Envoy's built-in filters.
  // The value is encoded as google.protobuf.Any.
  // If both :ref:`filter_metadata <envoy_v3_api_field_config.core.v3.Metadata.filter_metadata>`
  // and ``typed_filter_metadata`` fields are present in the metadata with same keys,
  // only ``typed_filter_metadata`` field will be parsed.
  map<string, google.protobuf.Any> typed_filter_metadata = 2;
}