Еще раз о документации

в 7:09, , рубрики: администрирование, документация, документирование, сервера, Серверное администрирование, системное администрирование, метки: , , ,

Уровень: начинающим, продолжающим, ленивым

Что, опять? Но зачем!?

О документации сказано уже много, в том числе и на хабре, где я нашел несколько статей. Однако те статьи которые я смотрел (раз, два, три, четыре) отвечают на вопросы зачем и что нужно документировать. Я же хочу привести два простых примера показывающих как, а также демонстрирующих, что документация может быть мягкой и шелковистой легкой и приятной.

В чем вести документацию?

Я считаю, что есть только один нормальный способо вести документацию. Спросите себя какой? Я думаю, вы угадали что это вики. Почему? Про возможности совместной работы я даже не буду упоминать, это очевидно. Главные преимущества вики-системы я вижу в следующем:
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


* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js