data-plane-api/api/base.proto

syntax = "proto3";

package envoy.api.v2;
option go_package = "api";

import "api/address.proto";

import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

import "validate/validate.proto";

// [#protodoc-title: Common types]

// Identifies location of where either Envoy runs or where upstream hosts run.
message Locality {
  // Region this :ref:`zone <envoy_api_field_Locality.zone>` belongs to.
  string region = 1;

  // `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.
message Node {
  // An opaque node identifier for the Envoy node.
  string id = 1 [(validate.rules).string.min_bytes = 1];
  // The cluster that the Envoy node belongs to.
  string cluster = 2 [(validate.rules).string.min_bytes = 1];
  // 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;
  // This is motivated by informing a management server during canary which
  // version of Envoy is being tested in a heterogeneous fleet. This will be set
  // by Envoy in management server RPCs.
  string build_version = 5;
}

// Upstream host identifier.
message Endpoint {
  Address address = 1;
}

// Metadata provides additional inputs to filters based on matched listeners,
// filter chains, routes and endpoints. It is structured as a map 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.
//
// 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.
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, google.protobuf.Struct> filter_metadata = 1;
}

// Runtime derived uint32 with a default when not specified.
message RuntimeUInt32 {
  // Default value if runtime value is not available.
  uint32 default_value = 2;

  // Runtime key to get value for comparison. This value is used if defined.
  string runtime_key = 3 [(validate.rules).string.min_bytes = 1];
}

// Envoy supports :ref:`upstream priority routing
// <arch_overview_http_routing_priority>` both at the route and the virtual
// cluster level. The current priority implementation uses different connection
// pool and circuit breaking settings for each priority level. This means that
// even for HTTP/2 requests, two physical connections will be used to an
// upstream host. In the future Envoy will likely support true HTTP/2 priority
// over a single upstream connection.
enum RoutingPriority {
  DEFAULT = 0;
  HIGH = 1;
}

// HTTP request method.
enum RequestMethod {
  METHOD_UNSPECIFIED = 0;
  GET = 1;
  HEAD = 2;
  POST = 3;
  PUT = 4;
  DELETE = 5;
  CONNECT = 6;
  OPTIONS = 7;
  TRACE = 8;
}

// Header name/value pair.
message HeaderValue {
  // Header name.
  string key = 1;

  // Header value.
  //
  // The same :ref:`format specifier <config_access_log_format>` as used for
  // :ref:`HTTP access logging <config_access_log>` applies here, however
  // unknown header values are replaced with the empty string instead of `-`.
  string value = 2;
}

// Header name/value pair plus option to control append behavior.
message HeaderValueOption {
  // Header name/value pair that this option applies to.
  HeaderValue header = 1;

  // Should the value be appended? If true (default), the value is appended to
  // existing values.
  google.protobuf.BoolValue append = 2;
}

// API configuration source. This identifies the API type and cluster that Envoy
// will use to fetch an xDS API.
message ApiConfigSource {
  // APIs may be fetched via either REST or gRPC.
  enum ApiType {
    // REST-JSON legacy corresponds to the v1 API.
    REST_LEGACY = 0;
    // REST-JSON v2 API. The `canonical JSON encoding
    // <https://developers.google.com/protocol-buffers/docs/proto3#json>`_ for
    // the v2 protos is used.
    REST = 1;
    // gRPC v2 API.
    GRPC = 2;
  }
  ApiType api_type = 1;
  // Multiple cluster names may be provided. If > 1 cluster is defined, clusters
  // will be cycled through if any kind of failure occurs.
  repeated string cluster_name = 2 [(validate.rules).repeated .min_items = 1];
  // For REST APIs, the delay between successive polls.
  google.protobuf.Duration refresh_delay = 3;
}

// Aggregated Discovery Service (ADS) options. This is currently empty, but when
// set in :ref:`ConfigSource <envoy_api_msg_ConfigSource>` can be used to
// specify that ADS is to be used.
message AggregatedConfigSource {
}

// Configuration for :ref:`listeners <config_listeners>`, :ref:`clusters
// <config_cluster_manager_cluster>`, :ref:`routes
// <config_http_conn_man_route_table>`, :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.
message ConfigSource {
  oneof config_source_specifier {
    option (validate.required) = true;
    // Path on the filesystem to source and watch for configuration updates.
    string path = 1;
    // API configuration source.
    ApiConfigSource api_config_source = 2;
    // When set, ADS will be used to fetch resources. The ADS API configuration
    // source in the bootstrap configuration is used.
    AggregatedConfigSource ads = 3;
  }
}

// Configuration for transport socket in :ref:`listeners <config_listeners>` and
// :ref:`clusters <config_cluster_manager_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 [(validate.rules).string.min_bytes = 1];

  // Implementation specific configuration which depends on the implementation being instantiated.
  // See the supported transport socket implementations for further documentation.
  google.protobuf.Struct config = 2;
}