What Belongs on an Internal Developer Platform?

Most platform teams eventually hit the same scope problem: once an internal developer platform starts working, everything begins to look like a candidate for the platform.

Databases. CI/CD. Secrets. Observability. Kubernetes. Cloud accounts. Service templates. Cost controls. Security scans. Runtime policies. Developer portals. Documentation. Incident tooling. Feature flags. Data pipelines. Model gateways.

The question is not whether these things can be put behind a platform. Almost all of them can. The useful question is whether doing so creates enough shared value to justify centralizing an interface, an operating model, and an ongoing maintenance obligation.

That distinction matters because an internal platform can fail in two opposite ways. It can be too thin to remove meaningful friction, leaving teams to assemble the same infrastructure and controls repeatedly. Or it can become a second infrastructure estate: a large, mandatory abstraction that developers must learn in addition to the cloud, deployment system, security model, and application stack underneath it.

The right boundary is neither “everything developers touch” nor “only infrastructure.” It is the smallest set of reusable capabilities that makes important engineering workflows materially easier, safer, and more self-service.

The CNCF Platforms White Paper states the principle directly: platform capabilities should be selected according to the needs of platform users, with common use cases prioritized over capabilities that serve only one team. DORA’s platform engineering guidance reaches the same conclusion from a product perspective: start from critical user journeys and make the most common workflow demonstrably better before expanding the platform.

That gives platform leaders a practical way to decide what belongs.

Start with journeys, not technologies

A weak platform roadmap is usually organized as a list of technologies:

• Kubernetes
• Terraform
• Vault
• Argo CD
• Backstage
• Prometheus
• cloud accounts

A stronger roadmap starts with recurring developer journeys:

• create a new production service;
• provision a database;
• deploy a change safely;
• expose an API;
• obtain a secret;
• debug a production problem;
• create an ephemeral environment;
• publish an event;
• satisfy a security control;
• understand service ownership and health.

Technology still matters, but it becomes an implementation detail beneath a user-visible capability.

This changes the scope discussion. “Should Kubernetes belong on the platform?” is too vague. A better question is: “Should teams need Kubernetes expertise to deploy an ordinary service?” The answer may be no even when Kubernetes remains the runtime.

The platform can own the experience without owning every underlying system.

CNCF explicitly separates these responsibilities. Its white paper notes that platform teams do not necessarily operate compute, storage, databases, identity systems, or other backing services. They are primarily responsible for the interfaces and experiences through which product teams consume those capabilities.

That distinction is one of the most useful boundary rules in platform engineering.

A capability belongs when reuse creates leverage

The strongest platform candidates usually share several characteristics.

They are needed by multiple teams. They recur frequently. Teams would otherwise solve them independently. Their implementation contains operational, security, reliability, or policy complexity that application developers should not need to master. They can be exposed through a stable self-service contract. And improving the capability once creates benefits across many consuming teams.

Consider database provisioning.

If several teams independently decide how to create a managed PostgreSQL database, configure backups, network access, secrets, observability, lifecycle policies, and cost attribution, the organization is repeating undifferentiated work. A platform capability can standardize the contract:

Request a PostgreSQL database with this capacity class, availability profile, retention policy, and owner.

The platform can translate that request into the organization’s chosen provider, policies, networking, identity model, observability, and lifecycle automation.

The platform team does not need to build PostgreSQL. It may not even operate PostgreSQL. Its product is the safe, supported, repeatable way to consume it.

The same logic often applies to:

• service creation and repository bootstrapping;
• build and deployment workflows;
• managed databases and caches;
• secrets and service identity;
• observability bootstrap;
• artifact repositories;
• common messaging services;
• environment provisioning;
• security and compliance checks;
• standard runtime configurations.

The CNCF platform capability model lists many of these domains, but it is not a checklist. The paper repeatedly emphasizes that the actual platform should reflect user needs.

“Belongs on the platform” does not mean “the platform team builds it”

Platform scope becomes easier to manage when capability ownership is separated from implementation ownership.

A platform team can provide at least four different levels of involvement.

Build and operate

The platform team owns the implementation because no suitable external or internal service exists, or because the experience itself is strategically important enough to justify custom engineering.

Examples might include an organization-specific deployment control plane or a proprietary environment orchestration layer.

This should be the most expensive option because the platform team inherits reliability, support, upgrades, security, capacity, documentation, migration, and lifecycle obligations.

