Надёжная внутренняя документация по инфраструктуре защищает вашу компанию от простоев, аудитов и инцидентов безопасности. С Trupeer вы можете сэкономить часы на документации по инфраструктуре, начав с бесплатного шаблона, настроив его с помощью ваших бренд-гайдлайнов и превращая документацию в видеообходы для команд IT и MSP.

Большинство документаций по инфраструктуре пишется один раз — во время проекта — и уже через шесть месяцев оказывается неверной. Она остаётся на вики, ей никто не доверяет, и во время следующего инцидента кто-то её читает, сомневается и звонит тому, кто действительно знает.

Исправление — это не больше документации. Это меньше документации, которая остаётся актуальной, выбранной через вопрос о том, что человеку реально понадобится в три часа ночи.

Скачать шаблон документации по инфраструктуре

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

Какая документация вам нужна?

Как настроить этот шаблон в Trupeer

Шаг 1: Откройте раздел «Templates»

Перейдите в раздел Templates из главной навигации.

Шаг 2: Выберите и откройте шаблон

Нажмите на любой шаблон, с которым хотите работать, чтобы открыть его.

Шаг 3: Разверните просмотр шаблона

При необходимости разверните просмотр шаблона, чтобы увидеть полную структуру и детали.

Шаг 4: Отредактируйте шаблон

Нажмите Edit, чтобы начать изменять выбранный шаблон.

В редакторе вы можете:

• Добавлять новые разделы

• Задавать или обновлять правила форматирования

• Добавить логотип и настроить его положение и связанные параметры

Шаг 5: Сохраните настроенный шаблон

После того как вы внесёте все необходимые изменения, нажмите Save, чтобы сохранить обновлённый шаблон как свой.

Шаг 6: Предпросмотр и точная настройка шаблона

Когда вы захотите увидеть, как выглядит ваш настроенный шаблон, откройте Preview.

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

С шаблоном внутренней документации по инфраструктуре вы можете:

• Экономить часы на написании: пропускайте пустую страницу с структурой, созданной для IT-инфраструктуры.

• Улучшать уровень безопасности: встроенные поля закрепляют безопасные практики работы с учётными данными.

• Оставаться в рамках бренда: применяйте логотип, шрифты и цвета с помощью бренд-набора Trupeer.

• Сокращать время простоя: понятная документация снижает MTTR во время инцидентов.

• Быть готовыми к аудитам: соответствует SOC 2, ISO 27001 и аналогичным фреймворкам.

• Достигать глобальных команд: переводите документацию на 65+ языков одним кликом.

Тест на три часа ночи

Единственный тест, который действительно важен для документации по инфраструктуре.

Представьте инцидент в три часа ночи. Человек, который собирал систему, сейчас в самолёте. Кто-то компетентный, но незнакомый с вашей документацией, смотрит на неё. Сможет ли он понять, что сломалось, от чего это зависит, что произойдёт, если он перезапустит это, и кому нужно эскалировать?

Всё, что помогает в этом, стоит записывать. Всё остальное — опционально, а опциональная документация размывает полезные части и съедает бюджет на поддержку.

Применяйте это безжалостно. Подробная история о том, почему технологию выбрали в 2021 году, не проходит. Заметка о том, что этот сервис нужно запускать после базы данных и до API gateway, — тоже.

Что проходит тест на три часа ночи

• Что существует. Системы, серверы, сервисы — и что делает каждый из них в одном предложении.

• Где это находится. Провайдер облака и регион или физическое расположение и стойка.

• От чего зависит и что зависит от него. Самая ценная вещь в документации по инфраструктуре.

• Как до него добраться. Хостнеймы, адреса, консоли — но никогда не учётные данные.

• Как выглядит «нормально». Чтобы незнакомый человек мог понять, что что-то действительно не так.

• Что это ломает. Известные сценарии отказов и их симптомы.

• Как безопасно перезапустить, включая порядок и всё, что нужно сделать в первую очередь.

• Кто владелец, и маршрут эскалации с реальными контактными данными.

• Каков радиус последствий. Что пойдёт вниз, если это произойдёт.

Что обычно не проходит

Написано ради полноты, а не ради использования, поэтому это не стоит поддерживать.

Полные дампы конфигураций, которые устаревают на следующий день после экспорта. Подробные обоснования прошлых решений, которые должны быть в архитектурной записи (architecture decision record), а не в операционной документации. Каждый параметр каждой системы, когда операционно важны лишь несколько. Скриншоты консолей, которые быстро стареют и редко помогают. И всё, что дублирует источник правды где-то ещё, потому что две копии означают, что одна неверна, и вы не можете понять, какая именно.

Общий принцип: если это можно обнаружить в системе быстрее, чем прочитать в документе, не документируйте это.

Инвентаризация инфраструктуры

