Malhar Ujawane

Blog

Explainer·(updated October 31, 2026)

What is platform engineering? Internal platforms, explained

Platform engineering is building an internal platform, run as a product, so product teams self-serve infra with golden paths. How it works, with a Python demo.

What is platform engineering? Internal platforms, explained

Platform engineering is the practice of building and running an internal platform, treated as a product, that lets product teams provision infrastructure, ship code and get observability, security and compliance through self-service instead of tickets. The platform team’s customers are the company’s own engineers, and its job is to make the right way to build a service also the easiest way. Most of what that means in practice is golden-path templates, APIs and a portal on top of tools the company already runs.

The CNCF’s platforms white paper defines a platform as “an integrated collection of capabilities defined and presented according to the needs of the platform’s users.” The important words are “according to the needs of the platform’s users”. A pile of Terraform modules and a wiki page is infrastructure. It becomes a platform when someone owns the experience of using it.

Where did platform engineering come from?

From DevOps hitting a limit. “You build it, you run it” gave product teams ownership of production, which was right. It also gave every team a Kubernetes cluster’s worth of decisions: ingress, secrets, CI, image scanning, dashboards, alerting, rollout strategy. Ten teams made those decisions ten ways, and each team spent a slice of its time on plumbing instead of the product.

The vocabulary most people use comes from Team Topologies by Matthew Skelton and Manuel Pais, published in 2019. It names four team types: stream-aligned, enabling, complicated-subsystem and platform. A platform team is “a grouping of other team types that provide a compelling internal product to accelerate delivery by Stream-aligned teams.” Of its three interaction modes, the one a platform aims for is X-as-a-Service: “one team provides and one team consumes something as a Service”, with no meeting required.

The book’s core argument is cognitive load. In the site’s words: “Just as overloaded CPUs slow down computers, overloaded teams make poor decisions and move slowly.” A platform is a way to take load off stream-aligned teams without taking ownership away from them.

How does platform engineering work?

The CNCF paper lists thirteen capability areas a platform may offer, from “web portals for observing and provisioning products and capabilities” and “APIs (and CLIs) for automatically provisioning” to observability, identity and secrets, security scanning and artifact storage. No company builds all thirteen first. In practice a platform has four layers:

  1. Interfaces. A portal, a CLI, an API, or a pull request against a config repo. This is where a developer asks for something.
  2. Golden paths. In the paper’s words, “‘Golden path’ templates and docs enabling optimal use of capabilities.” A new-service template that already has CI, tracing, a rollout strategy and a secrets reference wired in.
  3. Policy. Checks that run on every service, golden path or not: who owns it, does it emit traces, does it roll out in stages, does it handle personal data correctly.
  4. The underlying tools. Kubernetes, a cloud provider, a CI system, an observability backend. The platform composes these; it rarely replaces them.

The paper’s advice on scope is the line I would put on the platform team’s wall: “Seek to build the thinnest viable platform layer over implementations from managed providers.” The platform is glue and opinion, not a reimplementation of the cloud.

Backstage, from Spotify, is the best-known open-source portal. It describes itself as “an open source framework for building developer portals”, with a software catalog for every service, library and pipeline, software templates “for quickly spinning up new projects”, and TechDocs for docs-as-code. It is a CNCF incubating project. Backstage is a framework for building the interface layer; it is not a platform out of the box.

What does a golden path look like in code?

Here is the smallest version of the two things a platform team ships: a template that scaffolds a service with the defaults already right, and a policy check that every manifest must pass. Python 3 standard library only.

# golden_path.py: a toy internal developer platform. One template, one policy check.
# Python 3 stdlib only.
import json

# The golden path: what a new service gets if the team asks the platform for one.
def scaffold(name, team, tier):
    return {
        "name": name, "team": team, "tier": tier,
        "runtime": "python3.13",
        "replicas": 3 if tier == "critical" else 1,
        "otel": {"traces": True, "metrics": True},       # observability on by default
        "rollout": {"strategy": "canary", "steps": [1, 10, 50, 100]},
        "secrets": "vault://" + team + "/" + name,          # no secrets in the manifest
        "data_classes": [],
    }

# Platform policy: the rules every manifest must pass, golden path or not.
RULES = [
    ("owner set",             lambda m: bool(m.get("team"))),
    ("tracing on",            lambda m: m.get("otel", {}).get("traces") is True),
    ("staged rollout",        lambda m: m.get("rollout", {}).get("strategy") in ("canary", "blue-green")),
    ("critical has 3+ pods",  lambda m: m.get("tier") != "critical" or m.get("replicas", 0) >= 3),
    ("no inline secrets",     lambda m: not str(m.get("secrets", "")).startswith("plain:")),
    ("PII needs retention",   lambda m: "pii" not in m.get("data_classes", []) or "retention_days" in m),
]

def check(manifest):
    return [name for name, ok in RULES if not ok(manifest)]

paved = scaffold("checkout-api", "payments", "critical")
offroad = {"name": "loyalty-export", "team": "growth", "tier": "critical", "replicas": 1,
           "rollout": {"strategy": "all-at-once"}, "secrets": "plain:hunter2",
           "data_classes": ["pii"]}

