Приветствую, друг!

На предстоящем nexthop-е команда NOC Яндекса собирается проводить некий ивент, связанный с их софтиной - Аннушкой, она же annet.

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

Зачем тебе это читать? Если “читать чужой код” так же больно для тебя, то вполне может оказаться полезным. А т.к я пишу это уже после 3-х увлекательных вечеров путешествия в дебри чужого кода - читать исходники тут придется. Потыкаем сам инсторумент, закроем пробел в доке с hello world лабой и даже не только gen поглядим, но и все остальные методы (обязательные и не очень), а еще и netbox зацепим. Это факультативно т.к нужное можно и руками натыкать в GUI.

Почему решил смотреть именно эту репу? Совпало желание с контекстом + достаточно мало инфы, а продукт очень даже интересный.

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

Что есть annet?

Кто/(Что) такое “Аннушка” и почему “Аннушка”?

Аннушка или Annet - внутренняя софтина в сетевой автоматизации Яндекса, которая призвана решить вопрос с управлением конфигами т.е умеет в генерацию, дифф и даже заливку на мультивендорное оборудование средствами gnetcli.

Не берусь утверждать, но первое публичное выступление про annet было на Nexthop 2018 от Алексея Андриянова одного из разработчиков. Тогда инструмент был еще сырой и сам Алексей описывал его как “собранный на коленке”, НО отвечающий текущим потребностям.

В опенсорс annet вышла лишь ~10 месяцев назад. Времени с 2018 утекло не мало, инструмент подрос и оперился логикой. В опенсорсе, как я понял, лежит некоторый билд, а основной инструмент живет и развивается в стенах Я.

“Аннушка” потому что да, потому что Булгаков и потому что конфиги мы “льем”, а не “катим” :)

На Nexthop 2022 уже Федор Жуков рассказывал более интересные вещи. По факту про то, что изменилось с Nexthop 2018 и как теперь используется Аннушка:

  • с annet научили работать в едином пайплайне т.е теперь нет необходимости запускать annet на ноуте инженера (такова была идеология раньше);
  • теперь работает с Netbox;
  • появились тесты.

Глобально, инструмент разрабатывается по принципу атомарности конфигов т.е не пытается описать все и сразу, как это делает YANG, например, а делает это секциями.

Я не возьмусь нарисовать архитектуру инструмента, но вот основные куски, которые мне удалось “распарсить”:

Примерный набор кусочков архитектуры annet

Если вы знаете больше - добро пожаловать в комментарии, с удовольствием поправлю.

Немного статистики:

У меня ушло около 3 вечеров на путь от “да какого хрена тут происходит” до “о, круто! я смог создать vlan через deploy!”.

Причина тому - достаточно скудная документация. Есть кусочек в README и отдельно кусочек, который нужно сбилдить из исходников и сделать open index.html. А т.к информации у нас и так кот наплакал, то определенно не стоит пропускать “сборочную” доку.

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

Пару вопросов удалось решить прям не отходя от кассы и это круто!

Как сбилдить доку написано в README, но я таки продублирую. Сначала нужно склонировать основную репу annet в нужный каталог на локальной тачке, а затем собирать доку т.к requirements-doc.txt лежит в корне:

mkdir myproject
cd myproject
git clone git@github.com:annetutil/annet.git

Установить зависимости из requirements-doc.txt:

pip install -r requirements-doc.txt

Собрать:

sphinx-build -M html docs docs-build

Открыть docs-build/html/index.html.

Изучаем документацию

Интереса ради, попробуем двигаться прям по документации, но с некоторыми уточнениями (которые все равно нам не помогут).

Первая страница документации, описание

Первая страница содержит достаточно много полезной инфы. Мы сразу можем выяснить, что получится “пообщаться” с такими вендорами как: Huawei, Cisco IOS, Cisco NX-OS, Juniper. Устройства, настроенные через файлы, типа Linux, FreeBSD and Cumulus туда же.

А еще активно пилят RouterOS и, судя по коммиту, B4com.

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

Основные методы

Это, как не сложно догадаться, основной инструментарий:

  • annet gen на основе самописных генераторов генерит либо конфиг целиком, либо по частям;
  • annet diff сначала делает gen затем делает diff предварительно спросив у устройства его конфиг. (конфиг можно передать и файлом, как доп. аргумент);
  • annet patch сначала сделает diff затем выведет конфиг, который будет залит на устройство;
  • annet deploy сначала сделает patch попросит его подтвердить, а после пойдет лить на устройство.

Диагностические методы

Инструмент обладает очень подробным логом (запилено с помощью logger, что круто) включается annet --log-level DEBUG. Из интересного, это метод show:

  • annet show группа команд по запросу полезной предварительной инфы;
    • current сходит на коробку и покажет текущий конфиг;
    • device-dump сходит в инвентори и покажет структуру конкрентой коробки;
    • generators покажет какие есть генераторы на данный момент.

Ну и обычная справка:

  • annet -h - ожидаемо, справка;
  • annet gen -h - с правка по конкретному методу.

