Привет Хабр! Доводилось ли вам испытывать трудности с документацией на корпоративные Voice и Unified Communications инфраструктуры?

• Что это за номер? Откуда он приходит?
• Этот SIP-транк еще актуален?
• В каком из этих Excel-файлов нужная мне информация?
• Есть у нас свободный городской номер для новой услуги?
• Телефонные_номера_новый_072019(3).xlsx?!

Звучит до боли знакомо? Есть вариант, который может с этим помочь.
Всем заинтересовавшимся добро пожаловать под кат!

TLDR: Использование парадигмы Source of Truth (и NetBox как его реализации) в сфере Voice и Unified Communications может быть полезным и перспективным. А еще я разработал и опубликовал новый плагин для NetBox для управления телефонными номерами и еще много чем.

Как и что компании документируют

Начиная с 2011 года, когда я начал свою карьеру в корпоративном ИТ, я видел множество вариантов организации документации. Я работал с распределенными Voice и UC инфраструктурами с тысячами пользователей, отказоустойчивыми кластерами, сотнями голосовых устройств и каналов связи в сумме. Однако, независимо от региона и размера, у всех этих инфраструктур было что-то общее: вся документация на Voice и UC состояла из Microsoft Office и PDF файлов разной степени упорядоченности.

Хороший вопрос, насколько репрезентативна эта выборка. Но, судя по разговорам с другими инженерами из индустрии, это довольно типичная ситуация. (Расскажите и вы о своем опыте в комментариях.) Специализированные решения для документирования Voice и UC не очень распространены в корпоративном секторе. "И в чем проблема?" — возможно, спросите вы. Давайте попробуем в этом разобраться.

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

1. Документация на внедрение и пояснительные записки. Каков дизайн и как это все должно работать?
   Подобный пакет документации той или иной степени ГОСТовости обычно можно найти во многих компаниях.
2. Сетевые и специфические для этой сферы диаграммы. Как взаимосвязь компонентов выглядит визуально? Это может быть составной частью п.1.
3. Инвентарная информация. Какие физические и виртуальные компоненты у нас есть: Voice и UC оборудование, виртуальные машины, модули PRI, DSP и т.д. Их модели, парт-номера, серийники и подобное обычно тоже попадает в эту категорию.
4. Кабельный журнал и детали о взаимосвязях. Как скроссированы кабели между патч-панелями и между портами? Те, кто провел незабываемые часы, разбираясь с кроссировками от легаси АТСок с тестером и прозвонкой, вероятно, понимающе вздохнут на этом пункте. *Вздыхает.* Но и в VoIP окружениях эта информация не менее полезна.
5. IP-адресация. Как мы назначаем IP-адреса на устройства?
6. Голосовые каналы связи. Какие каналы связи у нас есть: SIP-транки, PRI, медь и т.д. Полезно и важно знать, какие у них параметры, и какое количество соединительных линий они имеют.
7. Телефонные номера. Какие пулы городских и внутренних номеров у нас есть?
8. Маршрутизация вызовов. Как мы маршрутизируем номера и паттерны?
9. Детали о конфигурациях и их шаблоны. Какие конфигурации преобразуют п.1 в работающую инфраструктуру? Зачастую источником этой информации будут конфигурации на самих устройствах.
10. Информация о менеджмент-доступе. Как залогиниться на каждый из компонентов?
11. Внешние контракты и соглашения. Какие сервисы у нас есть и за что приходят счета? Поиск городских номеров по PDF-сканам договоров с провайдерами — занятие увлекательное. *Снова вздыхает*.

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

1. Нет четкой взаимосвязи между различными частями информации. Особенно, между различными документами.
2. Сложно искать, индексировать и версионировать информацию, хранящуюся разрозненно во множестве файлов.
3. Требуется знать, какой файл за что отвечает и где он находится.
4. Информация может дублироваться в различных документах.
5. Эту информацию сложно валидировать и сравнить с актуальным состоянием инфраструктуры.
6. Построение отчетности требует дополнительных трудозатрат и ручного сведения и преобразования данных.
7. Может не быть целостной картины инфраструктуры. Команды, отвечающие за сеть и за Voice/UC, могут работать независимо друг от друга. Отсутствие общих инструментов может затруднять коммуникации и усложнять решение кросс-функциональных задач (например, настройку end-to-end QoS на сети для голосового трафика).

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

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

