SensusAgent/docs/collectors/proxvms.md

Коллектор proxvms

Автор: Сергей Антропов
Сайт: https://devops.org.ru

Описание

Коллектор proxvms собирает подробную информацию о виртуальных машинах и LXC контейнерах в Proxmox кластере. Включает полную конфигурацию каждой VM/контейнера, структурированные данные о сетевых интерфейсах, дисковых устройствах, IP конфигурациях и другую важную информацию.

Поддерживаемые платформы

• Linux: Полная поддержка
• macOS/Windows: Не поддерживается (возвращает пустой JSON)

Собираемые данные

Основная информация о кластере

{
  "cluster": {
    "cluster_name": "production-cluster",     // Имя кластера
    "cluster_uid": "a1b2c3d4e5f67890",      // Уникальный ID кластера (SHA256, 16 символов)
    "cluster_uuid": "12345678-1234-1234-1234-123456789abc", // UUID кластера
    "version": "8.1.4"                       // Версия Proxmox VE
  }
}

Информация о виртуальных машинах и контейнерах

{
  "vms": [
    {
      "vmid": 100,                           // ID виртуальной машины/контейнера
      "name": "web-server",                  // Имя VM/контейнера
      "status": "running",                   // Статус (running, stopped, suspended)
      "type": "QEMU",                        // Тип: QEMU или LXC
      "node_name": "pve1",                   // Имя ноды
      "cluster_uid": "a1b2c3d4e5f67890",    // ID кластера
      "node_uid": "d8b7a93c2f0e4f16",       // ID ноды
      "machine_id": "pc-i440fx-7.2",        // Machine ID
      "machine_uid": "f3e2d1c0b9a8f7e6",    // Уникальный ID машины (SHA256, 16 символов)
      "is_template": false,                  // Является ли шаблоном
      "cpu_type": "kvm64",                   // Тип CPU
      "boot_disk": "scsi0",                  // Загрузочный диск
      "resources": {                         // Ресурсы
        "memory_mb": 4096,                   // Память в МБ
        "max_memory_mb": 8192,               // Максимальная память в МБ
        "cpu_cores": 4,                      // Количество ядер CPU
        "max_disk_gb": 100                   // Максимальный размер диска в ГБ
      },
      "config": {                            // Полная конфигурация
        "description_parsed": {              // Парсированный JSON из description
          "vm_name": "web-server",
          "description": "Веб-сервер для продакшена",
          "responsible": "Иван Петров",
          "creation_date": "01.01.2024",
          "deletion_date": "01.01.2025"
        },
        "network": {                         // Сетевые интерфейсы
          "net0": {
            "bridge": "vmbr0",               // Мост
            "virtio": "52:54:00:12:34:56",   // MAC адрес
            "ip": {                          // IP конфигурация
              "ip": "192.168.1.100",         // IP адрес
              "mask": "255.255.255.0",       // Маска подсети
              "mask_cidr": "/24",            // Маска в формате CIDR
              "gw": "192.168.1.1"            // Шлюз
            }
          }
        },
        "ipconfig": {                        // IP конфигурации
          "ipconfig0": {
            "ip": {
              "ip": "192.168.1.100",
              "mask": "255.255.255.0",
              "mask_cidr": "/24",
              "gw": "192.168.1.1"
            }
          }
        },
        "scsi": {                            // SCSI устройства
          "scsi0": {
            "pool": "local-lvm",             // Пул хранения
            "pool_disk": "vm-100-disk-0",    // Диск в пуле
            "pool_disk_size": "50G",         // Размер диска в пуле
            "aio": "threads",                // Асинхронный I/O
            "cache": "writeback",            // Кэширование
            "discard": "on",                 // Поддержка discard
            "enable": true,                  // Включено
            "iothread": "1"                  // I/O поток
          }
        },
        "ide": {                             // IDE устройства
          "ide2": {
            "pool": "local",                 // Пул хранения
            "pool_disk": "vm-100-cloudinit", // Диск в пуле
            "media": "cdrom",                // Тип носителя
            "enable": true                   // Включено
          }
        }
      }
    },
    {
      "vmid": 200,
      "name": "db-container",
      "status": "running",
      "type": "LXC",                         // LXC контейнер
      "node_name": "pve1",
      "cluster_uid": "a1b2c3d4e5f67890",
      "node_uid": "d8b7a93c2f0e4f16",
      "machine_id": "db-container",
      "machine_uid": "a1b2c3d4e5f67890",
      "is_template": false,
      "os_template": "ubuntu-22.04-standard_22.04-1_amd64.tar.zst",
      "resources": {
        "memory_mb": 2048,
        "max_memory_mb": 4096,
        "cpu_cores": 2,
        "max_disk_gb": 20
      },
      "config": {
        "description_parsed": {
          "vm_name": "db-container",
          "description": "Контейнер базы данных",
          "responsible": "Мария Сидорова"
        },
        "network": {
          "net0": {
            "bridge": "vmbr1",
            "hwaddr": "02:00:00:00:00:01",
            "ip": {
              "ip": "10.0.0.100",
              "mask": "255.255.255.0",
              "mask_cidr": "/24",
              "gw": "10.0.0.1"
            },
            "name": "eth0",
            "tag": "100",
            "type": "veth"
          }
        },
        "rootfs": {                          // Корневая файловая система LXC
          "pool": "local-lvm",
          "pool_disk": "vm-200-disk-0",
          "pool_disk_size": "20G",
          "enable": true
        },
        "mp": {                              // Точки монтирования LXC
          "mp0": {
            "pool": "nfs-storage",
            "pool_disk": "vm-200-disk-1",
            "pool_disk_size": "100G",
            "mp": "/var/lib/postgresql",     // Точка монтирования
            "backup": "1",                   // Включен бэкап
            "enable": true
          }
        }
      }
    }
  ]
}

