Parts of an Internal Developer Platform

Consider an illustrative platform team shipping a portal. It looks good: every service in the company is listed with its owner, its documentation, its dashboards and its repository. Leadership is pleased. Six weeks later usage has settled into a pattern nobody planned — developers open it to find out who owns something, and then go to Slack to ask that person for a database. The portal helps people find owners but has not changed database fulfillment.

The CNCF platforms white paper distinguishes web portals from provisioning APIs among thirteen capability domains. A portal can expose both information and actions, but an action needs an execution path behind it. A useful review follows that path from the screen to the system that creates or changes the resource.

For an internal developer platform, examine both what users can discover and what happens after they submit a request.

Thirteen domains, and where the portal sits

The CNCF white paper places platforms between underlying capability providers and their users. Platforms connect those services and apply agreed security, performance and cost practices through a consistent experience. A portal is one interface to that arrangement.

The following grouping organizes the paper’s thirteen domains by their role in that arrangement. The grouping is the author’s; the capability categories come from the white paper.

• User interface. Portals for observing capabilities and initiating provisioning
• Consumption paths. Provisioning APIs and CLIs; golden-path templates and documentation
• Development and operation. Build and test automation; delivery and verification automation; development environments; application observability
• Underlying services. Infrastructure; data services; messaging and events; identity and secrets; security checks and enforcement; artifact storage

The portal domain includes observing and provisioning capabilities. Its screen can display catalog records, collect parameters and start workflows. Provisioning APIs and backend actions then create, update, delete or inspect the underlying resources. Separate responsibilities can belong to the same product: a Backstage installation can combine a catalog with Software Templates and backend integrations.

This is a menu, not a specification every platform must implement. The CNCF paper recommends choosing capabilities with users. Frequent, shared needs such as pipelines, databases and observability are useful starting candidates; their priority still depends on user requirements, reuse and operating cost.

One domain may contain several features. Observability can include metrics, traces, logs and cost visibility. Define the supported workflows and service commitments rather than treating the domain name as a complete scope.

Different users may consume the same capability through an IDE, CLI, API or web portal. A supported API or CLI enables programmatic use without depending on fragile browser automation. Keep the concepts, authorization rules and results consistent across these entry points.

Catalog records and provisioning workflows

A service catalog records software ownership and metadata. Backstage uses this model for services, websites, libraries and data pipelines. That record helps users find a component and understand where to go for documentation and support.

Ownership discovery supports incident response, patching and handover. The accountable team and the first on-call responder may differ, so connect the owner record to a current support and escalation route. A catalog makes this information easier to find; it cannot make a team accept responsibility merely by naming it.

The catalog itself is a metadata system rather than a provisioning engine, although its interface can link to or launch one. Repository YAML is a common input to Backstage; entity providers can also ingest authoritative external systems, and processors can enrich records before they are stored. Specify the source for each field and expose ingestion age and failures. Successful harvesting helps keep records current but does not establish that an ownership claim is true. Confirm responsibility with the named team and track entries whose support commitments remain unacknowledged.

Backstage’s core model distinguishes components, the software being described; APIs, the interfaces between components; and resources, the infrastructure components need. User and group entities represent people and organizational groups. This vocabulary is useful even when another tool stores the records.

The system model treats API contracts as first-class, machine-readable descriptions. It also discusses public, restricted and private visibility, while warning that some modeled concepts are not implemented. Do not assume that visibility is a standard queryable field in your installed schema: use a documented extension if needed. A visibility label describes intended consumers, not enforced access. Private APIs still have internal consumers whose changes must be coordinated.

Systems group components and resources behind exposed APIs so consumers can rely on a contract while implementation details evolve. Domains relate systems through business purpose, terminology and models; Backstage connects this idea to a bounded context. These are modeling boundaries, not automatic network or security boundaries.

A Software Template describes the parameters collected by its form and the steps its scaffolder executes. The catalog records the result; the execution workflow creates it. Verify which actions, permissions and recovery behavior the installed plugins actually support.

Self-service is a rung, and you can locate yourself on it

The CNCF maturity model evaluates interfaces separately from investment, adoption and operations. Its interface levels progress from custom processes through standard tooling and self-service solutions to integrated services. Evaluate discovery and use across initial requests, maintenance and incident diagnosis, not just the creation screen.

Read as a description of what the click does, with each level’s own stated limitation:

Level	What happens after the click	The documented catch
1. Custom processes	Provider-assisted requests through locally defined routes	Users may struggle to find the process or required expertise
2. Standard tooling	Documented patterns and templates for requesting and using capabilities	Some tasks require specialist help; customized copies may be hard to update
3. Self-service solutions	Guided automated provisioning with less routine provider involvement	Later management or unusual requirements may have weaker support
4. Integrated services	Capabilities fit existing tools; some arrive by default	Integration needs investment justified by the user tasks it improves

Three things in that ladder are more useful than the ladder itself.

At the standard-tooling level, teams may customize copied templates and struggle to merge later central changes. Keep copied material small and provide a migration path. This is a risk of that delivery mechanism, not evidence that most platforms occupy a particular level.

The self-service level can make creation easier than later maintenance. Plan day 2 operations alongside creation: upgrades, resizing, backup, transfer and retirement. Otherwise routine creation can leave an accumulating maintenance backlog.

At the integrated level, the model describes capabilities that fit existing tools and can be composed or adapted. Decide which parts users can configure or separate while preserving required controls and the support contract. A bundled service can still be appropriate where its components must be operated together.

Each higher level requires investment, so the model does not prescribe reaching the top everywhere. Evaluate its aspects independently against user needs and costs. An early platform can reasonably rely on manual fulfillment while testing demand; the useful assessment identifies what to improve next.

