Документація, яку має писати девопс. Обговорення зразка
Доброго дня. Мене звати Андрій і я девопс.
Хочу обговорити з колегами наступне питання — як девопс має документувати свою роботу.
Не за допомогою яких засобів (їх багато, різної складності та можливостей), а як і що він має описувати.
Візьмемо типовий випадок — onboarding нового співробітника devops, або ops (dev), які будут дотичними до цих процесів. Що він потрібен знати про проєкт, інфраструктуру, CI/CD pipelines?
Мені здається, що десь 10 % колег у своїй практиці могли бачити щось схоже не документацію при onboarding.
Але здогадуюсь, що майже 100 % повинні були її писати)). Або малювати схеми.
Я дуже не люблю писати документацію. Мені не подобається синдром «чистого аркуша» — коли ти не знаєш з чого почати писати, якого об’єму та ін.
Тому я вирішив створити щось на кшталт «кози», на основі якої можна буде створювати документацію в майбутніх проєктах.
Потім стало зрозуміло, що без реальної практики на тій «козі» далеко не поїдеш. Тому я знайшов тестовий проєкт із мікросервісами, на якому пройшов основні «девопсові» етапи і вже потім почав створювати документацію на його основі.
Проект на Github — github.com/...ewpas/devops-demo-project
Основне:
- у розробника все збирається та працює в docker compose
- гілка stage розгортається в kubernetes (Bare Metal + Proxmox + Rancher)
- гілка production розгортається на AWS EKS
- CI/CD на gitlab.com
- оточення stage створюється за допомогою Ansible
- оточення production створюється за допомогою Terraform
- документація автоматично генерується за допомогою ansible-doc (ansible playbook), terraform-docs (terraform resources), merge-markdown (інші розділи)
- схеми та діаграми створені в diagrams.net desktop
- зведена документація в README.MD у корені проєкту
Проєкт ще на початковій стадії (див. TODO), але може бути базою для тренування та відпрацювання нових підходів, технологій, інструментів
Пропоную обсудити в коментарях на прикладі моделі «onboarding нового devops на проєкті»:
- чого не вистачає в документації
- що є зайвим
- наскільки докладно потрібно все описувати
- де і як брати дані для автоматичного оновлення
- яка ступінь детальності потрібна для джуна, мідла
- може розкажете як у вас поставлений ций процес
- як описувати CI/CD
5 коментарів
Додати коментар Підписатись на коментаріВідписатись від коментарівЗакинув вам pull request з фіксами граматики. І ще часто по тексту зустрічається «deploiment.yml» в назвах файлів, то ви вже самі ) А так, велика подяка за працю, нічого схожого не бачив до цього, буду тестувати..
Дуже вам дякую! ))
А відповідь проста: треба представити, що ви перший раз цей проект бачите — яка інформація вам потрібна для того, щоб повністю розвернути цей проект з нуля?
Після цього — берете останні таски, дивитись на кожну знову-ж таки як людина, яка цей проект бачить перший раз. яка інформація вам потрібна, щоб таску виконати? Без питань до інших учасників проекту. Ви один, всіх інших звільнили, контактів немає. ;)
Якщо є інструкція, за якою людина зі сторони зможе проект задеплоїти «з нуля» піднявши всі дані з бекапів до останньої робочої версії, якщо ця людина зможе зробити будь-яку таску просто подивившись у документацію, без питань до будь-кого — то документація у чудовому стані. ;)
.пайплайну відкриваєш
Схеми малювати таке, вони застаріють наступного дня.
Автоматично генерувати може.
Але онбордінг навіть не про це.
Вчасно видати пермішини і то проблема