data-plane-api/api/base.proto

syntax = "proto3";

package envoy.api.v2;

import "api/address.proto";

import "google/protobuf/duration.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 {
  // An opaque node identifier for the Envoy node. This must be set.
  string id = 1;
  // The cluster that the Envoy node belongs to. This must be set.
  string cluster = 2;
  google.protobuf.Struct metadata = 3;
  Locality locality = 4;
  // This is motivated by informing a management server during canary which
  // version of Envoy is being tested in a heterogeneous fleet.
  string build_version = 5;
}

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

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

message ApiConfigSource {
  // APIs may be fetched via either REST or gRPC.
  enum ApiType {
    // REST legacy corresponds to the v1 API.
    REST_LEGACY = 0;
    REST = 1;
    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;
  // For REST APIs, the delay between successive polls.
  google.protobuf.Duration refresh_delay = 3;
}

// ADS will be used to fetch resources.
message AggregatedConfigSource {
}

// Configuration for listeners, clusters, routes, endpoints etc. may either be
// sourced from the filesystem or from an API source. Filesystem configs are
// watched with inotify for updates.
message ConfigSource {
  oneof config_source_specifier {
    string path = 1;
    ApiConfigSource api_config_source = 2;
    AggregatedConfigSource ads = 3;
  }
}