Connected means it arrives already wired

The hard part of composing a platform is not acquiring capabilities. It is that a developer shipping one new service needs an environment, a pipeline, an identity, secrets, network reachability, storage and observability — and each of those arriving separately is seven onboarding tasks rather than one.

It also means several things must succeed together, which raises the question the happy path hides: what does the platform owe you when half of it worked? A database is created and the secret is not registered; the dashboard exists and the credential does not; the response times out after the resource was made. If retrying creates another database, the automated path has a correctness defect that users need help to resolve.

Retry safety requires a stable identity for the intended operation or resource, together with a contract that prevents duplicate effects. A natural key or a fixed resource identity with reconciliation can meet that requirement when the API guarantees the necessary semantics. For a request-token contract, obtain an idempotency key before the first submission. Preserve it across retries and browser reconnection; use a new key for a genuinely new operation. Bind it to the caller or tenant, operation and relevant region, validate that the parameters match, and coordinate concurrent attempts through durable, atomic request registration and controlled execution. Document retention and the retry window, including downstream providers’ limits. Each external step needs its own retry-safe token or a way to reconcile its outcome. A missing response or an empty lookup may leave the result unknown; do not create another resource until that uncertainty is resolved. Expose progress and failed steps, resume only after checking what succeeded, and assign cleanup responsibility. Self-service provisioning develops this contract further. Scaffolder logs help diagnosis but do not themselves provide recovery.

The maturity model illustrates a database capability with connection details, a secure credential location and an observability dashboard. Together these let a user connect and inspect its behavior. Other capabilities need different outputs: completeness means supplying the access, usage and status information required for the supported task, rather than a universal three-item bundle.

Some integrated capabilities arrive automatically. The model gives examples such as injected observability agents and default pipeline and runtime spaces for new projects. Defaults can coexist with approved alternatives; document the supported options and who operates each one.

The white paper also describes complete environments and workflows combining development and runtime services. Its golden path example joins a template, documentation and a workflow for building, scanning, testing, deploying and observing an application. Integration makes those parts usable together.

Evaluate that integration by walking a defined user journey, such as creating a service or diagnosing a production issue. Count handoffs, tools and approvals, then measure waiting time, hands-on effort, success and rework against the previous path. Fewer clicks can conceal more waiting or diagnosis. Include partial failure and safe retry in the exercise.

DORA’s 2025 findings associate clear task feedback with a positive platform experience. Logs and actionable status can help users troubleshoot, but they do not eliminate every support need. Distinguish a deployment request rejected by authorization or admission controls from a network policy blocking a running workload’s connection and causing readiness or rollout checks to fail. The standard NetworkPolicy API does not automatically explain each dropped connection; platform diagnostics must combine relevant plugin evidence and connectivity checks.

Plan for the capability lifecycle

A capability’s roadmap must cover operation after launch as well as its interface. Budget that work over the capability’s lifecycle.

The maturity model treats operations as work across a capability’s lifetime: accepting requests, releasing, upgrading, maintaining, supporting and eventually retiring it. Its warning that much work follows launch is a reason to budget beyond initial delivery.

Agree the support period and retirement conditions before adding a capability. Plan notice, migration assistance and exceptions rather than promising indefinite support to every remaining user. Compare shared maintenance cost with per-consumer support and exceptional work. These costs depend on reuse, automation, scope and service quality; they are not necessarily proportional to capability count multiplied by team count. A thinnest viable platform limits what the team must build and operate, while toil reduction addresses repetitive operational effort.

DORA recommends extensibility so other teams can contribute tools and services. Contributions still need agreed interfaces, ownership and support; the central team need not implement every capability itself.

Assessing the supported user journey

Use these six questions as independent improvement checks. A weakness in one does not make the others irrelevant or establish that an emerging platform is not a platform.

1. How much of the ordinary request path is automatic? Distinguish avoidable manual fulfillment from required review for cost, sensitive data or destructive changes. State the approved envelope, exceptions, expected waiting time and next improvement.
2. Are catalog sources, ingestion freshness and ownership confirmed? Check processing failures as well as whether the named team accepts the stated responsibility.
3. Is there a supported programmatic entry point where users need one? Evaluate API or CLI access alongside the web interface.
4. Does the capability supply what its task requires? For a database this may include connection details, access to credentials and health information; define equivalent completion criteria for other offerings.
5. Can users understand success, rejection and partial failure? Check diagnostic usefulness and escalation routes through representative tasks.
6. Which parts can users configure, replace or separate? Make those choices and their control and support requirements explicit.

A directory can be a valuable first platform capability, and manually fulfilled services can be appropriate while demand is being tested. Report the specific outcome: faster discovery, shorter request queues or automated fulfillment. These gains are different and should be measured separately.

Choose capabilities with users, define their operating and support contracts, and connect request, execution, feedback and recovery. Budget for maintenance and retirement as well as launch. The portal exposes this work; backend workflows and providers carry it out. Judge platform engineering by the effort and uncertainty it removes from users’ tasks. The Load Has to Land Somewhere covers the responsibility boundary; developer portal distinguishes the internal platform interface from the API consumer portal.

References

• CNCF TAG App Delivery: Platforms White Paper
• CNCF Platform Engineering Maturity Model
• Backstage: Software Catalog
• System Model
• Software Templates
• DORA: Platform engineering
• Backstage: External integrations
• AWS: EC2 API idempotency
• AWS Builders’ Library: Making retries safe with idempotent APIs
• AWS: EC2 eventual consistency
• Kubernetes: Network Policies