Skip to content

SYSTEM

VTCtld

What it is

VTCtld is the cluster-management / administrative-control process of a Vitess cluster. It is the third named Vitess primitive alongside VTGate (query router) and VTTablet (MySQL sidecar). Its job is to expose an administrative interface — historically a daemon with a gRPC API (the vtctld server), driven by the vtctl / vtctldclient CLI — through which operators (human or automated) perform cluster-level operations: schema changes, tablet reparenting, keyspace creation, backup orchestration, resharding, workflow control, topology edits.

From PlanetScale's own pedagogy-101 description:

"The entire cluster is controlled by a vtctld instance, a management interface that our internal systems communicate with to perform administrative operations." (Source: )

Role in the Vitess architecture

The three Vitess primitives divide responsibility along a control-plane / data-plane axis:

Primitive Plane Responsibility
VTGate Data Accept MySQL-protocol queries, route to tablets
VTTablet Data Connection pool + health-check the local mysqld
VTCtld Control Administrative operations on the cluster

VTCtld sits out of the query path. No customer query ever touches it. It only runs administrative verbs against the cluster — read topo-server, write topo-server, invoke per-tablet RPCs for operations like PlannedReparentShard, EmergencyReparentShard, ApplySchema, Backup, Restore, MoveTables, Reshard, VDiff. This is a canonical control-plane / data-plane separation: the data plane (VTGate + VTTablet) keeps serving queries even if VTCtld is unreachable; VTCtld failure caps blast radius to "cannot perform admin operations right now" rather than "database is down."

VTCtld in PlanetScale's branching substrate

canonicalises a load-bearing fact about PlanetScale's database branching model: every branch is an independent Vitess cluster, and branch creation is a vtctld-to-vtctld operation:

"when you create a branch, we'll spin up a new Vitess cluster for it and (using the vtctld component of the two clusters) apply the schema of the source database branch with the one you just created!"

Translation: to clone the schema from source branch → new branch, PlanetScale signals Kubernetes to provision a new Vitess cluster (new VTTablet pods, new VTGate pods, new VTCtld pod), then the new cluster's vtctld pulls the schema from the source cluster's vtctld and applies it. Schema-clone is a control-plane-to-control-plane operation; no data-plane involvement.

Fleet topology

In PlanetScale's multi-tenant Kubernetes fleet (see patterns/custom-operator-over-statefulset):

  • One vtctld pod per Vitess cluster (where "Vitess cluster" = "PlanetScale database branch")
  • Co-located with the per-branch VTGate + VTTablet pods
  • Driven by PlanetScale's internal control plane (not customer-facing)
  • Customer never sees vtctld directly — admin operations the customer can initiate (deploy requests, schema changes, branch creation, shard operations via Workflows) are mediated by PlanetScale's product surface that calls into vtctld on the customer's behalf

What VTCtld does NOT do

  • Does not proxy queries — that is VTGate's job.
  • Does not hold MySQL connections — that is VTTablet's job.
  • Is not on the customer's hot path — customer applications never connect to VTCtld.
  • Is not durable state storage — cluster state (tablet roles, keyspace topology, VSchema, routing rules) lives in the topo-server (etcd or ZooKeeper). VTCtld reads and writes topo but is not itself the source of truth.
  • Is not leader-elected — VTCtld is effectively stateless from the cluster's perspective. Multiple vtctld processes can coexist (and historically did: the older UI-serving vtctld vs the RPC-serving vtctld split before the mid-2022 vtctldclient unification; PlanetScale's naming collapses that distinction at pedagogy altitude).

Seen in

  • — canonical pedagogy-101 wiki disclosure of VTCtld as the third Vitess primitive alongside VTGate and VTTablet. Brian Morrison II (2023-08-23) supplies the verbatim definition ("a management interface that our internal systems communicate with to perform administrative operations") and the load-bearing vtctld-to-vtctld schema-clone-across-branches framing that makes PlanetScale's branching model coherent. First wiki ingest to name VTCtld with its own page despite ~30 prior references across the Vitess corpus.
  • — Morrison II's 2022-10-21 predecessor post names VTGate + VTTablet but elides vtctld (consistent with pedagogy-101 altitude of that post: the connection-scaling argument doesn't need the admin primitive).
  • — Morrison II's 2023-09-27 follow-up post canonicalises the Vitess Operator as the Kubernetes-custom-resource layer that provisions vtctld alongside VTGate / VTTablet pods per cluster.
Last updated · 542 distilled / 1,571 read