Una solida documentazione dell'infrastruttura interna protegge la tua azienda da interruzioni, controlli e incidenti di sicurezza. Con Trupeer, puoi risparmiare ore sulla documentazione dell'infrastruttura partendo da un modello gratuito, personalizzandolo con le tue linee guida del brand e trasformando la documentazione in video tutorial per i team IT e gli MSP.

La maggior parte della documentazione dell'infrastruttura viene scritta una sola volta, durante un progetto, e risulta errata entro sei mesi. Rimane sulla wiki, nessuno se ne fida e, durante l'incidente successivo, qualcuno la legge, esita e telefona alla persona che sa davvero come stanno le cose.

La soluzione non è produrre più documentazione. È produrne meno ma mantenerla accurata, selezionando i contenuti chiedendosi di cosa avrebbe effettivamente bisogno qualcuno alle tre del mattino.

Scarica il modello di documentazione dell'infrastruttura

Gratuito, modificabile, senza filigrana. Excel svolge la maggior parte del lavoro qui, perché la documentazione dell'infrastruttura è in gran parte costituita da dati strutturati che fingono di essere prosa.

Di quale documentazione hai bisogno?

Come personalizzare questo modello in Trupeer

Passaggio 1: Apri la sezione Modelli

Vai alla sezione Modelli dal menu di navigazione principale.

Passaggio 2: Seleziona e apri un modello

Fai clic su qualsiasi modello con cui desideri lavorare per aprirlo.

Passaggio 3: Espandi la vista del modello

Se necessario, espandi la vista del modello per vedere chiaramente il layout completo e i dettagli.

Passaggio 4: Modifica il modello

Fai clic su Modifica per iniziare a modificare il modello selezionato.

All'interno dell'editor puoi:

• Aggiungere nuove sezioni

• Definire o aggiornare le regole di formattazione

• Aggiungere un logo e regolarne la posizione e le relative impostazioni

Passaggio 5: Salva il tuo modello personalizzato

Dopo aver apportato tutte le modifiche necessarie, fai clic su Salva per memorizzare il modello aggiornato come tuo.

Passaggio 6: Visualizza l'anteprima e perfeziona il modello

Quando desideri vedere come appare il tuo modello personalizzato, apri l'Anteprima.

Dalla schermata di anteprima, puoi continuare a apportare modifiche direttamente se necessario, assicurandoti che il modello appaia esattamente come desideri.

Con un modello di documentazione dell'infrastruttura interna puoi:

• Risparmiare ore di scrittura: Salta la pagina bianca con una struttura creata appositamente per l'infrastruttura IT.

• Migliorare il livello di sicurezza: I campi integrati impongono pratiche sicure di gestione delle credenziali.

• Rimanere in linea con il brand: Applica il tuo logo, font e colori utilizzando il kit del brand di Trupeer.

• Ridurre i tempi di inattività: Una documentazione chiara riduce il MTTR (tempo medio di ripristino) durante gli incidenti.

• Essere sempre pronto per gli audit: Allineato con SOC 2, ISO 27001 e framework simili.

• Raggiungere team globali: Traduci la documentazione in oltre 65 lingue con un solo clic.

Il test delle 3 del mattino

L'unico test che conta davvero per la documentazione dell'infrastruttura.

Immagina un incidente alle tre del mattino. La persona che ha creato il sistema è su un aereo. Qualcuno di competente ma che non ha familiarità con il sistema sta guardando la tua documentazione. È in grado di capire cosa è rotto, da cosa dipende, cosa succede se lo riavvia e a chi rivolgersi per l'escalation?

Tutto ciò che aiuta a rispondere a queste domande vale la pena di essere scritto. Tutto il resto è facoltativo, e la documentazione facoltativa è ciò che diluisce le parti utili e consuma il budget di manutenzione.

Applica questa regola senza pietà. Una storia dettagliata del perché una tecnologia sia stata scelta nel 2021 non supera il test. Una nota che dice che questo servizio deve essere avviato dopo il database e prima del gateway API, invece, lo supera.

Cosa supera il test delle 3 del mattino