UC Infrastructure-as-Code и UC Source-of-Truth

Одно из решений, к которому пришла индустрия ИТ, это Infrastructure-as-Code (IaC) в совокупности с Single-Source of-Truth (или просто Source-of-Truth, SoT). Эти подходы переопределяют то, как рассматриваются инфраструктуры и как в них вносятся изменения:

• Инфраструктура начинает рассматриваться как совокупность машино-читабельных скриптовых (реже) или декларативных (чаще) конфигураций. Этот подход в свою очередь позволяет переиспользовать многие практики из области традиционной разработки ПО, тестирования и DevOps.
• Single Source of Truth (или Source-of-Truth, SoT), он же Единый Источник Правды или просто Источник Правды — это подход, при котором определяется и фиксируется единственный источник происхождения и внесения изменений для каждого отдельного взятого фрагмента информации об инфраструктуре. Это не обязательно означает, вся информация должна храниться в едином месте или системе. И не предполагает, что не может больше существовать несколько копий какой-то информации в разных местах. Ключевое требование — именно наличие единственного мастер-источника для каждого типа данных.
• Изменения применяются на инфраструктурные компоненты не напрямую. Сначала они вносятся в Source-of-Truth. Затем происходит их автоматическая валидация, применение к скриптовым или декларативным моделям Infrastructure-as-Code, тестирование и уже после всего этого (в идеале), доставка на целевые устройcтва и виртуальные машины средствами выбранного стека автоматизации.

Souce-of-Truth содержит целевое состояние инфраструктуры. Задача стека автоматизации — привести текущее состояние инфраструктуры в соответствие с Souce-of-Truth на основе скриптовых или декларативных моделей IaC. Это устраняет проблему неактуальнйо документации, так как теперь изменения в инфраструктуре применяются на основании изменений в документации.

Важно заменить, что переход от традиционных сценариев работы к Source-of-Trust и Infrastructure-as-Code не обязательно предполагает революционное изменение за один шаг. Вполне возможно (и даже нужно) мигрировать процессы и процедуры постепенно. Перестроение стека и подхода к документированию инфраструктуры может быть хорошей стартовой точкой в этом вопросе.

В принципе, при наличии достаточного времени и усердия, Excel позволяет реализовать сколь угодно сложные сценарии работы внутри себя: его формулы полны по Тьюрингу. Но поддержка такого решения может быть кошмаром. К тому же возможность интеграции с какими-то внешними системами будет довольно ограничена. Это приводит нас к необходимости использование специализированных систем.

В целом, подобные концепции и утилиты уже широко используются DevOps-инженерами. Будучи примененными к сфере сетевых технологий, они получили распространение и значительно развились в последние годы в виде NetDevOps. И я уверен, многие из этих практик применимы и в сфере UC. Не говоря уже о том, что UC даже может делить с традиционными сетевыми функциями общие платформы и ресурсы. Первоначальный провиженинг (может подскажете русский аналог этого емного англицизма?) маршрутизатора или коммутатора и SBC — во многом схожие задачи. Как и автоматизация настройки BGP-пиринга во многом сравнима с таковой для SIP-транков.

Многие практики, средства и системы из NetDevOps могут быть перенесены в сферу UC. Одной из таких систем является NetBox.

Почему NetBox

И очевидный вопрос: "А что такое NetBox?" Емкий ответ от его разработчиков в моем вольном переводе:

NetBox — это веб-приложение с открытым исходным кодом, призванное помочь в управлении и документировании компьютерных сетей. Будучи изначально задуманным командой сетевых инженеров из DigitalOcean, NetBox был разработан специально для удовлетворения потребностей инженеров-сетевиков и инфраструктурщиков. Он охватывает следующие аспекты управления сетью:

• IP address management (IPAM) — IP сети и адреса, VRF'ы и VLAN'ы.
• Equipment racks — Стойки для оборудования, организованные по группам и площадкам.
• Devices — Типы устройств и то, где они установлены.
• Connections — Сетевые, консольные подключения и электропитание устройств.
• Virtualization — Виртуальные машины и кластеры.
• Data circuits — Внешние каналы передачи данных и провайдеры.
• Secrets — Зашифрованное хранилище чувствительных логинов и паролей.