Integrate and wrap

The platform exposes a stable interface while a managed provider or another internal team owns the underlying service.

This is often the right model for databases, identity, secrets, artifact storage, cloud resources, observability backends, and messaging.

The platform adds value through defaults, policy, lifecycle automation, discoverability, consistent credentials, cost attribution, and a common user experience.

Standardize and compose

The platform does not hide the underlying product. Instead, it supplies templates, policy bundles, configuration, documentation, and automation that compose existing tools into a supported path.

This can be enough for CI/CD, service bootstrapping, telemetry, or cloud-resource patterns.

Document and recommend

Sometimes the correct platform feature is simply a clear supported pattern.

Team Topologies’ Thinnest Viable Platform concept is deliberately useful here: if documentation and a small amount of guidance are enough to remove uncertainty, building a control plane may add more complexity than it removes.

This four-level model prevents an important failure mode: assuming every platform capability needs a new service.

Do not centralize application-specific logic

A useful platform boundary becomes clearer when you look at what should usually stay outside it.

Business rules belong with the teams that own the business domain. Product-specific workflows belong with the product. Specialized technology needed by a single workload should usually remain with the team that has the context to operate it.

If one team needs an unusual graph database, a custom stream processor, or a specialist ML runtime, forcing the platform team to productize that capability immediately can create more coordination than it removes.

This is where a common platform organization makes a category mistake: it interprets “platform team” as “team that owns shared technology.”

Shared ownership alone is not enough. The platform needs a repeatable user problem and enough reuse to create leverage.

A capability used by one team may later become a platform feature. The safer path is often to let the first team solve the problem locally, observe the pattern, and promote the capability only when the need generalizes.

That keeps the platform from becoming a warehouse of one-off abstractions.

The platform should be thinner than the systems beneath it

Team Topologies describes the idea of a Thinnest Viable Platform: build only as much platform as is necessary to improve the experience of stream-aligned teams.

That can feel counterintuitive because platform initiatives often begin with an ambition to hide complexity. Hiding complexity is useful only when the abstraction is simpler than the thing it hides.

A platform that reproduces every option from a cloud provider has not necessarily reduced cognitive load. It may simply have created another API to learn.

A platform should abstract decisions the organization has already made.

If the organization has standardized on a small set of deployment models, supported databases, identity patterns, and observability conventions, the platform can encode those decisions into simple interfaces. If a choice remains genuinely workload-specific, the platform should be careful not to pretend there is one correct answer.

A useful test is:

Does this abstraction remove decisions that most consumers should not have to make?

If yes, it probably creates platform value.

If it merely renames provider concepts, it may not.

Self-service separates a platform from a shared operations queue

A capability does not create much platform leverage if every ordinary request still requires a human handoff.

CNCF describes self-service as a core platform attribute: users should be able to request and receive capabilities autonomously and with minimal manual intervention. DORA similarly puts automation, repeatability, and self-service at the center of platform engineering.

This creates another scope test.

A capability is a strong platform candidate when it can be expressed as a repeatable contract and safely automated.

For example:

• create a service from an approved template;
• provision a database;
• rotate credentials;
• request an ephemeral test environment;
• create a deployment pipeline;
• register a service in the catalog;
• expose standard telemetry;
• obtain a DNS name;
• create an approved messaging topic.

By contrast, a workflow dominated by ambiguous judgment, infrequent negotiation, or highly bespoke architecture may not benefit from being forced into a platform interface.

The goal is not to eliminate human expertise. It is to reserve human expertise for cases that actually require judgment.

Put guardrails where they remove repeated risk

Some capabilities belong on a platform not primarily because developers request them frequently, but because the organization repeatedly needs the same controls.

Identity, secret handling, artifact provenance, baseline observability, deployment policy, network boundaries, vulnerability scanning, and cost attribution are common examples.

A platform can make the safe path the default path.

This is different from creating a central approval gate. The stronger pattern is to encode controls into templates, APIs, policies, and automation so that a normal workflow satisfies requirements without waiting for another team.

The CNCF Platforms White Paper includes secure defaults, policy enforcement, identity, secrets, security services, and delivery verification among the capability domains a platform may expose.

The test is not “can governance own this?” It is “can a shared platform make the compliant path easier and more automatic?”

If yes, the capability has platform leverage.

Golden paths should be preferred paths, not golden cages

