Research · v1.0.0

Generated Everything, Drifted Nowhere: Drift Gates for a Self-Service Platform Catalog

Lars Shakya Buch-Jepsen

v1.0.0Latest stable release: 2026-11-20

Generated Everything, Drifted Nowhere: Drift Gates for a Self-Service Platform Catalog

1. Introduction

Platform engineering sells self-service: a developer opens a catalog, picks a template, and receives running infrastructure. Between the catalog entry and the running service, however, stretches a chain of artifacts — documentation pages, gateway routes, automation playbooks, infrastructure examples, UI fixtures — and every one of them is a copy of something else: of the template, of the flow definition, of the catalog itself. Copies drift. The documentation says the flow exists; the gateway says otherwise; the Terraform example references a module that was renamed three weeks ago. Catalogs rot not because their sources rot, but because their derived artifacts do.

This article presents the architecture of Backstage-Infrastructure- Ordering [1], a private Backstage-based ordering platform [2], and the discipline that keeps its derived artifacts honest: the drift-gate pattern — every generated artifact has a generator, every generator ships a --check mode, and every check mode runs as a CI gate, so an artifact that has drifted from its generator cannot reach the main branch. The catalog that grounds the article is not a pilot: it carries 365 flows — ordering flows, concrete service flows, and day-2 operations — with every ordering flow paired with day-2 change and decommission twins, dispatched through an AWX/Ansible automation layer [3], API-gateway configuration generated from the same catalog source [4], and Terraform examples generated per flow [5]. The automation layer is not a thin provisioning shim: each component is backed by an Ansible library covering all of its day-2 operations, and every automation run calls its results back into the repository’s CI as callback items, so executed changes leave the same auditable trail as committed ones.

The argument of the article is that generated everything is only tenable with drifted nowhere — and that the drift gate, plus its supporting conventions (day-2 pairing with two-tier action visibility, the automation feedback loop, and declarative desired state across a heterogeneous estate of Windows, Linux, and hardware), is what makes a large self-service catalog a maintainable object rather than a museum.

1.1 Contributions

  • the drift-gate pattern stated with its full mechanics: generated artifacts, generator check modes, and CI enforcement (Sections 3–4);
  • the day-2 pairing convention: orderable implies operable, by construction, with actions presented in two tiers — a visual customer tier and the full action set for engineers and architects (Section 5);
  • the automation feedback loop: per-component Ansible libraries covering every day-2 operation, and per-run CI callbacks recording all changes done (Section 6);
  • declarative desired state across the estate — Windows DSC, native Ansible modules on Linux, and hardware — as the enforcement endgame (Section 7);
  • and an honest account of the pattern’s costs and its evidence base (Sections 8–9).

2. Background: Platform Catalogs and Their Copies

Backstage [2] established the template-and-catalog model for internal developer platforms: software templates describe what can be ordered; the catalog indexes what exists; integrations make ordering real. The model’s strength — a single source of truth in the template — is also its weakness: nearly everything a user touches is derived. The docs page for a flow, the gateway route that fronts it, the automation job that provisions it, the infrastructure example that mirrors it, and the UI fixture that tests the catalog page listing it are all projections of the same definition. Each projection can be regenerated; each can also be hand-edited, partially updated, or simply forgotten.

The infrastructure-as-code tradition has long faced the analogous problem on hosts — configuration drift between declared and actual state — and answered it with desired-state tooling and plan/apply mechanics [5], [6]. The platform catalog’s version of the problem lives one level up, in the repository: artifact drift between generators and their outputs. The drift-gate pattern is the repository-level analog of a plan check: nothing that disagrees with its source merges.

3. The Platform, Briefly

The platform is a conventional Backstage deployment with an unconventional quantity of generated material. The order of composition is:

  1. Templates — Backstage scaffolder templates, registered in the catalog.
  2. Ordering flows — the service catalog entries users order from; each flow declares what the service is and which automation delivers it.
  3. Gateway configuration — Kong routes generated from the flow catalog, so the API front door and the catalog cannot disagree [4].
  4. Automation — AWX/Ansible playbooks that execute provisioning and operations; site-level playbooks map catalog names to thin, declarative roles, backed by per-component Ansible libraries covering each component’s full day-2 operation set [3].
  5. Infrastructure examples — Terraform (and Pulumi) examples, one per flow, generated from the same catalog source [5].
  6. Documentation and diagrams — per-flow documentation and diagram files (Markdown with draw.io twins), generated.

The key architectural fact is that steps 3–6 are all generated from the same source as step 2. The catalog is not merely displayed; it is projected into every surface a user or operator touches.

3.1 The Gated Artifacts

The platform’s CI suite — twenty checks in the deployment studied — includes, among its lint, syntax, and test lanes, a set of drift gates, one per generator:

The generated artifacts and their drift gates.
Generated artifact Gate
Flow documentation pages generator --check
Per-flow documentation details generator --check
API-gateway configuration generator --check
Template locations index generator --check
Flow diagrams (Markdown + draw.io twins) generator --check
Terraform examples (per flow) generator --check + fmt/validate
UI test fixtures (template catalog) generator --check

