Documentação de rede: por que ninguém mantém e como resolver

Todo provedor tem um diagrama de rede. O problema é que ele foi desenhado uma vez, está num PDF perdido no Drive e mostra um POP que já foi desativado e dois agregadores que ainda não existiam quando o desenho foi feito. Quando cai um enlace às 3 da manhã, ninguém abre o diagrama: liga pro técnico que "conhece a rede". Esse técnico é a sua documentação. E ele tira férias, fica doente e, um dia, pede demissão.

A documentação de rede não morre por falta de ferramenta. Morre porque é desacoplada da operação. Documentar é trabalho manual, feito depois do fato, sem ninguém cobrando, enquanto a rede muda todo dia. Toda planilha de IPAM, todo diagrama, toda lista de senhas começa correta e degrada sozinha a partir da primeira alteração que ninguém anotou.

Por que a documentação sempre apodrece

O padrão se repete em provedor de dois mil e de cinquenta mil assinantes:

• É um artefato paralelo, não um subproduto do trabalho. Você troca uma OLT, configura uma nova VLAN, sobe um peering no IX.br — e a documentação não muda junto. Atualizar é uma segunda tarefa que compete com a fila do NOC. Sempre perde.
• Não tem dono nem gatilho. "Atualizar a planilha" não está em nenhum runbook, não bloqueia nenhuma mudança, não dispara nenhum alerta. O que não é cobrado, não acontece.
• Vive espalhada. IPAM numa planilha, topologia num PDF, inventário de equipamento na cabeça do gerente, senha do core num post-it dentro da gaveta ou num grupo de WhatsApp. Nenhuma fonte fala com a outra.
• A fonte da verdade é o equipamento, não o documento. O running-config do MikroTik, da OLT Huawei, do roteador Juniper — esse é o estado real. O documento é uma cópia que nasce desatualizada.

O resultado é o que chamamos de risco de uma pessoa só: o conhecimento da rede está concentrado em quem opera há anos. É bônus de retenção involuntário e bomba-relógio de continuidade ao mesmo tempo.

O custo real de não documentar

Não é teórico. Em provedor isso aparece em lugares concretos:

• MTTR alto. Boa parte do tempo de um incidente é gasta descobrindo como a rede está montada, não consertando. Sem topologia e inventário confiáveis, todo troubleshooting começa do zero.
• Onboarding lento. Técnico novo demora pra ser produtivo porque a rede não está escrita em lugar nenhum — está sendo transmitida oralmente.
• Mudança arriscada. Mexer num agregador sem saber o que depende dele vira tentativa e erro em produção.
• Auditoria e LGPD. Você precisa saber quem acessou qual equipamento e quando. Senha compartilhada em planilha não dá rastreabilidade nenhuma.
• Bloqueio judicial e Marco Civil. Quando chega um ofício pedindo a correlação de IP, porta e sessão CGNAT num instante específico, você precisa de IPAM e inventário corretos. "Acho que esse bloco está no POP tal" não é resposta pra juiz.

Documentação viva: o conceito que muda o jogo

A saída não é "se esforçar mais pra manter a planilha". É mudar o modelo. Documentação viva é aquela que:

1. Está acoplada ao inventário real. O documento é o inventário. Você não descreve a rede num lugar e cadastra os equipamentos em outro — é a mesma base.
2. Tem uma única fonte da verdade. Inventário, IPAM, topologia, contatos e credenciais convivem no mesmo sistema, referenciando os mesmos objetos. Um equipamento tem seu modelo, seus IPs, suas interfaces, seu POP e suas senhas ligados a ele.
3. Reflete o estado, não a intenção. O ideal é que a documentação seja alimentada pela rede — descoberta via SNMP, varredura de sub-redes, polling de status — e não só por digitação humana.
4. Embute o porquê. Comentário em config se perde. Por que aquele prefixo é anunciado com AS-PATH prepend? Por que aquela rota estática existe? Isso precisa morar junto do objeto, não na memória de alguém.

A diferença prática: quando a documentação é subproduto do inventário operacional, ela não apodrece — porque você a usa todo dia pra operar. O que se usa, se mantém.

Como o NetPulse resolve na prática

O NetPulse, plataforma de NOC multi-tenant da CloudFace, foi desenhado exatamente em cima desse problema. Em vez de tratar documentação como um PDF à parte, ela é a consequência natural de operar a rede no sistema:

• Inventário / DCIM como base única: equipamentos (MikroTik, Cisco, Huawei, Juniper), POPs, racks, interfaces e enlaces cadastrados como objetos reais, não como caixinhas num desenho estático.
• IPAM integrado ao inventário: cada bloco e sub-rede ligado ao equipamento e ao POP que o usa. Acabou a planilha de IP que ninguém sabe se está certa. Útil direto pra responder ofício e pra planejar crescimento de CGNAT.
• Monitoramento SNMP que alimenta a documentação: o estado real das interfaces e dos equipamentos entra no sistema sozinho. A topologia reflete o que está no ar, não o que alguém lembrou de desenhar.
• Documentação contextual presa aos objetos: o "porquê" daquele peering, daquela rota, daquele cliente especial fica anexado ao equipamento ou ao bloco — onde o operador vai olhar de qualquer forma.
• Cofre de credenciais com segundo fator, multi-tenant: senha de equipamento deixa de morar em post-it, planilha ou grupo de WhatsApp. Fica num cofre com controle de acesso e 2FA, com rastreabilidade de quem viu o quê. Isso ataca de frente o risco de uma pessoa só e o problema de auditoria.

O ponto não é "comprar um software". É parar de manter documentação como artefato morto e passar a operar num lugar onde documentar é o efeito colateral de trabalhar.

Por onde começar

Não tente documentar tudo de uma vez — esse projeto sempre falha. Comece pelo que dói:

• Inventário do core e dos agregadores primeiro. É onde o incidente custa caro.
• IPAM dos blocos públicos e do CGNAT, pela exigência legal e pela frequência de uso.
• Cofre de credenciais já, porque é o risco mais agudo e o mais rápido de resolver.
• Topologia depois, alimentada por descoberta automática sempre que possível — desenho manual é o que envelhece mais rápido.

E principalmente: amarre a atualização a um gatilho operacional. Toda mudança de rede passa pelo sistema. Se não está no sistema, não aconteceu.

Na CloudFace a gente vive isso dos dois lados: operando NOC 24/7 pra provedores e construindo o NetPulse pra que documentação de rede pare de ser ficção. Se a topologia do seu ISP está num PDF de dois anos atrás e a senha do core está na cabeça de uma pessoa só, vale uma conversa. Chama no WhatsApp pra um diagnóstico inicial gratuito da sua operação — sem compromisso, direto ao ponto.