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

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

📇 धडा 04 — Service catalog: प्रत्येक वर्गखोलीची नोंदवही

📍 तुम्ही इथे आहात: 12 पैकी धडा 04 · मागे: lesson-03-golden-paths · पुढे: lesson-05-self-service-infra

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

धडे 01–03, आणि service catalog: प्रत्येक service आणि resource ची एक नोंदवही, तिचा मालक कोण, आणि ती कशावर अवलंबून आहे. त्यावरून पहाटे 3 वाजता महत्त्वाच्या असलेल्या प्रश्नांची उत्तरे मिळतात: मी कोणाला फोन करू, हे बंद पडले तर आणखी काय बंद पडते, आणि कोणत्या services चा आता कोणीच मालक नाही. idp/office.py मधले Catalog, idp/demo.py मधले catalog() आणि school_catalog().

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

शाळेचे कार्यालय प्रत्येक खोलीची एक नोंदवही 📇 ठेवते: "खोली 12 — विज्ञान प्रयोगशाळा — मालक विज्ञान विभाग — गॅसची लाइन आणि आपत्कालीन दार लागते."

एका सकाळी गॅसची लाइन बिघडते. कोणावर परिणाम होतो? दीपिका नोंदवही उघडते आणि "लागते" चे बाण उलटे फिरते: विज्ञान प्रयोगशाळेला गॅसची लाइन लागते, आणि पालकांच्या open day ला विज्ञान प्रयोगशाळा लागते. म्हणजे एक नाही, तर दोन गोष्टी अडचणीत आहेत.

मग तिला दोन विचित्र नोंदी सापडतात. canteen orders खोलीचा मालक "2019 hackathon team" असे लिहिले आहे. ती team वर्षांपूर्वीच विखुरली. fees खोलीला मालकच नाही. या अनाथ खोल्या आहेत: अजूनही वापरात असलेल्या पण कोणीच न सांभाळणाऱ्या. तिथे काही बिघडले तर कोणालाच फोन जात नाही.

आणि fees खोली म्हणते की तिला "payments office" लागते — पण नोंदवहीत payments office नावाचे काहीच नाही. हा एक तुटलेला संदर्भ आहे: एकतर ते हरवले आहे, किंवा टीप चुकीची आहे.

🗺️ आकृती

flowchart LR
    pp["parent-portal<br/>maths"] --> er["exam-results<br/>science"]
    pp --> tt["timetable<br/>maths"]
    er --> db[("results-db<br/>science")]
    er --> auth["auth<br/>facilities-office"]
    tt --> auth
    co["canteen-orders<br/>⚠️ team-2019-hackathon"] --> auth
    fe["fees<br/>⚠️ no owner"] --> auth
    fe -.-> pay["❓ payments-api<br/>not in the catalog"]
    ls["library-search<br/>library"] -.-> si["❓ search-index<br/>not in the catalog"]

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

❓ काय

Service catalog — software components, त्यांची metadata आणि त्यांचे संबंध यांची एक मध्यवर्ती यादी. बहुतेक developer portals चे हे हृदय आहे (Backstage चा Software Catalog, Port, Cortex, OpsLevel).
catalog-info.yaml — Backstage ची पद्धत: प्रत्येक repo मध्ये, code च्या शेजारी, entity चे वर्णन करणारी एक YAML file. Catalog या files वाचतो, म्हणून नोंदवही ती ज्याचे वर्णन करते त्याच्या जवळ राहते.
Entity kinds — Backstage इतरांबरोबर Component (service, website, library), Resource (database, bucket, queue), API, System, Domain, Group आणि User वापरतो. हा lab Component आणि Resource वापरतो.
Owner — spec.owner: entity साठी जबाबदार group. "मी कोणाला फोन करू?" याचे हे उत्तर आहे. Owner ही एक व्यक्ती नसून team असावी, म्हणजे सुट्ट्या आणि नोकरी बदल यातून ती टिकते.
Lifecycle — Backstage च्या उदाहरणांमध्ये experimental, production किंवा deprecated. वाचणाऱ्यांना ते सांगते की त्यावर किती विश्वास ठेवायचा आणि किती अवलंबून राहायचे.
Dependencies — spec.dependsOn: या entity ला काय लागते. उलटे फिरले की ते blast radius देतात: एक गोष्ट बंद पडली तर बंद पडू शकणारे सगळे.
Orphan (या lab मध्ये) — owner नसलेली entity, किंवा ज्याचा owner group आता अस्तित्वात नाही अशी. ⚠️ Backstage स्वतः "orphan" हा शब्द वेगळ्या गोष्टीसाठी वापरतो: अशी entity जिला तिचे source location आता तयार करत नाही (तिच्यावर backstage.io/orphan: 'true' ही annotation लावलेली असते). शब्द एकच, समस्या वेगळी — दोन्ही साफ करायला हव्यात.
Broken reference — dependsOn catalog ला माहीत नसलेल्या गोष्टीकडे निर्देश करतो.