• Cosa esiste. Sistemi, server, servizi, descrivendo cosa fa ciascuno in una sola frase.

• Dove si trova. Provider cloud e regione, oppure posizione fisica e rack.

• Da cosa dipende e cosa dipende da esso. L'elemento in assoluto più prezioso nella documentazione dell'infrastruttura.

• Come raggiungerlo. Hostname, indirizzi, console, ma mai le credenziali.

• Qual è il comportamento normale. In modo che una persona non familiare possa capire se c'è effettivamente qualcosa che non va.

• Cosa lo rompe. Modalità di guasto note e relativi sintomi.

• Come riavviarlo in sicurezza, inclusi l'ordine di avvio e qualsiasi operazione preliminare necessaria.

• Chi ne è il proprietario, e il percorso di escalation con dettagli di contatto reali.

• Qual è il raggio d'azione dell'impatto (blast radius). Cosa smette di funzionare se questo sistema va offline.

Cosa di solito non supera il test

Contenuti scritti per completezza formale piuttosto che per utilità pratica, e che quindi non vale la pena mantenere.

Dump completi di configurazione che risultano obsoleti il giorno dopo l'esportazione. Motivazioni dettagliate per decisioni passate, che appartengono a un registro delle decisioni architetturali piuttosto che alla documentazione operativa. Ogni singolo parametro di ogni sistema quando solo una manciata conta a livello operativo. Screenshot di console, che invecchiano rapidamente e raramente sono d'aiuto. E tutto ciò che duplica una fonte di verità esistente altrove, poiché due copie significano che una è errata e non è possibile capire quale.

Il principio generale: se un'informazione può essere scoperta dal sistema più velocemente di quanto possa essere letta da un documento, non documentarla.

L'inventario dell'infrastruttura

La fondazione. Una riga per ogni sistema o servizio.

L'ultimo campo è quello che la maggior parte degli inventari omette ed è quello che determina se qualcuno si fida o meno del documento. Una riga che nessuno controlla da due anni dovrebbe essere visibilmente non attendibile piuttosto che silenziosamente errata.

Livelli di criticità

Definiscili, perché guidano la quantità di documentazione che ciascun sistema merita.

La maggior parte delle organizzazioni documenta il livello 3 con la stessa profondità del livello 1, esaurisce le energie e finisce con l'avere tutto documentato a metà. Gestisci correttamente il livello 1 e lascia che il livello 3 sia una singola riga.

Dipendenze

La parte più preziosa e più trascurata della documentazione dell'infrastruttura.

Durante un incidente, la domanda raramente riguarda ciò che è rotto. Riguarda cos'altro ne viene influenzato e di cosa ha bisogno questo elemento per ripartire. Nessuna delle due informazioni è rilevabile da un semplice elenco di server.

Documenta le dipendenze in entrambe le direzioni:

Due elementi rendono utile questo schema: l'ordine di avvio, perché riavviare le cose nella sequenza sbagliata trasforma un breve incidente in uno lungo, e se la dipendenza sia forte o debole, poiché un servizio che si degrada gradualmente rappresenta un problema molto diverso da uno che si blocca immediatamente.

Includi le dipendenze esterne. Fornitori di servizi di pagamento, identity provider, DNS, autorità di certificazione e API SaaS causano interruzioni che non puoi risolvere direttamente, e saperlo rapidamente vale moltissimo alle 3 del mattino.

Documentazione di rete

La scadenza dei certificati merita un'attenzione particolare. Causa interruzioni del tutto prevedibili, del tutto prevenibili e con una probabilità sproporzionatamente alta di verificarsi durante il fine settimana. Documenta cosa scade e quando, chi si occupa del rinnovo e se il rinnovo è automatizzato.

Runbook

Il documento che qualcuno apre effettivamente durante un incidente.

La sezione "cosa non fare" è rara quanto preziosa. Ogni sistema maturo ha un'azione che sembra ragionevole ma che in realtà peggiora l'incidente: riavviare nell'ordine sbagliato, svuotare una cache che richiede sei ore per essere ricostruita, effettuare il failover quando il secondario è in ritardo.

