data-plane-api/api/base.proto

syntax = "proto3";

package envoy.api.v2;

import "api/address.proto";

import "google/protobuf/any.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 {
  ResolvedAddress 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;
}

// 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. Each type_url
  // (see below) has an independent version associated with it.
  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. LDS/CDS expect empty resource_names, since this is global
  // discovery for the Envoy instance. The LDS and CDS responses will then imply
  // a number of resources that need to be fetched via EDS/RDS, which will be
  // explicitly enumerated in resource_names.
  repeated string resource_names = 3;
  // Type of the resource that is being requested, e.g.
  // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This is implicit
  // in requests made via singleton xDS APIs such as CDS, LDS, etc. but is
  // required for ADS.
  string type_url = 4;
}

message DiscoveryResponse {
  string version_info = 1;
  repeated google.protobuf.Any resources = 2;
  // Canary is used to support two Envoy command line flags:
  // * --terminate-on-canary-transition-failure. When set, Envoy is able to
  //   terminate if it detects that configuration is stuck at canary. Consider
  //   this example sequence of updates:
  //   - Management server applies a canary config successfully.
  //   - Management server rolls back to a production config.
  //   - Envoy rejects the new production config.
  //   Since there is no sensible way to continue receiving configuration
  //   updates, Envoy will then terminate and apply production config from a
  //   clean slate.
  // * --dry-run-canary. When set, a canary response will never be applied, only
  //   validated via a dry run.
  bool canary = 3;
}

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