Визуальные методы

Визуальным, потому что есть возможность взять два файла (новый и старый конфиг) скормить их одному из двух методов:

  • annet file-diff позволяет получить дифф как в гите :);
  • annet file-patch визуально будет показан патч, который нужно “долить” на старый конф;

Внутрь обоих пока не копал, но работает только с заявленными вендорами (от Eltex ESR не прожевал).

Конфигурационные методы

Сюда можно определить только метод context, он позволяет манипулировать файлом context.yml.

Из README на гитхабе (а так же это есть в справке к методу context), можно вытянуть инфо об еще одной переменной окружения ANN_SELECTED_CONTEXT с помощью нее можно переписать selected_context, который определяется в context.yml

  • annet context группа команд по манипуляции с context.yml;
    • touch покажет путь до текущего файла с контекстом;
    • set-context устанавливает контекст (определяются в файле `context.yml);
    • edit открывает файл в либо в редакторе, что прописан в $EDITOR если пустая, то для винды - notepad++, для остального - vi;
    • repair должен чинить структуру context.yml, если есть артефакты от старых версий, но я эффекта не увидел.

Вторая страница содержит установку инструмента и пример (неправильный) файла context.yml:

Вторая страница документации, установка

Если пройдете по шагам, описанным в установке, у вас, ожидаемо, ничего не получится…по многим причинам..

Я работаю на MacOS, поэтому далее везде будут описаны препоны именно данной ОС (возможно, будет работать и для Linux)

Начинаем как обычно, создать директорию, создать окружение python…Тут все отлично, это можем делать:

mkdir myproject
cd myproject
python3 -m venv venv
source venv/bin/activate

А вот дальше начинаются варианты. Я делал (в том числе) как в инструкции, но, как мне кажется, верный путь это использовать setup.py в корне самой репы.

Для начала обновим pip и вспомогательные инструменты по сборке:

pip install --upgrade pip setuptools wheel build

Далее делал git clone annet:

git clone git@github.com:annetutil/annet.git

Переходим в корень репы и запускаем setup.py, который лежит в корне, с ключом install:

cd annet
python setup.py install

Не тратил время на разбор, что же там внутри, но оно точно закидывает в pip нужные модули и дотягивет все остальные зависимости (все ли?).

Далее предлагается создать файл context.yml в корне домашней директории, сделаем это, но наполнять тем, что указано в доке, не будем, оно не работает.

touch ~/.annet/context.yml

Мое любимое! Предлагается и генератор написать и из вима потом как-то выйти…ладно, шутка уже не смешная (:q!):

# write generators
vim /path/to/myproject/my_generators/__init__.py

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

Чтобы поехало - надо наконфигурить то, что мы будем использовать. Прыгаем в секцию Configurations:

Третья страница документации, конфигурация

Нам сразу говорится, что есть ордеринг (очередность чтения) файла context.py в зависимости от его расположения.

Порядок следующий:

  • ANN_CONTEXT_CONFIG_PATH переменная окружения, туда можно записать расположение, какое заблагорассудится и оно будет приоритетным
  • ~/.annet/context.yml то место, где мы, чуть ранее, создали файл context.yml
  • annet/configs/context.yml лежит внутри склонированного репозитория, пусть там и остается, до него очередь у нас не дойдет

Далее идет важная секция - Storages, в логике annet это варианты нашего инвентори т.е информация об устройствах аля имя, хостнейм, IP-адрес, модель и т.п Это может быть либо файл, либо нетбокс (других вариантов я не нашел).

Будем использовать нетбокс (это интересней!) для него можно установить две обязательные переменные и, я так понял, инфа о подключении приоритетно будет тянуться оттуда, либо добавить эти строчки в context.yml, тогда будут браться оттуда (но это не точно).

В следующих частях отдельно поглядим на context.yml:

Что за переменные? NETBOX_URL - указывает на наш инстанс с нетбоксом, а NETBOX_TOKEN определяет API-токен. В факультативной части на этом остановимся подробнее.

export NETBOX_URL="https://demo.netbox.dev"
export NETBOX_TOKEN="1234567890abcdef01234567890abcdef0123456"

Последняя страница именуется как Extending, на нее пока смотреть не будем, но annet может и так - настроить сеанс и интерфейсы устройства BGP на основе общих правил и соединений с другими устройствами.

Четвертая страница документации, расширение

На этом дока заканчивается, а мы остаемся с кучей вопросов…

Но мы то только начали! Увидимся в скором продолжении.

Поглядим на структуру проекта, разберемся что за context.yml, попробуем потыкать методы, справимся с ошибками несовпадения версий netbox, погуляем по исходникам, поймем, зачем же в названии устройства annet докидывает точку…

Факультативная часть, которая выйдет пораньше т.к уже почти проделана и написана, будет настройка лабы Netbox+pnetlab+VMWare WS Pro.

Trust me!

Хочешь обсудить тему?

С вопросами, комментариями и/или замечаниями, приходи в чат или подписывайся на Telegram-канал.