Описание

В данном репозитории хранится инструкция и пример создания LXC контейнера с помощью вызова API на сервере виртуализации Proxmox.

Инструкция актуальна для версии Proxmox API 7.3-4
посмотреть текущую версию api можно по ссылке
https://{host}:8006/api2/json/version/

ссылки на официальную документацию
https://pve.proxmox.com/wiki/User_Management
https://pve.proxmox.com/wiki/Proxmox_VE_API
https://pve.proxmox.com/wiki/Linux_Container
https://pve.proxmox.com/pve-docs/api-viewer/index.html#/nodes/{node}/lxc

Лирическое отступление
Данный LXC контейнер, с установленным ansible, используется для первоначального развертывания инфраструктуры проекта на сервере виртуализации Proxmox. После создания необходимых виртуальных машин, контейнер удаляется.

1. Получение доступа

Все действия производятся на сервере Proxmox на уровне Datacenter.

• Groups: Логическое объединение пользователей.
• Users: PVE или PAM. PVE - аутентификации сервера Proxmox, PAM - аутентификация linux.
• Pools: Логическое объединение виртуальных машин и контейнеров
• API Tokens: Secret созданного token id показывается один раз, необходимо запомнить его. Privilege separation - разделение прав пользователя и token id. Внимание! Токены, разделенные привилегиями, никогда не могут иметь разрешений на какой-либо заданный путь, которых нет у связанного с ними пользователя.
• Permission:
  • storage, где хранится шаблон контейнера
  • storage, где будет храниться образ контейнера
  • nodes/, в которой будем создавать контейнер
  • pool, в котором будем создавать контейнер
  • vms, внимание! Так как контейнер еще не существует, нам придется выдать права на все виртуальные машины и контейнеры
• Roles: логическое объединение прав

Посмотреть какие в точности необходимы права для каждого endpoint можно на его странице API в разделе Required permissions

2. LXC контейнеры

Шаблоны контейнеров можно скачать в web интерфейсе proxmox. Во вкладке CT Templates, необходимого storage, нажимаем Templates и качаем готовые контейнеры. Кроме готовых контейнеров также доступны контейнеры от Turnkey, с предустановленными сервисами, настраиваемыми через GUI при первом запуске контейнера. Есть возможность скачать контейнер по кнопке Download from URL, что может быть полезно если надо скачать новую версию контейнера с официального сайта.
http://download.proxmox.com/images/system/

3. Формирование JSON-файла

Синтаксис JSON: значения разделяются запятыми, строка в кавычках, число без кавычек, экранирование спецсимволом /

   {  
    "ключ": "строка",  
    "ключ": число,
    "ключ": "спецсимвол/@"   
   }

Для создания контейнера обязательно 3 параметра: vmid, ostemplate, node (указывается в url endpoint). В репозитории можно найти два файла:
lxc_ansible.json.template - шаблон для заполнения
example_synthetics_data.json - файл с синтетическими данными