Scrivi runbook per i sistemi di livello 1 e per tutto ciò che ha causato un incidente in passato. Non per ogni singola cosa.

Accesso e credenziali

La sezione in cui la documentazione rischia di causare danni anziché prevenirli.

Non inserire mai le credenziali nella documentazione. Né password, né chiavi API, né stringhe di connessione con segreti incorporati, né chiavi private. Non sulla wiki, non nel file Excel, nemmeno "temporaneamente".

Documenta invece il metodo di accesso. Quale sistema conserva le credenziali, chi può concedere l'accesso e come richiederlo alle 3 del mattino. Questo è ciò di cui la persona ha effettivamente bisogno, ed è sicuro da scrivere.

Quindi, documenta correttamente la procedura break-glass, perché l'indisponibilità dell'accesso di emergenza durante un'emergenza è un fallimento comune ed evitabile.

Disaster Recovery

Cosa deve contenere la documentazione di DR per essere davvero utile.

Obiettivi di tempo di ripristino (RTO) e punto di ripristino (RPO) per ciascun sistema di livello 1, concordati con il business piuttosto che ipotizzati dall'IT. Qual è effettivamente la procedura di ripristino, passo dopo passo. Dove si trovano i backup e, aspetto critico, quando è stato testato con successo l'ultimo ripristino. Chi dichiara lo stato di disaster e chi avvia il piano. Come comunica il team quando i sistemi normali sono fuori servizio, poiché un piano di DR memorizzato solo sui sistemi che sono andati offline è un classico imbarazzo.

La singola riga più importante in qualsiasi documento di DR è la data dell'ultimo test di ripristino andato a buon fine. Un backup che non è mai stato ripristinato è solo un'ipotesi.

Diagrammi

L'infrastruttura beneficia dei diagrammi più di quasi ogni altra documentazione, ma questi diventano obsoleti ancora più rapidamente.

• Un diagramma di alto livello che mostra i componenti principali e come si collegano. Questo è quello che le persone usano davvero.

• Topologia di rete, laddove l'ambiente è abbastanza complesso da richiederlo.

• Flusso dei dati, in particolare dove attraversa confini fiduciari o giurisdizionali.

• Mantienili semplici. Un diagramma che nessuno riesce a leggere a colpo d'occhio durante un incidente è solo una decorazione.

• Inserisci una data e indica il proprietario su di essi.

• Prediligi i diagrammi definiti tramite codice (diagrams-as-code) se il tuo team è in grado di gestirli, poiché un diagramma in un formato di testo sottoposto a controllo di versione viene aggiornato insieme alla modifica stessa anziché a posteriori.

Un diagramma sbagliato è peggio di nessun diagramma, perché le persone si fidano delle immagini più che delle parole.

Mantenere l'accuratezza

Il problema principale, nonché il motivo per cui la maggior parte della documentazione dell'infrastruttura fallisce.

• Documenta meno. L'accuratezza è inversamente proporzionale al volume. Quindici pagine accurate sono migliori di duecento pagine obsolete.

• Collega gli aggiornamenti della documentazione al processo di gestione delle modifiche (change process). Una modifica che altera l'infrastruttura non è completa finché la documentazione non la rispecchia. Questo è l'unico meccanismo che funziona in modo affidabile.

• Automatizza ciò che può essere rilevato. Inventario, indirizzi, configurazioni e topologia possono spesso essere generati automaticamente. La documentazione generata non può diventare obsoleta nello stesso modo in cui lo diventa quella scritta a mano.

• Scrivi a mano solo ciò che non può essere rilevato automaticamente. Scopo, proprietà, criticità, dipendenze, modalità di guasto note, cosa non fare. Le macchine non possono dedurre nessuna di queste informazioni.

• Metti una data su tutto e mostrala in evidenza. Una data di ultima verifica visibile consente ai lettori di calibrare il loro livello di fiducia.

• Pianifica le revisioni in base al livello di criticità, trimestralmente per il livello 1.

• Correggi la documentazione durante gli incidenti. Il momento in cui qualcuno scopre che la documentazione è errata è proprio il momento in cui ha le conoscenze per correggerla. Rendi questa operazione un compito da cinque minuti, non un ticket da gestire in seguito.

