data-plane-api/envoy/service/status/v4alpha/csds.proto

syntax = "proto3";

package envoy.service.status.v4alpha;

import "envoy/admin/v4alpha/config_dump.proto";
import "envoy/config/core/v4alpha/base.proto";
import "envoy/type/matcher/v4alpha/node.proto";

import "google/api/annotations.proto";

import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";

option java_package = "io.envoyproxy.envoy.service.status.v4alpha";
option java_outer_classname = "CsdsProto";
option java_multiple_files = true;
option java_generic_services = true;
option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;

// [#protodoc-title: Client Status Discovery Service (CSDS)]

// CSDS is Client Status Discovery Service. It can be used to get the status of
// an xDS-compliant client from the management server's point of view. It can
// also be used to get the current xDS states directly from the client.
service ClientStatusDiscoveryService {
  rpc StreamClientStatus(stream ClientStatusRequest) returns (stream ClientStatusResponse) {
  }

  rpc FetchClientStatus(ClientStatusRequest) returns (ClientStatusResponse) {
    option (google.api.http).post = "/v3/discovery:client_status";
    option (google.api.http).body = "*";
  }
}

// Status of a config from a management server view.
enum ConfigStatus {
  // Status info is not available/unknown.
  UNKNOWN = 0;

  // Management server has sent the config to client and received ACK.
  SYNCED = 1;

  // Config is not sent.
  NOT_SENT = 2;

  // Management server has sent the config to client but hasn’t received
  // ACK/NACK.
  STALE = 3;

  // Management server has sent the config to client but received NACK. The
  // attached config dump will be the latest config (the rejected one), since
  // it is the persisted version in the management server.
  ERROR = 4;
}

// Config status from a client-side view.
enum ClientConfigStatus {
  // Config status is not available/unknown.
  CLIENT_UNKNOWN = 0;

  // Client requested the config but hasn't received any config from management
  // server yet.
  CLIENT_REQUESTED = 1;

  // Client received the config and replied with ACK.
  CLIENT_ACKED = 2;

  // Client received the config and replied with NACK. Notably, the attached
  // config dump is not the NACKed version, but the most recent accepted one. If
  // no config is accepted yet, the attached config dump will be empty.
  CLIENT_NACKED = 3;
}

// Request for client status of clients identified by a list of NodeMatchers.
message ClientStatusRequest {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.service.status.v3.ClientStatusRequest";

  // Management server can use these match criteria to identify clients.
  // The match follows OR semantics.
  repeated type.matcher.v4alpha.NodeMatcher node_matchers = 1;

  // The node making the csds request.
  config.core.v4alpha.Node node = 2;
}

// Detailed config (per xDS) with status.
// [#next-free-field: 8]
message PerXdsConfig {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.service.status.v3.PerXdsConfig";

  oneof status_config {
    // Config status generated by management servers. Will not be present if the
    // CSDS server is an xDS client.
    ConfigStatus status = 1;

    // Client config status is populated by xDS clients. Will not be present if
    // the CSDS server is an xDS server. No matter what the client config status
    // is, xDS clients should always dump the most recent accepted xDS config.
    ClientConfigStatus client_status = 7;
  }

  oneof per_xds_config {
    admin.v4alpha.ListenersConfigDump listener_config = 2;

    admin.v4alpha.ClustersConfigDump cluster_config = 3;

    admin.v4alpha.RoutesConfigDump route_config = 4;

    admin.v4alpha.ScopedRoutesConfigDump scoped_route_config = 5;

    admin.v4alpha.EndpointsConfigDump endpoint_config = 6;
  }
}

// All xds configs for a particular client.
message ClientConfig {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.service.status.v3.ClientConfig";

  // Node for a particular client.
  config.core.v4alpha.Node node = 1;

  repeated PerXdsConfig xds_config = 2;
}

message ClientStatusResponse {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.service.status.v3.ClientStatusResponse";

  // Client configs for the clients specified in the ClientStatusRequest.
  repeated ClientConfig config = 1;
}