Хостинг-провайдеры

Подключите аккаунт провайдера в Settings > Integrations > Hosting, чтобы создавать ВМ и управлять ими из Gateway. Сохранение подключения не создаёт ВМ; заказ подтверждается отдельно.

Настройка провайдеров

Выберите провайдера и раскройте инструкцию. Для добавления коннектора нужны права integrations:hosting:view и integrations:hosting:manage в Gateway; права токена провайдера настраиваются отдельно.

Proxmox VE

Создание QEMU ВМ и управление существующими ВМ/CT на выбранном хосте. Нужны API-токен, ACL и профиль хранилищ/сети для создания ВМ.

Настройка Proxmox VE

Создание учётных данных

1. В Proxmox откройте Datacenter > Permissions > Users > Add. Создайте отдельного пользователя, например gateway@pve, в области аутентификации Proxmox VE. Не используйте root@pam.
2. В Permissions > Roles > Create создайте роли с привилегиями из таблицы ниже. Разделите права ВМ, хранилищ и необязательные права фаервола кластера, чтобы назначать каждую роль на нужном пути.
3. В Permissions добавьте записи User Permission для gateway@pve на нужных путях. Включайте наследование только там, где доступ должны получать дочерние объекты. Для создания нужны разрешения на будущие VMID из диапазона выделения, а не только на существующие ВМ.
4. Откройте Permissions > API Tokens > Add, выберите gateway@pve, задайте имя hosting и оставьте Privilege Separation включённым. Задайте срок действия. Сразу скопируйте секрет: повторно он не показывается.
5. Добавьте соответствующие записи API Token Permission для gateway@pve!hosting. При разделении привилегий эффективные права — пересечение прав пользователя и токена. Административная учётная запись владельца не делает такой токен администратором автоматически.

Привилегии и пути ACL

Выдавайте только права для нужных функций. Замените шаблоны путей реальными объектами Proxmox: идентификатор ноды Gateway не является именем хоста Proxmox или VMID.

Операция	Привилегии Proxmox	Путь ACL
Обнаружение хостов и хранилищ	Sys.Audit, Datastore.Audit	Соответственно выбранные /nodes/<host> и /storage/<storage>
Чтение конфигурации и состояния ВМ	VM.Audit	/vms/<vmid>
Создание и настройка ВМ	VM.Allocate, VM.Config.CPU, VM.Config.Memory, VM.Config.Disk, VM.Config.Network, VM.Config.HWType, VM.Config.Options, VM.Config.CDROM, VM.PowerMgmt	Каждый разрешённый будущий /vms/<vmid> либо настроенный /pool/<pool>
Выделение дисков ВМ	Datastore.AllocateSpace	Дисковое /storage/<storage> с типом содержимого images
Загрузка/импорт образа ОС и загрузочного носителя	Datastore.AllocateTemplate, Datastore.Allocate	Хранилище образов с import и хранилище загрузочных носителей с iso
Скачивание образа гипервизором	Sys.AccessNetwork	Выбранный /nodes/<host>
Подключение моста или VNet	SDN.Use	Путь разрешений моста/VNet в Proxmox
Запуск, выключение, перезагрузка	VM.PowerMgmt	/vms/<vmid>
Изменение размера	VM.Config.CPU, VM.Config.Memory, VM.Config.Disk; рост диска также требует выделения места	Пути ВМ и дискового хранилища
Удаление ВМ	VM.Allocate	/vms/<vmid>
Чтение файлов идентификации гостевой ОС	VM.GuestAgent.FileRead либо более широкое VM.GuestAgent.Unrestricted; в старых версиях — VM.Monitor	/vms/<vmid>
Установка/восстановление через QEMU Guest Agent	VM.GuestAgent.Unrestricted; в старых версиях — VM.Monitor	/vms/<vmid>
Создание/удаление снапшотов	VM.Snapshot	/vms/<vmid>
Восстановление снапшота	VM.Snapshot.Rollback; для последующего запуска также VM.PowerMgmt	/vms/<vmid>
Чтение/изменение фаервола ВМ и участия интерфейса	VM.Audit, VM.Config.Network	/vms/<vmid>
Чтение состояния фаервола кластера	Sys.Audit	/
Управление группами безопасности Gateway в фаерволе кластера	Sys.Modify	/ — необязательный широкий доступ на уровне кластера

