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.yamlpasses the check: eleven capabilities, every one owned byplatform, three of themplanned, every offered or beta one with a self-service interface. All are forhumansfor 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
| Layer | What it holds | CNCF capability areas |
|---|---|---|
| interfaces | How users reach the platform | Web portals; APIs (and CLIs) |
| context | What users and agents need to know: the catalog, docs, instructions | "Golden path" templates and docs |
| delivery | From commit to production, with checks | Automation for building and testing; automation for delivering and verifying; development environments; artifact storage |
| runtime | Where services run, and their data | Infrastructure services; data services; messaging and event services |
| agent-control | Identity, permissions and audit for agents | Identity and secret management services; security services |
| model-gateway | One way to call models, with budgets | Not in the white paper's list; new with AI |
| observe-cost-trust | Logs, metrics, cost, across every layer | Observability |
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
offeredshould 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
C2of 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
- 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
- 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
- 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
- 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.
- 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.
- 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.