🤔 का

कारण मोठ्या संस्थेत incident च्या वेळी सर्वात महागडा प्रश्न असतो "हे कोणाचे आहे?". Catalog नसेल तर उत्तर chat च्या इतिहासात आणि लोकांच्या डोक्यात राहते. Catalog असेल तर ते फक्त शोधणे असते. या कोर्समधल्या पुढच्या जवळजवळ सगळ्या गोष्टींचा पाया सुद्धा catalog आहे: scorecards (धडा 10) catalog नोंदींना गुण देतात, portal (धडा 12) त्यावर बांधले जाते, आणि policies (धडा 09) प्रत्येक service ला owner असणे बंधनकारक करू शकतात.

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

idp/office.py मधले Catalog(groups) catalog-info.yaml सारख्या आकाराच्या नोंदी ठेवते: kind, name, owner, lifecycle, depends_on. owned_by(group) एका group च्या नोंदींची यादी देते; orphans() ज्यांचा owner नाही किंवा माहीत असलेला group नाही अशा नोंदी शोधते; broken_refs() catalog मध्ये नसलेली depends_on नावे शोधते; आणि dependents(name) dependency चे बाण उलटे, साखळ्या पकडत फिरते आणि blast radius देते. idp/demo.py मधले school_catalog() शाळेच्या 8 नोंदी बनवते.

🧪 करून पाहा

python3 idp/demo.py catalog
python3 - <<'EOF'
import sys; sys.path.insert(0, "idp"); from demo import school_catalog
c = school_catalog()
print("if timetable breaks:", c.dependents("timetable"))
print("if exam-results breaks:", c.dependents("exam-results"))
c.register("Component", "canteen-orders", "facilities-office", lifecycle="experimental", depends_on=["auth"])   # adopted
c.register("Resource", "search-index", "library")                                                                # declared
print("orphans now:", c.orphans(), "· broken references now:", c.broken_refs())
print("library owns:", c.owned_by("library"))
EOF

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

catalog हे छापते:

── the catalog holds 8 entries owned by groups ['science', 'maths', 'library', 'facilities-office']
   science            owns ['exam-results', 'results-db']
   orphans (no owner, or the owner group is gone): ['canteen-orders', 'fees']
   broken references: [('fees', 'payments-api'), ('library-search', 'search-index')]
── blast radius — if auth breaks, these depend on it: ['canteen-orders', 'exam-results', 'fees', 'parent-portal', 'timetable']
   if results-db breaks: ['exam-results', 'parent-portal']

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

if timetable breaks: ['parent-portal']
if exam-results breaks: ['parent-portal']
orphans now: ['fees'] · broken references now: [('fees', 'payments-api')]
library owns: ['library-search', 'search-index']

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

results-db चा थेट user एकच आहे, exam-results, पण तिचा blast radius दोन आहे: parent-portal हे exam-results वर अवलंबून आहे, म्हणून त्यालाही फटका बसतो. साखळी फिरणे महत्त्वाचे आहे. auth हा शाळेतला सर्वात जास्त वाटून घेतलेला भाग आहे — 5 नोंदी त्यावर अवलंबून आहेत — आणि म्हणूनच त्याचा मालक सुविधा कार्यालय आहे. आणि नोंदवही जाहीर करून नाही, तर करून सुधारते: एका adoption ने canteen चे अनाथपण दूर केले, एका जाहीर केलेल्या resource ने एक तुटलेला संदर्भ दुरुस्त केला. fees अजूनही तुटलेल्या संदर्भासह अनाथ आहे — हेच पुढचे काम.

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

एकदा हाताने भरलेला आणि कधीच अद्ययावत न केलेला catalog — त्याऐवजी file प्रत्येक repo मध्ये ठेवा
groups ऐवजी व्यक्ती असलेले owners ("Aishwarya") — प्रत्येक नोकरी बदलाबरोबर ते जुने होतात
कोणत्याच dependencies जाहीर केलेल्या नाहीत, म्हणून blast radius नेहमी "कोणीच नाही"
catalog ला scorecards आणि policy वापरत असलेला data न मानता फक्त documentation मानणे
orphans आणि broken references चा नियमित अहवाल नाही — ते फक्त वाढत जातात

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