И еще подробнее о NetBox, не покидая Хабра, – в посте из цикла АСДМ от eucariot.

NetBox задуман как Network Source-of-Truth, Источник Правды о Сети. В NetBox все является объектами и почти все доступно через API, что дает отличные возможности для интеграции NetBox с внешними системами. Объекты в NetBox взаимосвязаны и имеют под собой релиционную СУБД (PostgreSQL). NetBox основательно задокументирован и имеет хорошее сообщество, в том числе русскоязычное. Не удивительно, что популярность и распространенность NetBox растет по всему миру. Возможно, ваша команда сетевиков уже знает о нем.

Как вы уже могли заметить, список функционала NetBox покрывает некоторые категории из ранее обозначенного списка Voice и UC документации. Так (IP)-АТС, SBC, шлюзы, MCU и прочие Voice и UC компоненты точно являются устройствами (Devices). Как правило, их можно найти установленными в стойках (Equipment Racks) под ToR-коммутаторами. Они соединены друг с другом и с сетью различными подключениями (Connections) и могут терминировать на себе каналы связи (Data Circuits) от провайдеров телефонии (Providers), несущие поверх голосовую сигнализацию и трафик. Какие-то из Voice и UC функций могут иметь виртуальное исполнение (Virtual Machines). И все Voice и UC компоненты (если только это не легаси АТС) будут иметь IP-адреса (IPAM).

Но при этом некоторые важные данные, такие как Телефонные Номера, Голосовые Каналы Связи, и Маршрутизация Вызовов в этом списке отсутствуют. К счастью, в NetBox есть крайне мощный инструмент для расширения его фунционала — Плагины (Plugins). Они позволяют расширять схему данных NetBox и встраивать в него дополнительный функционал. В совокупности с нативными моделями данных NetBox подобный дал бы полный набор абстракций, необходимых для описания Voice и UC инфраструктур.

Несколько основных преимуществ такого подхода:

• Облегчается моделирование кросс-доменных взаимосвязей. Voice и UC компоненты значительно полагаются на сетевую инфраструктуру и взаимосвязаны с ней.
• Унифицируются инструменты для документирования сети и Voice с Unified Communications, что дает полную картину инфраструктуры.
• Общие инструменты документирования облегчают кросс-функциональные и межкомандные коммуникации.
• Построение отчетности и поиск данных становятся более гибкими и мощными.

И на этом моменте позвольте рассказать о PhoneBox плагине для NetBox.

PhoneBox Plugin

PhoneBox плагин задуман для того, чтобы устранить пробел между сетевыми и Voice&UC абстракциями в NetBox.
Я начал его разработку недавно и уже выпустил бета-версию, реализующую базовое управление Телефонными Номерами. Это позволяет начать причинять пользу уже сейчас. К тому же feature request'ы на подобный функционал от сообщества NetBox уже были.

Каждый Телефонный Номер (Phone Number) в плагине содержит следующий набор атрибутов:

• Number – Отдельно взятый телефонный номер. Могут быть неуникальными.
• Tenant – Обязательная зависимость с нативным Netbox объектом типа Tenant. Необходимо для организации партишенинга номерных планов. Уникальными должны являться пары Number-Tenant.
• Description – Опциональное описание для номера.
• Provider – Опциональная зависимость с нативным NetBox объектом типа Provider. Используется для указания провайдера, предоставляющего номер.
• Region – Опциональная зависимость с нативным NetBox объектом типа Region. Используется для указания географической принадлежности номера.
• Forward_To – опциональная зависимость с другим объектом плагина типа Number. Используется для моделирования сценариев с переадресацией одного номера на другой.
• Tags – Опциональная зависимость с нативными NetBox объектами типа tag.

В интерфейсе NetBox это выглядит примерно так:

Плагин поддерживает все CRUD (Create, Read, Update, Delete) операции над Телефонными Номерами (Phone Numbers) через веб-интерфейс NetBox и его REST API.
Также реализована возможность массового импорта Телефонных Номеров и их атрибутов из CSV-файлов для облегчения миграции данных.

Исходный код плагина и инструкции по его установке и активации внутри NetBox доступны на моей странице на GitHub.

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

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