AGENTS.md

1# gRPC Load Balancing
2 
3This directory contains the implementation of gRPC's load balancing framework.
4 
5See also: [gRPC Client Channel overview](../client_channel/AGENTS.md)
6 
7## Overarching Purpose
8 
9The code in this directory provides a flexible and extensible framework for load balancing. It allows different load balancing policies to be plugged in to gRPC to control how RPCs are distributed across a set of backend servers.
10 
11## Core Concepts
12 
13The load balancing framework is built around a few key abstractions:
14 
15*   **`LoadBalancingPolicy`**: The `LoadBalancingPolicy` is the main abstraction for load balancing in gRPC. It is responsible for creating and managing subchannels, and for deciding which subchannel to use for each RPC.
16*   **`SubchannelPicker`**: The `SubchannelPicker` is a simple interface that is used to select a subchannel for a given RPC. Each `LoadBalancingPolicy` has a `SubchannelPicker` that is used to make the final routing decision.
17*   **`LoadBalancingPolicyFactory`**: A `LoadBalancingPolicyFactory` is responsible for creating instances of a particular `LoadBalancingPolicy`.
18*   **`LoadBalancingPolicyRegistry`**: The `LoadBalancingPolicyRegistry` is a global registry of `LoadBalancingPolicyFactory` instances. This registry is used to create `LoadBalancingPolicy` instances by name.
19 
20## Load Balancing Policies
21 
22gRPC comes with a number of built-in load balancing policies, each of which is implemented in its own subdirectory:
23 
24*   **`pick_first`**: This policy tries to connect to the first address in the list, and if that fails, it tries the next one, and so on. It's the default policy if no other is specified.
25*   **`round_robin`**: This policy distributes RPCs across all available backend connections in a round-robin fashion.
26*   **`weighted_round_robin`**: A more advanced version of round-robin that takes into account the weights of the different backends.
27*   **`ring_hash`**: This policy uses a consistent hashing algorithm to distribute RPCs across the backends. This is useful for session affinity, as it ensures that all RPCs for a given session are sent to the same backend.
28*   **`grpclb`**: This policy uses an external load balancer to make load balancing decisions. The external load balancer is typically a separate process that is running on the same machine as the gRPC client.
29*   **`xds`**: This policy uses the xDS protocol to configure load balancing. xDS is a set of APIs that are used to configure service discovery, load balancing, and other features in a service mesh. See the [xDS documentation](../xds/AGENTS.md) for more details.
30*   **`rls`**: Route Lookup Service. This policy uses a separate service to determine the route for each RPC.
31 
32## Files
33 
34*   **`lb_policy.h`, `lb_policy.cc`**: These files define the core `LoadBalancingPolicy` interface.
35*   **`lb_policy_registry.h`, `lb_policy_registry.cc`**: These files define the `LoadBalancingPolicyRegistry`.
36*   **`subchannel_interface.h`**: Defines the interface that a subchannel must implement to be used by a `LoadBalancingPolicy`.
37*   **`child_policy_handler.h`, `child_policy_handler.cc`**: A helper class for implementing composite load balancing policies that delegate to child policies. This is used by policies like `xds` and `priority`.
38*   **`address_filtering.h`, `address_filtering.cc`**: A helper class for filtering addresses based on a set of attributes. This is used by policies like `xds` to implement locality-based routing.
39*   **`health_check_client.h`, `health_check_client.cc`**: A client for the gRPC health checking protocol. This is used by some LB policies to determine the health of the backends.
40 
41## Notes
42 
43*   gRPC's load balancing framework is highly extensible. New load balancing policies can be added by implementing the `LoadBalancingPolicy` and `LoadBalancingPolicyFactory` interfaces and registering the factory with the `LoadBalancingPolicyRegistry`.
44*   The load balancing policy is chosen based on the service config, which can be provided by the [resolver](../resolver/AGENTS.md).
45*   Load balancing is primarily used in the client channel. See the [client channel documentation](../client_channel/AGENTS.md) for more details.
46