Библиотека python-selvpcclient

python-selvpcclient

Наш сервис Виртуальное приватное облако построен на базе платформы OpenStack. Первоначальное конфигурирование облака и управление некоторыми типами объектов осуществляется через наш собственный API.

Для удобного взаимодействия с нашим сервисом мы разработали библиотеку selvpcclient. Она написана на языке Python и покрывает весь API, благодаря чему вы можете управлять проектами, квотами, ресурсами из своего программного кода или консоли.

Подготовка к работе

1. Загрузите библиотеку из pypi командой:

pip install python-selvpcclient

2. Получите API Token для работы с облаком (например, ключ следующего вида «xxxxvGBYVXcQ3q86zQCGxgvk_42069»).

3. Получите актуальный адрес API URL, например, https://api.selectel.ru/vpc/resell/v2.

Использование библиотеки

После успешной установки библиотеки, её нужно импортировать и инициализировать:

from selvpcclient.client import Client, setup_http_client
    
SEL_TOKEN=YOUR_API_TOKEN_HERE
SEL_URL="https://api.selectel.ru/vpc/resell"
SEL_API_VERSION=2

http_client = setup_http_client(api_url=SEL_URL,
                                api_version=SEL_API_VERSION, 
                                api_token=SEL_TOKEN)
selvpc = Client(client=http_client)

Примечание: API URL и версия API указываются отдельно!

Объект selvpc имеет следующие поля:

  • projects — для управления проектами;
  • quotas — для управления квотами проектов;
  • limits — для получения информации о доменных ограничениях;
  • users — для управления пользователями;
  • licenses — для управления лицензиями;
  • roles — для взаимодействия ролями пользователей;
  • floatingips — для управления плавающими адресами;
  • subnets — для управления подсетями;
  • vrrp — для управления VRRP подсетями;
  • capabilities — для получения вспомогательной информации (информация о доступных регионах, зонах и так далее);
  • tokens — для получения токена позволяющего взаимодействовать с OpenStack API напрямую.

Поля обладают следующими методами:

  • list — для получения списка объектов (кроме tokens);
  • show — для показа детальной информации об объекте (кроме tokens);
  • create — для создания объекта (только projects / users);
  • add — для добавления ресурса в проект (кроме tokens);
  • update — для обновления объекта (только projects / users);
  • delete — для удаления объекта (кроме tokens).

Создаем проект и устанавливаем квоты

При создании проекта, установим базовые квоты и добавим лицензию для Windows Server 2012:

project = selvpc.projects.create("Bonnie")

Примечание: Также с версии библиотеки 1.1 можно получить «голый» json ответ от API, для этого необходимо передать ключ return_raw:

   project_json = selvpc.projects.create("Clyde", return_raw=True)

project_json будет содержать значение:

     {
        "name": "Clyde",
        "id": "f3504dc929ee40e5a296143218bf435d",
        "url": "https://xxxx.selvpc.ru",
        "enabled": True
     }

Результатом данной операции будет объект класса «Project», который имеет вспомогательные методы (delete, update и так далее).

Теперь установим квоты на созданный проект:

    "quotas": {
            "compute_cores": [
                {
                    "region": "ru-1",
                    "zone": "ru-1a",
                    "value": 10
                }
            ],
            "compute_ram": [
                {
                    "region": "ru-1",
                    "zone": "ru-1a",
                    "value": 1024
                }
            ]
        }
    }

    # via object
    project.update_quotas(quotas)

    # via quotas manager
    quotas = client.quotas.update(project.id, quotas=quotas)

Добавим лицензию:

    "licenses": [{
          "region": "ru-1",
          "quantity": 1,
          "type": "license_windows_2012_standard"
      }]
    }

    # via object
    project.add_license(license)

    # via licenses manager
    licenses = selvpc.licenses.add(project.id, licenses=licenses)

CLI

Вместе с библиотекой предоставляется консольное приложение selvpc. Оно основано на python-cliff — фреймворке для создания консольных приложений.

Подробнее о python-cliff можно послушать здесь.

Подготовка к работе

Для работы консольного приложения с облаком необходимы URL API и токен.

Консольное приложение может получить их одним из двух способов: из соответствующих переменных окружения SEL_URL и SEL_TOKEN или из аргументов, переданных при вызове («- -url» URL, «- -token» TOKEN).

Примечание: по умолчанию, библиотека уже настроена на работу с 2 версией API, SEL_API_VERSION / — -api-version можно не указывать.

Примечание: если информация передана через аргументы и присутствует в переменных окружения, то приоритет будет отдан аргументам.

    export SEL_TOKEN="xxxxvGBYVXcQ3q86zQCGxgvk_42069"
    export SEL_URL="https://api.selectel.ru/vpc/resell"
    export SEL_API_VERSION=2

    selvpc --url "https://api.selectel.ru/vpc/resell" --token "xxxxvGBYVXcQ3q86zQCGxgvk_42069" project list