Основа. Одна строка на систему или сервис.

Последнее поле — то, которое чаще всего пропускают в инвентаризациях, и то, которое определяет, доверяют ли документу. Строка, которую никто не проверял два года, должна выглядеть явно недоверенной, а не молча неверной.

Уровни критичности

Определите их, потому что они определяют, сколько документации заслуживает каждая система.

Большинство организаций документируют уровень 3 на той же глубине, что и уровень 1, заканчиваются силы, и в итоге всё оказывается задокументированным наполовину. Правильно сделайте уровень 1 и пусть уровень 3 будет одной строкой.

Зависимости

Самая ценная и при этом самая игнорируемая часть документации по инфраструктуре.

Во время инцидента вопрос редко звучит так: «Что сломалось?». Обычно это: «Что ещё затронуто?» и «Что нужно этому, чтобы вернуться в рабочее состояние?». Ни то, ни другое нельзя обнаружить из списка серверов.

Документируйте зависимости в обе стороны:

Две вещи делают это полезным. Порядок запуска — потому что перезапуск в неправильной последовательности превращает короткий инцидент в долгий. И то, является ли зависимость «жёсткой» или «мягкой», потому что сервис, который деградирует корректно, — это совсем другая проблема, чем сервис, который падает сразу.

Включайте внешние зависимости. Провайдеры платежей, провайдеры идентификации, DNS, центры сертификации и API SaaS вызывают простои, которые вы не можете исправить самостоятельно, и знание об этом быстро стоит очень многого в 3 часа ночи.

Сетевая документация

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

Runbooks

Документ, который человек действительно открывает во время инцидента.

Раздел «Чего не делать» встречается редко и ценен. У каждой зрелой системы есть действие, которое кажется разумным и делает инцидент хуже: перезапуск в неправильном порядке, очистка кэша, который перестраивается шесть часов, или фейловер, когда вторичная система отстаёт.

Пишите runbooks для систем уровня 1 и для всего, что уже приводило к инциденту. Не для всего подряд.

Доступ и учётные данные

Раздел, где документация приносит вред, а не предотвращает его.

Никогда не размещайте учётные данные в документации. Не пароли, не ключи API, не строки подключения со встроенными секретами, не приватные ключи. Не на вики, не в Excel-файле, не «временно».

Документируйте способ доступа. Какая система хранит учётные данные, кто может предоставить доступ и как человек запрашивает его в 3 часа ночи. Именно это нужно человеку на практике, и это безопасно записывать.

Затем правильно документируйте процедуру break-glass, потому что отсутствие экстренного доступа во время экстренной ситуации — частая и предотвратимая причина отказа.

Аварийное восстановление (Disaster recovery)

Что должна содержать документация по DR, чтобы иметь смысл.

Целевое время восстановления (recovery time) и целевая точка восстановления (recovery point) для каждой системы уровня 1 — согласованные с бизнесом, а не предполагаемые IT. Что на самом деле представляет собой процедура восстановления, шаг за шагом. Где находятся резервные копии и, критически важно, когда в последний раз восстановление успешно тестировали. Кто объявляет катастрофу и кто запускает план. Как команда сообщает, когда обычные системы недоступны, потому что DR-план, хранящийся только на тех системах, которые сейчас недоступны, — знакомый и неловкий сценарий.

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

Диаграммы

Инфраструктура выигрывает от диаграмм больше, чем большинство других типов документации, и они устаревают быстрее.

• Одна диаграмма верхнего уровня с основными компонентами и тем, как они связаны. Именно ей люди реально пользуются.

• Сетевая топология, когда окружение достаточно сложное и без неё не обойтись.

• Потоки данных, особенно там, где они пересекают границы доверия или юрисдикции.

• Держите их простыми. Диаграмма, которую никто не может прочитать с первого взгляда во время инцидента, — это декор.

• Добавляйте дату, и указывайте владельца.

• Предпочитайте диаграммы-as-code, если ваша команда будет их поддерживать: диаграмма в текстовом формате с контролем версий обновляется вместе с изменением, а не «потом».

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

Поддерживайте актуальность

Вся проблема — и причина, по которой большая часть документации по инфраструктуре не работает.

• Документируйте меньше. Точность обратно пропорциональна объёму. Пятнадцать точных страниц лучше, чем двести устаревших.

• Привязывайте обновления документации к процессу изменений. Изменение, которое затрагивает инфраструктуру, не завершено, пока документация не отражает его. Это единственный механизм, который стабильно работает.

• Автоматизируйте то, что можно обнаружить. Инвентаризация, адреса, конфигурации и топология часто генерируются. Сгенерированная документация не устаревает так, как устаревает рукописная.

• Пишите вручную только то, что нельзя обнаружить. Назначение, владелец, критичность, зависимости, известные сценарии отказов, чего не делать. Машины не могут вывести ничего из этого.