A platform needs opinions. Without opinions it cannot simplify much.

But every opinion has a boundary.

DORA warns against a one-size-fits-all platform that becomes a “golden cage.” CNCF describes successful platforms as optional and composable, allowing product teams to consume only the capabilities they need and to manage something outside the platform when necessary.

This matters because workload diversity is real.

A typical stateless service, a mobile application, a data pipeline, a latency-sensitive transaction service, and a GPU-heavy AI workload may share some platform capabilities while needing very different runtime patterns.

The platform should make the common path excellent without pretending the common path is universal.

That means maintaining explicit escape hatches:

• unsupported capability with team-owned operation;
• exception path with documented controls;
• contribution model for adding a new reusable capability;
• extension points around the common workflow;
• direct provider access where platform abstraction adds no value.

The strongest adoption signal is not that teams are unable to bypass the platform. It is that they prefer not to.

The portal is not the platform

One frequent scope mistake is to define the platform by what appears in the developer portal.

A portal is an interface. The platform is the collection of capabilities, contracts, workflows, controls, and experiences behind it.

The CNCF discussion on internal developer portals identifies an anti-pattern in putting data and tooling logic directly into the portal, because that makes it harder to expose the same capability through other interfaces.

A platform capability should normally be consumable through an API or automation layer first. A portal can then provide a discoverable human interface. A CLI can use the same contract. CI/CD can call it. An IDE extension can call it. An automation agent can call it.

Backstage’s Software Templates illustrate the useful side of portals: a user can choose a template, provide inputs, and trigger a repeatable scaffolding workflow. The value is the workflow and contract, not the existence of a web form.

This distinction matters increasingly as more non-human clients consume engineering capabilities.

Platformization has a permanent cost

The most important argument against putting a capability on the platform is rarely the initial implementation effort.

It is the long-term contract.

Once teams depend on a platform capability, the platform inherits expectations around:

• availability;
• compatibility;
• support;
• documentation;
• security;
• observability;
• migrations;
• deprecation;
• upgrade paths;
• cost management;
• incident response;
• ownership boundaries.

A small wrapper around a cloud API can therefore create a large organizational obligation.

This is why “we can automate it” is not enough.

Before promoting a workflow into the platform, ask what contract is being created. Will consumers expect the interface to remain stable? Who handles provider changes? Who migrates old configurations? Who owns incidents? What happens when the underlying service is deprecated? How are breaking changes communicated?

A platform capability should earn this permanent cost through reuse and leverage.

Decide with an explicit capability test

Platform scope should not depend on who argues most effectively in a roadmap meeting.

Use a consistent test for every proposed capability.

1. Is there repeated demand?

Do multiple teams need this, or is it a one-off request?

2. Is the workflow frequent enough to matter?

Automating a workflow used constantly has different leverage from automating a rare exception.

3. Is the work undifferentiated?

Would product teams create meaningful business advantage by implementing this themselves?

4. Does centralization reduce cognitive load?

Can the platform remove infrastructure, security, policy, or operational details that most teams should not need to master?

5. Can it be self-service?

Can the common path be made deterministic and safely automated?

6. Do shared guardrails create value?

Would a platform implementation reduce repeated security, compliance, reliability, or cost risk?

7. Can the interface remain stable while implementations change?

A stable platform contract can protect teams from provider or tooling churn.

8. Is the capability composable?

Can teams use it without being forced into unrelated platform choices?

9. Is there a clear owner and operating model?

A platform feature without lifecycle ownership becomes another dependency nobody can safely rely on.

10. Can success be measured?

Can the team observe task success, adoption, developer satisfaction, fulfillment time, delivery effects, reliability, or another meaningful outcome?

The answers do not need to be binary. The point is to expose the assumptions behind the scope decision.

Add a second decision: expose, standardize, or own

A capability can pass the “belongs on the platform” test without requiring full ownership.

A useful decision sequence is:

1. Should this user journey be part of the platform experience?
2. What is the thinnest intervention that improves it?
3. Who should own the backing implementation?

For a managed database, the answer might be: yes, expose it; provide a standard contract and guardrails; let the cloud provider operate the database.

For service creation, the answer might be: yes, standardize it; provide templates and automation; leave application ownership with product teams.

For a proprietary deployment control plane, the answer might be: yes, build and operate it, because no existing service satisfies the organization’s requirements.

