data-plane-api/api/base.proto

syntax = "proto3";

package envoy.api.v2;

import "api/address.proto";

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

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

  // Availability Zone (AZ) in AWS, Zone in GCP.
  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. Remote server may have per Envoy configuration.
message Node {
  string id = 1;
  google.protobuf.Struct metadata = 2;
  Locality locality = 3;
}

message Endpoint {
  ResolvedAddress address = 1;
}

// Metadata provides additional inputs to filters based on matched listeners,
// filter chains and routes. 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.
message Metadata {
  // Key is the reverse DNS filter name.
  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 comparision. This value is used if defined.
  string runtime_key = 3;
}

// Envoy supports upstream priority routing 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;
}

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

  // Header value.
  string value = 2;
}

// Header name/value pair plus option to control append behavior.
message HeaderValueOption {
  // Header Name/Value pair that this option applies to.
  //
  // The same format specifier as used for HTTP access logging applies here,
  // however unknown header values are replaced with the empty string instead
  // of -. [V2-API-DIFF].
  HeaderValue header = 1;

  // Should the value be appended? If false (default), the value overrides
  // existing values [V2-API-DIFF].
  google.protobuf.BoolValue append = 2;
}

// A DiscoveryRequest requests a set of versioned resources of the same type for
// a given Envoy node on some API.
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.
  string version_info = 1;
  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.
  repeated string resource_names = 3;
}

message DiscoveryResponse {
  string version_info = 1;
  repeated google.protobuf.Any resources = 2;
}