gerodimos.dev

Architecture area

Developer experience

Backstage is the only interface a developer needs. Every action it offers is a pull request, and everything it shows is read back from the platform.

The shape

A developer uses Backstage. Backstage's only write is a pull request to application-repositories. It reads service repositories for the catalog, platform resources on the management cluster, rollout state from Argo CD, pods, logs and schema status from the workload clusters, and metrics from Mimir. Developer fills in a form Backstage golden paths one page per service application-repositories a pull request, merged by a person PR Service repositories catalog-info.yaml Platform resources Component · Release · Database … Argo CD sync and health dev · prod pods, rollouts, schemas, logs (read-only) Mimir metrics, fixed queries
Scroll sideways to see all of it. The highlighted arrow is the portal's only write. Dashed arrows are what it reads to show the result.

How it works

  1. Golden paths are templates

    Each asks a handful of questions and renders one or two small files.

    • Onboard Service: name, owner, scaffold template and version, auto-deploy on or off. Adds a Component and its first Release.
    • Create deployment: environment, a green build, which databases to bind. Adds or updates a Release.
    • Add Database: environment, name, size. Adds a Database.
    • Apply database schema: environment and a published schema version, showing the migrations it adds. Adds or updates a DatabaseSchema. See Database schemas.

  2. A pull request, not an API call

    The files go to application-repositories as a pull request from the portal's own GitHub App. A person reviews and merges it; the operators and Argo CD take it from there. See GitOps delivery.

  3. One page per service

    Each environment gets a deployment card: the running version and what changed, live rollout steps, sync and health, the public URL, the database schema it runs against (with a warning when the code ships a migration the database doesn't have), and logs for the owner. Desired state comes from the Release on the management cluster, delivery from Argo CD, and running state from the workload cluster itself, read with a read-only role. See Hub and spoke. Metrics and dependencies have their own tabs; each database shows whether it's available, has the newest schema and is bound, and its own page lists every schema check with the states it can be in.

  4. A catalog nobody registers into

    Services appear because their scaffolded repository contains a catalog-info.yaml, found by scanning GitHub. Databases appear because a small provider reads Database resources and publishes them as catalog entities linked to their Component.

Design choices

Pull requests, not API calls

A template that wrote to a cluster would bypass review and Git history. A pull request is reviewable and revertable, and it's the same path everything else takes.

Trade-off: every action waits for a merge. Dev auto-deploys after that; prod is meant to wait.

Discovery by label, not by name

Argo CD Applications and Kubernetes workloads are found through the platform's component and environment labels, so naming conventions can change without breaking the portal.

Read-only to the world

Anyone can sign in as a guest and browse. An explicit allowlist decides what guests can do: a permission a new plugin introduces stays denied until it's added. Templates, logs and a failed migration's database error are owner-only.

Fixed queries for guests

The Metrics tab's backend takes only a component and an environment and runs a fixed set of queries, instead of exposing a Prometheus proxy anyone could query.

A bot, not a person's token

Pull requests come from the portal's GitHub App with short-lived tokens, so nothing depends on an individual's account.

Stock plugins first

Catalog, scaffolder, Kubernetes and the community Argo CD plugin do most of the work. Small platform modules fill the gaps, such as the database provider and the metrics route.

Trade-off: those modules have to be carried through every Backstage upgrade.

Not built yet

  • Promote to prod. A button on the dev card that opens the prod pull request; prod's Rollback button already exists.
  • Log history. Logs are read live from the pods; there is no central log store yet.

Code

backstage

The portal, its templates and platform modules.

application-repositories

Where every template's pull request lands.