exam-results साठी खरी Backstage catalog-info.yaml, तिच्या repo च्या root वर ठेवलेली:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: exam-results
  description: Publishes exam results to students and parents
  annotations:
    github.com/project-slug: school/exam-results
spec:
  type: service
  lifecycle: production
  owner: group:science
  dependsOn:
    - resource:results-db
    - component:auth

Backstage अशा files त्याच्या app-config.yaml मधल्या catalog.locations मधून, किंवा संस्थेच्या repositories scan करणाऱ्या discovery provider मधून शोधतो. खऱ्या instance वर, catalog REST API मालकीच्या प्रश्नांची थेट उत्तरे देतो:

curl -s "https://backstage.school.example/api/catalog/entities/by-query?filter=spec.owner=group:default/science" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.items[].metadata.name'

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: incident च्या वेळी योग्य लोकांपर्यंत पोहोचण्याचा सर्वात जलद मार्ग म्हणजे catalog. "अस्तित्वात असलेला owner आहे" हा एक नियम (धडा 09) आणि एक scorecard check (धडा 10) बनवा, फक्त आशा नाही.

⏭️ पुढे

भाग 1 पूर्ण झाला: तुम्हाला माहीत आहे का, आधी काय बनवायचे, service कशी सुरू करायची आणि तिचा owner कसा शोधायचा. भाग 2 धडा 02 मधल्या सर्वात मोठ्या त्रासापासून सुरू होतो: ticket शिवाय database मिळवणे.

git checkout lesson-05-self-service-infra

📇 Lesson 04 — The service catalog: the register of every classroom

📍 You are here: Lesson 04 of 12 · Previous: lesson-03-golden-paths · Next: lesson-05-self-service-infra

📦 What's in this branch

Lessons 01–03, plus the service catalog: one register of every service and resource, who owns it, and what it depends on. From that you can answer the questions that matter at 3 a.m.: who do I call, what else breaks if this breaks, and which services nobody owns any more. Catalog in idp/office.py, catalog() and school_catalog() in idp/demo.py.

🧒 Explain like I'm 5

The school office keeps a register 📇 of every room: "Room 12 — science lab — owned by the science department — needs the gas line and the fire exit."

One morning the gas line breaks. Who is affected? Dipika opens the register and follows the "needs" arrows backwards: the science lab needs the gas line, and the parent open day needs the science lab. So two things are in trouble, not one.

Then she finds two strange entries. The canteen orders room says its owner is "the 2019 hackathon team". That team broke up years ago. The fees room has no owner at all. These are orphans: rooms still in use that nobody looks after. If something breaks there, nobody gets the call.

And the fees room says it needs a "payments office" — but there is no payments office in the register. A broken reference: either it is missing, or the note is wrong.

🗺️ Diagram

flowchart LR
    pp["parent-portal<br/>maths"] --> er["exam-results<br/>science"]
    pp --> tt["timetable<br/>maths"]
    er --> db[("results-db<br/>science")]
    er --> auth["auth<br/>facilities-office"]
    tt --> auth
    co["canteen-orders<br/>⚠️ team-2019-hackathon"] --> auth
    fe["fees<br/>⚠️ no owner"] --> auth
    fe -.-> pay["❓ payments-api<br/>not in the catalog"]
    ls["library-search<br/>library"] -.-> si["❓ search-index<br/>not in the catalog"]

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

❓ What

