Уровень: начинающим, продолжающим, ленивым
Что, опять? Но зачем!?
О документации сказано уже много, в том числе и на хабре, где я нашел несколько статей. Однако те статьи которые я смотрел (раз, два, три, четыре) отвечают на вопросы зачем и что нужно документировать. Я же хочу привести два простых примера показывающих как, а также демонстрирующих, что документация может быть мягкой и шелковистой легкой и приятной.
В чем вести документацию?
Я считаю, что есть только один нормальный способо вести документацию. Спросите себя какой? Я думаю, вы угадали что это вики. Почему? Про возможности совместной работы я даже не буду упоминать, это очевидно. Главные преимущества вики-системы я вижу в следующем:
1. Сохраняется история правок. Всегда можно посмотреть, кто виноват и кому в башку сапог.
2. Простота установки, настройки и использования. Вики можно использовать везде.
Документация на сервера
Документацию я веду преимущественно текстовую. Но сейчас я отклонюсь от темы и расскажу про схемы.
Отсупление про графические схемы
Я люблю красивые схемы, но использую их только в крайнем случае, потому у них есть несколько принципиальных недостатков.
1. Схему нужно скачивать из вики, менять и заливать обратно. Этот недостаток насколько важен, что я остановлюсь на нем особо. Итак, ключевое условие для своевременного ведения документации состоит в принципах «документируй по ходу работы» и «документируй легко». Для изменения документации нужно совершать минимальное количество действий. И правда, если для того, чтобы задокументировать измение в топологии сети или в схеме работы кластера нужно открывать схему, изменять ее и заливать обратно, есть довольно большая вероятность что делать этого просто не будут. А даже если будут, то совсем не радостно, потому что это весьма муторно.
2. По схемам нельзя искать. И даже если искать по схемам в программе создания схем можно, то навряд ли это будет работать когда схема, вероятнее всего преобразованная в картинку, будет вставлена в вики.
3. Схема не заменит грамнотное словесное описание. Конечно, есть вещи для которых схемы подходят больше, но в своей повседневной практике я столкнулся с тем, что большинство вещей с которыми я работаю отлично описываются текстом, а схемы иногда лепят просто для красоты.
Итак, текст
Я люблю текст. Скажу даже больше, я люблю plaintext. Он быстро набирается и достаточно выразителен, если правильно использовать отступы, причем позволяет сосредоточиться на структуре а не на оформлении. Структура это самое главное. Поэтому еще раз скажу: «Используйте отступы!» Они позволяют сосредоточиться на том что вы описываете не отвелкаясь на оформление, и при этом представить информацию удобной, структурированной и легкой для восприятия форме. Может немного перехвалил? Ну да ладно.
Итак, несколько принципов работы с текстом:
1. Документацию пишут для того, чтобы ее читать. Поэтому при разработке формата документации отталкивайтесь исключительно оттого, что сможет помочь вам в работе. Спрашивайсте себя «Что я должен знать об этом сервисе? Об этой машине?»
2. Пишите лаконичо. Если что-то можно не писать, потому что оно уже где-то есть, то не пишите, потому что по опыту получаются дебри текста, на которые затем просто забивают. Наприметр, спецификации сервера можно указать ссылкой на документ на сайте производителя. Итак, нет избыточности и лишней работе!
3. Не пишите, копируйте! Если что-то можно взять прямо из конфига, берите прямо из конфига. Вывод команды тоже пойдет. Если можно сделать скрипт, которым сам выдергивает информацию из конфигов и кладет в вики (а это несложно) — делайте. Документацию на сами сервера вооще можно класть в /etc/motd и потом выгружать в вики, тогда документировать изменения будет намного проще вообще всем.
3. Структурирование — наше все. Выделяйте отступами подчиненные элементы. Можно использовать списки, но списки это хорошо, а отступы лучше.
4. Стандарты документации должны быть, но здравый смысл важнее. Например, если в функционировании сервера есть некоторые неявные особенности, делайте новый подраздел раздел и пишите. Если с сервером что-то не так, выносите это наверх и выделяйте красным.
5. Мониторинг это не документация. Системы управления конфигурацией тоже не документация. Понятно, что если есть 100 однотипных серверов, то можно задокументировать только один но, с другой стороны, если у вас есть 100 однотипных серверов, то вы и так это знаете.
Шаблон для описания сервера
Итак, ниже представлен шаблон для описания сервера. В настоящей вики он выглядит примерно также, как и тут. Как видите, я настолько люблю отступы, что действительно использую очень много тегов pre pre pre.
Cам шаблон состоит из следующих пунктов:
1. Имя сервера
2. Предоставляемые сервисы
3. Отвественные
4. Система
5. Мониторинг
6. Бэкап
Имя сервера
powerconsumer.site
Предоставляемые сервисы
Сервис пожирания процессора
---------------------------
Описание:
Многопоточный демон, который пожирает процессор вычисляя число пи до 10^100 десятичного знака.
Помогает жрать память, случайно дергая через сокет процесс memeater.
Взаимодействие:
Memory eating service, socket
http://bofh.ntk.net/BOFH/ 80/tcp
Приложение: /usr/local/bin/cpueater
init-скрипт: /etc/init.d/cpueater
Рабочий каталог: /srv/bofh/cpueater
Логи: /var/log/cpueater[1,7]
Ротация: every day, keeping last 7 days
Мониторинг: http://zabbix.site/cpueater/
Конфиги: /etc/cpueater/cpueater.conf
Сервис пожирания памяти
-----------------------
Описание:
Многопоточный демон, который пожирает память выделяя ее для демона вычисления числа пи.
Взаимодействие:
Memory eating service, socket
http://bofh.ntk.net/BOFH/ 80/tcp
Приложение: /usr/local/bin/memeater
init-скрипт: /etc/init.d/memeater
Рабочий каталог: /srv/bofh/memeater
Логи: /var/log/memeater[1,7]
Ротация: every day, keeping last 7 days
Мониторинг: http://zabbix.site/memeater/
Конфиги: /etc/memeater/memeater.conf
Отвественные
BOFH
Система
Debian Squeeze 6.04
Disk subsystem
--------------
RAID-6 on LSI-based controller with 10 active disks and 2 hot-spares.
10.0GB ext4 / boot
10.0GB linux-swap(v1) swap
10.0GB ext4 /tmp
10.0GB ext4 /usr
20.0GB ext4 /var
40.0GB ext4 /home
20.0GB /opt
2300GB /srv/bofh
Network subsystem
-----------------
iface eth0 inet static
address 192.168.1.10
netmask 255.255.255.0
network 129.168.1.0
gateway 192.168.1.1
up sleep 5; /sbin/ethtool -s eth0 autoneg off speed 100 duplex full
Мониторинг
Zabbix-agent with custom scripts:
/opt/zabbix/cpueater.py
/opt/zabbix/memeater.py
Бэкап
/srv/bofh/cpueater/
/srv/bofh/memeater/
Взаимодействие между серверами
Как показала практика, это самая главная страница. Она намного чаще используется, чем страницы отедльных серверов. Смысл этой страницы прост: в одном месте, максимально простым способом, описать возможно полную картину взаимодействия всех машин.
Итак, если вам лень вести документацию, сделайте хотя-бы это!
Формат документации простой. Для каждого сервиса (демона) на хосте записываются все хосты и сервисы с которыми описываемый сервис взаимодействует.
balancer.site
-------------
ngnix: --> webserver0.site/ngnix: 80/tcp
ngnix: --> webserver1.site/ngnix: 80/tcp
webserver0.site
---------------
php-fpm: --> sql.site/postgresql: 5423/tcp
webserver1.site
---------------
php-fpm: --> sql.site/postgresql: 5423/tcp
sql.site
--------
postgresql: --> backup.sql.site/postgresql: 22/tcp
backup.sql.site
---------------
amanda.site
-----------
amanda-server: --> balancer.site/amanda-client: 30000-30100/tcp, 10800/udp
amanda-server: --> webserver0.site/amanda-client: 30000-30100/tcp, 10800/udp
amanda-server: --> sql.site/amanda-client: 30000-30100/tcp, 10800/udp
zabbix.site
-----------
zabbix-server: --> balancer.site/zabbix-agent: 10050/tcp
zabbix-server: --> webserver0.site/zabbix-agent: 10050/tcp
zabbix-server: --> webserver1.site/zabbix-agent: 10050/tcp
zabbix-server: --> sql.site/zabbix-agent: 10050/tcp
zabbix-server: --> backup.sql.site/zabbix-agent: 10050/tcp
zabbix-server: --> amanda.site/zabbix-agent: 10050/tcp
Напоследок
Приведенные выше примеры не обязательно применимы к вам напрямую, их можно и нужно переделывать под обстоятельства.
Ну вот и все. Всем привет!
Автор: sistemshik