Команды

Команды стандартны для консольных клиентов OpenStack:
1. Для создания объекта – * create (например, project create);
2. Для обновления объекта – * update (например, user update);
3. Для получения списка объектов – * list (например, license list);
4. Для удаления объекта – * delete (например, subnet delete).

Где * – ключевое имя объекта: «project, user, role, floatingip, subnet, vrrp, license».

Для примера создадим проект, воспользовавшись командой project create:

    selvpc project create -n awesome

Получим список проектов:

    selvpc project list

    +----------------------------------+----------+-------------------------+---------+
    | id                               | name     | url                     | enabled |
    +----------------------------------+----------+-------------------------+---------+
    | f3504dc929ee40e5a296143218bf435d | awesome  | https://xxxxx.selvpc.ru | True    |
    +----------------------------------+----------+-------------------------+---------+

Вы всегда можете получить список доступных команд, введя в консоли команду:

    selvpc help

    Commands:
      ...
      capabilities show traffic  Show available traffic values
      complete       print bash completion command
      floatingip add  Create new floatingip IP address
      floatingip delete  Delete floatingip IP
      floatingip list  List floatingip IP
      ...

Создание виртуальной машины на базе Ubuntu 16 x64

Рассмотрим подробный пример того, как с помощью консольных клиентов можно создать виртуальную машину.

Общая последовательность действий будет примерно такой:
1. Создаем проект, пользователя и добавляем роль.
2. Выделяем ресурсы.
3. Подготавливаем окружение.
4. Создаем виртуальную машину.

Создаем проект

Создаём проект:

    selvpc project create -n "another-project"

    +---------+----------------------------------+
    | Field   | Value                            |
    +---------+----------------------------------+
    | id      | 96063b0c4a71443c8a842c647bdab316 |
    | name    | "another-project"                |
    | url     | https://xxxxx.selvpc.ru          |
    | enabled | True                             |
    +---------+----------------------------------+

Так как пользователей у нас ещё нет, создадим их:

    selvpc user create --name "T-Rex" --password "c1017e8c8fd14b7e8057618a882240df"

    +---------+----------------------------------+
    | Field   | Value                            |
    +---------+----------------------------------+
    | id      | 052027b58a3f49e390c3849d6697e2f3 |
    | name    | "T-Rex"                          |
    | enabled | True                             |
    +---------+----------------------------------+

Добавим пользователя «T-Rex» (052027b58a3f49e390c3849d6697e2f3) в проект «another-project» (96063b0c4a71443c8a842c647bdab316):

    selvpc role add -p 96063b0c4a71443c8a842c647bdab316 -u 052027b58a3f49e390c3849d6697e2f3

    +------------+----------------------------------+
    | Field      | Value                            |
    +------------+----------------------------------+
    | project_id | 96063b0c4a71443c8a842c647bdab316 |
    | user_id    | 052027b58a3f49e390c3849d6697e2f3 |
    +------------+----------------------------------+

Выделяем ресурсы

Для нашей новой машины мы выделим 1 ядро, 512 МБ памяти и 5 ГБ диска.
Доступные на данный момент ресурсы можно получить, используя следующую команду:

    /приводим фрагмент вывода/

selvpc capabilities show resources

    +-------------------------------+-------------+----------+------------+
    | name                          | quota_scope | quotable | unbillable |
    +-------------------------------+-------------+----------+------------+
    | compute_cores                 | zone        | True     | True       |
    | compute_ram                   | zone        | True     | True       |
    | volume_gigabytes_fast         | zone        | True     | False      |
    +-------------------------------+-------------+----------+------------+

Квоты на проект можно установить командой «selvpc quota set» (описание аргументов можно узнать через help: «selvpc _help_ quota set»):

    selvpc quota set 96063b0c4a71443c8a842c647bdab316 --region ru-1 --zone ru-1a --value 1 --resource compute_cores
    selvpc quota set 96063b0c4a71443c8a842c647bdab316 --region ru-1 --zone ru-1a --value 512 --resource compute_ram
    selvpc quota set 96063b0c4a71443c8a842c647bdab316 --region ru-1 --zone ru-1a --value 5 --resource volume_gigabytes_fast

    +----------------------------+--------+-------+-------+
    | resource                   | region | zone  | value |
    +----------------------------+--------+-------+-------+
    | compute_cores              | ru-1   | ru-1a | 1     |
    | compute_ram                | ru-1   | ru-1a | 512   |
    | volume_gigabytes_fast      | ru-1   | ru-1a | 5     |
    +----------------------------+--------+-------+-------+

