AGENTS.md

1# gRPC xDS
2 
3This directory contains the implementation of gRPC's xDS support. xDS is a set of APIs that allow a gRPC client or server to discover and configure itself dynamically.
4 
5See also: [gRPC Core overview](../AGENTS.md)
6 
7## Overarching Purpose
8 
9The code in this directory provides a gRPC implementation of the xDS APIs. This allows gRPC clients and servers to be configured by a central control plane. xDS is one way that service configurations can be delivered to a gRPC application; see [service config](../service_config/AGENTS.md) for more information.
10 
11## Core Concepts
12 
13*   **`XdsClient`**: The `XdsClient` is the core of the xDS implementation. It is responsible for managing the connection to the xDS server, sending resource requests, and receiving and processing resource updates.
14*   **Bootstrap File**: The `XdsClient` is configured via a bootstrap file. The bootstrap file is a JSON file that contains the information that the `XdsClient` needs to connect to the xDS server.
15*   **xDS Resources**: xDS is a set of APIs for discovering and configuring different types of resources. The most important resource types for gRPC are:
16    *   **LDS (Listener Discovery Service)**: Used to discover the listeners that are running on a gRPC server.
17    *   **RDS (Route Discovery Service)**: Used to discover the routes that are available for a given listener.
18    *   **CDS (Cluster Discovery Service)**: Used to discover the clusters that are available to the gRPC client.
19    *   **EDS (Endpoint Discovery Service)**: Used to discover the endpoints (i.e., the backend servers) that are in a given cluster.
20 
21## `xds_client` Directory
22 
23The `xds_client` directory contains the core implementation of the xDS client.
24 
25### Files
26 
27*   **`xds_client.h`, `xds_client.cc`**: These files define the `XdsClient` class.
28*   **`xds_bootstrap.h`, `xds_bootstrap.cc`**: These files define the `XdsBootstrap` class, which is responsible for reading the xDS bootstrap file and creating the initial `XdsClient` configuration.
29*   **`xds_api.h`, `xds_api.cc`**: These files define the `XdsApi` class, which provides a high-level API for interacting with the xDS server.
30*   **`lrs_client.h`, `lrs_client.cc`**: These files define the `LrsClient` class, which is used to send load reports to the xDS server.
31*   **`xds_resource_type.h`**: Defines the interface for a specific xDS resource type. Each resource type (e.g., LDS, RDS, CDS, EDS) has its own implementation of this interface.
32 
33### Major Classes
34 
35*   **`grpc_core::XdsClient`**: The core of the xDS client implementation.
36*   **`grpc_core::XdsBootstrap`**: Responsible for reading the xDS bootstrap file.
37*   **`grpc_core::XdsApi`**: A high-level API for interacting with the xDS server.
38*   **`grpc_core::LrsClient`**: A client for sending load reports to the xDS server.
39 
40## Notes
41 
42*   xDS is a complex and powerful feature. A full understanding of xDS requires reading the official [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol).
43*   The gRPC xDS implementation is still under active development.
44*   The xDS implementation is a good example of how gRPC can be extended with new features. It is implemented as a set of plugins that are loaded at runtime, and it uses the `CoreConfiguration` class to register its factories.
45