Описание популярных параметров:

    "vmid":             ## id контейнера
    "ostemplate":       ## путь до шаблона контейнера: <storage>:vztmpl/<имя шаблона>
    "ostype":           ## указывается для корректных изменений специфических для данной ОС конфигурационных файлов
    "description":      ## описание, заметки
    "tags":             ## тэг
    "arch":             ## архитектура процессора: amd64 | i386 | arm64 | armhf
    "cores":            ## количество ядер
    "cpulimit":         ## лимит CPU
    "memory":           ## размер ОЗУ
    "swap":             ## размер файла подкачки
    "hostname":         ## имя хоста контейнера
    "nameserver":       ## DNS сервер
    "net0":                 ## настройка сети
                            ## name= <имя сетевого интерфейса контейнера>
                            ## bridge= <мост хоста для подключения сетевого интерфейса контейнера>
                            ## firewall= <определяет, следует ли использовать правила брандмауэра этого интерфейса>
                            ## gw= <шлюз по умолчанию для трафика IPv4>
                            ## hwaddr= <MAC-адрес, должен быть свободен, для этого смотреть на хосте занятые маки и добавлять + 1>
                            ## ip= <IPv4-адрес контейнера>
                            ## type= <Тип сетевого интерфейса, по умолчанию veth>
    "onboot":           ## поведение контейнера при старте гипервизора
    "start":            ## стартовать контейнер после создания
    "startup":          ## порядок включения\выключения
    "unprivileged":     ## privileged - небезопасно, unprivileged - безопасно
    "protection":       ## защита от случайного удаления
    "rootfs":           ## настройка файловой системы корня, для создаваемых контейнеров указывается вида STORAGE_ID:SIZE_IN_GiB
    "storage":          ## в каком хранилище искать шаблон
    "pool":             ## логическая группа контейнеров и виртуальных машин
    "password":         ## root пароль контейнера
    "ssh-public-keys":  ## открытый ключ для подключения к учетной записи root по SSH, спецсимволы экранируется \

4. Запрос к серверу

a) curl

–insecure - указывает на игнорирование проверки сертификата SSL / TLS при выполнении запроса и будет продолжаться выполнение запроса, даже если сертификат сервера не может быть проверен или не является доверенным
–verbose - curl будет выводить дополнительную информацию о процессе выполнения запроса, включая отправленные и полученные заголовки HTTP, коды состояния, информацию о соединении и другие детали
–data-raw - для указания данных, которые будут отправлены на сервер в их исходном виде - без изменений, когда данные - содержат специальные символы или форматы, которые не должны быть автоматически обработаны или изменены
–header “Authorization: PVEAPIToken=!=”
где

• user_token - user, к которому привязали token
• token_id, token который мы создали и запомнили в п.1
• secret_token, secret токена, который мы создали и запомнили в п.1

Пример:

curl -X POST https://{host}:8006/api2/json/nodes/pve/lxc --verbose --insecure --header "Authorization: PVEAPIToken=user@pve!token_id=sfgddg-hdf-dfhg" --header 'Content-Type: application/json' --data-raw ''

или, используя локальный файл lxc-ansible.json

curl -X POST https://{host}:8006/api2/json/nodes/pve/lxc --verbose --insecure --header "Authorization: PVEAPIToken=user@pve!token_id=sfgddg-hdf-dfhg" --header 'Content-Type: application/json' --data-raw @lxc-ansible.json 

b) postman

Данные по авторизации передаем через заголовки, соотвествующая вкладка Headers:
key= Authorization value= PVEAPIToken=user@pve!token_id=sfgddg-hdf-dfhg

В тело запроса (body) передаем json

• используя raw формат данных
  или
• вложенный файл формат binary

5. Настройка контейнера

Параметром hookscript можно привязать к контейнеру скрипт, но сделать это можно только от root, что делать не рекомендуется из соображений безопасности.
Красивого решения на данный момент не существует.

В репозитории можно найти файл alpine_ansible_postinstall.sh в нем описаны вызовы к api, которые позволяют с хоста выполнять команды внутри контейнера. Данный файл необходимо скопировать в storage/snippets, после чего файл появится в web интерфейсе данного storage. Запускается скрипт только из консоли хоста.

Пример storage:
/mnt/storage/snippets

Внимание! Синтаксиc важен.
pct exec [ct_id] – [command]
pct exec 100 hostname && hostname - первая команда hostname будет выполнена в контейнере, вторая на хосте
pct exec 100 hostname && pct exec 100 hostname - обе команда будут выполнены в контейнере
pct exec 100 – ls -la - для запуска в контейнере команды с параметрами используется – после идентификатора контейнера

6. Типичные ошибки

Proxmox шлет в теле ответа ошибки. Как правило ошибки связаны либо с не валидным json, либо с правами.

Примеры:

403 Permission check failed

Не достаточно прав у token id для выполнения запроса.