netbox-incidents

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

Содержание

• Возможности
• Скриншоты
• Требования
• Установка
• Настройка
• Использование
  • Создание инцидента
  • Просмотр инцидентов на объектах
  • Список инцидентов
  • Отчёты
  • REST API
• Разработка
  • Миграции
  • Тестирование
  • Вклад в развитие
• Лицензия

Возможности

• Отдельная модель Incident:
  • Статус (Открыто / Закрыто)
  • Дата начала и окончания
  • Контактное лицо (выбор из tenancy.Contact, опционально фильтруется по группе)
  • Причина (настраиваемый список)
  • Комментарий (поддерживает Markdown, есть шаблон по умолчанию)
• Привязка к объектам:
  • Device
  • Interface
  • Module
  • Rack
  • Используется Generic Foreign Key — ровно один объект на инцидент.
• Вкладка «Incidents» на карточках Device / Interface / Module / Rack:
  • Список привязанных инцидентов
  • Форма быстрого добавления нового инцидента
• Стандартные механизмы NetBox:
  • Список, фильтры, массовое редактирование/удаление
  • Импорт из CSV
  • Построено на NetBoxModelForm, NetBoxModelFilterSet и т.д.
• Отчёты (xlsx):
  • Период задаётся датами «с» / «по»
  • Общий отчёт — построчный список инцидентов по группам сайтов (место установки, оборудование, начало/конец простоя, причина, контакт, примечание — комментарий инцидента целиком)
  • Детальный отчёт — те же инциденты с группировкой «группа сайтов → причина → тип объекта (Стойка/Устройство/Модуль/Интерфейс)» и подытогами на каждом уровне
  • Статистика — количество и суммарное время простоя по причинам (колонки), в разрезе группы сайтов и типа объекта (строки), с итогами по группе и по всем данным
• REST API (/api/plugins/incidents/incidents/) — обязателен для самого NetBox (используется системой логирования изменений), также доступен для внешних интеграций.

Скриншоты

1. Список инцидентов — общий вид таблицы с фильтрами, статусами и причинами.
2. Форма создания инцидента — выбор объекта (устройство/интерфейс/модуль/стойка), контактного лица, статуса, причины, дат и комментария.
3. Страница отчётов — три блока: «Общий отчёт», «Детальный отчёт», «Статистика» с выбором периода.
4. Вкладка Incidents на карточке устройства — список инцидентов и форма быстрого добавления.
5. Пример общего отчёта (xlsx) — плоская таблица с группировкой по группам сайтов.
6. Пример детального отчёта (xlsx) — иерархическая группировка с подытогами.
7. Пример статистики (xlsx) — сводная таблица по причинам и типам объектов.

Требования

• NetBox >= 4.6.0
• Python >= 3.10
• Django (устанавливается вместе с NetBox)
• openpyxl (для генерации xlsx-отчётов)

Установка

1. Активируйте виртуальное окружение NetBox:

   source /opt/netbox/venv/bin/activate
   

2. Установите плагин одним из способов:

   Из исходников:

   pip install /path/to/netbox-incidents
   

   Через local_requirements.txt (рекомендуется для разработки):

   -e /opt/netbox_incidents
   

3. Установите зависимость openpyxl:

   pip install openpyxl
   

4. Включите плагин в configuration.py (см. раздел Настройка).

5. Выполните миграции (см. раздел Миграции).

6. Перезапустите NetBox и RQ:

   sudo systemctl restart netbox netbox-rq
   

Быстрый деплой (пример):

sudo /opt/netbox/venv/bin/pip install --force-reinstall --no-deps /opt/netbox_incidents
sudo /opt/netbox/venv/bin/pip install openpyxl
sudo chown -R user:user /opt/netbox/venv/lib/python3.12/site-packages/netbox_incidents
sudo systemctl restart netbox netbox-rq

Настройка

В файле configuration.py добавьте плагин в PLUGINS и при необходимости настройте параметры:

PLUGINS = ['netbox_incidents']

PLUGINS_CONFIG = {
    'netbox_incidents': {
        # slug группы Contact (tenancy.Contact), из которой выбирается
        # "Контактное лицо". Оставьте '' — без фильтра, доступны все контакты.
        'contact_group_slug': '',
    }
}

Использование

Создание инцидента

1. Перейдите в раздел Инциденты в главном меню.
2. Нажмите Добавить.
3. Заполните поля:
   • Объект — выберите тип (Устройство, Интерфейс, Модуль, Стойка) и конкретный объект.
   • Контактное лицо — выберите контакт (список может фильтроваться настройкой contact_group_slug).
   • Статус — Открыто / Закрыто.
   • Причина — выберите из списка.
   • Дата начала — обязательное поле.
   • Дата окончания — опционально (для закрытых инцидентов).
   • Комментарий — поддерживает Markdown.
4. Нажмите Создать или Создать и добавить ещё.

Просмотр инцидентов на объектах

На карточках Device, Interface, Module и Rack появилась вкладка Incidents. Она содержит:

• Таблицу связанных инцидентов.
• Форму быстрого добавления нового инцидента (без перехода в общий список).

Список инцидентов

Раздел Инциденты предоставляет:

• Фильтры по статусу, причине, дате, объекту и т.д.
• Массовые действия: редактирование, удаление.
• Экспорт в CSV (стандартный функционал NetBox).
• Импорт из CSV.

Отчёты

Раздел Отчёты содержит три формы для выгрузки xlsx-файлов:

1. Общий отчёт

   • Выберите период (даты «с» и «по»).
   • Нажмите Скачать.
   • Файл содержит плоский список инцидентов, сгруппированный по группам сайтов.
   • Колонки: место установки, оборудование, начало простоя, конец простоя, время простоя, причина, кому сообщили, примечание.

2. Детальный отчёт

   • Выберите период.
   • Нажмите Скачать.
   • Файл содержит иерархическую структуру: группа сайтов → причина → тип объекта (Стойка/Устройство/Модуль/Интерфейс).
   • На каждом уровне выводятся подытоги.

3. Статистика

   • Выберите период.
   • Нажмите Скачать.
   • Файл содержит сводную таблицу:
     • Строки: группа сайтов + тип объекта.
     • Колонки: причины (количество и общее время простоя).
     • Итоги по группе и общий итог.

REST API

Плагин предоставляет стандартный REST API по адресу:

/api/plugins/incidents/incidents/

Доступны все операции CRUD, фильтрация, пагинация. API используется самим NetBox для логирования изменений, а также может применяться для внешних интеграций.

Разработка

Миграции

В репозитории пока не закоммичены файлы миграций Django — сгенерируйте их в своём dev-окружении перед первым запуском. Рекомендуется закоммитить папку netbox_incidents/migrations/ в репозитории перед публикацией релиза, чтобы конечным пользователям не нужно было включать DEVELOPER = True.

Порядок действий:

1. Включите режим разработчика:

   cd /opt/netbox
   sudo nano netbox/netbox/settings.py   # или configuration.py: DEVELOPER = True
   

2. Сгенерируйте миграции:

   sudo -u netbox venv/bin/python3 netbox/manage.py makemigrations netbox_incidents
   

3. Примените миграции:

   sudo -u netbox venv/bin/python3 netbox/manage.py migrate netbox_incidents
   

4. Выключите DEVELOPER = False и перезапустите сервисы:

   sudo systemctl restart netbox netbox-rq
   

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

Для запуска тестов используйте стандартные средства Django:

python manage.py test netbox_incidents

Вклад в развитие

Pull request'ы приветствуются. Пожалуйста, создавайте issue для обсуждения новых функций или сообщений об ошибках.

Лицензия

Apache 2.0