Module 00 · Orientation · 15 min · You are: Platform team
Orientation: a platform design you can check
In this module
- You learn: What this course is: a platform designed on paper first, written as files in Git, so that every decision can be read, reviewed and checked like code. No cluster and no cloud account.
- You do: Tell the course your GitHub name, check your tools, clone the reference repo, create your own repo
platform-design, copy in the design check, run it on your laptop, and watch it run on GitHub. - You end with: Your repo on GitHub holds
package.json,package-lock.json,.gitignore,scripts/check.mjsand.github/workflows/check.yaml.npm run checkprints eight lines markednot written yetandNothing written yet. The check is ready.The workflow run onmainis green.
Most platforms are not designed. They grow from the first tool someone installed, and a year later nobody can say who the platform is for, what it offers or whether it helps. A platform team that writes its design down can be asked "why?" and answer from a file. Writing it as structured files in Git, with a check on every pull request, treats the design like everything else the team ships: reviewed, versioned and tested. You play the platform team, and now and then team-checkout, a product team that uses the platform.
Open this module in the interactive course to track progress.
Concepts
- Platform engineering
- Building and running an internal platform that product teams use to deliver software themselves. The CNCF Platforms White Paper calls a platform "an integrated collection of capabilities defined and presented according to the needs of the platform's users".
- Design as code
- The design lives in files with a fixed shape, so a program can read it. A change to the design is a pull request a colleague can review.
- The design check
scripts/check.mjsreads the files and prints every rule they break, each with an id such asP2. It never runs anything from the repo.- Two kinds of user
- People and the coding agents that work for them. This course designs the platform for both from the start, which is what "for the AI era" means here.
What your repo will hold
| File | What it says | Module |
|---|---|---|
platform.yaml | Who the platform is for, what it solves for them, and what it will not do | 01, 05 |
teams.yaml | The teams and how they work together | 02 |
capabilities.yaml | What the platform offers, who owns it, how it is reached | 03, 05 |
golden-paths/new-service.yaml | The supported way to start a new service | 04, 05 |
agents/policy.yaml | What each agent may do, where, as whom, for how much | 05 |
metrics/scorecard.yaml | How you know it works | 06 |
docs/adr/0001-*.md, plan/90-days.yaml | The first decision and the first 90 days | 07 |
Files to know
Where you are heading, in two minutes. These files from the reference repo describe the finished design. Click Quick look on each: it opens the real file right here, with numbered circles on the lines that matter.
Open them in your editor or on GitHub; the bullets say what to look at.
README.md(reference, your repo): The map of the reference repo. Read the table, skip the prose.- One file per part of the design, with its owner and the module that writes it L12–27
scripts/check.mjs(reference, your repo): The design check. You copy it and never need to edit it..github/workflows/check.yaml(reference, your repo): The same check on every pull request.
Steps
1. Tell the course who you are
Your GitHub user (or organisation) and a folder for your repo and the reference clone. Every command and link uses them. They stay in your browser.
Set your GitHub user and workspace folder in the interactive course or the form at the top of the notes index; these notes then show your values.
2. Check your tools
Paste this into a terminal. Each tool reports ok (with its version), MISSING (with where to get it) or PROBLEM (installed but not usable yet). Install what is missing your usual way, then run it again until it says All set. You need Git, the GitHub CLI logged in, and Node.js 20 or newer with npm.
check() { # tool, works-check, version, problem, where-to-get-it
if ! command -v "${1%% *}" >/dev/null 2>&1; then printf ' MISSING %-22s install it: %s\n' "$1" "$5"; bad=$((bad+1))
elif ! eval "$2" >/dev/null 2>&1; then printf ' PROBLEM %-22s %s\n' "$1" "$4"; bad=$((bad+1))
else printf ' ok %-22s %s\n' "$1" "$(eval "$3" 2>&1 | head -n 1)"; fi
}
bad=0
check 'git' 'git --version' 'git --version' 'installed, but it does not run' 'https://git-scm.com/downloads'
check 'gh' 'gh auth status' 'gh --version' 'installed, but not logged in: run gh auth login' 'https://cli.github.com/'
check 'node' "node -e 'process.exit(+process.versions.node.split(\".\")[0] < 20)'" 'node --version' 'installed, but older than 20: install Node.js 20 or newer' 'https://nodejs.org/en/download'
check 'npm' 'npm --version' 'npm --version' 'installed, but it does not run' 'https://docs.npmjs.com/downloading-and-installing-node-js-and-npm'
if [ "$bad" -eq 0 ]; then echo "All set: every tool is ready."; else echo "$bad tool(s) need attention. Install or fix them, then run this check again."; fi
3. Clone the reference repo
The finished design for the example company. You copy the check from it and compare your files with it; you never push to it.
mkdir -p ~/platformengr && git clone -q https://github.com/platformengr/platform-fundamentals.git ~/platformengr/platform-fundamentals
Check that it arrived. You should see README.md, agents, capabilities.yaml, docs, golden-paths, metrics, package.json, plan, platform.yaml, scripts and teams.yaml:
ls ~/platformengr/platform-fundamentals
4. Create your repo
Your repo: the platform team's design. Public, so the lab checks on this site can read it.
cd ~/platformengr && gh repo create YOUR_GITHUB_USER/platform-design --public --clone
Go into it and copy the check in: the package file with its one dependency (a YAML parser, pinned), its lock file, the list of files Git ignores, the script and the workflow.
cd ~/platformengr/platform-design && git switch -C main && mkdir -p scripts .github/workflows
cp ~/platformengr/platform-fundamentals/package.json ~/platformengr/platform-fundamentals/package-lock.json ~/platformengr/platform-fundamentals/.gitignore . && cp ~/platformengr/platform-fundamentals/scripts/check.mjs scripts/ && cp ~/platformengr/platform-fundamentals/.github/workflows/check.yaml .github/workflows/
5. Run the check
Install the parser from the lock file, then run the check on a repo with no design in it yet.
npm ci installs exactly what package-lock.json says. --ignore-scripts means no package may run code while it installs.
npm ci --ignore-scripts
Run the check. Expect eight lines that start with - and end in not written yet, one per part of the design, and then Nothing written yet. The check is ready.
npm run check
6. Push, and watch the check on GitHub
The same check runs on every push to main and on every pull request. The course page offers Connect your repo after this step: it adds a small workflow so this site can read your progress.
git add -A && git commit -qm "The design check" && git push -qu origin main
Give GitHub half a minute, then look at the latest run. Expect completed and success in the first two columns, with the workflow name design-check. If it says in_progress, run it again.
gh run list --workflow design-check --limit 1
Simplified for the course
The example company is small: five teams and twelve capabilities. A real map has more, and it grows with the platform.
The check tests the shape of a design and a few principles. It cannot tell whether a design is right for your company. That is what reviews with your users are for, and what each module practises.
You push to
mainuntil module 07. A platform team's design repo usually protectsmainand takes every change as a pull request, with the check required.
Break it on purpose: Pushed without running the check
You start on the platform description straight away, type it in a hurry and push it before going to lunch. You did not run the check, because "it is only YAML". Do this one, fix included: the next steps build on what the fix leaves in your repo.
You practise: reading a failed check on GitHub, and getting main green again.
1. Break it
Create platform.yaml
name: Internal developer platform
mission: Product teams ship safely without waiting
git add -A && git commit -qm "Start the platform description" && git push -q
2. What you see
Give GitHub half a minute. Expected: completed success. You get: completed failure from gh run list --workflow design-check --limit 1.
To see why, print the log of the failed step: gh run view --log-failed. Look for a line with [Y1].
3. Fix it yourself
Get main green again. Done when gh run list --workflow design-check --limit 1 shows success and npm run check on your laptop prints Nothing written yet. The check is ready. again.
Hint 1
[Y1] means the file is not valid YAML, so nothing else could be checked. Which line does the message point at?
Hint 2
The second line starts with two spaces, so YAML reads it as part of the first. You write platform.yaml properly in module 01; for now, take it out of the repo.
The fix
Fixing the indentation would also make the YAML valid, and the check would then fail on the rules for a platform description (P1 to P6). That is the point of the check: it says what is missing before a reviewer has to.
git rm -q platform.yaml
npm run check
git commit -qm "Remove the unfinished platform description" && git push -q
gh run list --workflow design-check --limit 1
After you fixed it: the five questions
- What failed?
- The design check on
main. The file could not even be parsed. - How was it detected?
- By the workflow on GitHub, on the push, within a minute.
- Who responds?
- The person who pushed: here the platform team.
- How is it corrected?
- Run the check on your laptop, correct or remove the file, push again.
- How is it prevented?
- Run
npm run checkbefore every push. In a team: protectmain, take changes by pull request, and make the check required.
Quiz
- What does the design check do with the files in your repo?
- It deploys the platform they describe to a test cluster and reports what failed
- It reads them as data and reports every rule they break, without running anything from the repo
- It sends them to the course site, which grades them and returns a score
- Why does
npm ci --ignore-scriptsmatter here?- It installs exactly the versions in the lock file and lets no package run code while installing
- It installs the newest version of every dependency so the check has the latest rules
- It skips installing dev dependencies so the install is faster on a laptop
- Why keep a platform design in Git rather than in a slide deck?
- Git can render the design as diagrams automatically for leadership
- Slide decks cannot hold tables, and a capability map needs one
- Every change is a reviewable diff with a history, and a check can test it on every pull request
Answers
- It reads them as data and reports every rule they break, without running anything from the repo The check only parses YAML and Markdown; the same is true of the lab checks on this site.
- It installs exactly the versions in the lock file and lets no package run code while installing
npm cifollows the lock file;--ignore-scriptsblocks install scripts, a common way for a bad package to run code. - Every change is a reviewable diff with a history, and a check can test it on every pull request The design is then versioned, reviewed and tested like the rest of the platform.
Field note
The first thing I ask a platform team is "who is your platform for, and what will it not do?" Most teams can answer the first half in a meeting. Almost none can point to where it is written down. The ones that can are the ones that still agree with each other six months later.