Como você evita que a documentação do servidor fique fora de sincronia com a configuração real?

Question

Temos uma documentação razoavelmente boa para o nosso ambiente (no formato AsciiDoc) que recentemente permitiu que outra pessoa recriasse toda a configuração do zero em menos de 30 minutos.
No entanto, notei que após a configuração inicial, acontece facilmente que pequenas alterações feitas no sistema (digamos: inetd é desabilitado, meu servidor IMAP escuta em uma porta adicional para conexões ManageSieve, um novo roteador é adicionado à configuração exim) acabe na documentação imediatamente (se for o caso).

Minha idéia era evitar esse problema (parcialmente?) gerando a documentação dos arquivos de configuração e os comentários nele - uma maneira de implementar isso pode ser colocar /etc e /usr/local/etc em algum sistema de gerenciamento de código fonte (say - git) e, em seguida, execute um script que regenere a documentação em cada commit. No entanto, eu não tenho certeza se isso seria um exagero e / ou muito difícil de acertar (afinal, eu não quero cópias completas dos arquivos de origem em minha documentação, mas sim apenas os diffs).

Como outras pessoas evitam que a documentação do servidor fique desatualizada - existe uma boa maneira de mantê-las sincronizadas automaticamente ou você só tem a disciplina para atualizar a documentação ao mesmo tempo em que modifica o sistema?

    

Answer 1

Você nunca vai ficar longe de alguma documentação, mas como você sugeriu, existem sistemas que podem ser integrados em seu processo de mudança para cobrir muito disso.

• Use uma ferramenta de gerenciamento de configuração (como puppet ou chef ).
• Armazene sua configuração de maneira controlada por alteração. (como git ou SVN )
• Verifique se a configuração é legível / acessível por seres humanos (por exemplo, texto simples, db pesquisável)

Desta forma, a documentação de nível inferior que todos nós normalmente perdemos (ou não nos incomodamos) é reforçada pelo armazenamento de informações de implantação em itens de configuração ou código como parte do sistema para o qual você está fazendo alterações. Isso também tem um bônus adicional de o processo se tornar mais repetitivo no futuro.

A documentação externa ainda precisa ser atualizada, mas se torna um nível muito alto com ponteiros para "implantar x" ou "implantar y", em vez de listagens longas de comandos / arquivos. Isso também torna as mudanças na documentação menos freqüentes e mais fáceis, o que também significa que será mais provável que seja feito.

Além disso, antes de ir para casa, com boneco, alguém provavelmente já escreveu algo para gerenciar o que você quer.

    

Answer 2

Se você administrar apenas um ou dois sistemas pequenos, configurar um sistema de gerenciamento de configuração grande, como fantoches ou chefes, parece um exagero. (Porém, se você planeja ter mais sistemas no futuro, faça isso agora!)

Para uma configuração pequena como essa, recomendo usar algo como etckeeper , um programa que coloca /etc em um repositório git e fornece algumas funções úteis, como fazer uma confirmação automática sempre que você instala, atualizar ou remover um pacote.

    

Answer 3

Você só precisa atualizar sua documentação toda vez que fizer uma alteração no sistema. AKA Change Management .

O fato de que a maioria das empresas implementa o gerenciamento de mudanças de maneira tão ridícula a ponto de torná-lo pior do que nada não deve prejudicar a utilidade do conceito básico ou impedir que você o faça corretamente.

Eu costumava usar html ou algum tipo de wiki para rastrear todas as minhas configurações. Agora eu trabalho em uma loja Windows com ( shudder ) SharePoint, então agora eu uso os "modelos" de documento do Word que criei para rastrear todos os sistemas que tenho e todas as alterações que eu faço, o que não é tão ruim como parece, dado que muitos sistemas são apenas cópias de outros que podem ser agrupados no mesmo documento. (E eu mantenho cópias locais de todas as minhas documentações no meu disco rígido, na verdade organizadas de maneira sensata, além de jogá-las no heap não organizado que é o site do SharePoint de qualquer pessoa.)

O maior desafio é realmente fazer o tempo para documentar, o que eu faço adicionando o tempo de documentação como parte do tempo para fazer a mudança. Então, não é tão difícil assim, especialmente se você é um idiota e não se importa em dizer às pessoas para errarem e esperar na fila porque você está muito ocupado com o problema delas no momento.