Automazione e discovery

Vale la pena investirci, perché elimina la causa di fallimento più comune.

Database di gestione della configurazione (CMDB), inventari dei provider cloud, repository di infrastructure-as-code e strumenti di discovery di rete possono generare continuamente informazioni accurate sullo stato attuale. Tutto ciò che possono produrre non dovrebbe essere gestito manualmente.

La suddivisione ottimale del lavoro: le macchine documentano cosa esiste, gli esseri umani documentano cosa significa. Un inventario generato automaticamente ti dice che esiste un server e cosa vi è installato. Solo una persona può dirti che è proprio quel server che non deve essere riavviato tra le 2 e le 4 del mattino a causa dell'elaborazione batch.

Laddove l'infrastruttura è definita tramite codice, il codice stesso è la documentazione di ciò che esiste. Ciò che resta da scrivere è l'intento, la conoscenza operativa e le modalità di guasto.

Chi ne è il proprietario

Assegna la proprietà per singolo sistema invece di rendere la documentazione il compito di una sola persona, una pratica che non sopravvive mai alla partenza di quest'ultima.

Il team che gestisce un sistema è proprietario della sua documentazione. Un individuo designato è proprietario dello standard generale, dei modelli e della frequenza di revisione. E il processo di modifica impone gli aggiornamenti, perché la proprietà senza un meccanismo di controllo rimane solo un'intenzione.

Il modello fallimentare classico è un proprietario della documentazione che deve rincorrere tutti gli altri. Questo approccio funziona al massimo per un paio di mesi.

Testare la documentazione

L'equivalente di un test di ripristino, e altrettanto trascurato.

Prendi qualcuno che non ha costruito il sistema, forniscigli solo la documentazione e chiedigli di completare un'attività operativa di routine. Un riavvio controllato, un failover, un ripristino in un ambiente di test.

Tutto ciò che non riescono a fare basandosi sulla documentazione è una lacuna. Tutto ciò che sbagliano è un difetto. Questo processo può essere scomodo, ma è l'unico modo affidabile per sapere se la documentazione funzionerebbe alle 3 del mattino, poiché la persona che l'ha scritta può sempre colmare le lacune attingendo alla propria memoria.

Fai questo test per i sistemi di livello 1 almeno una volta all'anno, idealmente come parte di una simulazione (game day) o di un'esercitazione di DR.

Best practice

• Applica il test delle 3 del mattino a qualsiasi contenuto prima di scriverlo.

• Documenta il livello 1 in modo approfondito e il livello 3 in modo minimo.

• Documenta le dipendenze in entrambe le direzioni, indicando l'ordine di avvio.

• Mai inserire credenziali, documenta sempre i metodi di accesso.

• Inserisci la data di ultima verifica su ogni record.

• Automatizza tutto ciò che è rilevabile, scrivi a mano solo l'intento e la conoscenza operativa.

• Aggiornamenti della documentazione imposti dal processo di gestione delle modifiche.

• I runbook devono includere cosa non fare.

• Test di ripristino datati all'interno del piano di DR.

• Testa la documentazione con qualcuno che non ha familiarità con il sistema, ogni anno.

Errori comuni

• Credenziali salvate nella wiki.

• Tutto documentato con la stessa profondità, con il risultato che nulla viene aggiornato.

• Dipendenze documentate in una sola direzione.

• Nessun ordine di avvio specificato, quindi il ripristino richiede più tempo dell'interruzione stessa.

• Dump di configurazione obsoleti non appena creati.

• Diagrammi senza data e senza proprietario, di cui ci si fida molto tempo dopo che hanno smesso di essere veritieri.

• La documentazione intesa come deliverable finale del progetto, mai più aggiornata in seguito.

• Una sola persona nominalmente responsabile di tutta la documentazione.

• Piani di DR memorizzati sulla stessa infrastruttura che dovrebbero coprire.

• Backup documentati, ma ripristini mai testati.

• Nessuna data di ultima verifica, impedendo ai lettori di valutare cosa sia attendibile.