A change that edits a flow definition without regenerating its projections — or that edits a projection by hand — fails the gate with a byte-level diff. The repository has no channel by which a derived artifact can change silently.

4. The Drift-Gate Pattern

Stated as a pattern:

  1. One source per projection. Each generated artifact names its generator unambiguously. There is no artifact whose provenance is “unclear — probably the docs generator.”
  2. Generators ship a check mode. The same code that regenerates also verifies (--check): regenerate in a scratch area, diff against the committed artifact, exit non-zero on any byte difference. Verification and regeneration share code by construction, so the gate cannot rot away from the generator.
  3. The gate runs on every change. CI runs all --check modes on every pull request. Drift is a merge-blocked condition, not a weekly audit finding.
  4. Nothing generated is hand-edited. Culturally enforced by the gate: a hand edit is indistinguishable from drift and fails identically.

The pattern’s subtlety is in what it does not require: no monorepo discipline beyond the repository itself, no artifact store, no build orchestration. The gate is a deterministic script that answers one question — “does the committed copy still equal the generated copy?” — and refuses to let the repository proceed on “no.”

A practical note on operating the gates at catalog scale: the deployment’s generated surface spans documentation, gateway configuration, diagrams, per-flow infrastructure examples, and UI fixtures, and the CI suite that carries them runs in minutes, not hours — because each gate is a diff, not a rebuild. Deterministic generation is what keeps the pattern cheap enough to run everywhere; a generator that embeds timestamps or machine state into its output would make the gate noisy and eventually ignored.

5. The Day-2 Pairing Convention and the Two-Tier Action Catalog

A second convention structures the catalog itself: every ordering flow ships with a pair of day-2 flows — one for change, one for decommission — dispatched through the automation layer under distinct operational roles. The convention is enforced as catalog structure, not review habit: the pairing is visible in the generated documentation and exercised by the automation mapping.

The convention exists because self-service platforms have a well-known blind spot: they make ordering trivial and operating invisible. A catalog where a service can be requested in two minutes but requires a ticket to modify and a mystery to decommission teaches users to hoard. The day-2 pairing makes the whole lifecycle orderable at the same counter — and, because the pairs are generated alongside the flows, the generated documentation and automation mappings always agree about what the lifecycle of a service is.

The same convention fixes how the lifecycle is presented: in two tiers, between a visual subset and the full action catalog. The visual tier is for customers: catalog pages and generated documentation present the lifecycle actions a customer triggers (order, change, decommission) graphically, without automation or implementation detail. The full tier is for engineers and architects: the complete action set for a component, including every day-2 operation its Ansible library covers (Section 6), with the automation mappings in plain view. Both tiers are projections of the same source, so the tiering is a property of the generated catalog, not a documentation promise that can drift: the customer tier is by construction a subset of the full action set.

6. The Automation Feedback Loop

The day-2 pairing says what must exist next to every ordering flow. The automation feedback loop governs the automation layer itself, and it keeps two further promises: that day-2 operations are covered automation rather than runbook prose, and that every change the automation layer executes becomes visible in CI.

Per-component libraries. Each component ships with an Ansible library: collections and roles covering all day-2 operations for that component. Whatever a component’s lifecycle requires beyond ordering (change, reconfiguration, scaling, patching, backup and restore, decommission) exists as a dedicated, thin, declarative role in the component’s library, dispatched through the same site-level playbook mapping that carries the ordering flows [3]. Coverage is therefore a property of the library rather than of operator diligence: a day-2 operation without a backing role is a visible gap in the component, and the roles run the same offline smoke checks in CI (syntax and lint, check mode) that the rest of the automation layer runs.

Run callbacks as CI items. Every automation run, whether ordering, day-2 change, or decommission, ends with a callback that records what changed as CI items: the run’s outcome, the flows affected, and the operations performed are checked back into the repository’s CI, so all changes done through the automation layer leave an auditable record in the same surface that enforces the drift gates. The automation server’s job history is a convenience, not the system of record: the repository’s CI items are. Executed changes are consequently as observable as committed ones. Repository drift is merge-blocked; executed changes are callback-recorded.

7. The Endgame: Declarative Desired State Across the Estate

Drift gates keep the repository honest; they cannot keep hosts honest. The platform’s enforcement endgame is declarative desired state, and the estate it governs is heterogeneous: Windows hosts, Linux hosts, and hardware. Each estate segment is expressed in the declarative form its tooling natively supports, driven through the same automation layer [3]:

  • Windows hosts as DSC resources [6], executed through Ansible’s Windows DSC module as thin, declarative roles;
  • Linux hosts through Ansible’s native idempotent modules, which provide the same desired-state comparability with no intermediary;
  • hardware through the automation layer’s declarative inventory and roles, so device state is declared and checked rather than imperatively reconfigured where the device class supports it.

