🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🛤️ धडा 03 — सोनेरी वाट आणि templates: तयार वर्ग-संच

📍 तुम्ही इथे आहात: 12 पैकी धडा 03 · मागे: lesson-02-platform-as-product · पुढे: lesson-04-service-catalog

📦 या ब्रँचमध्ये काय आहे

धडे 01–02, आणि पहिला संच: एक सोनेरी वाट (golden path). एक scaffolder version असलेल्या template मधून नवी service बनवतो — code, tests, Dockerfile, pipeline, deployment values, docs आणि catalog नोंद — आणि चुकीचे input कसे दुरुस्त करायचे ते सांगणाऱ्या message सह नाकारतो. idp/office.py मधले TEMPLATES आणि Scaffolder, idp/demo.py मधले goldenpath().

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

कतरिनाला तिच्या नव्या विज्ञान मंडळासाठी एक वर्गखोली हवी आहे. ती सुविधा कार्यालयात जाते आणि म्हणते: "एक वर्ग-संच द्या. नाव: exam-results. मालक: science."

दीपिका फळीवरून एक संचाची पेटी काढते. 📦 लेबलवर लिहिले आहे "python-service, version 3". आत 8 गोष्टी आहेत, आधीच एकमेकांना जोडलेल्या: बाके (code), धुराचा alarm (tests), कुलूप असलेले दार (Dockerfile), वेळापत्रकातला तास (pipeline), खोलीचा आराखडा (deploy values), सूचना फलक (docs) आणि शाळेच्या नोंदवहीसाठी नावाचे कार्ड (catalog नोंद).

कतरिनाची मैत्रीण आधी "Exam Results!" हे नाव देऊन पाहते. दीपिका फक्त नाही म्हणत नाही. ती म्हणते: "नावे लहान अक्षरांत, डॅश लावून असतात — exam-results वापरून पाहा." दुसरी शिक्षिका आपला विभाग "sciense" असा लिहिते. दीपिका म्हणते: "हा group मला माहीत नाही — तुम्हाला यापैकी एखादा म्हणायचा होता का?"

संच हा सोपा मार्ग आहे, एकमेव मार्ग नाही. शिक्षिका आपली खोली पुन्हा रंगवू शकते. पण मग रंगाची काळजी तिला स्वतःलाच घ्यावी लागते.

🗺️ आकृती

flowchart LR
    k["👩‍🏫 Katrina<br/>template: python-service<br/>name: exam-results<br/>owner: science"] --> c{"✅ checks<br/>name rule · name free ·<br/>owner is a group ·<br/>template exists"}
    c -->|"refused"| f["💬 'use lowercase and dashes,<br/>e.g. exam-results'"]
    c -->|"ok"| t["📦 python-service v3"]
    t --> r["🗂️ 8 files<br/>src · tests · Dockerfile ·<br/>ci.yml · values.yaml ·<br/>docs · catalog-info.yaml"]
    r --> g["🚀 push → the paved<br/>pipeline runs"]

🗺️ काढलेली आकृती + एक lab: https://school-edh.pages.dev/platform-engineering/lesson-diagrams.html#l03

❓ काय