• Добавляйте дату ко всему, и показывайте её заметно. Видимая дата последней проверки помогает читателям калибровать уровень доверия.

• Проверяйте по расписанию в зависимости от уровня, ежеквартально для уровня 1.

• Исправляйте во время инцидентов. Момент, когда кто-то обнаружил, что документация неверна, — это момент, когда у него есть знания, чтобы её исправить. Сделайте это задачей на пять минут, а не тикетом.

Автоматизация и обнаружение

Стоит инвестировать, потому что это убирает крупнейший сценарий отказа.

Базы данных управления конфигурациями (CMDB), инвентаризации провайдеров облака, репозитории инфраструктуры как кода (infrastructure-as-code) и инструменты сетевого обнаружения — всё это может непрерывно генерировать точную информацию о текущем состоянии. Всё, что они могут произвести, не должно поддерживаться вручную.

Рабочее разделение: машины документируют то, что существует, а люди — что это значит. Автогенерируемая инвентаризация сообщает, что сервер существует и что на нём установлено. Только человек может сказать, что это именно тот сервер, который нельзя перезагружать между 2:00 и 4:00 из-за пакетного запуска (batch run).

Там, где инфраструктура определена как код, код — это документация того, что существует. Остаётся записать намерение (intent), операционные знания и сценарии отказов.

Кто владеет этим

Назначайте владельца для каждой системы, а не делайте документацию задачей одного человека — ведь она никогда не переживёт его уход.

Команда, которая эксплуатирует систему, владеет её документацией. Конкретный человек владеет общим стандартом, шаблонами и частотой проверок. А процесс изменений обеспечивает обновления, потому что владение без механизма — это намерение.

Паттерн отказа такой: владелец документации догоняет всех остальных. Это работает примерно два месяца.

Тестирование документации

Аналог теста восстановления — и так же часто игнорируемый.

Возьмите человека, который не собирал систему, дайте ему только документацию и попросите выполнить рутинную операционную задачу. Контролируемый перезапуск, фейловер, восстановление в тестовую среду.

Всё, что он не может сделать по документации, — это пробел. Всё, что он делает неправильно, — это дефект. Это неприятно, но это единственный надёжный способ понять, сработает ли документация в 3 часа ночи, потому что автор всегда может заполнить пробелы по памяти.

Делайте это минимум раз в год для систем уровня 1, а в идеале — в рамках game day или учений по DR.

Лучшие практики

• Применяйте тест на три часа ночи ко всему, прежде чем это писать.

• Правильно документируйте уровень 1 и минимально — уровень 3.

• Зависимости в обе стороны, с порядком запуска.

• Никогда не учётные данные, всегда — способы доступа.

• Дата последней проверки в каждой записи.

• Автоматизируйте всё, что можно обнаружить, а вручную пишите только intent и операционные знания.

• Обновления документации обеспечиваются процессом изменений.

• Runbooks включают то, чего не делать.

• Тесты восстановления с датами в плане DR.

• Тестируйте документацию с человеком, который не знаком с системой, ежегодно.

Частые ошибки

• Учётные данные на вики.

• Всё документируется на одинаковую глубину, поэтому ничего не поддерживается.

• Зависимости документируются только в одну сторону.

• Нет порядка запуска, поэтому восстановление занимает больше времени, чем простой.

• Дампы конфигураций, которые устаревают к моменту получения.

• Диаграммы без дат и без владельцев, которым продолжают доверять долго после того, как они перестали быть правдой.

• Документация как проектный результат, который больше не обновляют.

• Один человек формально отвечает за всё.

• Планы DR хранятся на инфраструктуре, которую они покрывают.

• Резервные копии задокументированы, восстановления никогда не тестировали.

• Нет даты последней проверки, поэтому читатели не могут понять, чему доверять.

• Написано человеком, который это собрал, протестировано никем.

Зафиксируйте то, что знает только тот, кто это собрал

Откройте шаблоны в Trupeer AI, примените ваш бренд-набор, чтобы документация соответствовала вашим стандартам, и отредактируйте любой раздел напрямую. Настройка описана в руководстве по шаблону.

Автоматизация покрывает то, что существует. То, что она не может передать, — это операционные знания: порядок, в котором всё возвращается в рабочее состояние, проверка, которую вы делаете перед фейловером, и причина, по которой никто не перезапускает этот сервис во вторник.

Эти знания живут у одного или двух людей и уходят вместе с ними. Пусть они пройдут через фейловер или восстановление, записывая процесс, а Trupeer AI сгенерирует письменный runbook и озвученный видеообход из того же прохода — в том порядке, в котором они делают это на практике, а не в том, в котором они бы вспоминали, когда писали.

