Skip to content

PATTERN Cited by 1 source

UI-wrapped workflow primitive

Problem

Multi-step infrastructure operations — database sharding, cross-cluster migration, schema deployment, backup-restore — typically have two surfaces:

  • CLI / SDK / vtctldclient / kubectl — full expressive power; every corner case reachable; requires operator expertise.
  • Support-ticket-plus-professional-services — the vendor's SRE team runs the operation on behalf of the customer; gated behind Enterprise plans.

Neither surface scales. The CLI excludes the majority of customers who lack the operational expertise or appetite to run production data-motion from a terminal. The professional-services path doesn't scale to a vendor's installed base — every unsharded-to-sharded migration costs a multi-engineer-week engagement.

The missing tier is the self-service-but-safe tier: expose the workflow primitive to every customer, but constrain its parameterisation so it can't be misused, and surface its internal state so the customer can monitor and act on it without reaching into the CLI.

Solution

Take an existing multi-step CLI primitive, constrain it to monotonic progression with named phases, expose each phase as a button, and surface per-phase state in a dashboard. Every CLI-accessible safety property (zero-downtime cutover, VDiff-before-switch, reverse- replication-for-rollback) is preserved; the cognitive load of knowing the CLI verbs and correct invocation order is removed.

The constraints are load-bearing:

  • Named phases. Each step has a user-facing name the operator can reason about ("copying phase", "verify data", "switch traffic", "switch back") distinct from the underlying CLI verb (MoveTables Create, VDiff, SwitchTraffic, ReverseTraffic).
  • Monotonic progression. The UI only offers the next-valid-phase button. An operator cannot fire SwitchTraffic before the copy phase has completed
  • VDiff has run + validation checks have passed.
  • Validation gates. "PlanetScale will not allow you to start the workflow until all validation checks pass" (Source: sources/2026-04-21-planetscale-introducing-sharding-on-planetscale-with-workflows). Pre-checks run automatically and block advancement.
  • Progress visibility. Per-phase state is shown live (copy progress, replication lag, validation status). The operator can monitor a long-running data-motion without running vtctldclient Workflow show in a terminal.
  • Plan-agnostic exposure. Features previously gated behind Enterprise plans become available on every plan because the UI enforces safe usage.

Canonical wiki instance

PlanetScale Workflows wraps MoveTables as a dashboard-level operator surface on all PlanetScale plans (Source: sources/2026-04-21-planetscale-introducing-sharding-on-planetscale-with-workflows).

UI-verb to Vitess-verb mapping:

Dashboard verb Vitess CLI verb
New workflow / Validate pre-check
Create workflow MoveTables Create
(copying phase) VReplication row-copy + binlog tail
Verify data VDiff
Switch traffic MoveTables SwitchTraffic
Switch back MoveTables ReverseTraffic
(implied) Complete MoveTables Complete

Composes with:

Required substrate

  • A mature CLI workflow primitive. The UI wrap only works because the underlying primitive is already safe, fault-tolerant, and idempotent. The UI constrains usage; it does not add safety that wasn't already there.
  • A topology-server or equivalent coordination layer. Per-phase state (workflow lock, routing rules, reverse-workflow metadata) must be durably persistent so the UI can reflect ground truth and survive page refreshes / browser closes / phase hangs.
  • A validation-check framework. Pre-checks at every phase gate must be explicit and automatable. Without them the UI is no safer than the CLI.
  • Phase observability. Copy progress, replication lag, VDiff progress must be queryable and presentable to the operator.

Sister patterns

  • patterns/operator-scheduled-cutover — same shape (operator-visible dashboard gesture over a safe underlying mechanism) on the schema-deployment axis. PlanetScale's Gated Deployments UI uses the same discipline: an Auto-apply checkbox + Apply changes button let the operator schedule the cutover moment precisely. Both are operator-surface layers over an already-safe substrate; they differ in default direction (Workflows default is auto-progress to the next phase, Gated Deployments default is auto-apply unless the operator unchecks).
  • patterns/instant-deploy-opt-in — same shape on the fast-path-vs-safe-path axis. Automatic pre-evaluation + conditional UI + safe default + explicit opt-in surface. Workflows' Validate gate is the same structural move.

Generalisation beyond Workflows

The pattern generalises to any multi-step infra operation with:

  1. A CLI primitive that is already safe.
  2. A customer base that cannot run the CLI primitive themselves.
  3. An SRE team that does not scale to running the primitive on behalf of every customer.

Examples in the wild:

  • AWS Console as UI wrap over AWS SDK — the full AWS API is available via CLI / SDK, but the Console exposes a subset with named workflows (e.g. RDS Blue/Green deployment).
  • Kubernetes dashboards (Argo, Lens, Rancher) over kubectl — deployment lifecycle, workload scaling, node drain all expressible via kubectl but surfaced as phased UI operations in dashboards.
  • Cloudflare's Zero Trust setup wizards over the underlying Cloudflare API.

In each case the UI wrap is a legitimate product surface because the underlying primitive is already the ground-truth substrate; the UI constrains its usage, not its semantics.

Seen in

Last updated · 378 distilled / 1,213 read