### The Process of Assigning a New TiDB Pod

The assignment of a TiDB pod in this serverless architecture is a dynamic, on-demand process orchestrated by several controllers and components. The core idea is to decouple the logical user cluster from the physical compute resources (the TiDB pods) until one is actually needed. This is achieved using a combination of Kubernetes Custom Resources, a pod pooling mechanism, and `etcd` for service discovery.

#### Key Components Involved:

*   **`Branch`/`Cluster` Controller:** Manages the lifecycle of the user's logical database.
*   **`Keyspace` & `KeyspacePoolConfig` Controllers:** Manage a pool of pre-warmed, ready-to-use keyspaces.
*   **`TiDB Manager`:** A central component (not a controller itself, but used by them) that manages the pool of available (free) and assigned TiDB pods.
*   **`TiDB Gateway`:** The public-facing entry point that routes user connections to the correct TiDB pod.
*   **`TiDB Pod Sync Cache Controller`:** Keeps the `TiDB Manager`'s cache of pod statuses up-to-date.

---

### Step-by-Step Assignment Flow

Here is the sequence of events that occurs when a new TiDB pod is required for a new cluster.

#### 1. Initiation: A New Cluster is Created

A user or an automated process creates a `Branch` or `Cluster` Custom Resource (CR) in Kubernetes. This represents the user's desire for a new database instance. The controller for that resource (`Branch` or `Cluster`) picks up this new CR and begins its reconciliation loop.

#### 2. Keyspace Assignment

The first major step within the controller is to secure a unique, isolated data space for the new cluster.

*   The controller calls the `assignKeyspace()` function.
*   Instead of creating a new keyspace from scratch (which can be slow), it fetches an **available** `Keyspace` resource from a pre-warmed pool. This pool is maintained by the `KeyspacePoolConfig` controller.
*   This `Keyspace` object contains a crucial piece of information: the `keyspaceToken`. This token becomes the unique identifier for the user's logical cluster from this point forward.
*   The controller updates the `Branch`/`Cluster` CR's status to include this `keyspaceToken`.

#### 3. Signaling the Need for a Pod via `etcd`

Now that the logical cluster has an identity (`keyspaceToken`), it needs a physical pod to run on. The controller does **not** create a pod directly. Instead, it signals its need to the pod management system.

*   The controller calls the `resetEtcdToken()` function.
*   This function writes a set of keys into `etcd`, prefixed with the `keyspaceToken`. The most important key created is `.../<keyspaceToken>/endpoints`.
*   Crucially, the value of the `endpoints` key is **initially set to be empty**. This empty value is the **signal** that a new pod assignment is required.

#### 4. The TiDB Manager Assigns a Pod

The `TiDB Manager` component is constantly watching `etcd` for these signals.

*   It detects the new `keyspaceToken` with an empty `endpoints` key.
*   It consults its internal "free cache" – a list of running, healthy, and currently unassigned TiDB pods. The health status of these pods is kept current by the `TiDB Pod Sync Cache Controller`.
*   It picks one pod from this free cache.

#### 5. Completing the Mapping in `etcd`

Once a pod is chosen, the `TiDB Manager` completes the service discovery loop.

*   It takes the IP address of the selected TiDB pod.
*   It writes this IP address into the `.../<keyspaceToken>/endpoints` key in `etcd`.

The mapping is now complete: the logical `keyspaceToken` is officially linked to the IP address of a physical TiDB pod.

#### 6. The User Connection Flow

When a user connects to the database:

1.  The connection hits the `TiDB Gateway`.
2.  The user's connection string or client provides the `keyspaceToken`.
3.  The gateway retrieves the pod's IP address and proxies the SQL connection directly to that pod.

#### 7. Maintaining the Pool

In the background, the `TiDB Manager` will notice its free cache has one less pod and will work to provision a new TiDB pod to replenish the pool, ensuring one is ready for the next assignment request.