Golden path (सोनेरी वाट) — एखादी सामान्य गोष्ट (Java service, data pipeline) बनवण्याच्या आधार असलेल्या, ठाम मते असलेल्या, चांगल्या documentation असलेल्या मार्गाला Spotify ने दिलेले नाव. Netflix याच कल्पनेला paved road म्हणते. ही tooling चा आधार असलेली शिफारस आहे, नियम नाही.
Template — placeholders ({{name}}, {{owner}}) असलेला project चा सांगाडा, जे नवी service बनवताना भरले जातात. Templates मध्ये कार्यालयाचे defaults असतात: base image, pipeline, resource limits, health checks, docs.
Scaffolder — template भरणारे, input तपासणारे आणि repository बनवणारे tool. उदाहरणे: Backstage Software Templates (parameters आणि steps असलेली एक Template entity), cookiecutter आणि Yeoman (local generators).
Template versioning — template ला स्वतःची versions असतात (इथे v3). v3 मधून बनलेली service तिला जे मिळाले ते ठेवते; नंतर template सुधारल्याने अस्तित्वात असलेल्या services आपोआप बदलत नाहीत. त्यांना अद्ययावत ठेवणे हे वेगळे काम आहे (धडा 07 pipelines साठी एक मार्ग दाखवतो, धडा 10 कोण मागे आहे ते मोजतो).
दुरुस्तीसह validation — प्रत्येक नकार काय चुकले आणि काय करायचे ते सांगतो. stack trace देऊन अपयशी होणारा template कोणालाच काही शिकवत नाही.
Day 1 विरुद्ध day 2 — day 1 म्हणजे service बनवणे; day 2 म्हणजे त्यानंतरचे सगळे (upgrades, patches, नवे नियम). फक्त day 1 ला मदत करणारी सोनेरी वाट ही अर्धीच वाट आहे.

🤔 का

कारण नव्या service चा पहिला तास बरेच काही ठरवतो: तिच्यात tests, health check, resource limits, owner, security scan असलेली pipeline आहे की नाही. प्रत्येक team कोऱ्या पानापासून सुरू झाली तर प्रत्येक team ला यातला वेगळाच भाग मिळतो. Template मुळे चांगले defaults हीच सर्वात सोपी गोष्ट बनते. त्यामुळे services सारख्या दिसतात, म्हणजे कोणताही engineer कोणत्याही repo मध्ये रस्ता शोधू शकतो — आणि platform नंतर त्यातल्या अनेक services एकाच पद्धतीने सुधारू शकतो.

🔧 कसे (या repo मध्ये)

idp/office.py मधल्या TEMPLATES मध्ये दोन templates आहेत: python-service (v3, 8 files) आणि static-site (v1, 3 files). Scaffolder(templates, groups, taken) ला templates, खरे groups आणि आधीच वापरात असलेली नावे माहीत असतात. check() सगळ्या अडचणी एकदमच परत देते, प्रत्येकीसोबत दुरुस्ती; create() {{name}}, {{owner}} आणि {{version}} भरते आणि {path: content} परत देते. नावांसाठी एकच नियम: 3–31 लहान अक्षरे, अंक किंवा डॅश, सुरुवात अक्षराने. तयार झालेल्या ci.yml मध्ये pipeline नसते — ती कार्यालयाची सामायिक pipeline बोलावते (धडा 07).

🧪 करून पाहा

python3 idp/demo.py goldenpath
python3 - <<'EOF'
import sys; sys.path.insert(0, "idp"); from office import Scaffolder, TEMPLATES
sc = Scaffolder(TEMPLATES, ["science", "maths", "library"], taken={"timetable"})
for args in (("static-site", "open-day", "maths"), ("static-site", "open-day", "maths"), ("python-service", "x", "library")):
    ok, out = sc.create(*args)
    print(args, "→", sorted(out) if ok else out)
ok, files = sc.create("python-service", "book-returns", "library")
print(files["README.md"].splitlines()[1])
print(files[".github/workflows/ci.yml"].splitlines()[-1].strip())
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

goldenpath हे छापते (आधी नकार, मग संच):

── create ('python-service', 'Exam Results!', 'science') → refused:
   • name 'Exam Results!' — use 3–31 lowercase letters, digits or dashes, starting with a letter, e.g. 'exam-results'
── create ('python-service', 'timetable', 'sciense') → refused:
   • name 'timetable' is taken — pick another, or ask its owner in the catalog
   • owner 'sciense' is not a known group — choose one of: facilities-office, library, maths, science
── Katrina creates 'exam-results' from python-service v3 → 8 files, ready to push:

तुमचा snippet हे छापतो:

('static-site', 'open-day', 'maths') → ['README.md', 'catalog-info.yaml', 'site/index.html']
('static-site', 'open-day', 'maths') → ["name 'open-day' is taken — pick another, or ask its owner in the catalog"]
('python-service', 'x', 'library') → ["name 'x' — use 3–31 lowercase letters, digits or dashes, starting with a letter, e.g. 'my-new-service'"]
Owned by library. Made from the python-service template v3.
uses: school/paved-road/.github/workflows/python.yml@v2

🏁 तुम्ही आत्ताच काय सिद्ध केले

एकच विनंती दोनदा केली तर दोन उत्तरे मिळतात: पहिले open-day बनते, दुसरे नाकारले जाते कारण ते नाव आता घेतलेले आहे — scaffolder लक्षात ठेवतो. एका विनंतीतल्या दोन चुकांना दोन messages एकदमच मिळतात, म्हणजे शिक्षिका दोन्ही एकाच वेळी दुरुस्त करते. आणि नवी service pipeline ची copy करत नाही; ती @v2 वरच्या कार्यालयाच्या सामायिक pipeline कडे निर्देश करते, म्हणजे त्या pipeline मधली नंतरची दुरुस्ती तिच्यापर्यंत पोहोचू शकते (धडा 07). प्रत्येक file सांगते की ती कोणत्या template आणि version ने बनवली.

⚠️ नेहमीच्या चुका

कोणाच्याच मालकीचे नसलेले templates — ते सडतात, आणि नव्या services मागच्या वर्षीच्या अडचणींसह सुरू होतात
"fire and forget": जुन्या template versions मधून बनलेल्या services अद्ययावत करण्याचा कोणताच आराखडा नाही
एकाच template मध्ये प्रत्येक पर्याय घालत राहणे, जोपर्यंत तो कोऱ्या पानापेक्षा वापरायला अवघड होत नाही
दुरुस्ती न सांगणारे नकार ("invalid input") — मग लोक त्याऐवजी जुन्या repo ची copy करतात
template हाच एकमेव परवानगी असलेला मार्ग, खरी गरज असलेल्या team साठी जागा नाही

🏭 प्रत्यक्ष वापरात

खऱ्या Backstage instance वरचा Backstage Software Template ही एक YAML entity असते. एक छोटा template — दोन प्रश्न विचारा, सांगाडा भरा, repo publish करा, catalog मध्ये नोंदवा:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: python-service
  title: Python service (golden path)
spec:
  owner: facilities-office
  type: service
  parameters:
    - title: About the service
      required: [name, owner]
      properties:
        name:
          type: string
          pattern: '^[a-z][a-z0-9-]{2,30}$'
        owner:
          type: string
          ui:field: OwnerPicker
  steps:
    - id: fetch
      action: fetch:template
      input: {url: ./skeleton, values: {name: '${{ parameters.name }}', owner: '${{ parameters.owner }}'}}
    - id: publish
      action: publish:github
      input: {repoUrl: 'github.com?owner=school&repo=${{ parameters.name }}'}
    - id: register
      action: catalog:register
      input: {repoContentsUrl: '${{ steps.publish.output.repoContentsUrl }}', catalogInfoPath: /catalog-info.yaml}

Backstage नसेल तर cookiecutter day-1 चा भाग local वर करतो:

pip install cookiecutter
cookiecutter gh:school/python-service-template   # asks for name and owner, writes the skeleton

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: किती नव्या services template मधून सुरू होतात ते मोजा. teams त्याऐवजी जुन्या repo ची copy करत असतील तर template अजून सोपी वाट बनलेला नाही — का ते शोधा (धडा 02).

⏭️ पुढे

प्रत्येक संचाने एक catalog-info.yaml बनवली. पुढे: त्या वाचणारी नोंदवही — कशाचा मालक कोण, काय कशावर अवलंबून आहे, आणि कोणत्या वर्गखोल्यांची कोणीच काळजी घेत नाही.

git checkout lesson-04-service-catalog

🛤️ Lesson 03 — Golden paths & templates: a ready classroom kit

📍 You are here: Lesson 03 of 12 · Previous: lesson-02-platform-as-product · Next: lesson-04-service-catalog

