Self-service platforms: golden paths, templates and developer tooling

Generated by Claude through GigAI 0.1.11.10 on 2026-10-12.

Concept: Self-service platform / paved road · also covers Platform engineering, Developer tooling and experience · Step 33 of 35 in MLOps / ML platform engineer · version 1

A self-service platform lets ML and product teams get a working, compliant project, pipeline or endpoint without filing a ticket. The platform team packages its opinions as golden paths: templates, a catalog and a small set of well-documented interfaces that make the supported way the easiest way. The work is treated as product management as much as engineering, with users, feedback and adoption metrics.

How it is done in practice

A platform team usually starts by picking the one or two workload shapes that most teams ship, such as a batch training pipeline and an online endpoint, and builds a template for each that produces a deployable repository in minutes. The template lives in a portal, most often Backstage, alongside the catalog and documentation, and it calls the same CI, GitOps and infrastructure modules the platform team uses itself. The team then onboards a friendly pilot team, watches where they get stuck, fixes the template and documentation, and only then advertises the path widely. Templates are versioned, changes are reviewed like product changes, and a dashboard tracks adoption and time to first deployment so the roadmap is driven by evidence.

Technologies

Diagram

flowchart LR
  U[ML engineer] --> P[Developer portal]
  P --> T[Software template]
  T --> R[New repository from skeleton]
  T --> C[Catalog entry with owner]
  R --> CI[CI build and tests]
  CI --> G[GitOps deploy]
  G --> K[Platform runtime]
  K --> O[Dashboards and alerts]
  O --> P

flowchart LR
  U[ML engineer] --> P[Developer portal]
  P --> T[Software template]
  T --> R[New repository from skeleton]
  T --> C[Catalog entry with owner]
  R --> CI[CI build and tests]
  CI --> G[GitOps deploy]
  G --> K[Platform runtime]
  K --> O[Dashboards and alerts]
  O --> P

Code

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: model-endpoint
  title: Real-time model endpoint
spec:
  owner: ml-platform
  type: service
  parameters:
    - title: Service details
      required: [name, owner]
      properties:
        name: {type: string}
        owner: {type: string}
  steps:
    - id: fetch
      action: fetch:template
      input:
        url: ./skeleton
        values: {name: '${{ parameters.name }}'}

Subtopics

Treating the platform as a product

What changes when users are internal customers

The CNCF platforms white paper describes a platform as a curated set of capabilities offered to internal users through consistent interfaces, run by a team that treats those users as customers. For an ML platform the capabilities are things like compute for training, pipeline orchestration, artifact and model storage, serving, observability and identity. The product stance means the team does user research, publishes a roadmap, writes documentation as a first-class deliverable and keeps adoption optional where it can, so that usage is a real signal. The platform team aims to reduce cognitive load: a data scientist should need to understand the model and the contract of the platform, not the cluster, the network and the IAM layout underneath it.

Thinnest viable platform

Start with the smallest set of capabilities that removes a real, repeated pain, often just a template, a CI pipeline and a documented deploy path. Wrap existing provider services instead of rebuilding them, and add abstraction only where several teams hit the same friction. Each capability needs an owner, a support channel and a stated service level, otherwise it is a shared script and not a product.

Golden paths and software templates

What a golden path is

A golden path is the supported, opinionated route from idea to production for one kind of workload: for example a batch training job, a real-time model endpoint or a feature pipeline. It bundles a repository skeleton, a build and test pipeline, deployment manifests, default dashboards and alerts, and the security settings the organization requires. The path is paved, not walled: teams can leave it, but then they own what the platform would have given them for free.

Scaffolding with Backstage templates

Backstage Software Templates implement this with a Template entity. The parameters section declares a form, rendered in the portal, that collects inputs such as service name, owner and model type. The steps section runs scaffolder actions in order: fetch a skeleton and render it with the inputs, publish the result to a new repository, and register the new component in the catalog. Custom actions can add steps such as creating a namespace, an experiment in the tracking server or a pipeline definition.

The developer portal and software catalog

One place to find and own things

Backstage is an open framework for building developer portals. Its center is the software catalog: every service, library, pipeline, dataset or model is described by a small metadata file kept next to the code, stating its kind, owner, lifecycle and relations to other entities. The portal ingests those files and gives a searchable inventory with ownership attached. Around the catalog sit TechDocs, which renders documentation written beside the code, and a plugin system that surfaces CI status, deployments, cost or on-call data on the entity page. For an ML platform the useful extension is modeling ML-specific entities, so a served model links to its training pipeline, its registry entry, its feature sources and the team that answers the page.

Anatomy of an ML golden path

From template to serving endpoint

A typical ML path starts with a template that creates a repository with a standard project layout, a container build, unit tests and a pipeline definition. Training runs through the platform orchestrator, logs parameters and metrics to the tracking server and writes a versioned artifact to the model registry. A promotion step runs evaluation gates, then a GitOps change deploys the model to the serving layer with a staged rollout. Dashboards, alerts, drift monitors and cost labels are created by the path, not by the team.

Choosing the abstraction level

The interface is usually a short declarative spec: model name, framework, resource class, scaling bounds and data dependencies. The platform expands it into the full Kubernetes or cloud resources. Keep an escape hatch, such as an overlay or raw manifest patch, so unusual workloads are possible without forking the path. Version the templates and provide an upgrade mechanism, because generated repositories drift from the template the day after they are created.

Measuring adoption and closing the feedback loop

Signals that the platform works

Measure the platform the way a product is measured. Useful signals include the share of workloads on the golden path, time from template creation to first production deployment, deployment frequency and failure rate for path users, the number of support tickets per team and how many requests still need a human on the platform team. Developer surveys add the qualitative side. Recurring support questions are the backlog: each one is a candidate for better documentation, a clearer error message, a new template parameter or a new capability. Office hours, an open support channel and embedding with a user team for a sprint are common ways to see friction first hand. Deprecate paths that nobody uses, since every supported path carries maintenance cost.

Sources

• docWhat is Backstage? (backstage.io)
• docBackstage Software Templates (backstage.io)
• guideCNCF Platforms White Paper (tag-app-delivery.cncf.io)

Related lessons

• System design for multi-tenant ML infrastructure: isolation, quotas and backpressure
• Writing and reviewing design docs and architecture decision records
• Reproducible environments: GitOps with Argo CD and infrastructure as code with Terraform
• CI/CD for models and services with GitHub Actions
• MLOps and the ML lifecycle: from experiment to production system