Service catalog — a central list of software components, their metadata and their relations. It is the heart of most developer portals (Backstage's Software Catalog, Port, Cortex, OpsLevel).
catalog-info.yaml — Backstage's convention: a YAML file in each repo, next to the code, that describes the entity. The catalog reads these files, so the register stays close to the thing it describes.
Entity kinds — Backstage uses Component (a service, website, library), Resource (a database, bucket, queue), API, System, Domain, Group and User, among others. This lab uses Component and Resource.
Owner — spec.owner: the group responsible for the entity. It is the answer to "who do I call?" An owner should be a team, not one person, so it survives holidays and job changes.
Lifecycle — experimental, production or deprecated in Backstage's examples. It tells readers how much to trust and depend on it.
Dependencies — spec.dependsOn: what this entity needs. Followed backwards, they give the blast radius: everything that may break if one thing breaks.
Orphan (in this lab) — an entity with no owner, or an owner group that no longer exists. ⚠️ Backstage itself uses "orphan" for something else: an entity whose source location no longer produces it (it is marked with the annotation backstage.io/orphan: 'true'). Same word, different problem — both deserve a clean-up.
Broken reference — dependsOn points to something the catalog does not know.

🤔 Why

Because in a big organisation the most expensive question during an incident is "whose is this?". Without a catalog the answer lives in chat history and people's heads. With one, it is a lookup. The catalog is also the base for almost everything later in this course: scorecards (lesson 10) score catalog entries, the portal (lesson 12) is built on it, and policies (lesson 09) can require that every service has an owner.

🔧 How (in this repo)

Catalog(groups) in idp/office.py keeps entries shaped like catalog-info.yaml: kind, name, owner, lifecycle, depends_on. owned_by(group) lists a group's entries; orphans() finds entries whose owner is missing or is not a known group; broken_refs() finds depends_on names the catalog does not hold; and dependents(name) walks the dependency arrows backwards, following chains, to give the blast radius. school_catalog() in idp/demo.py builds the school's 8 entries.

🧪 Try it

python3 idp/demo.py catalog
python3 - <<'EOF'
import sys; sys.path.insert(0, "idp"); from demo import school_catalog
c = school_catalog()
print("if timetable breaks:", c.dependents("timetable"))
print("if exam-results breaks:", c.dependents("exam-results"))
c.register("Component", "canteen-orders", "facilities-office", lifecycle="experimental", depends_on=["auth"])   # adopted
c.register("Resource", "search-index", "library")                                                                # declared
print("orphans now:", c.orphans(), "· broken references now:", c.broken_refs())
print("library owns:", c.owned_by("library"))
EOF

✅ Verify — what you should see

catalog prints:

── the catalog holds 8 entries owned by groups ['science', 'maths', 'library', 'facilities-office']
   science            owns ['exam-results', 'results-db']
   orphans (no owner, or the owner group is gone): ['canteen-orders', 'fees']
   broken references: [('fees', 'payments-api'), ('library-search', 'search-index')]
── blast radius — if auth breaks, these depend on it: ['canteen-orders', 'exam-results', 'fees', 'parent-portal', 'timetable']
   if results-db breaks: ['exam-results', 'parent-portal']

Your snippet prints:

if timetable breaks: ['parent-portal']
if exam-results breaks: ['parent-portal']
orphans now: ['fees'] · broken references now: [('fees', 'payments-api')]
library owns: ['library-search', 'search-index']

🏁 What you just proved

results-db has only one direct user, exam-results, but its blast radius is two: parent-portal depends on exam-results, so it is hit too. Walking the chain matters. auth is the most shared piece in the school — 5 entries depend on it — which is exactly why the facilities office owns it. And the register gets better by doing, not announcing: one adoption fixed the canteen orphan, one declared resource fixed a broken reference. fees is still an orphan with a broken reference — the next job.

⚠️ Common mistakes

a catalog filled once by hand and never updated — keep the file in each repo instead
owners that are people ("Aishwarya") instead of groups — they go stale with every job change
no dependencies declared, so the blast radius is always "nobody"
treating the catalog as documentation only, instead of the data that scorecards and policy use
no regular report of orphans and broken references — they only grow

🏭 In production

A real Backstage catalog-info.yaml for exam-results, kept at the root of its repo:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: exam-results
  description: Publishes exam results to students and parents
  annotations:
    github.com/project-slug: school/exam-results
spec:
  type: service
  lifecycle: production
  owner: group:science
  dependsOn:
    - resource:results-db
    - component:auth

Backstage finds such files through catalog.locations in its app-config.yaml, or through a discovery provider that scans an organisation's repositories. On a real instance, the catalog REST API answers ownership questions directly:

curl -s "https://backstage.school.example/api/catalog/entities/by-query?filter=spec.owner=group:default/science" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.items[].metadata.name'

🏭 Why this matters in production: during an incident, the catalog is the fastest way to the right people. Make "has an owner that exists" a rule (lesson 09) and a scorecard check (lesson 10), not a hope.

⏭️ Next

Part 1 is done: you know why, what to build first, how to start a service and how to find its owner. Part 2 starts with the biggest pain from lesson 02: getting a database without a ticket.

git checkout lesson-05-self-service-infra

← Previousgolden paths Next →self service infra

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