No imperative scripting appears in the roles, so Ansible’s check mode can compare desired against actual state on any segment of the estate and report drift as a dry-run result rather than an outage post-mortem. The same check-mode mechanics run in CI as smoke tests (syntax and lint offline), keeping the roles honest before they ever reach a host.

Together the two layers close the loop: repository drift is merge-blocked; host and hardware drift is check-detectable. The catalog’s claim — “what you ordered is what runs” — is enforced at both places the claim could fail.

8. What the Discipline Costs

Honesty requires the costs:

  • Generators are a product. Five-plus generators with check modes are code that must be maintained, tested, and extended as the catalog grows. The platform treats generator work as first-class backlog, not tooling debt.
  • Libraries are a product too. The per-component Ansible libraries that make day-2 orderable are code that must be maintained, extended, and smoke-tested as the catalog grows; the platform treats library work as first-class backlog alongside generator work.
  • CI scales with the catalog. Twenty checks run per change; new generated surfaces add lanes. The mitigation is that gates are diffs — cheap per lane, but lane count is real.
  • Convention is load-bearing. The day-2 pairing and generated-only rules survive because CI enforces them; a generated surface without a gate would decay quietly.
  • YAML discipline. At this catalog size, template metadata defects (unquoted descriptions, comment-like tokens in names) surface as surprising downstream failures — the generated-everything chain amplifies small source defects into cross-artifact incidents, which is precisely why the gates exist.

9. Evaluation Status

Evaluation status. The deployment described is shipped and operating: 365 flows (ordering, concrete, and day-2) with generated documentation, gateway configuration, diagrams, per-flow infrastructure examples, and UI fixtures, kept byte-consistent by generator check-mode CI gates in a twenty- check suite — measured facts from one deployment. The day-2 pairing, the two-tier action presentation (visual customer tier, full engineer/architect tier), the automation feedback loop (per-component Ansible libraries and per-run CI callback items), and heterogeneous declarative desired state (DSC on Windows, native Ansible modules on Linux, declarative roles for hardware) are shipped conventions of that deployment. The article’s generalizations — that catalogs rot through artifact drift and that drift gates prevent it — are design analysis grounded in this single deployment, not cross-organization findings; no adoption, effort, or defect-reduction numbers are claimed. Internal flow names, organization specifics, and CI implementation details are deliberately omitted.

10. Limitations

  1. Single-deployment evidence. The pattern is argued from one catalog; its transferability to other platform stacks is analytic, not measured.
  2. Gate, not guarantee. Drift gates prevent committed drift; they do not detect a generator that is itself wrong — a generator bug propagates consistently to every artifact and passes every gate.
  3. Diff-ability dependency. The pattern requires deterministic, byte-stable generation; outputs with embedded volatile data (timestamps, machine paths) make gates noisy.
  4. No host-state evidence here. The heterogeneous desired-state layer (Windows DSC, Linux via native Ansible modules, hardware) is described as deployed architecture; host-level drift detection results are organization-specific and not reported.
  5. Catalog-scale CI. The twenty-check suite is the cost side of the pattern at 365 flows; the article does not measure how the approach behaves at multiples of that scale.

11. Conclusion

A self-service catalog is a machine for making copies: every surface it presents is a projection of a source definition. The drift-gate pattern accepts that and installs the feedback loop — generators that verify, verification that blocks merges — so the copies can never quietly stop being copies. Paired with the day-2 convention, which makes operation as orderable as acquisition and splits the action catalog into a visual customer tier and the full set for engineers and architects; with the automation feedback loop, which gives every component an Ansible library for all of its day-2 operations and checks every executed change back into CI; and with declarative desired state across Windows, Linux, and hardware, the platform keeps its one-sentence promise auditably true: what the catalog says, the infrastructure does, and what the infrastructure did, CI records. The pattern is not free — generators and libraries become products, CI grows lanes — but the alternative is not a static catalog: it is a decaying one, and the decay is invisible until a user orders something that no longer exists.

[1]
L. S. Buch-Jepsen, “Backstage-Infrastructure-Ordering: A drift-gated platform catalog.” 2026.
[2]
Backstage contributors, “Backstage — an open platform for building developer portals.” Accessed: Oct. 30, 2026. [Online]. Available: https://backstage.io/docs/
[3]
Red Hat and Ansible contributors, “Ansible documentation.” Accessed: Oct. 30, 2026. [Online]. Available: https://docs.ansible.com/
[4]
Kong Inc., “Kong gateway documentation.” Accessed: Oct. 30, 2026. [Online]. Available: https://docs.konghq.com/gateway/
[5]
HashiCorp, “Terraform documentation.” Accessed: Oct. 30, 2026. [Online]. Available: https://developer.hashicorp.com/terraform/docs
[6]
Microsoft, “Desired state configuration (DSC) documentation.” Accessed: Oct. 30, 2026. [Online]. Available: https://learn.microsoft.com/powershell/dsc/