Как избежать того, чтобы документация сервера не синхронизировалась с фактической настройкой?

У нас есть достаточно хорошая документация для нашей среды (в формате AsciiDoc), которая недавно позволила другому человеку воссоздать всю установку с нуля менее чем за 30 минут.
Тем не менее, я заметил, что после первоначальной настройки легко случается, что в систему вносятся небольшие изменения (скажем: inetd отключается, мой IMAP-сервер прослушивает дополнительный порт для соединений ManageSieve, в конфигурацию exim добавляется новый маршрутизатор). Не попадайте в документацию немедленно (если вообще).

Моя идея состояла в том, чтобы избежать этой проблемы (частично?) Генерирования документации из файлов конфигурации и комментарии в нем - один из способов реализации этого может быть поставить /etcи /usr/local/etcв какой - то системы управления исходным кодом (скажем - мерзавец) , а затем запустить скрипт, который восстанавливает документацию при каждом коммите. Тем не менее, я не уверен, будет ли это излишним и / или слишком трудным для понимания (в конце концов, я не хочу, чтобы в моей документации были полные копии исходных файлов, а скорее просто различия).

Как другие люди избегают устаревания документации сервера - есть ли хороший способ автоматически синхронизировать их, или у вас просто есть дисциплина для обновления документации в то же время, когда вы модифицируете систему?

Вы никогда не уйдете от какой-либо документации, но, как вы уже заметили, есть системы, которые можно интегрировать в процесс изменений, чтобы охватить многие из них.

• Используйте инструмент управления конфигурацией (например, puppet или chef ).
• Храните ваши настройки в контролируемом порядке. (как мерзавец или SVN )
• Убедитесь, что конфигурация читаема / доступна для людей (т.е. простой текст, доступный для поиска БД)

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

Внешняя документация все еще нуждается в обновлении, но она становится очень высокого уровня с указателями для «развертывания x» или «развертывания y» вместо длинных списков команд / файлов. Это дополнительно делает изменения документации менее частыми и более легкими, что также означает, что с большей вероятностью это будет сделано.

Также перед тем, как пойти домой, варить, с марионеткой кто-то, вероятно, уже написал что-то, чтобы справиться с тем, что вы хотите.

Если вы управляете только одной или двумя небольшими системами, настройка большой системы управления конфигурациями, такой как puppet или chef, выглядит излишней. (Хотя, если вы планируете иметь больше систем в будущем, сделайте это сейчас!)

Для такой небольшой установки я бы порекомендовал использовать что-то вроде etckeeperпрограммы, которая помещает /etcв gitрепозиторий и предоставляет несколько полезных функций, таких как автоматическое принятие, когда вы устанавливаете, обновляете или удаляете пакет.

Вам просто нужно обновлять документацию каждый раз, когда вы вносите изменения в систему. АКА Change Management.

Тот факт, что большинство компаний внедряют управление изменениями таким нелепым образом, что это делает его хуже, чем ничего, не должно умалять полезность базовой концепции или мешать вам делать это правильно.

Раньше я использовал htmlили какую-то вики для отслеживания всех моих конфигов. Теперь я работаю в магазине Windows с ( дрожью ) SharePoint, поэтому теперь я использую «шаблоны» документов Word, которые я создал, чтобы отслеживать каждую систему, которую я имею, и каждое изменение конфигурации, которое я делаю, что не так плохо, как кажется, учитывая, что многие системы - это просто копии других файлов, которые можно объединить в один документ. (И я храню локальные копии всех своих документов на жестком диске, фактически организованные разумным способом, в дополнение к тому, что они выбрасываются в неорганизованную кучу, которая является чьим-либо сайтом SharePoint.)

Самая большая проблема заключается в том, чтобы действительно потратить время на документирование, что я делаю, добавляя время документирования как часть времени для внесения изменений. Так что, на самом деле, это не так сложно, особенно если вы немного попка и не против сказать людям, чтобы они отстали и ждали своей очереди, потому что вы слишком заняты для их проблемы в данный момент.