הערה: כאשר חברה מפעילה יותר מ-20 שירותים, מתחילה קטסטרופה שקטה: אף אחד לא יודע מי הבעלים של המיקרוסרוויס, היכן התיעוד שלו, לאילו שירותים הוא מתחבר, או מה מצב הפריסה. מפתח חדש מבלה את השבוע הראשון שלו רק בניסיון להבין מה פרוס בקלאסטר. אנו מיישמים Service Catalog כדי לעצור את הכאוס הזה. הניסיון שלנו מראה: תוך 1–2 שבועות ניתן לקבל קטלוג עובד שמחזיר את ההשקעה על ידי הפחתת זמן האירועים ב-30% והאצת קליטת עובדים חדשים ליומיים. החיסכון מההטמעה מגיע לעשרות אלפי דולרים בשנה.
Service Catalog הוא רישום של כל השירותים הפנימיים, הרכיבים, ה-API, הספריות והצוותים עם מטא-דאטה קריא למכונה ונתוני מצב חיים. במקום לשמור את ארכיטקטורת הקלאסטר בראשים של המהנדסים, מקבלים מקור אמת יחיד שמתעדכן אוטומטית. אנו משתמשים ב-Backstage — האפשרות היחידה הבוגרת בקוד פתוח לקטלוגי שירותים ארגוניים, הנתמכת באופן פעיל על ידי CNCF.
מדוע המשבר פוגע ללא קטלוג?
בחברות ללא קטלוג, הידע על התשתית מפוזר בצורה כאוטית: מישהו זוכר שירות X כי הוא כתב אותו לפני שלוש שנים. מישהו יודע שגרסת ספרייה מסוימת נמצאת בשימוש בפרודקשן כי הוא היה מעורב באירוע. מהנדס DevOps חדש לא יכול לענות על השאלה "כמה שירותים משתמשים ב-Redis?" ללא חיפוש ידני במאגרי הקוד. בזמן אירוע, זה הופך קריטי: payments-service נופל, צריך לקבוע מי בתורנות, מהן התלויות ומה ה-runbook. ללא רישום מאוחד, זמן התגובה גדל — אנשים ממהרים לשלוח הודעות לעמיתים ב-Slack. ה-Service Catalog שלנו מצמצם את זה לכמה קליקים.
כיצד Backstage פותר את בעיית "הידע בראשים"?
Backstage כתוב ב-TypeScript, יש לו מערכת אקולוגית ענקית של תוספים, והוא נפרס פי 5 מהר יותר מפתרונות ביתיים. הישות המרכזית היא catalog-info.yaml לצד קוד השירות. Backstage סורק את מאגרי הקוד ובונה גרף תלויות מהקבצים האלה:
דוגמה ל-catalog-info.yaml
```yaml apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: order-service description: Order management service tags: - nodejs - kafka - postgresql annotations: gitlab.com/project-slug: backend/order-service backstage.io/kubernetes-id: order-service pagerduty.com/service-id: P1ABC23 prometheus.io/rule: order_service backstage.io/techdocs-ref: dir:. spec: type: service lifecycle: production owner: group:order-team system: commerce dependsOn: - component:postgresql-orders - component:kafka-cluster - component:inventory-service providesApis: - order-api-v2 ```Backstage קורא את הקובץ הזה, רושם את השירות, ובונה אוטומטית גרף תלויות. בעמוד order-service רואים: בעלים, תורנות, מצב Kubernetes (פודים רצים/נכשלים), קומיטים אחרונים מ-GitLab, לוח מחוונים של Grafana, ותיעוד.
מה אנחנו בעצם בונים בקטלוג?
מלאי רכיבים. כל שירות, ספרייה, מסד נתונים, תור — הכל הופך לישות עם סוג (service, library, database, queue, api). עבור מאגרי קוד קיימים, אנו משתמשים בספקי הישויות של Backstage — GitHub Discovery, GitLab Discovery סורקים אוטומטית קבוצות ויוצרים רשומות.
גרף תלויות. Backstage בונה גרף תלויות ויזואלי המבוסס על dependsOn ו-consumesApis/providesApis. זהו הכלי הראשון שמראה את רדיוס הפיצוץ: אם inventory-service נופל, אילו שירותים מושפעים.
בעלות וצוותים. Backstage תומך בישויות Group ו-User, ומסנכרן מ-LDAP, Okta, GitHub Teams. לכל רכיב יש בעלים — צוות או מהנדס. בזמן אירוע, רואים מיד מי אחראי.
קטלוג API. עבור REST API — מפרט OpenAPI ישירות ב-Backstage עם ממשק משתמש לניווט. מפתחים מוצאים את ה-API הדרושים ללא חיפושים מייגעים ב-Confluence. Backstage תומך ב-OpenAPI, AsyncAPI (ל-Kafka/אירועים), ו-GraphQL schema.
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
name: order-api-v2
description: REST API для управления заказами
spec:
type: openapi
lifecycle: production
owner: group:order-team
definition:
$text: https://gitlab.company.com/backend/order-service/-/raw/main/openapi.yaml
---TechDocs: תיעוד לצד הקוד
Backstage TechDocs — MkDocs מובנה בקטלוג. מפתחים כותבים apiVersion: backstage.io/v1alpha1 kind: API metadata: name: order-api-v2 description: REST API для управления заказами spec: type: openapi lifecycle: production owner: group:order-team definition: $text: https://gitlab.company.com/backend/order-service/-/raw/main/openapi.yaml לצד הקוד, ו-Backstage מציג אותם בעמוד הרכיב. התיעוד מגיע עם גרסאות יחד עם הקוד ותמיד עדכני.
---
# mkdocs.yml в корне репозитория
site_name: Order Service
nav:
- Обзор: index.md
- Архитектура: architecture.md
- API: api.md
- Runbook: runbook.md
- ADR: adr/
---
זה פותר את בעיית תיעוד ה-Confluence המיושן: אם הקוד משתנה, המפתח מעדכן את התיעוד באותו PR.
תוכנית הטמעת Service Catalog שלב אחר שלב
אנו מבצעים את העבודה במספר שלבים, ומבטיחים תוצאות תוך שבוע:
- התקנה ואינטגרציה. אנו מקימים את Backstage, אימות (Okta/GitHub SSO), מחברים את GitLab/GitHub לסריקה אוטומטית של מאגרי קוד. שבוע ראשון.
- תוספים מרכזיים. אנו מוסיפים Kubernetes (מצב פודים), Grafana (לוחות מחוונים), PagerDuty (תורנות). הצוות מקבל ערך מיידי. שבוע שני.
- מילוי הקטלוג. אנו מוסיפים
docs/למאגרי קוד קיימים. יוצרים ישויות Group ו-User. מתארים את גרף התלויות, מוסיפים ישויות API. שבוע שלישי עד רביעי. - אימות CI. אנו בודקים
# mkdocs.yml в корне репозитория site_name: Order Service nav: - Обзор: index.md - Архитектура: architecture.md - API: api.md - Runbook: runbook.md - ADR: adr/בצנרת באמצעות Backstage CLI — אם הקובץ לא תקין, ה-PR לא מתמזג. זה מונע הידרדרות של הקטלוג.
---
# .gitlab-ci.yml — валидация catalog-info.yaml
validate-catalog:
image: node:18
script:
- npx @backstage/cli catalog validate --config catalog-info.yaml
only:
changes:
- catalog-info.yaml
מה כלול בעבודה?
- פריסת Backstage על Kubernetes (Helm chart) עם יתירות.
- אינטגרציה עם GitLab/GitHub, PagerDuty, Grafana, Prometheus.
- יצירת תבניות עבור
catalog-info.yamlותיעוד ADR. - הכשרת הצוות (1–2 סדנאות) וכתיבת runbook.
- תמיכה בשלב המילוי: עזרה במילוי מטא-דאטה.
השוואת פתרונות: Backstage מול קטלוג ביתי
| קריטריון | Backstage | קטלוג ביתי |
|---|---|---|
| זמן פריסה | 1–2 ימים | 2–4 שבועות |
| אינטגרציות | 100+ תוספים | בנייה מאפס |
| תמיכת CNCF | כן | לא |
| תיעוד | TechDocs מובנה | פתרון נפרד |
| קהילה | 10k+ כוכבים ב-GitHub | אין |
Backstage עולה על פתרונות ביתיים פי 5 במהירות הפריסה ויש לו מערכת אקולוגית מוכנה לניהול APIs, תיעוד ותלויות.
מדוע קטלוגים מתדרדרים ואיך מונעים זאת?
ללא שני דברים, Service Catalog הופך ל"בית קברות של YAML": בעל פלטפורמה שמבטיח עדכניות, ודרישה לרשום שירותים חדשים לפני פריסה. אנו מטמיעים שער איכות ב-CI: אם רכיב לא רשום ב-Backstage, הפריסה לסטייג'ינג נחסמת. קפדני אבל יעיל. בנוסף, אנו מגדירים בדיקות אוטומטיות למטא-דאטה מיושן ומבצעים ביקורות תקופתיות.
במשך יותר מ-5 שנים אנו מיישמים פתרונות DevOps, ומשלימים 50+ פרויקטים של ניהול תשתית. המהנדסים המוסמכים שלנו מבטיחים שהקטלוג יהיה כלי חי, לא תצוגה סטטית. צרו קשר לקבלת ייעוץ על הטמעת קטלוג. נבצע הערכה של הפרויקט שלכם תוך יום אחד — פשוט ציינו את מספר השירותים והכלים הנוכחיים, ואנו נציע תוכנית הטמעה.
| היקף | לוח זמנים | היקף העבודה |
|---|---|---|
| עד 20 שירותים | 1–2 שבועות | פריסה, אינטגרציות, תבניות |
| 20–60 שירותים | 3–6 שבועות | + מילוי, הכשרה, אימות CI |
| 60+ שירותים | 2–3 חודשים | + רפקטורינג מורשת, העברת תיעוד |