print(json.dumps(paved, indent=None)[:96] + "...")
for m in (paved, offroad):
    failed = check(m)
    print(f"{m['name']:15} {'PASS' if not failed else 'FAIL'}  {', '.join(failed)}")

assert check(paved) == []
assert check(offroad) == ["tracing on", "staged rollout", "critical has 3+ pods",
                          "no inline secrets", "PII needs retention"]

Output (Python 3.13.11):

{"name": "checkout-api", "team": "payments", "tier": "critical", "runtime": "python3.13", "repli...
checkout-api    PASS  
loyalty-export  FAIL  tracing on, staged rollout, critical has 3+ pods, no inline secrets, PII needs retention

The service names and rules are made up; the shape is the real one. The team that took the golden path passed every check without reading a single policy document, because the template encoded the policy. The team that hand-rolled its manifest failed five. That asymmetry is the product: following the path is cheaper than leaving it, and leaving it is still allowed, it just has to pass the same checks.

Swap the toy parts for real ones and you get a Backstage template or a cookiecutter repo for scaffold, and a policy engine in CI or an admission controller in the cluster for check.

Why does platform engineering matter to a builder?

It is where cross-cutting requirements actually land. Tracing, staged rollouts, SBOMs, secrets handling, data retention: every one of them is a rule that’s easy to write in a wiki and hard to apply across a few hundred services. A platform makes the rule a default. If you want every service to emit OpenTelemetry traces, put the SDK in the template. If you want an SBOM for every image, generate it in the platform’s build pipeline. If you want no repeat of the CrowdStrike outage, make canary rollout the only deploy strategy the platform offers for critical tiers.

From the data-platform and privacy seat I sat in at Walmart, the line I would circle is the PII needs retention rule. Privacy compliance only scales if data classification and retention are fields in the service definition that a machine checks, not answers in a spreadsheet someone fills in once a year. A platform is the place to make that true.

It is the paved road for agents too. Coding agents follow golden paths better than people do, because a template is unambiguous. A repo created from a good template, with its conventions written down in an AGENTS.md, is also easier to hand to an agent.

Does platform engineering actually help?

The honest answer from the research is “yes, with a dip”. The 2024 DORA report announcement (October 23, 2024) lists four findings: internal developer platforms increase developer productivity; they are more common in larger organizations; implementing one “might lead to a temporary decrease in performance before improvements manifest as the platform matures”; and the best results come from user-centered design, developer independence and a product approach. DORA’s report page says a platform “improves individual productivity, team performance, and overall organizational performance” but “can also lead to decreased change stability and throughput.”

So a platform is not free. It is a migration, and migrations make things worse before they make them better. Plan and budget for the dip.

Where does platform engineering break?

Platform as a mandate, not a product. The CNCF paper’s first attribute is “platform as a product”: “A platform exists to serve the requirements of its users.” A platform built to satisfy an architecture review and imposed on teams becomes a ticket queue with a portal on top.

Building too much. A team that builds its own deployment system, its own secrets store and its own dashboards ends up operating a cloud provider badly. Hence the thinnest viable platform.

No escape hatch. The paper asks for capabilities that are “optional and composable”, so teams can “use only parts of its offerings”. A golden path with no exit pushes the teams with the hardest problems, often the most important ones, to work around the platform entirely.

Measuring the wrong thing. Counting services on the platform measures compliance. The CNCF’s platform engineering maturity model frames progress across investment, adoption, interfaces, operations and measurement, from “provisional” to “optimizing”. I would add one blunt metric: time from “I need a new service” to “it is serving traffic with tracing and alerts”.

What I would do

  1. Start with one golden path for the most common service type, end to end: repo template, CI, deploy with a canary, tracing and alerts. Ship that before a portal.
  2. Pick two or three partner teams and build with them, as the CNCF paper recommends. Their friction is your backlog.
  3. Encode policy as code that runs on every service, and make the template pass it by construction. Put ownership, rollout strategy and data classification in the service manifest.
  4. Use managed services and existing open-source tools underneath. Add Backstage or a similar portal once there is a catalog worth browsing.
  5. Measure lead time for a new service and the DORA delivery metrics before and after, and expect a dip.
  6. Staff it like a product team: someone owns the roadmap and talks to users every week.

FAQ

What is the difference between platform engineering and DevOps?

DevOps is a set of practices and a culture where the people who build software also run it. Platform engineering is one way to make that sustainable at scale: a dedicated team builds self-service tooling so product teams keep ownership without each rebuilding the same infrastructure.

What is an internal developer platform?

The product a platform team ships: the templates, APIs, CLIs, portal and policies that let developers create and run services themselves. The CNCF calls it “an integrated collection of capabilities defined and presented according to the needs of the platform’s users.”

What is a golden path?

A supported, opinionated route for a common task, such as creating a new service, with templates and docs that already include the organization’s defaults. It is the easy way, not the only way.

Is Backstage a platform?

No. Backstage is an open-source framework for building a developer portal: a catalog, templates and docs. It is one interface onto a platform. The capabilities behind it still have to exist.

Do small teams need platform engineering?

Usually not as a separate team. DORA found platforms are more common in larger organizations. A small team gets most of the benefit from one good template and a CI pipeline everyone uses.

Sources

Get new posts in your inbox

© 2026 Malhar Ujawane. Built with Astro.