PlatformEngr® Platform fundamentals course

Module 03 · What the platform offers · 25 min · You are: Platform team

The capability map: what the platform offers

In this module

  • You learn: What a platform capability is, the capability areas in the CNCF Platforms White Paper, the layers of a platform that serves both people and agents, and why a capability offered only through a ticket is not self-service.
  • You do: Write the capability map of the example company: what is offered, what is in beta and what is only planned, who owns each, and whether it is reached through a portal, a CLI, an API or Git. Then list a capability the way many teams do, through a ticket, and see the check refuse it.
  • You end with: capabilities.yaml passes the check: eleven capabilities, every one owned by platform, three of them planned, every offered or beta one with a self-service interface. All are for humans for now.

A capability map is the platform's menu: what a team can get, from whom, and how. Without one, every team discovers the platform by asking around, and the platform team cannot see what is missing. The map also keeps the platform honest. The CNCF Platforms White Paper names self-service as a platform attribute, and a capability that needs a ticket and a person to act is a queue, not self-service. Marking things planned is just as useful: it tells teams what not to build on yet.

Open this module in the interactive course to track progress.

Concepts

Capability
Something a team can get from the platform, such as a namespace, a pipeline or a database. Described by what the user gets, not by the tool behind it.
Capability areas
The CNCF Platforms White Paper lists thirteen areas, from web portals and APIs to observability, identity and secrets, and artifact storage.
Layer
Where a capability sits: interfaces, agent control, context, model gateway, delivery, runtime, and observe-cost-trust across all of them. The course's grouping, for a platform that serves people and agents.
Status
offered (supported, build on it), beta (usable, may change), planned (not yet: nothing may depend on it).
Self-service interface
A portal, a CLI, an API or Git: the user acts without waiting for a person. A ticket is not one.

The layers in this course, and the CNCF capability areas they cover

LayerWhat it holdsCNCF capability areas
interfacesHow users reach the platformWeb portals; APIs (and CLIs)
contextWhat users and agents need to know: the catalog, docs, instructions"Golden path" templates and docs
deliveryFrom commit to production, with checksAutomation for building and testing; automation for delivering and verifying; development environments; artifact storage
runtimeWhere services run, and their dataInfrastructure services; data services; messaging and event services
agent-controlIdentity, permissions and audit for agentsIdentity and secret management services; security services
model-gatewayOne way to call models, with budgetsNot in the white paper's list; new with AI
observe-cost-trustLogs, metrics, cost, across every layerObservability

Capability areas from the CNCF Platforms White Paper. The layers are this course's grouping, not a standard.

Files to know

Open them in your editor or on GitHub; the bullets say what to look at.

Steps

1. Write the capability map

Eleven capabilities, grouped by layer with comments. Read the status of each as you type it: three are planned.

cd ~/platformengr/platform-design

Create capabilities.yaml

# What the platform offers, by layer, who owns it, and how people and agents reach it.
# Owner: the platform team. Read by the design check (rules C1 to C3).
# status: offered (supported today), beta (usable, may change), planned (not yet: nothing may depend on it).
capabilities:
  # interfaces: how users reach the platform
  - id: service-catalog
    name: Service catalog and ownership
    layer: context
    owner: platform
    status: offered
    interfaces: [portal, api]
    users: [humans]
  # delivery and verification
  - id: repo-template
    name: New repository from a template
    layer: delivery
    owner: platform
    status: offered
    interfaces: [portal, cli, api]
    users: [humans]
  - id: ci-pipeline
    name: Build, test and scan on every pull request
    layer: delivery
    owner: platform
    status: offered
    interfaces: [git]
    users: [humans]
  - id: preview-environments
    name: A preview environment per pull request
    layer: delivery
    owner: platform
    status: beta
    interfaces: [git, api]
    users: [humans]
  - id: deploy
    name: Deploy through Git, with progressive rollout and rollback
    layer: delivery
    owner: platform
    status: offered
    interfaces: [git, api]
    users: [humans]
  # runtime and data
  - id: team-namespace
    name: A namespace with quota and access per team and environment
    layer: runtime
    owner: platform
    status: offered
    interfaces: [git, api]
    users: [humans]
  - id: postgres
    name: A managed Postgres database
    layer: runtime
    owner: platform
    status: planned
    interfaces: [ticket]
    users: [humans]
  # agent control plane and model gateway
  - id: agent-identity
    name: An identity per agent, with scoped tokens and audit
    layer: agent-control
    owner: platform
    status: planned
    interfaces: [api]
    users: [humans]
  - id: model-gateway
    name: One gateway for model calls, with budgets per team
    layer: model-gateway
    owner: platform
    status: planned
    interfaces: [api]
    users: [humans]
  # observe, cost and trust
  - id: logs-and-metrics
    name: Logs, metrics and dashboards per service
    layer: observe-cost-trust
    owner: platform
    status: offered
    interfaces: [portal, api]
    users: [humans]
  - id: cost-report
    name: Cloud and AI cost per team and per change
    layer: observe-cost-trust
    owner: platform
    status: beta
    interfaces: [portal, api]
    users: [humans]

