Портал розробників & Backstage Vocabulary: 20 Термінів для команд платформи
Архітектура Backstage, каталог програмного забезпечення, TechDocs, шаблони scaffolder, додатки і словник порталу розробників.
Платформа інженерії трансформувала спосіб організації управління внутрішніми інструментами розробників. У центрі цього руху є Backstage — відкритий код, створений Spotify і тепер проект CNCF — разом з більш широкою концепцією порталу розробників. Якщо ви працюєте у команді з розробки платформи або разом з нею, ви зіткнетеся з багатим словником термінів, які рідко з’ являються у стандартних курсах англійської мови з інформаційних технологій. Цей посібник містить 20 основних термінів, а також приклади реальних розмов, які допоможуть вам використовувати їх у повсякденному спілкуванні.
Основні принципи архітектури
** Backstage ** — фреймворк з відкритим кодом для створення внутрішніх порталів розробників. Він надає об’єднаний інтерфейс, де інженери можуть знаходити послуги, читати документацію, створювати нові проекти і відстежувати технічне стан - все в одному місці.
«Ми оцінили Port і Cortex, але в кінцевому підсумку обирали Backstage, тому що екосистема плагінів набагато більша»
«Backstage дало нам одне скло — до того, половина команди навіть не знала, які послуги існують»
** Каталог програмного забезпечення ** — серце Backstage: централізоване сховище всіх компонентів програмного забезпечення, API, систем і команд у вашій організації. Вона відповідає на питання “Що ми володіємо і хто володіє ним?”
Каталог програмного забезпечення нарешті оновлений — кожна служба має власника і посилання на її runbook
«До того, як ми мали каталог, набір займав тиждень, щоб зрозуміти, які репозиторії клонувати»
** Сутність каталогу ** — один елемент, зареєстрований у каталогу програмного забезпечення. Кожна сутність має поле kind, яке класифікує те, що вона представляє. Серед звичайних типів:
- ** Компонент ** — розгортається одиниця, наприклад, мікросервіс, бібліотека або веб- сайт
- ** API ** — опублікований інтерфейс (REST, GraphQL, gRPC або Async)
- ** Система ** — набір пов’ язаних компонентів, які утворюють межу продукту
- ** Домен ** — ділова область високого рівня, що об’ єднує декілька систем
«Ми моделюємо кожну мікросервіс як Компонент, а потім групуємо їх в Систему за продуктовою областю»
Домен платежів містить три системи: касовий апарат, фактури і прирівнювання
catalog-info.yaml — файл манифесту, розташований у кореневому каталогу сховища, який реєструє це сховище як об’ єкт каталогу. Він декларує тип сутності, власника, стадію життєвого циклу, а також посилання на документацію або API.
«Кожне нове сховище повинно включати
catalog-info.yaml— команда платформи не буде вас приймати без нього»
«Я тільки що оновив наш
catalog-info.yaml, щоб позначити службу якlifecycle: deprecated, щоб люди перестали залежати від неї»
Документація і шаблони
** TechDocs ** — вбудований у Backstage розв’ язок для документів як коду. Технічна документація написана на Markdown, живе разом з кодом в тому ж сховищі, і відображається всередині порталу. Фраза * document- as- code * означає, що документація виконує ті ж самі операції, що і код: запити на витягування, перегляди, контроль версій.
«Ми мігрували нашу Confluence wiki до TechDocs минулого кварталу — тепер документи живуть поряд з кодом і залишаються в синхронізованому стані»
«TechDocs означає, що я можу оновити readme і документацію порталу в одному затвердженні.»
** Скаффолдер ** — функція Backstage, яка надає змогу командам платформи визначати і публікувати шаблони проектів, які можна використовувати знову і знову. Розробники заповнюють коротку форму, і scafffolder створює нове сховище, попередньо налаштоване з конвеєрами CI, лінтингом і реєстрацією каталогу.
«Скафольдер скоротив час нашого нового сервісу з двох днів до близько п’ятнадцяти хвилин»
«Ми заблокували шаблони скелетних робіт за кроком схвалення, тому що деякі команди розгортали послуги, не кажучи нікому»
** Шаблон служби ** (також * шаблон золотого шляху *) — шаблон скелета, який кодує бажаний спосіб організації для створення певного типу служби. Це називається * золотий шлях *, тому що він веде інженерів до схваленого, добре підтримуваного підходу, а не дозволяє кожній команді вигадувати свій власний ланцюжок інструментів.
Наш шаблон золотого шляху поставляється з Dockerfile, конвеєром GitHub Actions і панелями Datadog, які вже підключені
Якщо ви хочете створити новий Node.js API, просто використовуйте шаблон золотого шляху — він обробляє всі типові елементи
** Додаток ** — самостійний розширення, яке додає нові функціональні можливості до екземпляра Backstage. Плагіни є основним способом як Spotify, так і спільноти розширити портал. Існує два підтипи:
** Додаток переднього плану ** — компонент інтерфейсу користувача, заснований на React, який відображає нову вкладку, картку або сторінку у веб- програмі Backstage.
«Ми побудували плагін для початку, щоб показати поворот на виклик безпосередньо на сторінці сервісу — більше не потрібно копати через PagerDuty.»
** Додаток сервера ** — розширення на стороні сервера, яке відкриває нові маршрути API, інтегрує з зовнішніми інструментами або обробляє дані перед тим, як вони потрапляють до інтерфейсу користувача.
«Плагін вартості має бекенд, який запитує AWS Cost Explorer кожну годину і кешує результати.»
Власність, якість і прийняття
** Власник сутності ** — призначення команди або групи як відповідальної сторони за сутність каталогу. Власність декларується в catalog-info.yaml через поле spec.owner і використовується для маршрутизації попереджень, фільтрування панелей управління і забезпечення підзвітності.
«Власність суб’єкта є тим, що робить каталог насправді корисним — якщо ніхто не володіє послугою, ніхто не виправляє її, коли вона ламається»
«Ми зробили власника обов’язковим в нашому
catalog-info.yamllint правилі; PR без поля власника блокуються.»
** Технічний радар ** — візуальний інструмент (розроблений ThoughtWorks і інтегрований у Backstage як додаток), який поділяє технології на чотири категорії: * Прийняти *, * Випробувати *, * Оцінити * і * Затримати *. Команди платформи використовують його для того, щоб повідомити, які інструменти затверджені, які оцінюються, а які повинні бути поступово виключені.
Згідно з нашим технічним радаром, Kafka знаходиться в режимі прийняття, а NATS все ще в режимі випробування — використовуйте Kafka для будь-чого, що має критичне значення для виробництва
Перед тим, як вибрати новий інструмент спостережливості, перевірте технічний радар — ми вже маємо Grafana в Adopt
** Scorecard ** — структурований набір перевірок, застосованих до об’ єктів каталогу для вимірювання їх стану і відповідності. Поширені перевірки картки показників включають: чи має служба власника, чи має вона покриття за викликом, чи є її документація актуальною, і чи проходить вона сканування безпеки?
«Наша карта показників не вдалася нам у двох пунктах: відсутній посилання на runbook і не визначено SLO»
Команда платформи надсилає щотижневу суму результатів картки результатів — команди з червоними послугами отримують поштовх, щоб їх виправити
** Метрика прийняття порталу ** — вимірювання, яке використовується для відстеження того, наскільки широко портал розробників використовується у вашій організації. Серед типових показників: відсоток служб, зареєстрованих у каталогу, щотижневі активні користувачі, кількість запусків scafffolder і рівень документації.
«Наша метрика прийняття порталу знаходиться на рівні 68% — близько третини послуг все ще не в каталозі»
«Команда платформи повідомляє про прийняття порталу до керівництва щоквартально; це один з ключових KPI для інженерії платформи»
Як використовувати ці терміни в розмові
Вивчення словникового запасу — це лише половина роботи — інша половина — це знати, коли і як його застосовувати. Ось кілька шаблонів, які інженери платформи використовують регулярно.
Пропозиція роботи:
«Ми повинні підключити плагін вартості до наших каталогів і виставити його як плагін фронтенду на кожній сторінці сервісу»
Пояснюю, як це працює:
“Щоб отримати вашу послугу в каталог, додайте
catalog-info.yaml, встановіть власника і пов’язайте ваші TechDocs. У scaffolder є шаблон міграції, якщо ви хочете почати з першого разу»
** Обговорення воріт якості: **
«Наша карта показників тепер перевіряє на покриття TechDocs і власність суб’єкта — все нижче 80% викликає автоматичне нагадування Slack»
** Говорячи про стандарти: **
«Технічний радар каже, що GraphQL знаходиться в Assess, тому не використовуйте його для нового публічного API без обговорення цього з групою архітектури спочатку»
Отчетность перед руководством:
“Прийняття порталу на 75% в цьому спринті. Наші шаблони золотого шляху скоротили час налаштування нових послуг на 70%, а використання scaffolder подвоїлося після того, як ми додали шаблон Python. “
Таблиця швидких посилань
| Term | In Plain English |
|---|---|
| Backstage | Open-source framework for building an internal developer portal |
| Software catalog | Central registry of all services, APIs, and teams |
| Catalog entity | One item in the catalog (Component, API, System, or Domain) |
| catalog-info.yaml | Manifest file that registers a repo in the catalog |
| TechDocs | Docs-as-code: Markdown documentation rendered inside the portal |
| Scaffolder | Tool for generating new projects from approved templates |
| Golden path template | Pre-approved project blueprint encoding best practices |
| Plugin | Extension that adds new UI or backend functionality to Backstage |
| Scorecard | Automated health checks applied to catalog entities |
| Tech radar | Visual guide to approved, trial, and deprecated technologies |
Завдяки цьому словнику ви зможете більш впевнено робити внесок у роботу команди з розробки платформи, перегляд архітектури і документації. Наступним кроком є дослідження того, як ці концепції пов’ язані між собою: шаблон служби створює об’ єкт компонента з увімкнутими TechDocs, який потім з’ являється у каталогу програмного забезпечення з власником, оцінюються за допомогою карти показників і виводяться на поверхню керівництва за допомогою метрики прийняття порталу. Коли ви побачите повний опис, термінологія встановиться на своє місце.