Как избежать того, чтобы документация сервера не синхронизировалась с фактической настройкой?
У нас есть достаточно хорошая документация для нашей среды (в формате AsciiDoc), которая недавно позволила другому человеку воссоздать всю установку с нуля менее чем за 30 минут.
Тем не менее, я заметил, что после первоначальной установки легко случается, что в систему вносятся небольшие изменения (скажем: inetd отключается, мой IMAP-сервер прослушивает дополнительный порт для соединений ManageSieve, в конфигурацию exim добавляется новый маршрутизатор). Не попадайте в документацию немедленно (если вообще).
Моя идея состояла в том, чтобы избежать этой проблемы путем (частично?) Генерации документации из файлов конфигурации и комментариев к ней - одним из способов реализации этого может быть установка /etc а также /usr/local/etc в какую-то систему управления исходным кодом (скажем, git), а затем запустите скрипт, который обновляет документацию при каждом коммите. Тем не менее, я не уверен, будет ли это излишним и / или слишком трудным для понимания (в конце концов, я не хочу, чтобы в моей документации были полные копии исходных файлов, а скорее просто различия).
Как другие люди избегают устаревания документации сервера - есть ли хороший способ автоматически синхронизировать их, или у вас просто есть дисциплина для обновления документации в то же время, когда вы модифицируете систему?
3 ответа
Если вы управляете только одной или двумя небольшими системами, настройка большой системы управления конфигурациями, такой как puppet или chef, выглядит излишней. (Хотя, если вы планируете иметь больше систем в будущем, сделайте это сейчас!)
Для такой небольшой установки я бы рекомендовал использовать что-то вроде etckeeper, программа, которая ставит /etc в git хранилище и предоставляет несколько полезных функций, таких как автоматическая фиксация при установке, обновлении или удалении пакета.
Вам просто нужно обновлять документацию каждый раз, когда вы вносите изменения в систему. AKA Change Management,
Тот факт, что большинство компаний внедряют управление изменениями таким нелепым образом, что это делает его хуже, чем ничего, не должно умалять полезность базовой концепции или мешать вам делать это правильно.
Я использовал, чтобы использовать html или какая-то вики для отслеживания всех моих конфигов. Теперь я работаю в магазине Windows с (дрожью) SharePoint, поэтому теперь я использую "шаблоны" документов Word, которые я создал, чтобы отслеживать каждую систему, которую я имею, и каждое изменение конфигурации, которое я делаю, что не так плохо, как кажется, учитывая, что многие системы - это просто копии других файлов, которые можно объединить в один документ. (И я храню локальные копии всех своих документов на жестком диске, фактически организованные разумным способом, в дополнение к тому, что они выбрасываются в неорганизованную кучу, которая является чьим-либо сайтом SharePoint.)
Самая большая проблема заключается в том, чтобы действительно уделить время документированию, что я делаю, добавляя время документирования как часть времени для внесения изменений. Так что, на самом деле, это не так сложно, особенно если вы немного попка и не против сказать людям, чтобы они отстали и ждали своей очереди, потому что вы слишком заняты для их проблемы в данный момент.
Вы никогда не откажетесь от какой-либо документации, но, как вы уже заметили, есть системы, которые можно интегрировать в процесс изменений, чтобы охватить многие из них.
- Используйте инструмент управления конфигурацией (например, puppet или chef).
- Храните ваши настройки в контролируемом порядке. (как мерзавец или SVN)
- Убедитесь, что конфигурация читаема / доступна для людей (т.е. простой текст, доступный для поиска БД)
Таким образом, обеспечивается низкоуровневая документация, которую мы все обычно пропускаем (или не беспокоимся), сохраняя информацию о развертывании в элементах конфигурации или коде как часть системы, в которую вы вносите изменения. У этого также есть дополнительный бонус процесса, становящегося более повторяемым в будущем.
Внешняя документация все еще нуждается в обновлении, но она становится очень высокого уровня с указателями для "развертывания x" или "развертывания y" вместо длинных списков команд / файлов. Это дополнительно делает изменения документации менее частыми и более легкими, что также означает, что с большей вероятностью это будет сделано.
Также перед тем, как пойти домой, варить, с марионеткой кто-то, вероятно, уже написал что-то, чтобы справиться с тем, что вы хотите.