For an unusual specialist datastore, the answer may be: not yet; document the exception path and let the consuming team own it.

This avoids collapsing every platform decision into “centralize or decentralize.”

Use a capability scorecard, but do not pretend it is mathematics

A lightweight scorecard can make roadmap trade-offs explicit.

For each proposed capability, assess:

This should not become a fake numerical model with arbitrary thresholds. Its purpose is to expose where the case is strong or weak.

A capability with broad demand, heavy duplication, high cognitive load, clear guardrail value, and strong self-service potential is a natural platform candidate.

A capability with one user, low frequency, weak abstraction value, and unclear ownership is probably not.

Promote capabilities instead of collecting them

A healthy platform roadmap can work like a promotion system.

A problem begins locally. One team solves it. Another team encounters the same problem. The organization observes duplication. A common interface emerges. The platform team then evaluates whether it can provide a reusable capability with a lower total cognitive and operational cost.

This avoids premature centralization.

It also creates a natural contribution model. A product team can build the first implementation; the platform team can later help generalize the contract, add guardrails, document it, and make it self-service.

The reverse path matters just as much.

The CNCF portal guidance explicitly connects platform-as-product thinking with removing capabilities that are no longer useful or cost too much to maintain. A platform that only accumulates features becomes harder to understand, harder to operate, and harder to evolve.

Every platform capability should therefore have both an entry test and an exit test.

Make deprecation part of the platform architecture

Deprecation is easier when the platform separates contracts from implementations.

If consumers depend directly on an internal implementation detail, every migration becomes a coordination exercise. If they depend on a stable platform contract, the platform team has more freedom to replace the provider or implementation beneath it.

But that only works when the abstraction is meaningful and intentionally versioned.

Platform teams should know:

• which teams consume each capability;
• which versions or configurations are active;
• which dependencies prevent removal;
• which capabilities are unused;
• which workflows generate support load;
• which provider features are leaking through the abstraction;
• where users are bypassing the platform.

This makes capability retirement an engineering process rather than an archaeological exercise.

Measure whether the capability deserved to be platformized

The strongest way to validate platform scope is to measure the user journey that justified the capability.

DORA recommends a balanced view that includes software-delivery performance, developer satisfaction, adoption and retention, and task success. CNCF also points to user satisfaction, fulfillment latency, onboarding time, and delivery measures.

For a database provisioning capability, useful signals might include:

• whether teams actually adopt the path;
• whether provisioning succeeds without platform-team intervention;
• how long the workflow takes;
• whether users return to the platform for later databases;
• whether exceptions are common;
• how much operational support the capability creates;
• whether required controls are consistently applied.

For service creation, the useful measure may be the effort from repository creation to a deployable, observable, policy-compliant service.

For incident diagnostics, it may be whether engineers can find ownership, logs, traces, dashboards, and runbooks without opening a support ticket.

For a golden path, it may be adoption and retention rather than one-time onboarding.

A platform capability that produces no observable improvement should not be protected because it has already been built.

Revisit boundaries as the organization changes

Platform scope is not static.

A capability that was too specialized last year may become common after a strategic shift. A custom internal service may become unnecessary when a managed provider matures. A manual compliance process may become automatable. A popular platform abstraction may become redundant when the underlying cloud service becomes simple enough to consume directly.

The same applies to emerging workloads.

If many teams begin deploying AI-backed services, capabilities such as model access, credential management, evaluation hooks, usage policy, observability, or cost controls may become common platform concerns. That does not mean every AI tool belongs on the platform. The same tests still apply: repeated demand, reusable contracts, cognitive-load reduction, shared guardrails, self-service, and measurable value.

A platform should absorb recurring complexity, not trends.

The practical boundary

The simplest rule is this:

Put a capability on the internal platform when making it shared, self-service, opinionated, and reusable removes more organizational complexity than the platform itself introduces.

That usually means the platform should own common engineering journeys, interfaces, defaults, guardrails, and automation.

It usually should not own product-specific logic, specialist one-off technology, or abstractions that provide no meaningful reduction in cognitive load.

And it does not need to own every backing system it exposes.

The best platform is not the one with the most capabilities. It is the one that makes the right engineering work easy while staying out of the way of everything else.

Also read:

• Why Engineering Leaders Need Product Thinking

• 7 Operating Principles of High-Performing Engineering Teams

• 8 Leadership Patterns for Scaling Engineering Organizations