Не выдавайте Sys.Modify на / только ради успешного теста соединения. Текущая интеграция фаервола использует его для групп безопасности кластера; это не разрешение на одну ВМ. Если такой доступ неприемлем, оставьте управление фаерволом недоступным. Gateway не включает фаервол кластера. Для образов и загрузочных носителей лучше выделить отдельные хранилища: Datastore.Allocate шире права загрузить один файл. VM.Backup не заменяет привилегии снапшотов.

Набор привилегий Guest Agent зависит от версии Proxmox. Выбирайте доступные в установленной версии и проверяйте право, указанное в ошибке API. Если получение сведений через Guest Agent требует VM.GuestAgent.Audit, добавьте его отдельно; чтение файлов само по себе не разрешает команды установки.

Подключение в Gateway

1. Откройте Settings > Integrations, в блоке Hosting нажмите Add connector.
2. На шаге Connection выберите Provider → Proxmox VE. Заполните Connector name (например, Proxmox production), API origin (https://pve.example.com:8006, без /api2/json), Token ID (gateway@pve!hosting) и API token (только секрет). Нажмите Continue.
3. На шаге Proxmox host выберите Certificate verification: System trust для доверенного системного сертификата, Private CA certificate для собственного CA либо Verified certificate fingerprint для независимо проверенного отпечатка. В последних двух случаях заполните Trusted CA certificate в PEM или Certificate SHA-256 pin.
4. Нажмите Test Connection. После загрузки списка выберите Physical host. Один коннектор привязан к одному физическому хосту; VMID уникальны во всём кластере.
5. Оставьте VM provisioning включённым для создания ВМ. Если нужны только существующие ВМ/CT и их привязка, выключите его: шаги Infrastructure и Network будут пропущены. Нажмите Continue.
6. На шаге Infrastructure заполните параметры из таблицы и нажмите Continue.

Поле	Что указать
Disk storage	Существующее хранилище выбранного хоста с содержимым images для дисков ВМ
Image storage	Хранилище с import для образов ОС
Seed storage	Хранилище с iso для загрузочного носителя
Allowed VMIDs	Разрешённые ID и диапазоны, например 9000-9010,9020; не более 1000 уникальных ID. Занятые ID пропускаются
Maximum CPU budget (cores)	Необязательный общий бюджет vCPU коннектора, включая ожидающие операции
Maximum memory budget (MiB)	Необязательный общий бюджет RAM
Maximum disk budget (GiB)	Необязательный общий бюджет дисков
Resource pool	Имя существующего пула Proxmox, если он нужен; иначе пусто

7. На шаге Network выберите Bridge и Address assignment. Для DHCP в выбранной сети должен работать DHCP. Для Static IPv4 pool укажите IP pool, Subnet и Gateway: адресов должно быть не меньше разрешённых VMID. Зарезервируйте их вне DHCP и ручного выделения.
8. При необходимости задайте VLAN, DNS servers, Search domain, MTU. Interface firewall определяет участие сетевого интерфейса в фаерволе, но не включает фаервол кластера и не создаёт правила. Нажмите Review.
9. Проверьте Profile summary. В Synchronization and scope настройте Automatic sync и Sync interval (seconds) — от 60 до 86400. Automatic adoption включайте, если нужно автоматически связывать существующие ноды при однозначном подтверждении идентичности; одного совпадения IP/VMID недостаточно.
10. Нажмите Create connector. При выключенном VM provisioning эти настройки находятся на последнем шаге Settings, без сводки профиля. Сохранение коннектора не создаёт ВМ.
11. Откройте сохранённый аккаунт из Nodes > Providers или списка интеграций. Проверьте синхронизацию и список ресурсов. Для создания ноды нажмите Create VM, выберите роль, имя, ОС и ресурсы, проверьте Review node и подтвердите Confirm and create VM. Дождитесь завершения установки и появления ноды онлайн.

Если Test Connection не загрузил хосты, проверьте сертификат и ACL. Если нет нужного хранилища, проверьте его тип содержимого и доступ на выбранном хосте. Кнопка Create VM требует включённого профиля создания и прав Gateway на создание нод и ресурсов выбранного аккаунта.

Проверка прав

Если API отклоняет запрос, проверьте эффективные права токена из административной консоли Proxmox, заменив пути на свои:

pveum user token permissions gateway@pve hosting --path /vms/9000
pveum user token permissions gateway@pve hosting --path /storage/gateway-images
pveum user token permissions gateway@pve hosting --path /

Команды только читают права. Для токена с разделением привилегий проверьте ACL и пользователя, и токена.

Документация Proxmox.

DigitalOcean

Создание и управление Droplets, фаерволами и снапшотами. Доступ задаётся правами персонального API-токена.

Настройка DigitalOcean

Создание API-токена

1. В панели DigitalOcean переключитесь на нужную команду. Откройте API > Tokens > Generate New Token.
2. Задайте отдельное имя и срок действия. Выберите Custom Scopes и права из нужных строк ниже вместе с обязательными зависимостями. Роль создателя в команде должна разрешать эти операции.
3. Создайте токен и сразу скопируйте секрет для следующего шага.

Возможность	Права токена
Учётная запись и список ВМ	account:read, droplet:read
Локации, размеры, образы	regions:read, sizes:read, image:read
Создание Droplet	droplet:create, droplet:read, tag:create, tag:read, regions:read, sizes:read, actions:read, image:read, snapshot:read, vpc:read
Питание; создание/восстановление снапшота через действия Droplet	droplet:update и droplet:read, regions:read, sizes:read, actions:read, image:read, snapshot:read
Изменение размера	Права обновления из строки выше плюс droplet:create и его зависимости
Удаление Droplet	droplet:delete, droplet:read
Просмотр/удаление снапшотов	snapshot:read; для удаления также snapshot:delete
Управление и очистка фаерволов	firewall:read, firewall:create, firewall:update, firewall:delete, droplet:read, tag:read
Баланс и финансы	billing:read

Отдельного права snapshot:create в этом API нет: создание снапшота Droplet является действием над Droplet. Не нужны посторонние права Kubernetes, Spaces или баз данных. Чтобы изменить набор прав, создайте новый токен, замените его в Gateway, проверьте и только затем отзовите старый.

Источники: создание персонального токена, справочник прав DigitalOcean.

Подключение в Gateway

1. Откройте Settings > Integrations, в блоке Hosting нажмите Add connector.
2. На шаге Connection выберите Provider → DigitalOcean и задайте Connector name, например DigitalOcean production. API origin заполняется автоматически: https://api.digitalocean.com; менять его не нужно.
3. В API token вставьте секрет созданного токена. Нажмите Test Connection. При сообщении Connected with limited permissions проверьте недостающие права по таблице выше; успешная авторизация не означает доступность всех операций.
4. Нажмите Continue. На шаге Settings настройте параметры ниже.

Поле	Что указать
Automatic sync	Включить плановое обновление ресурсов провайдера
Sync interval (seconds)	Интервал от 60 до 86400 секунд
Automatic adoption	Автоматическая привязка существующих нод только при однозначном подтверждении идентичности
Node scope	Необязательные UUID нод Gateway через запятую для ограничения автоматической привязки. Не ID ВМ провайдера; пустое поле означает все доступные для привязки ноды
Default location, Default size, Default image	Необязательные ID из каталога провайдера для предварительного выбора в мастере создания ВМ. Если ID неизвестны, оставьте поля пустыми и выберите значения при создании

5. Нажмите Create connector. Это сохраняет подключение, но не заказывает ВМ.
6. Откройте сохранённый аккаунт из списка интеграций или Nodes > Providers. Проверьте синхронизацию, ресурсы нужного аккаунта/команды и доступные финансовые данные. Неизвестный баланс не равен нулю.
7. Чтобы создать ноду, нажмите Create VM, выберите роль, имя, локацию, ОС и размер. Проверьте конфигурацию и цену в Review node, затем нажмите Confirm and create VM — это уже платный заказ. Дождитесь создания ВМ, установки демона и появления ноды онлайн.
8. Для изменения настроек откройте меню аккаунта Configure, пройдите мастер и нажмите Save. При редактировании оставьте поле замены учётных данных пустым, чтобы сохранить прежний секрет.

Если Add connector недоступна, нужны права Gateway на администрирование хостинг-интеграций. Для Create VM дополнительно нужны права создания нод и ресурсов выбранного аккаунта, а также возможность создания у провайдера.

Hetzner Cloud

Управление облачными серверами одного проекта через API-токен. Hetzner Robot и выделенные серверы не поддерживаются.

Настройка Hetzner Cloud

Создание API-токена

1. В Hetzner Console выберите нужный облачный проект и откройте Security > API Tokens > Generate API Token.
2. Задайте имя. Выберите Read только для просмотра или Read & Write для создания ВМ, питания, изменения размера, фаервола и снапшотов. Отдельных прав по операциям, как в DigitalOcean, здесь нет.
3. Создайте токен и сразу скопируйте секрет для следующего шага.

Ограничьте доступ отдельным проектом. Текущий коннектор Gateway не позволяет заменить токен проекта Hetzner на месте: создайте новый коннектор и явно согласуйте зависимые ресурсы перед удалением прежнего. Дополнительного права для баланса нет: интеграция не предоставляет API баланса аккаунта.

Источник: настройка API Hetzner Cloud.

Подключение в Gateway

1. Откройте Settings > Integrations, в блоке Hosting нажмите Add connector.
2. На шаге Connection выберите Provider → Hetzner Cloud и задайте Connector name, например Hetzner production. API origin заполняется автоматически: https://api.hetzner.cloud; менять его не нужно.
3. В API token вставьте секрет созданного токена. Нажмите Test Connection. При сообщении Connected with limited permissions проверьте недостающие права по таблице выше; успешная авторизация не означает доступность всех операций.
4. Нажмите Continue. На шаге Settings настройте параметры ниже.

Поле	Что указать
Automatic sync	Включить плановое обновление ресурсов провайдера
Sync interval (seconds)	Интервал от 60 до 86400 секунд
Automatic adoption	Автоматическая привязка существующих нод только при однозначном подтверждении идентичности
Node scope	Необязательные UUID нод Gateway через запятую для ограничения автоматической привязки. Не ID ВМ провайдера; пустое поле означает все доступные для привязки ноды
Default location, Default size, Default image	Необязательные ID из каталога провайдера для предварительного выбора в мастере создания ВМ. Если ID неизвестны, оставьте поля пустыми и выберите значения при создании

5. Нажмите Create connector. Это сохраняет подключение, но не заказывает ВМ.
6. Откройте сохранённый аккаунт из списка интеграций или Nodes > Providers. Проверьте синхронизацию, ресурсы нужного проекта и доступные финансовые данные. Неизвестный баланс не равен нулю.
7. Чтобы создать ноду, нажмите Create VM, выберите роль, имя, локацию, ОС и размер. Проверьте конфигурацию и цену в Review node, затем нажмите Confirm and create VM — это уже платный заказ. Дождитесь создания ВМ, установки демона и появления ноды онлайн.
8. Для изменения настроек откройте меню аккаунта Configure, пройдите мастер и нажмите Save. Для замены токена Hetzner создайте новый коннектор: поле токена существующего коннектора недоступно.

Если Add connector недоступна, нужны права Gateway на администрирование хостинг-интеграций. Для Create VM дополнительно нужны права создания нод и ресурсов выбранного аккаунта, а также возможность создания у провайдера.

HOSTKEY

Заказ и управление ВМ через API-ключ аккаунта Invapi. Ключ отдельного сервера не подходит для заказа новых ВМ.

Настройка HOSTKEY

Создание API-ключа

1. Войдите в Invapi, откройте API keys и создайте именованный ключ клиента/аккаунта. Ключ отдельного сервера не подходит для заказа других ВМ и чтения финансов аккаунта.
2. Если ограничиваете IP, укажите внешний адрес исходящих соединений сервера Gateway и включите ключ. Это не адрес браузера, из которого вы настраиваете интеграцию.
3. Сразу скопируйте оригинальный секрет. После создания интерфейс может показывать только хеш; он не подходит для авторизации Gateway. Если создание ключа для аккаунта недоступно, сначала уточните условия доступа у HOSTKEY.

У ключей HOSTKEY нет строк прав в формате DigitalOcean. Границы задаются типом ключа и ограничением IP; доступ уровня аккаунта может разрешать платные заказы. Не передавайте такой ключ пользователям, которым нужны только операции с существующей нодой Gateway.

Источник: авторизация и ключи API HOSTKEY.

Подключение в Gateway

1. Откройте Settings > Integrations, в блоке Hosting нажмите Add connector.
2. На шаге Connection выберите Provider → HOSTKEY и задайте Connector name, например HOSTKEY production. API origin заполняется автоматически: https://invapi.hostkey.com; менять его не нужно.
3. В API key вставьте оригинальный API-ключ Invapi, не хеш и не временный токен сессии. Нажмите Test Connection. При сообщении Connected with limited permissions проверьте недостающие права по таблице выше; успешная авторизация не означает доступность всех операций.
4. Нажмите Continue. На шаге Settings настройте параметры ниже.

Поле	Что указать
Automatic sync	Включить плановое обновление ресурсов провайдера
Sync interval (seconds)	Интервал от 60 до 86400 секунд
Automatic adoption	Автоматическая привязка существующих нод только при однозначном подтверждении идентичности
Node scope	Необязательные UUID нод Gateway через запятую для ограничения автоматической привязки. Не ID ВМ провайдера; пустое поле означает все доступные для привязки ноды
Default location, Default size, Default image	Необязательные ID из каталога провайдера для предварительного выбора в мастере создания ВМ. Если ID неизвестны, оставьте поля пустыми и выберите значения при создании

5. Нажмите Create connector. Это сохраняет подключение, но не заказывает ВМ.
6. Откройте сохранённый аккаунт из списка интеграций или Nodes > Providers. Проверьте синхронизацию, ресурсы нужного аккаунта и доступные финансовые данные. Неизвестный баланс не равен нулю.
7. Чтобы создать ноду, нажмите Create VM, выберите роль, имя, локацию, ОС и размер. Проверьте конфигурацию и цену в Review node, затем нажмите Confirm and create VM — это уже платный заказ. Дождитесь создания ВМ, установки демона и появления ноды онлайн.
8. Для изменения настроек откройте меню аккаунта Configure, пройдите мастер и нажмите Save. При редактировании оставьте поле замены учётных данных пустым, чтобы сохранить прежний секрет.

Если Add connector недоступна, нужны права Gateway на администрирование хостинг-интеграций. Для Create VM дополнительно нужны права создания нод и ресурсов выбранного аккаунта, а также возможность создания у провайдера.

Создание и регистрация ноды

1. Откройте Nodes > Add Node и выберите создание у провайдера либо создайте ВМ со страницы учётной записи.
2. Выберите роль, имя, учётную запись, локацию, совместимую ОС и ресурсы ВМ.
3. Проверьте конфигурацию и доступную оценку цены, затем подтвердите заказ один раз.
4. Следите за созданием ВМ, установкой, регистрацией и готовностью роли.

Работающая ВМ не обязательно означает доступную ноду Gateway. Дождитесь демона и возможностей его роли. См. Добавление первой ноды и Роли нод.

Если ВМ создалась, но установка завершилась ошибкой, используйте Retry installation в этой операции вместо нового заказа. Неоднозначный ответ провайдера сначала нужно согласовать с его фактическим состоянием. Для установки на существующую ВМ нужен поддерживаемый канал Guest Agent либо доверенное SSH-подключение именно к этой ВМ. Совпадения VMID или IP недостаточно для автоматической привязки.

Управление ВМ

• Питание и размер: действия зависят от состояния провайдера, прав и возможностей ресурса. Диски Proxmox можно увеличивать, но не уменьшать.
• Фаервол: вкладка доступна только для поддерживаемых ресурсов. В Proxmox участие сетевого интерфейса и включение фаервола ВМ — отдельные настройки; также важны фаервол кластера и права токена. Gateway не включает фаервол кластера за вас.
• Снапшоты: у поддерживаемых ресурсов Proxmox, DigitalOcean и Hetzner на странице ноды доступны создание, удаление, восстановление и папки. Для создания выключать ВМ не нужно. Proxmox позволяет включить RAM работающей ВМ и управляет остановкой и запуском при восстановлении; для других интеграций Gateway сейчас требует остановленную ВМ перед восстановлением. HOSTKEY не заявлен как провайдер снапшотов.
• Стоимость и согласованность: хранение снапшотов может быть платным. Таблица показывает оценку стоимости, если она доступна; прочерк означает неизвестный размер или цену. Снапшот ВМ не заменяет согласованную резервную копию базы данных и может не включать подключённые тома.

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

Права, алерты и восстановление

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

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

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