Особенности парсинга

Структурированные данные

Коллектор автоматически парсит и структурирует следующие типы конфигураций:

1. Сетевые интерфейсы (net0, net1, netX)

   • Парсит строки типа bridge=vmbr0,virtio=52:54:00:12:34:56
   • Извлекает IP адреса с масками подсети
   • Включает шлюз в секцию IP

2. IP конфигурации (ipconfig0, ipconfig1, ipconfigX)

   • Парсит IP адреса с масками в формате CIDR
   • Конвертирует маски в формат 255.255.255.0
   • Включает шлюз в секцию IP

3. SCSI устройства (scsi0, scsi1, scsiX)

   • Парсит пулы и диски в формате pool:disk
   • Переименовывает size в pool_disk_size
   • Извлекает все параметры конфигурации

4. IDE устройства (ide0, ide1, ide2, ideX)

   • Аналогично SCSI устройствам
   • Поддерживает различные типы носителей

5. LXC устройства (rootfs, mp0, mp1, mpX)

   • Парсит корневую файловую систему
   • Обрабатывает точки монтирования
   • Извлекает параметры пулов и дисков

6. Описания (description)

   • Парсит JSON из поля description
   • Переводит русские ключи на английский
   • Удаляет оригинальное поле при успешном парсинге

Удаление дублирования

• Если парсинг прошел успешно, оригинальные поля удаляются
• Если парсинг не удался, оригинальные поля остаются
• Это обеспечивает чистоту данных без потери информации

Конфигурация

config.yaml

collectors:
  proxvms:
    enabled: true
    type: exec
    key: proxvms
    interval: "1800s"    # 30 минут
    timeout: "300s"      # 5 минут
    exec: "./collectors/proxvms"
    platforms: [linux]

Переменные окружения

• COLLECTOR_TIMEOUT: Таймаут выполнения коллектора (по умолчанию 30s)

Требования

Системные требования

• Proxmox VE кластер
• Доступ к файлам конфигурации:
  • /etc/corosync/corosync.conf (основной)
  • /etc/pve/corosync.conf (альтернативный)
  • /var/lib/pve-cluster/corosync.conf (альтернативный)

Команды

Коллектор использует следующие команды (должны быть доступны):

• pvesh - утилита командной строки Proxmox VE
• pveversion - версия Proxmox VE

Уникальные идентификаторы

cluster_uid

Генерируется на основе:

• cluster_name из corosync.conf
• cluster_uuid из corosync.conf

Формула: SHA256(cluster_name + ":" + cluster_uuid)[:16] (первые 16 символов SHA256 хеша)

node_uid

Генерируется на основе:

• cluster_uuid кластера
• node_id ноды

Формула: SHA256(cluster_uuid + ":" + node_id)[:16] (первые 16 символов SHA256 хеша)