• Documentazione scritta da chi ha creato il sistema e mai testata da nessun altro.

Cattura ciò che solo chi ha costruito il sistema sa

Apri i modelli in Trupeer AI, applica il tuo kit del brand in modo che la documentazione rispetti i tuoi standard e modifica direttamente qualsiasi sezione. La configurazione è descritta nella guida ai modelli.

L'automazione copre ciò che esiste. Ciò che non può catturare è la conoscenza operativa: l'ordine con cui le cose devono ripartire, il controllo da fare prima del failover, il motivo per cui nessuno riavvia quel servizio di martedì.

Quella conoscenza risiede nella mente di una o due persone e scompare con loro quando lasciano l'azienda. Chiedi loro di effettuare un failover o un ripristino mentre registrano lo schermo e Trupeer AI produrrà il runbook scritto e un video tutorial narrato dallo stesso passaggio, seguendo l'ordine con cui lo fanno effettivamente anziché l'ordine con cui ricorderebbero di scriverlo.

Inoltre, richiede molto meno tempo rispetto alla scrittura, un aspetto cruciale perché il motivo per cui la conoscenza operativa rimane non documentata è che le persone che la possiedono sono anche le più impegnate. Traducila in oltre 65 lingue per i team distribuiti e conserva la raccolta nella tua knowledge base insieme ai runbook.

Registrala. Personalizzala con il tuo brand. Traducila. Falla con Trupeer.

Domande frequenti

Esiste un modello gratuito di documentazione dell'infrastruttura in Word?

Sì. Word è ideale per ospitare i runbook, la panoramica dell'architettura e il piano di DR, ovvero le parti che hanno una struttura propriamente narrativa. Download gratuito, nessuna registrazione richiesta, nessuna filigrana.

Esiste un modello gratuito di documentazione dell'infrastruttura in Excel?

Sì, ed Excel svolge la maggior parte del lavoro. Include l'inventario dei sistemi con livelli di criticità e date di ultima verifica, la matrice delle dipendenze bidirezionali, i dettagli di rete, il tracciamento della scadenza dei certificati e la pianificazione delle revisioni.

Esiste un modello gratuito di documentazione dell'infrastruttura in PDF?

Sì, utile per le versioni approvate e per tutto ciò che un revisore o un cliente chiede di vedere. Ti consigliamo però di mantenere modificabili le copie di lavoro, poiché la documentazione dell'infrastruttura che non può essere aggiornata rapidamente finisce per non essere aggiornata affatto.

Posso scaricare un modello gratuito di documentazione dell'infrastruttura?

Sì, ogni formato è scaricabile gratuitamente senza necessità di creare un account e senza obbligo di attribuzione.

Esistono modelli gratuiti di documentazione IT?

Sì. Questa pagina copre specificamente l'infrastruttura. Per la documentazione IT in senso più ampio, inclusi processi, policy e guide pratiche, consulta esempi e modelli di documentazione IT, mentre per le procedure IT vedi il modello SOP IT.

Esiste un modello di documentazione IT in Word?

Sì, alla pagina esempi e modelli di documentazione IT. Questa pagina è più specifica e copre i sistemi, le reti e le dipendenze che compongono l'infrastruttura.

Esiste un modello di documentazione di progetto in Word scaricabile gratuitamente?

Sì, alla pagina del modello di documentazione di progetto. La documentazione di progetto copre l'ambito, il piano e i deliverable di un progetto, mentre la documentazione dell'infrastruttura copre ciò che esiste in produzione, indipendentemente da quale progetto lo abbia creato.

Cos'è la documentazione dell'infrastruttura IT?

Una registrazione dei sistemi, delle reti, dei servizi e delle dipendenze che compongono il tuo ambiente, insieme alla conoscenza operativa necessaria per gestirli e ripristinarli. Copre ciò che esiste, cosa dipende da cosa, qual è il comportamento normale e come rispondere quando qualcosa si rompe.

Cosa dovrebbe includere la documentazione dell'infrastruttura?

