Работа с 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 виртуального приватного облака доступны следующие библиотеки:

База знаний