machine_uid

Генерируется на основе:

• Для QEMU VM: UUID из smbios1 или machine_id
• Для LXC контейнеров: hostname или machine_id

Формула: SHA256(machine_identifier)[:16] (первые 16 символов SHA256 хеша)

Примеры использования

Проверка работы коллектора

# Запуск коллектора напрямую
./bin/agent/collectors/proxvms

# Запуск через агент
make run

Фильтрация данных

# Информация о кластере
./bin/agent/collectors/proxvms | jq '.cluster'

# Все виртуальные машины
./bin/agent/collectors/proxvms | jq '.vms[] | select(.type == "QEMU")'

# Все LXC контейнеры
./bin/agent/collectors/proxvms | jq '.vms[] | select(.type == "LXC")'

# Только запущенные VM
./bin/agent/collectors/proxvms | jq '.vms[] | select(.status == "running")'

# VM с высоким использованием памяти (>4GB)
./bin/agent/collectors/proxvms | jq '.vms[] | select(.resources.memory_mb > 4096)'

# VM с определенным именем
./bin/agent/collectors/proxvms | jq '.vms[] | select(.name == "web-server")'

# Сетевые конфигурации
./bin/agent/collectors/proxvms | jq '.vms[] | select(.config.network != null) | {name, network: .config.network}'

# SCSI устройства
./bin/agent/collectors/proxvms | jq '.vms[] | select(.config.scsi != null) | {name, scsi: .config.scsi}'

# IP адреса с масками
./bin/agent/collectors/proxvms | jq '.vms[] | select(.config.network != null) | {name, ip: .config.network.net0.ip}'

# Парсированные описания
./bin/agent/collectors/proxvms | jq '.vms[] | select(.config.description_parsed != null) | {name, description: .config.description_parsed}'

# LXC с точками монтирования
./bin/agent/collectors/proxvms | jq '.vms[] | select(.type == "LXC" and .config.mp != null) | {name, mp: .config.mp}'

# VM с определенным пулом хранения
./bin/agent/collectors/proxvms | jq '.vms[] | select(.config.scsi.scsi0.pool == "local-lvm")'

Устранение неполадок

Частые проблемы

1. "no cluster data found"

   • Проверьте, что система является Proxmox VE кластером
   • Убедитесь в доступности файла corosync.conf
   • Проверьте права доступа к файлам конфигурации

2. "failed to parse corosync.conf"

   • Проверьте формат файла corosync.conf
   • Убедитесь, что в файле есть cluster_name и cluster_uuid

3. "cluster version not found"

   • Убедитесь, что установлен Proxmox VE
   • Проверьте доступность команды pveversion

4. Пустые данные о VM/контейнерах

   • Проверьте доступность команды pvesh
   • Убедитесь в правильности конфигурации кластера
   • Проверьте права доступа к Proxmox API

Отладка

# Проверка доступности команд
which pvesh pveversion

# Проверка файлов конфигурации
ls -la /etc/corosync/corosync.conf /etc/pve/corosync.conf

# Проверка статуса сервисов
systemctl status pve-cluster corosync pveproxy pvedaemon

# Проверка VM через pvesh
pvesh get /nodes --output-format json

# Проверка конкретной ноды
pvesh get /nodes/pve1/qemu --output-format json
pvesh get /nodes/pve1/lxc --output-format json

# Проверка конфигурации VM
pvesh get /nodes/pve1/qemu/100/config --output-format json

Безопасность

• Коллектор требует права на чтение системных файлов конфигурации
• Не передает пароли или секретные ключи
• Собирает только публичную информацию о VM/контейнерах
• Не выполняет привилегированные операции

Производительность

• Время выполнения: ~30-300 секунд (зависит от количества VM/контейнеров)
• Интервал сбора: рекомендуется 30 минут (1800s)
• Потребление ресурсов: минимальное
• Собирает информацию только с локальной ноды

Совместимость

• Proxmox VE: 6.0+
• VM: QEMU виртуальные машины
• Контейнеры: LXC контейнеры
• Хранилища: все поддерживаемые типы (local, nfs, ceph, lvm, zfs и др.)
• Сети: все типы интерфейсов (eth, ens, enp, vmbr и др.)
• Диски: все типы устройств (scsi, ide, virtio и др.)