Un inventario dei sistemi con proprietari e criticità, dipendenze in entrambe le direzioni con ordine di avvio, dettagli su rete e connettività, runbook per i sistemi critici, metodi di accesso ma mai le credenziali, dettagli su backup e disaster recovery (incluso l'ultimo test di ripristino andato a buon fine) e una data di ultima verifica su ogni elemento.

Come si mantiene aggiornata la documentazione dell'infrastruttura?

Documentando di meno, automatizzando tutto ciò che è rilevabile e collegando gli aggiornamenti della documentazione al processo di gestione delle modifiche, in modo che una modifica non sia considerata completata finché la documentazione non la rispecchia. Inserisci una data di ultima verifica visibile su ogni record, effettua le revisioni in base al livello di criticità e consenti a chiunque di correggere immediatamente gli errori anziché dover aprire un ticket.

Le credenziali dovrebbero essere memorizzate nella documentazione?

No. Né password, né chiavi API, né stringhe di connessione o chiavi private, in nessun sistema, né temporaneamente né in altro modo. Documenta invece quale vault o secrets manager conserva la credenziale, chi può concedere l'accesso e la procedura break-glass per le emergenze. Questo è ciò di cui si ha realmente bisogno durante un incidente ed è sicuro da scrivere.

Quanto dell'infrastruttura si dovrebbe documentare?

Abbastanza da superare il test delle 3 del mattino per i sistemi critici, e pochissimo per il resto. I sistemi di livello 1 necessitano di runbook completi, mappe delle dipendenze e DR testato. I sistemi di livello 3 necessitano solo di una riga di inventario e di un proprietario. Documentare tutto con la stessa profondità è il motivo per cui la maggior parte della documentazione dell'infrastruttura finisce per diventare obsoleta.

Cos'è un runbook?

Un documento operativo per un singolo sistema che descrive il comportamento normale, il significato degli avvisi comuni, come riavviarlo in sicurezza (compresi l'ordine e i prerequisiti), le modalità di guasto note, cosa non fare e quando avviare l'escalation. È il documento che si apre durante un incidente e dovrebbe essere scritto per una persona competente ma che non ha familiarità con quello specifico sistema.

Come si documentano le dipendenze?

In entrambe le direzioni, poiché durante un incidente è necessario sapere sia di cosa ha bisogno questo sistema, sia cosa smette di funzionare se si ferma. Includi l'ordine di avvio, se ciascuna dipendenza sia forte o debole e le dipendenze esterne come identity provider, DNS e processori di pagamento, che causano interruzioni che non puoi risolvere direttamente.

Con quale frequenza deve essere rivista la documentazione dell'infrastruttura?

In base al livello di criticità: trimestralmente per il livello 1, semestralmente per il livello 2 e in caso di modifica per il livello 3. Oltre alle revisioni pianificate, il processo di gestione delle modifiche dovrebbe imporre gli aggiornamenti e chiunque scopra un errore durante un incidente dovrebbe essere in grado di correggerlo immediatamente.

Come fai a sapere se la tua documentazione funziona davvero?

Testala. Prendi qualcuno che non ha costruito il sistema, forniscigli solo la documentazione e chiedigli di eseguire un'attività operativa di routine, come un riavvio controllato o un ripristino in un ambiente di test. Tutto ciò che non riesce a fare rappresenta una lacuna. Eseguire questo test annualmente per i sistemi di livello 1 equivale a un test di ripristino, ed è altrettanto spesso saltato.

Posso personalizzare questo modello di documentazione dell'infrastruttura?

Sì, ogni versione è completamente modificabile. Adatta i livelli di criticità e i campi al tuo ambiente. I due elementi che vale davvero la pena mantenere sono la data di ultima verifica e la mappatura bidirezionale delle dipendenze, poiché sono questi che determinano se la documentazione è ritenuta attendibile e se risulta utile durante un incidente.

Modelli correlati

• Esempi e modelli di documentazione IT

• Modello SOP IT

• Modello di documentazione tecnica

• Modello di documentazione software

• Modello di documentazione di progetto

• Modello SOP per il trasferimento della conoscenza

• Modello di documento di passaggio consegne (Handover)

• Modello di metodo di procedura (MOP)

• Modello di policy di protezione dei dati