Документація як код: декларативні конфіги YAML для малювання архітектур хмарних систем

💡 Усі статті, обговорення, новини про DevOps — в одному місці. Приєднуйтесь до DevOps спільноти!

Привіт! 👋

Мене звати Дмитро, я працюю Senior Software Engineer в продуктовій компанії Plum та веду DevOps-подкаст на YouTube-каналі DOU. Нещодавно я зробив невеличкий open source проєкт diagrams-as-code — command line interface (CLI), щоб малювати діаграми за допомогою коду замість інтерактивної взаємодії з графічними елементами в сервісах типу draw.io.

У вигляді коду постає конфігураційний файл на типу мові розмітки YAML, що є de facto стандартом в індустрії для опису інфраструктури та конфігурації різного програмного забезпечення. Ви просто вказуєте шлях до файлу в команді CLI та отримуєте згенеровану картинку.

Робота з YAML-файлом — це декларативний процес. Декларативний метод опису речей означає, що користувач просто описує необхідне рішення, як воно має виглядати, залишаючи процес на розсуд програмного забезпечення.

Загалом, diagram-as-code надає вам наступні переваги:

  • Не вимагає ніяких знань про те, як правильно намалювати діаграму архітектури. По суті, ви просто визначаєте набір ресурсів, об’єднуєте їх у групи та встановлюєте зв’язки, решту зробить за вас diagrams-as-code.
  • Дозволяє відстежувати зміни архітектурної діаграми за допомогою систем контролю версій типу Git і працювати з цим через пулл реквести.
  • Зменшує «витрати» на подальше оновлення початкової діаграми архітектури. По суті, коли ви створюєте зображення за допомогою інтерактивних сервісів, вам доведеться зрештою зберегти два файли: PNG-подібний для розміщення у вашій документації та XML, щоб мати можливість вносити зміни у зображення в майбутньому. Отже, більше немає потреби піклуватися про XML.
  • Резервне копіювання на випадок втрати файлів XML, оскільки файли YAML завжди зберігаються в репозиторії.
  • Покращує консистентність, оскільки тепер діаграма зберігається разом із кодом у сховищі, місці, яке ви відвідуєте та над яким часто працюєте, і його легше підтримувати в актуальному стані ніж якийсь Google Drive.

На данних момент є підтримка наступних компонентів:

  • Основні хмарні сервіси: AWS, Azure, GCP, IBM, Alibaba, Oracle, OpenStack, DigitalOcean і так далі.
  • On-Premise, Kubernetes, Firebase, Elastic, SaaS.
  • Мови програмування та фреймворки.

Більше про проєкт читайте в README на GitHub.

👍ПодобаєтьсяСподобалось10
До обраногоВ обраному0
LinkedIn
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Імхо, краще малювати діаграми у Mermaid, бо їх GitHub (і ще багато чого) нативно відображають прямо з маркдаун.

Із мінусів — немає модних іконок.

А для гарної альтернативи PlantUML є d2lang.com

Обгортка над Python бібліотекою diagrams.mingrammer.com ? Навіщо? Якийсь mermaid.js.org, наприклад, описується нескладним DSL і рендериться в GitHub’івському markdown’і.

Я більш ніж впевнений, що існує безліч LaTeX пакетів для цієї фігні.

Підписатись на коментарі