📦 What's in this branch

Lessons 01–02, plus the first kit: a golden path. A scaffolder creates a new service from a versioned template — code, tests, Dockerfile, pipeline, deployment values, docs and a catalog entry — and refuses bad input with a message that says how to fix it. TEMPLATES and Scaffolder in idp/office.py, goldenpath() in idp/demo.py.

🧒 Explain like I'm 5

Katrina needs a classroom for her new science club. She goes to the facilities office and says: "One classroom kit, please. Name: exam-results. Owner: science."

Dipika takes a kit box from the shelf. 📦 The label says "python-service, version 3". Inside are 8 things, already fitted together: desks (the code), a smoke alarm (the tests), a door with a lock (the Dockerfile), a timetable slot (the pipeline), a room plan (the deploy values), a notice board (the docs) and a name card for the school register (the catalog entry).

Katrina's friend tries first with the name "Exam Results!". Dipika does not just say no. She says: "Names are lowercase with dashes — try exam-results." Another teacher writes her department as "sciense". Dipika says: "I don't know that group — did you mean one of these?"

The kit is the easy way, not the only way. A teacher may repaint her room. But then she looks after the paint herself.

🗺️ Diagram

flowchart LR
    k["👩‍🏫 Katrina<br/>template: python-service<br/>name: exam-results<br/>owner: science"] --> c{"✅ checks<br/>name rule · name free ·<br/>owner is a group ·<br/>template exists"}
    c -->|"refused"| f["💬 'use lowercase and dashes,<br/>e.g. exam-results'"]
    c -->|"ok"| t["📦 python-service v3"]
    t --> r["🗂️ 8 files<br/>src · tests · Dockerfile ·<br/>ci.yml · values.yaml ·<br/>docs · catalog-info.yaml"]
    r --> g["🚀 push → the paved<br/>pipeline runs"]

🗺️ Drawn version + a lab: https://school-edh.pages.dev/platform-engineering/lesson-diagrams.html#l03

❓ What

Golden path — Spotify's name for the supported, opinionated, well-documented way to build a common kind of thing (a Java service, a data pipeline). Netflix calls the same idea the paved road. It is a recommendation with tooling behind it, not a rule.
Template — a skeleton project with placeholders ({{name}}, {{owner}}) that are filled in when a new service is made. Templates carry the office's defaults: the base image, the pipeline, resource limits, health checks, docs.
Scaffolder — the tool that fills the template, checks the input and creates the repository. Examples: Backstage Software Templates (a Template entity with parameters and steps), cookiecutter and Yeoman (local generators).
Template versioning — the template itself has versions (v3 here). A service made from v3 keeps what it got; improving the template later does not change existing services by itself. Keeping them up to date is a separate job (lesson 07 shows one way for pipelines, lesson 10 measures who is behind).
Validation with a fix — every refusal says what is wrong and what to do. A template that fails with a stack trace teaches nobody.
Day 1 vs day 2 — day 1 is creating the service; day 2 is everything after (upgrades, patches, new rules). A golden path that only helps on day 1 is half a path.

🤔 Why

Because the first hour of a new service decides a lot: whether it has tests, a health check, resource limits, an owner, a pipeline with a security scan. If each team starts from a blank page, each team gets a different subset of those. A template makes the good defaults the easiest thing to do. It also makes services look alike, so any engineer can find their way around any repo — and the platform can improve many of them the same way later.

🔧 How (in this repo)

TEMPLATES in idp/office.py holds two templates: python-service (v3, 8 files) and static-site (v1, 3 files). Scaffolder(templates, groups, taken) knows the templates, the real groups and the names already in use. check() returns every problem at once, each with a fix; create() fills {{name}}, {{owner}} and {{version}} and returns {path: content}. Names follow one rule: 3–31 lowercase letters, digits or dashes, starting with a letter. The generated ci.yml does not contain a pipeline — it calls the office's shared one (lesson 07).

🧪 Try it

