Skip to content

SYSTEM Cited by 2 sources

PlanetScale Vitess Operator

What it is

The PlanetScale Vitess Operator is a Kubernetes Operator — a custom controller that extends the Kubernetes Control Loop with custom resources — that PlanetScale uses to provision, reconcile, and lifecycle-manage Vitess clusters running MySQL on Kubernetes. It is the control-plane component (concepts/control-plane-data-plane-separation) that turns a PlanetScale-defined custom resource ("define the specifications of a PlanetScale database") into a running Vitess topology — VTGate deployments, VTTablet pods, vtctld control instances, PVCs bound to cloud storage, and the multi-AZ placement constraints that paid PlanetScale clusters require.

It is the canonical workaround to the three operational hard problems that plain StatefulSets leave unsolved when running MySQL on K8s: replication + failover, source-of-truth determination, and backup/restore semantics.

Role in the deployment data flow

"When a user needs to deploy a new database into our infrastructure… our API sends a request to our custom orchestration layer asking for that database to be created. Provided the request is valid, the orchestrator will define a custom resource definition we use to define the specifications of a PlanetScale database. The Operator… will use the built-in mechanism of Kubernetes (specifically, the Control Loop and the API) to detect that the current state and desired state do not match. The Operator will create the necessary resources to run and operate a Vitess cluster for the requested database." (Source: sources/2026-04-21-planetscale-scaling-hundreds-of-thousands-of-database-clusters-on-kubernetes)

User → PlanetScale API → custom orchestrator
   → writes CRD (desired state)
     → Vitess Operator reconciles via K8s Control Loop
       → creates VTGate Deployments, VTTablet Pods,
         vtctld, PVCs, cloud-storage bindings, multi-AZ spread
   ← orchestrator notified "ready"
User connects to VTGate and starts using the database

Responsibilities

  • Reconcile custom resources — watches the PlanetScale CRD and reconciles real Kubernetes resources to match. This follows the standard Kubernetes Operator loop (concepts/kubernetes-operator-pattern).
  • Manage Vitess topology — stands up VTGate pods, VTTablet pods, vtctld instances, and wires them together via the topo-server state.
  • Cloud-storage lifecycle — provisions EBS / GCP Persistent Disk volumes via PVCs, monitors utilisation, auto-grows them via cloud-provider APIs before the database runs out of space (patterns/automated-volume-health-monitoring).
  • AZ-failure reconciliation — when an AZ goes down, the operator detects the resource gap (pods and PVCs that should exist but don't) and applies "the necessary infrastructure changes to keep our databases online." See patterns/multi-az-vitess-cluster.
  • Pod-crash recovery — same Control-Loop reconcile path used by standard Kubernetes controllers, applied to the Vitess-specific topology.

Architectural choice: operator + PVC over StatefulSet

The headline design choice (patterns/custom-operator-over-statefulset): the Vitess Operator spins up plain pods with direct cloud PVC attachment, not StatefulSets, even though StatefulSets are the Kubernetes-documented default for databases.

"The recommended best practice is to use StatefulSets to run databases since the state is automatically tracked by Kubernetes. We actually don't do this and opt instead to use the logic built into the Vitess Operator to spin up pods that attach directly to cloud storage using a persistent volume claim (PVC). Because we already have a routing mechanism in place (VTGate), we don't need to be concerned about the name or address of a given pod."

This works because the two pillars StatefulSets provide are handled elsewhere in the Vitess stack:

StatefulSet guarantee Vitess-stack substitute
Stable pod name + network address VTGate routes via topo-server lookup — apps don't address pods directly
Persistent storage PVC bound directly to cloud-provider disk, operator-managed
Ordered pod startup Operator orchestrates via custom reconcile logic — order semantics that fit Vitess (primary-first, then replicas) rather than the generic pod-0, pod-1, pod-2 StatefulSet order

Open-source provenance

The Vitess Operator is a PlanetScale project; the current public releases (e.g. Vitess Operator 2.14.0, tracked in companies/planetscale.md) are hosted at planetscale/vitess-operator. It has been a contribution vehicle between PlanetScale engineering and the Vitess open-source community for years — repeated mentions in the corpus of Vitess release notes pair Vitess releases with Vitess Operator co-releases.

Seen in

  • sources/2026-04-21-planetscale-scaling-hundreds-of-thousands-of-database-clusters-on-kubernetes — Brian Morrison II, 2023-09-27. Canonical introduction of the operator's role, the CRD-driven deployment workflow, the operator+PVC-over-StatefulSet design choice, the auto-expanding storage behaviour, and the three-AZ-minimum placement constraint. This is the Tier-3 pedagogical-overview source; does not describe operator internals, reconcile timings, or case studies.
  • companies/planetscale — Vitess Operator mentioned across multiple Vitess-release-note entries as the companion K8s-side release to each Vitess release.
Last updated · 470 distilled / 1,213 read