Работа с API VPC
Введение: проекты, ресурсы и квоты
Базовым понятием в сервисе “Виртуальное приватное облако” является проект — это совокупность объектов и ресурсов в нескольких регионах и зонах доступности, к которым может иметь доступ пользователь: виртуальных машин, дисков, сетей и других. В рамках каждого проекта пользователь может распределять между объектами ресурсы (оперативную память, ядра CPU, дисковое пространство и так далее).
Управлять проектами, ресурсами и объектами можно с помощью API. Взаимодействие с API осуществляется с помощью стандартных HTTP-запросов. Чтобы осуществить вызов к API, нужно выбрать в документации нужный метод, сформировать запрос в соответствии с описанием этого метода и выполнить его. API возвращает ответ в формате JSON.
Структура типовых запросов (создание проекта, назначение квот для этого проекта и добавление пользователей) и ответов на них описана ниже. Полная документация опубликована в панели управления.
curl 'https://api.selectel.ru/vpc/resell/v2/projects' -X POST -H "Content-Type: application/json" --data-binary {project:{"name":"test"}}' -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx"
Подготовка к работе: получение ключа
Прежде чем приступать к работе с API, необходимо получить ключ (токен). Зарегистрированные пользователи Selectel могут получить ключ на странице my.selectel.ru/profile/apikeys. Токен представляется собой строку вида qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx, где xxxxx — это номер учётной записи пользователя.
Ключ передаётся в каждом запросе в заголовке X-Token, например:
curl -i https://api.selectel.ru/vpc/resell/v2/projects -H 'X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx'
Создание проекта
Создадим проект с именем test. Это мы сделаем при помощи следующего запроса:
curl 'https://api.selectel.ru/vpc/resell/v2/projects' -X POST -H "Content-Type: application/json" --data-binary {project:{"name":"test"}}' -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx"
Ответ:
{"project": {"url": "https://8888.selvpc.ru", "enabled": true, "id": "fa9e778a6cb64fcca46605be6b58164c", "name": "test"}}
В ответе содержится следующая информация о том, что:
проект создан и готов к работе;
внешняя панель управления проектом доступна по адресу https://8888.selvpc.ru;
проект получил идентификационный номер fa9e778a6cb64fcca46605be6b58164c (он понадобится в некоторых последующих запросах, а также для работы со сторонними библиотеками и консольными клиентами);
в соответствии с запросом проект получил имя test.
Для продолжения работы нам нужно выделить определённое количество ресурсов, то есть установить квоты.
Выделение ресурсов и установка квот
На этом этапе нужно указать, какие ресурсы и в каком количестве будут использоваться в проекте.
Рассмотрим конкретный пример:
curl -i -XPATCH "https://api.selectel.ru/vpc/resell/v2/quotas/projects/fa9e778a6cb64fcca46605be6b58164c" -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx " -H "Content-Type: application/json" -d '{"quotas": {"compute_cores": [{"region": "ru-1", "zone": "ru-1b", "value": 8}]}}'
Здесь мы обращаемся к API VPC и просим предоставить 8 процессорных ядер под проект в регионе ru-1 и в зоне ru-1b.
Далее запросим 8192 МБ памяти и 100 ГБ дискового пространства:
curl -i -XPATCH "https://api.selectel.ru/vpc/resell/v2/quotas/projects/fa9e778a6cb64fcca46605be6b58164c" -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx" -H "Content-Type: application/json" -H "Accept: application/json" -H "User-Agent: python-selvpcclient/1.0" -d '{"quotas": {"compute_ram": [{"region": "ru-1", "zone": "ru-1b", "value": 8192}]}}'
curl -i -XPATCH "https://api.selectel.ru/vpc/resell/v2/quotas/projects/fa9e778a6cb64fcca46605be6b58164c" -H "X-Token:qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx" -H "Content-Type: application/json" -H "Accept: application/json" -H "User-Agent: python-selvpcclient/1.0" -d '{"quotas": {"volume_gigabytes_universal": [{"region": "ru-1", "zone": "ru-1b", "value": 100}]}}'
Общую информацию о проекте можно просмотреть так:
curl 'https://api.selectel.ru/vpc/resell/v2/projects/fa9e778a6cb64fcca46605be6b58164c' -H 'X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_22302'
В ответ мы получим JSON с информацией о проекте:
{ "project": { "name": "test", "url": "https://51852.selvpc.ru", "enabled": true, "custom_url": null, "quotas": { "volume_gigabytes_basic": [ { "region": "ru-1", "used": 0, "zone": "ru-1b", "value": 0 }, { "region": "ru-1", "used": 0, "zone": "ru-1a", "value": 0 }, { "region": "ru-2", "used": 0, "zone": "ru-2a", "value": 0 } ], "compute_cores": [ { "region": "ru-1", "used": 4, "zone": "ru-1b", "value": 8 }, { "region": "ru-1", "used": 0, "zone": "ru-1a", "value": 0 }, { "region": "ru-2", "used": 0, "zone": "ru-2a", "value": 0 } ], "image_gigabytes": [ { "region": "ru-1", "used": 0, "zone": null, "value": 0 }, { "region": "ru-2", "used": 0, "zone": null, "value": 0 } ], "volume_gigabytes_universal": [ { "region": "ru-1", "used": 80, "zone": "ru-1b", "value": 100 }, { "region": "ru-1", "used": 0, "zone": "ru-1a", "value": 0 }, { "region": "ru-2", "used": 0, "zone": "ru-2a", "value": 0 } ], "compute_ram": [ { "region": "ru-1", "used": 4096, "zone": "ru-1b", "value": 8192 }, { "region": "ru-1", "used": 0, "zone": "ru-1a", "value": 0 }, { "region": "ru-2", "used": 0, "zone": "ru-2a", "value": 0 } ], "volume_gigabytes_fast": [ { "region": "ru-1", "used": 0, "zone": "ru-1b", "value": 0 }, { "region": "ru-1", "used": 0, "zone": "ru-1a", "value": 0 }, { "region": "ru-2", "used": 0, "zone": "ru-2a", "value": 0 } ], "volume_gigabytes_iso": [ { "region": "ru-1", "used": 0, "zone": null, "value": 0 }, { "region": "ru-2", "used": 0, "zone": null, "value": 0 } ] }, "theme": { "color": "#ff000", "logo": null }, "id": "fa9e778a6cb64fcca46605be6b58164c" } }
Точно такой же ответ API возвращал и на предыдущие запросы (параметры, которые ещё не были заданы, имели значение 0).
Чтобы виртуальные машины в проекте были доступны из внешней сети, добавим плавающие IP-адреса:
curl -i -XPOST 'https://api.selectel.ru/vpc/resell/v2/floatingips/projects/fa9e778a6cb64fcca46605be6b58164c' -H 'Content-Type: application/json' --data-binary '{"floatingips":[{"region":"ru-1","quantity":3}]}' -H 'X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_22302'
Структура запроса понята: мы добавляем 3 адреса ("quantity":3) в регионе ru-1.
Ответ на этот запрос выглядит так:
{"floatingips": [{"status": "DOWN", "region": "ru-1", "floating_ip_address": "77.244.220.30", "project_id": "fa9e778a6cb64fcca46605be6b58164c", "id": "d5489d04-6c5f-46f5-810b-7f86c71ce8ae"}, {"status": "DOWN", "region": "ru-1", "floating_ip_address": "77.244.220.50", "project_id": "fa9e778a6cb64fcca46605be6b58164c", "id": "12d78f81-3d56-4592-92f2-558d5c4e2f68"},{"status": "DOWN", "region": "ru-1", "floating_ip_address": "77.244.220.73", "project_id": "fa9e778a6cb64fcca46605be6b58164c", "id": "7569e8f8-3cb1-4823-8e1e-c69574b0282f"}
Каждый IP-адрес имеет статус DOWN, но это свидетельствует не о какой-то неполадке, а лишь о том, что в настоящий момент он не присвоен ни одной виртуальной машине. Как и у всех объектов VPC, у каждого IP-адреса есть ID.
Этот параметр также будет нужен в дальнейшем, когда мы будем создавать виртуальные машины и назначать им адреса.
Пользователи и роли
В проект могут быть добавлены пользователи. Порядок действий при этом таков: сначала нужно создать пользователя, а затем добавить его в проект.
Пользователь, который добавлен в проект и обладает определённым набором прав в рамках этого проекта, в терминологии OpenStack имеет роль в этом проекте. Роль в проекте нужна для работы с OpenStack API, например, с помощью программ, которые описаны в статье Консольные клиенты.
Чтобы создать нового пользователя, нужно отправить POST-запрос и передать логин и пароль:
curl -i -XPOST "https://api.selectel.ru/vpc/resell/v2/users" -H "X-Token: qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx" -H "Content-Type: application/json" -H "Accept: application/json -d '{"user": {"password": "password, "enabled": true, "name": "new user"}}'
Если запрос выполнен успешно, API возвращает ответ вида:
{"user": {"enabled": true, "name": "newuser", "id": "6000869ba906427aaeb997835c4babdb"}}
Чтобы назначить пользователю роль (т.е. добавить пользователя в проект), выполним запрос вида:
curl -i -XPOST "https://api.selectel.ru/vpc/resell/v2/roles/projects/{id проекта}/users/{id пользователя}" -H "X-Token:qX3Npu42ua73kPkhe4QCQ8Vv9_xxxxx"
Итак, проект создан, квоты назначены, пользователь добавлен. Всё готово к созданию виртуальных машин.
Эта операция осуществляется с помощью консольных клиентов OpenStack, работа с которыми описывается в статье Консольные клиенты.
Библиотеки для работы с API
Для работы с API виртуального приватного облака доступны следующие библиотеки: