syntax = "proto3";

package envoy.api.v2.core;

option java_outer_classname = "BaseProto";
option java_multiple_files = true;
option java_package = "io.envoyproxy.envoy.api.v2.core";
option go_package = "core";

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

import "validate/validate.proto";
import "gogoproto/gogo.proto";

import "envoy/type/percent.proto";

option (gogoproto.equal_all) = true;

// [#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_core.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_endpoint.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.
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_core.HealthCheck.HttpHealthCheck.service_name>`,
  // :ref:`runtime override directory <envoy_api_msg_config.bootstrap.v2.Runtime>`,
  // :ref:`user agent addition
  // <envoy_api_field_config.filter.network.http_connection_manager.v2.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;

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