Для того чтобы взаимодействовать с облаком через опенстековские клиенты необходимо авторизоваться.

Для удобства наших пользователей мы предоставляем RC-файл (он представляет собой скрипт, с помощью которого консольные клиенты могут авторизовываться в Identity API v3).

Для получения скрипта необходимо выполнить следующие действия:

  1. Перейдите в панель управления проектами.
  2. Откройте проект, в котором будете работать.
  3. Перейдите на вкладку Доступ.
  4. Выберите пользователя.
  5. Выберите регион.
  6. Нажмите кнопку Скачать.

python-selvpcclient

Пример содержания RC.sh:

    export OS_AUTH_URL="https://api.selvpc.ru/identity/v3"
    export OS_IDENTITY_API_VERSION="3"
    export OS_VOLUME_API_VERSION="2"

    export OS_PROJECT_DOMAIN_NAME='xxxx'
    export OS_PROJECT_ID='96063b0c4a71443c8a842c647bdab316'
    export OS_TENANT_ID='96063b0c4a71443c8a842c647bdab316'
    export OS_REGION_NAME='ru-1'

    export OS_USER_DOMAIN_NAME='xxxx'
    export OS_USERNAME='T-Rex'

    export OS_PASSWORD='c1017e8c8fd14b7e8057618a882240df'

Примечание: В оригинальном скрипте переменная «OS_PASSWORD» содержать пароль не будет, так как явно инициализирована для демонстрации. Никогда не светите свои пароли — это не безопасно!

После загрузки скрипта его необходимо исполнить командой source:

source RC.sh

Подготавливаем окружение

В данном примере мы будет использовать образ Ubuntu 16.04 LTS 64-bit.

Получим список доступных образов:

    openstack image list

    +--------------------------------------+---------------------------------+--------+
    | ID                                   | Name                            | Status |
    +--------------------------------------+---------------------------------+--------+
    | 9feac917-f155-4013-b2fa-f5c8b72fd33c | Ubuntu 16.04 LTS 64-bit         | active |
    +--------------------------------------+---------------------------------+--------+

Создадим диск на основе образа:

    openstack volume create ubuntu-volume --image "9feac917-f155-4013-b2fa-f5c8b72fd33c" --size 5

    +---------------------+--------------------------------------+
    | Field               | Value                                |
    +---------------------+--------------------------------------+
    | id                  | f79c0d35-f54c-4b6a-82ad-1764e425eec8 |
    +---------------------+--------------------------------------+

Для создания машины так же нужен flavor – конфигурация для создания машины.

Создадим новую приватную конфигурацию:

	openstack flavor create --private --ram 512 --vcpus 1 my-flavor

+----------------------------+--------------------------------------+
| Field                      | Value                                |
+----------------------------+--------------------------------------+
| id                         | 006f7e84-f957-4764-a3a7-db8575c54ba7 |
| name                       | my-flavor                            |
| os-flavor-access:is_public | False                                |
| ram                        | 512                                  |
| vcpus                      | 1                                    |
+----------------------------+--------------------------------------+

Создаем виртуальную машину

И, наконец, создаем виртуальную машину с громким именем «server-1»:

    openstack server create --wait --volume "f79c0d35-f54c-4b6a-82ad-1764e425eec8" --flavor "006f7e84-f957-4764-a3a7-db8575c54ba7" "server-1"

Примечание: если у вас в проекте несколько подсетей, то при создании ВМ необходимо указать, какую подсеть использовать.

	openstack subnet list
+--------------------------------------+----------------+--------------------------------------+----------------+
| ID                                   | Name           | Network                              | Subnet         |
+--------------------------------------+----------------+--------------------------------------+----------------+
| aa5919fb-d683-4589-a093-f185d27e046a | 192.168.0.0/24 | a220c08e-a63f-48b8-aca5-563136ee9131 | 192.168.0.0/24 |
| ce86a3f2-fa64-4803-bb8e-7f9bfeb8db2e | 192.168.0.0/24 | afc24500-65f0-4d28-ada0-773d92820850 | 192.168.0.0/24 |
+--------------------------------------+----------------+--------------------------------------+----------------+

openstack server create --wait --volume "f79c0d35-f54c-4b6a-82ad-1764e425eec8" --flavor "006f7e84-f957-4764-a3a7-db8575c54ba7" --network a220c08e-a63f-48b8-aca5-563136ee9131 "server-1"

Заключение

Задавайте вопросы в комментариях!

Если вы столкнулись с проблемой при использовании библиотеки или хотите что-то изменить, смело открывайте issue.

Примечание: актуальная версия библиотеки на момент написания статьи — 1.0.

Полезные ссылки

Библиотека python-selvpcclient на github

Документация к API VPC

Ключ для работы с облаком