Run the check. Expect ok capabilities.yaml. It checked that every owner is a team in teams.yaml, every status and layer is known, and every capability that is offered or in beta has an interface people can use without a ticket.

npm run check

2. Count what is really offered

The map is also a status report. A team lead asks what they can build on today.

Expect six: the capabilities a team can use and rely on now.

grep -c "status: offered" capabilities.yaml

Expect three: Postgres, agent identity and the model gateway. Nothing may depend on them yet, including the golden path you write next.

grep -B4 "status: planned" capabilities.yaml | grep "id:"

3. Commit

Save it.

git add -A && git commit -qm "Capability map" && git push -q
gh run list --workflow design-check --limit 1

Simplified for the course

Every capability is owned by the platform team. In a larger company some are owned by other teams, such as security or data, and the map shows that.

One line of interfaces per capability. Real maps also say which version of an API, the support hours and the service level.

There are no service levels in the map. A capability that is offered should have one, and module 06 measures the platform as a whole.

Break it on purpose: Offered, through a ticket

A team lead complains that Postgres is listed as planned, "but we have been giving teams databases for years: you open a ticket and the database team makes one in a week". You change the status to offered.

You practise: telling a self-service capability from a queue, and keeping the map honest.

1. Break it

Change in capabilities.yaml

-     status: planned
-     interfaces: [ticket]
+     status: offered
+     interfaces: [ticket]
npm run check

2. What you see

Expected: ok capabilities.yaml. You get: FAIL capabilities.yaml and a line with [C2] that names postgres.

3. Fix it yourself

Make the map tell the truth about databases. Done when the check passes, and you can say what a team that needs a database this month should do.

Hint 1

The team lead is right that databases are available. Is that the same as self-service?

Hint 2

Either give Postgres a real self-service interface (only if one exists), or mark it planned again: the ticket still works, it is just not a platform capability yet.

The fix

A team that needs a database this month still opens the ticket. The map says so honestly, and the platform team knows the ticket queue is a capability to build.

Change in capabilities.yaml

-     status: offered
-     interfaces: [ticket]
+     status: planned
+     interfaces: [ticket]
npm run check
git add -A && git commit -qm "Postgres stays planned until it is self-service" && git push -q
After you fixed it: the five questions
What failed?
The capability map. It called a ticket queue a platform capability.
How was it detected?
By rule C2 of the check.
Who responds?
The platform team, which owns the map.
How is it corrected?
Mark it planned, or build the self-service interface before calling it offered.
How is it prevented?
Review the map with users each quarter, and count ticket-only requests as a signal for what to build next.

Quiz

  1. Teams get a namespace by opening a ticket, and someone creates it within a day. Is that a self-service capability?
    • Yes, because the request is tracked and fulfilled quickly
    • Yes, if the ticket form has fields for everything the namespace needs
    • No: the team waits for a person to act. Self-service means a portal, CLI, API or Git change they make themselves
  2. Why list capabilities that are only planned?
    • So teams know not to build on them yet, and the platform team can see what is missing
    • So leadership sees a longer list and funds the team
    • So the golden path can already use them and save time later
  3. How should a capability be named in the map?
    • By the tool that implements it, so engineers know what to learn
    • By what the user gets, such as "a namespace with quota and access per team"
    • By the team that owns it, so requests reach the right people
Answers
  1. No: the team waits for a person to act. Self-service means a portal, CLI, API or Git change they make themselves Speed is good, but a queue does not scale with the number of teams.
  2. So teams know not to build on them yet, and the platform team can see what is missing Planned tells users what is coming and stops anything from depending on it today.
  3. By what the user gets, such as "a namespace with quota and access per team" Users ask for outcomes; the tool can change behind the same capability.

Field note

When I draw a team's capability map with them, the most useful column is status. Half of what people believed was offered turned out to be "ask Sam". That is not a failure, it is the roadmap: the most-asked "ask Sam" is usually the next capability to build.

Report a problem with this module