Comment éviter que la documentation du serveur ne soit désynchronisée avec la configuration réelle?

Nous avons une documentation assez bonne pour notre environnement (au format AsciiDoc) qui a récemment permis à une autre personne de recréer la configuration entière à partir de zéro en moins de 30 minutes.
Cependant, j'ai remarqué qu'après la configuration initiale, il arrive facilement que de petites modifications soient apportées au système (disons: inetd est désactivé, mon serveur IMAP écoute sur un port supplémentaire pour les connexions ManageSieve, un nouveau routeur est ajouté à la configuration exim) don 'finissent pas dans la documentation immédiatement (le cas échéant).

Mon idée était d'éviter ce problème en (partiellement?) La génération de la documentation sur les fichiers de configuration et les commentaires qui s'y trouvent - une façon de mettre en œuvre ce qui peut être de mettre /etcet /usr/local/etcdans un système de gestion de code source (disons - git), puis exécuter un script qui régénère la documentation sur chaque commit. Cependant, je ne sais pas si ce serait exagéré et / ou trop difficile à obtenir correctement (après tout, je ne veux pas de copies complètes des fichiers source dans ma documentation, mais seulement les différences).

Comment les autres peuvent-ils éviter que la documentation du serveur ne soit obsolète - existe-t-il un bon moyen de les maintenir synchronisés automatiquement, ou avez-vous simplement la discipline de mettre à jour la documentation en même temps que vous modifiez le système?

Vous ne vous éloignerez jamais de certains documents, mais comme vous l'avez laissé entendre, il existe des systèmes qui peuvent être intégrés dans votre processus de changement pour en couvrir une grande partie.

• Utilisez un outil de gestion de configuration (comme une marionnette ou un chef ).
• Stockez votre configuration d'une manière contrôlée par le changement. (comme git ou SVN )
• Assurez-vous que la configuration est lisible / accessible aux humains (c.-à-d. Texte brut, base de données consultable)

De cette façon, la documentation de niveau inférieur que nous manquons tous normalement (ou qui ne nous dérange pas) est appliquée en stockant les informations de déploiement dans des éléments de configuration ou du code en tant que partie du système auquel vous apportez des modifications. Cela a également pour avantage supplémentaire que le processus devienne plus reproductible à l'avenir.

La documentation externe doit toujours être mise à jour mais elle devient de très haut niveau avec des pointeurs pour "déployer x" ou "déployer y" au lieu de longues listes de commandes / fichiers. Cela rend en outre les changements de documentation à la fois moins fréquents et plus faciles, ce qui signifie également qu'ils seront plus susceptibles d'être effectués.

Avant de rentrer à la maison, avec une marionnette, quelqu'un a probablement déjà écrit quelque chose pour gérer ce que vous voulez.

Si vous administrez uniquement un ou deux petits systèmes, la mise en place d'un grand système de gestion de configuration comme marionnette ou chef semble exagéré. (Cependant, si vous prévoyez d'avoir plus de systèmes à l'avenir, faites-le maintenant!)

Pour une petite configuration comme celle-ci, je recommanderais d'utiliser quelque chose comme etckeeper, un programme qui place /etcdans un gitréférentiel et fournit quelques fonctions utiles, comme faire une validation automatique chaque fois que vous installez, mettez à niveau ou supprimez un package.

Il vous suffit de mettre à jour votre documentation à chaque fois que vous effectuez une modification sur le système. AKA Change Management.

Le fait que la plupart des entreprises mettent en œuvre la gestion du changement de manière si ridicule qu'elle ne fait qu'empirer les choses ne devrait pas nuire à l'utilité du concept de base ni vous empêcher de le faire correctement.

J'avais l'habitude d'utiliser htmlou une sorte de wiki pour suivre toutes mes configurations. Maintenant, je travaille dans une boutique Windows avec ( frémissement ) SharePoint, alors maintenant j'utilise des "modèles" de documents Word que j'ai créés pour suivre chaque système que j'ai et chaque changement de configuration que j'apporte, ce qui n'est pas aussi mauvais qu'il y paraît, étant donné que beaucoup les systèmes ne sont que des copies à l'emporte-pièce d'autres qui peuvent tous être regroupés dans le même document. (Et je conserve des copies locales de tous mes documents sur mon disque dur, en fait organisés de manière sensée, en plus de les jeter sur le tas non organisé qui est le site SharePoint de n'importe qui.)

Le plus grand défi est vraiment de prendre le temps de documenter, ce que je fais en ajoutant le temps de documentation dans le temps pour effectuer le changement. Donc, pas vraiment si difficile, surtout si vous êtes un peu idiot et que cela ne vous dérange pas de dire aux gens de se faire foutre et d'attendre parce que vous êtes trop occupé pour leur problème en ce moment.