python3 idp/demo.py goldenpath
python3 - <<'EOF'
import sys; sys.path.insert(0, "idp"); from office import Scaffolder, TEMPLATES
sc = Scaffolder(TEMPLATES, ["science", "maths", "library"], taken={"timetable"})
for args in (("static-site", "open-day", "maths"), ("static-site", "open-day", "maths"), ("python-service", "x", "library")):
    ok, out = sc.create(*args)
    print(args, "→", sorted(out) if ok else out)
ok, files = sc.create("python-service", "book-returns", "library")
print(files["README.md"].splitlines()[1])
print(files[".github/workflows/ci.yml"].splitlines()[-1].strip())
EOF

✅ Verify — what you should see

goldenpath prints (first the refusals, then the kit):

── create ('python-service', 'Exam Results!', 'science') → refused:
   • name 'Exam Results!' — use 3–31 lowercase letters, digits or dashes, starting with a letter, e.g. 'exam-results'
── create ('python-service', 'timetable', 'sciense') → refused:
   • name 'timetable' is taken — pick another, or ask its owner in the catalog
   • owner 'sciense' is not a known group — choose one of: facilities-office, library, maths, science
── Katrina creates 'exam-results' from python-service v3 → 8 files, ready to push:

Your snippet prints:

('static-site', 'open-day', 'maths') → ['README.md', 'catalog-info.yaml', 'site/index.html']
('static-site', 'open-day', 'maths') → ["name 'open-day' is taken — pick another, or ask its owner in the catalog"]
('python-service', 'x', 'library') → ["name 'x' — use 3–31 lowercase letters, digits or dashes, starting with a letter, e.g. 'my-new-service'"]
Owned by library. Made from the python-service template v3.
uses: school/paved-road/.github/workflows/python.yml@v2

🏁 What you just proved

The same request twice gives two answers: the first open-day is created, the second is refused because the name is now taken — the scaffolder remembers. Two mistakes in one request get two messages at once, so the teacher fixes both in one go. And the new service does not copy a pipeline; it points to the office's shared pipeline at @v2, so a later fix to that pipeline can reach it (lesson 07). Every file says which template and version made it.

⚠️ Common mistakes

templates nobody owns — they rot, and new services start with last year's problems
"fire and forget": no plan for updating services made from old template versions
putting every option into one template until it is harder to use than a blank page
refusals without a fix ("invalid input") — people then copy an old repo instead
a template that is the only allowed way, with no room for a team with a real need

🏭 In production

A Backstage Software Template, on a real Backstage instance, is a YAML entity. A small one — ask two questions, fill a skeleton, publish a repo, register it in the catalog:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: python-service
  title: Python service (golden path)
spec:
  owner: facilities-office
  type: service
  parameters:
    - title: About the service
      required: [name, owner]
      properties:
        name:
          type: string
          pattern: '^[a-z][a-z0-9-]{2,30}$'
        owner:
          type: string
          ui:field: OwnerPicker
  steps:
    - id: fetch
      action: fetch:template
      input: {url: ./skeleton, values: {name: '${{ parameters.name }}', owner: '${{ parameters.owner }}'}}
    - id: publish
      action: publish:github
      input: {repoUrl: 'github.com?owner=school&repo=${{ parameters.name }}'}
    - id: register
      action: catalog:register
      input: {repoContentsUrl: '${{ steps.publish.output.repoContentsUrl }}', catalogInfoPath: /catalog-info.yaml}

Without Backstage, cookiecutter does the day-1 part locally:

pip install cookiecutter
cookiecutter gh:school/python-service-template   # asks for name and owner, writes the skeleton

🏭 Why this matters in production: measure how many new services start from the template. If teams copy an old repo instead, the template is not the easy path yet — find out why (lesson 02).

⏭️ Next

Every kit made a catalog-info.yaml. Next: the register that reads them — who owns what, what depends on what, and which classrooms nobody looks after.

git checkout lesson-04-service-catalog

← Previousplatform as product Next →service catalog

This page is the lesson's README from the lesson-03-golden-paths branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.