И это занимает у них меньше времени, чем написание, что важно, потому что причина, по которой операционные знания остаются недокументированными, в том, что люди, которые их держат, самые загруженные. Переведите их на 65+ языков для распределённых команд и храните набор в вашей базе знаний рядом с runbooks.

Запишите. Оформите в бренде. Переведите. Trupeer it.

Часто задаваемые вопросы

Есть ли бесплатный шаблон документации по инфраструктуре в Word?

Да. Word хранит runbooks, обзор архитектуры и план DR — те части, которые действительно являются повествованием. Бесплатная загрузка, без регистрации, без водяного знака.

Есть ли бесплатный шаблон документации по инфраструктуре в Excel?

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

Есть ли бесплатный шаблон документации по инфраструктуре в PDF?

Да — как утверждённые версии и для всего, что нужно показать аудитору или клиенту. Держите рабочие копии редактируемыми, потому что документация по инфраструктуре, которую нельзя быстро обновить, не обновляется.

Могу ли я скачать бесплатный шаблон документации по инфраструктуре?

Да, каждый формат — это бесплатная загрузка без необходимости аккаунта и без указания авторства.

Есть ли бесплатные шаблоны документации по IT?

Да. Эта страница посвящена инфраструктуре. Для IT-документации в более широком смысле, включая процессы, политики и материалы с инструкциями, см. примеры и шаблоны IT-документации, а для IT-процедур — шаблон IT SOP.

Есть ли шаблон документации по IT в Word?

Да, на странице примеры и шаблоны IT-документации. Эта страница уже по фокусу: она охватывает системы, сети и зависимости, которые составляют вашу инфраструктуру.

Есть ли шаблон документации проекта в Word, который можно скачать бесплатно?

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

Что такое документация по IT-инфраструктуре?

Это запись систем, сетей, сервисов и зависимостей, которые составляют вашу среду, вместе с операционными знаниями, необходимыми для их работы и восстановления. Она охватывает то, что существует, от чего что зависит, как выглядит «нормально», и как реагировать, когда что-то ломается.

Что должна включать документация по инфраструктуре?

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

Как поддерживать документацию по инфраструктуре в актуальном состоянии?

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

Нужно ли хранить учётные данные в документации?

Нет. Не пароли, не ключи API, не строки подключения и не приватные ключи — ни в каких системах, временно или иначе. Вместо этого документируйте, в каком vault или secrets manager хранятся учётные данные, кто может предоставить доступ, и процедуру break-glass для экстренных случаев. Именно это нужно человеку во время инцидента, и это безопасно записывать.

Сколько инфраструктуры нужно документировать?

Достаточно, чтобы пройти тест на три часа ночи для критически важных систем, и очень мало — для остального. Системы уровня 1 требуют полных runbooks, карт зависимостей и протестированного DR. Системы уровня 3 требуют одной строки инвентаризации и владельца. Документирование всего на одинаковую глубину — причина того, что большинство документаций по инфраструктуре в итоге устаревают.

Что такое runbook?

Операционный документ для одной системы: как выглядит «нормально», что означают частые алерты, как безопасно перезапустить, включая порядок и предварительные условия, известные сценарии отказов, чего не делать и когда эскалировать. Это то, что человек открывает во время инцидента, и это должно быть написано для компетентного человека, который не знаком именно с этой системой.

Как документировать зависимости?

В обе стороны, потому что во время инцидента вам нужно знать и то, что требует эта система, и то, что сломается, если она остановится. Включайте порядок запуска, является ли каждая зависимость «жёсткой» или «мягкой», а также внешние зависимости — например, провайдеры идентификации, DNS и платёжные процессоры, которые вызывают простои, которые вы не можете исправить самостоятельно.

Как часто нужно пересматривать документацию по инфраструктуре?

По уровням критичности: ежеквартально для уровня 1, дважды в год для уровня 2 и при изменениях для уровня 3. Помимо запланированных проверок, процесс изменений должен принуждать к обновлениям, и любой, кто обнаружил ошибку во время инцидента, должен иметь возможность исправить её сразу.

Как понять, что ваша документация действительно работает?

Протестируйте её. Дайте человеку, который не собирал систему, только документацию, и попросите выполнить рутинную операционную задачу — например, контролируемый перезапуск или восстановление в тестовую среду. Всё, что он не может сделать, — это пробел. Ежегодное выполнение этого для систем уровня 1 — эквивалент теста восстановления, и так же часто пропускается.

Могу ли я настроить этот шаблон документации по инфраструктуре?

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

Связанные шаблоны

• примеры и шаблоны IT-документации

• шаблон IT SOP

• шаблон технической документации

• шаблон документации по ПО

• шаблон документации проекта

• шаблон SOP для передачи знаний

• шаблон документа для передачи дел

• шаблон метода процедуры

• шаблон политики защиты данных