Работа с виртуальными машинами через API

Пароль для доступа к API сейчас идентичен паролю от личного кабинета на портале https://mcs.mail.ru/.

Также в разделе личного кабинета "Профиль проекта" вы можете скачать API ключ (файл с расширением *.sh):

Что такое API?

API (программный интерфейс приложения, интерфейс прикладного программирования) (англ. application programming interface, API [эй-пи-ай]) — описание способов (набор классов, процедур, функций, структур или констант), которыми одна компьютерная программа может взаимодействовать с другой программой. Обычно входит в описание какого-либо интернет-протокола (например, RFC), программного каркаса (фреймворка) или стандарта вызовов функций операционной системы. Часто реализуется отдельной программной библиотекой или сервисом операционной системы. Используется программистами при написании всевозможных приложений.

Для чего можно использовать API?

Чтобы написанная вами (или любая сторонняя) программа, приложение, любая сущность - могла взаимодействовать с облачной инфраструктурой так, как вам необходимо, дёргая задокументированные "ручки" и получая обратно статусы/ответы на запрос и т.п. 

OpenStack — комплекс проектов свободного программного обеспечения, который может быть использован для создания инфраструктурных облачных сервисов и облачных хранилищ, при том как публичных, так и частных. Все проекты комплекса распространяются под лицензией Apache License.

Почему OpenStack API?

Так как многие сервисы MCS написаны с использованием технологий OpenStack, то с ними можно взаимодействовать через OpenStack API, если отдельно не указано обратное.

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

Актуально на: 2018-10-03 16:14

Используйте API-интерфейсы OpenStack для запуска экземпляров сервера, назначения метаданных экземплярам, создания контейнеров и объектов хранения, и выполнения других действий в облаке OpenStack.

Для получения дополнительной информации о значениях состояния API и информации о версии см. Обнаружение версии .

Обозначение «(микроверсии)» рядом со ссылкой на ссылку API указывает, что API следует шаблону, установленному службой Compute, чтобы обеспечить небольшие, документированные изменения API для каждого ресурса в отдельности.

Текущие версии API

Важно

Некоторые методы API, описанные в статьях ниже, могут быть неработоспособны в сервисах MCS. Это связано с динамикой разработки версий API компанией OpenStack.

Если вы заметили, что какие-то методы не работают или работают не так, как надо, напишите нам, пожалуйста, в форму обратной связи.

API службы контейнера приложений (микроверсии)

API резервного копирования v1

Bare Metal API v1 (микроверсии)

Block Storage API v3 (микроверсии)

API хранилища блоков v3 функционально идентичен API хранилища блоков v2. Последующие микроверсии API v3, такие как v3.1, отличаются от API v2.

API кластеризации v1

Compute API (микроверсии)

API управления контейнерной инфраструктурой (микроверсии)

Обработка данных v1.1

Оркестровка защиты данных v1

API службы баз данных v1.0

API сервера доменных имен (DNS) v2

EC2 API Сервис

Identity API v3

Расширения Identity API v3

API сервиса образов v2

Load Balancer API v2

Messaging API v2

Сетевой API v2.0

NFV Orchestration API v1.0

API хранилища объектов v1

API оркестровки v1

API размещения (микроверсии)

Resource Optimization API v1

API поиска v1

Shared File Systems API v2 (микроверсии)

API Shared File Systems v1 функционально идентичен API Shared File Systems v2. Последующие микроверсии API v2, такие как v2.1, отличаются от API v1.

 

Устаревшие версии API

API блочного хранилища v2

API хранилища блоков v3 функционально идентичен API хранилища блоков v2. Последующие микроверсии API v3, такие как v3.1, отличаются от API v2.

Расширения Identity API v2.0

Примеры быстрого запуска API

При установке TryStack/OpenStack эти службы работают вместе в фоновом режиме установки, и многие из этих примеров работают на TryStack.

После аутентификации с помощью Identity вы можете использовать другие API-интерфейсы OpenStack для создания ресурсов и управления ими в облаке MCS. Вы можете запускать экземпляры из образов и назначать метаданные экземплярам через API Compute или клиент командной строки openstack .

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

cURL

Инструмент командной строки, который позволяет отправлять HTTP-запросы и получать ответы. Смотрите раздел под названием OpenStack APIs .

Клиент командной строки OpenStack

Проект OpenStack предоставляет клиент командной строки, который позволяет вам получать доступ к API через простые в использовании команды. См. Раздел « Клиенты командной строки OpenStack» .

REST клиенты

Как Mozilla, так и Google предоставляют браузерные графические интерфейсы для REST. Для Firefox см. RESTClient . Для Chrome см. Rest-client.

OpenStack Python Software Development Kit (SDK)

Используйте этот SDK для написания скриптов автоматизации Python, которые создают и управляют ресурсами в вашем облаке MCS. В SDK реализованы привязки Python к API-интерфейсу OpenStack, который позволяет выполнять задачи автоматизации в Python, выполняя вызовы объектов Python вместо непосредственных вызовов REST. Все инструменты командной строки OpenStack реализованы с использованием Python SDK. См. OpenStack Python SDK в Руководстве пользователя OpenStack .

API OpenStack

Аутентификация и рабочий процесс запроса API

Аутентификация

Отправка запросов API

Клиенты командной строки OpenStack

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

Чтобы аутентифицировать доступ к сервисам OpenStack, вы должны сначала отправить запрос аутентификации с учётными данными в OpenStack Identity, чтобы получить токен аутентификации.

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

Когда вы отправляете запросы API, вы должны включать токен в заголовок X-Auth-Token . Если вы получаете доступ к нескольким службам OpenStack, вы должны получить токен для каждой службы. Токен действителен в течение ограниченного времени до истечения срока его действия. Токен также может стать недействительным по другим причинам. Например, если роли для пользователя изменяются, существующие токены для этого пользователя больше не действительны.

Аутентификация и рабочий процесс запроса API

Использование OS_PROJECT_ID

После 27 мая 2020 года сервис авторизации и аутентификации переходит на новый способ идентификации проектов.

Если вы используете API, клиент командной строки openstack-client или локальную утилиту для настройки инфраструктуры Terraform, вам нужно начать использовать идентификатор (OS_PROJECT_ID) проекта вместо его имени (OS_PROJECT_NAME) до 27 мая включительно.

Значение OS_PROJECT_ID и других параметров проекта можно посмотреть внутри личного кабинета: https://mcs.mail.ru/app/project/keys/

Примеры корректного использования параметра:

API

curl --location --request POST 'https://infra.mail.ru:5000/v3/auth/tokens' \
--header 'Content-Type: application/json' \
--data-raw '{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "domain": {
                        "id": "users"
                    },
                    "name": "YOUR USER NAME",
                    "password": "YOUR PASSWORD"
                }
            }
        },
        "scope": {
            "project": {
                "id": "YOUR PROJECT ID"
            }
        }
    }
}'

Провайдер Terraform

terraform.tf:

provider "openstack" {
    provider "openstack" {
    # the user name to login with
    user_name = "YOUR USER NAME"

    # the password to login with
    password = "YOUR PASSWORD"

    # the identifier of project to login with
    tenant_id = "YOUR PROJECT ID"

    # the domain identifier where the user is located
    user_domain_id = "users"

    # an API endpoint to connect to MCS identity service
    auth_url = "https://infra.mail.ru:5000/v3/"

    # use octavia to manage load balancers
    use_octavia = true
}

Командная строка OpenStackClient

openrc.sh:

#!/usr/bin/env bash

export OS_AUTH_URL=https://infra.mail.ru:5000/v3/

export OS_PROJECT_ID="YOUR PROJECT ID"
unset OS_PROJECT_NAME
unset OS_PROJECT_DOMAIN_ID

# unset v2.0 items in case set
unset OS_TENANT_ID
unset OS_TENANT_NAME

export OS_USERNAME="YOUR USER NAME"
export OS_USER_DOMAIN_NAME="users"

# With Keystone you pass the keystone password.
echo "Please enter your OpenStack Password for project $OS_PROJECT_ID as user $OS_USERNAME: "
read -sr OS_PASSWORD_INPUT
export OS_PASSWORD=$OS_PASSWORD_INPUT

export OS_INTERFACE=public
export OS_IDENTITY_API_VERSION=3

Важно

В приведенном выше запросе строка запроса nocatalog используется, поскольку вы просто хотите получить токен и не хотите, чтобы каталог служб (если он доступен для пользователя) загромождал возвращаемые данные. Если пользователь хочет получить каталог услуг, эту строку запроса не нужно добавлять к URL-адресу.

Отправка запросов API

В этом разделе показано, как выполнить некоторые базовые вызовы Compute API. Полный список вызовов Compute API см. в разделе Compute API .

Экспортируйте идентификатор токена в переменную окружения OS_TOKEN . Например:

 export OS_TOKEN=gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99BHrjdSGai--_-JstU3WazsFXmRHNbD07q
OQKTp5Sen2R_b9csaDkU49VXqSaJ0jh2nAlwJkys8aazz2oa3xSeUVe3Ndv_HRiW23-iWTr6jquK_AXdhRX7nvM4lmVTrxXFpelnJQ

По умолчанию время жизни токена истекает каждый час, хотя его можно настроить по-разному - см. Параметр истечения срока действия в Руководстве по настройке Identity Service .

Экспортируйте имя проекта в переменную среды OS_PROJECT_NAME . Например:

 export OS_PROJECT_NAME=demo

Затем используйте API Compute для вывода списка вариантов, заменив конечную точку API Compute на ту, которая содержит идентификатор вашего проекта ниже:

 $ curl -s -H "X-Auth-Token:  $OS_TOKEN " \
  $OS_COMPUTE_API /flavors \
  | python -m json.tool
 {
    "flavors" : [
        {
            "id" : "1" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/1" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/1" ,
                    "rel" : "bookmark"
                }
            ],
            "name" : "m1.tiny"
        },
        {
            "id" : "2" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/2" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/2" ,
                    "rel" : "bookmark"
                }
            ],
            "name" : "m1.small"
        },
        {
            "id" : "3" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/3" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/3" ,
                    "rel" : "bookmark"
                }
            ],
            "name" : "m1.medium"
        },
        {
            "id" : "4" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/4" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/4" ,
                    "rel" : "bookmark"
                }
            ],
            "name" : "m1.large"
        },
        {
            "id" : "5" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/5" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/5" ,
                    "rel" : "bookmark"
                }
            ],
            "name" : "m1.xlarge"
        }
    ]
}

Экспортируйте $ OS_PROJECT_ID из вызова токена, а затем используйте Compute API для вывода списка образов:

 $ curl -s -H "X-Auth-Token:  $OS_TOKEN " \
  http://8.21.28.222:8774/v2/ $OS_PROJECT_ID /images \
  | python -m json.tool
 {
    "images" : [
        {
            "id" : "2dadcc7b-3690-4a1d-97ce-011c55426477" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477" ,
                    "rel" : "bookmark"
                },
                {
                    "href" : "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477" ,
                    "type" : "application/vnd.openstack.image" ,
                    "rel" : "alternate"
                }
            ],
            "name" : "Fedora 21 x86_64"
        },
        {
            "id" : "cfba3478-8645-4bc8-97e8-707b9f41b14e" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e" ,
                    "rel" : "bookmark"
                },
                {
                    "href" : "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e" ,
                    "type" : "application/vnd.openstack.image" ,
                    "rel" : "alternate"
                }
            ],
            "name" : "Ubuntu 14.04 amd64"
        },
        {
            "id" : "2e4c08a9-0ecd-4541-8a45-838479a88552" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552" ,
                    "rel" : "bookmark"
                },
                {
                    "href" : "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552" ,
                    "type" : "application/vnd.openstack.image" ,
                    "rel" : "alternate"
                }
            ],
            "name" : "CentOS 7 x86_64"
        },
        {
            "id" : "c8dd9096-60c1-4e23-a486-82955481df9f" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f" ,
                    "rel" : "bookmark"
                },
                {
                    "href" : "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f" ,
                    "type" : "application/vnd.openstack.image" ,
                    "rel" : "alternate"
                }
            ],
            "name" : "CentOS 6.5 x86_64"
        },
        {
            "id" : "f97b8d36-935e-4666-9c58-8a0afc6d3796" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796" ,
                    "rel" : "bookmark"
                },
                {
                    "href" : "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796" ,
                    "type" : "application/vnd.openstack.image" ,
                    "rel" : "alternate"
                }
            ],
            "name" : "Fedora 20 x86_64"
        }
    ]
}

Экспортируйте $ OS_PROJECT_ID из вызова токена, а затем используйте Compute API для вывода списка серверов:

 $ curl -s -H "X-Auth-Token:  $OS_TOKEN " \
  http://8.21.28.222:8774/v2/ $OS_PROJECT_ID /servers \
  | python -m json.tool
 {
    "servers" : [
        {
            "id" : "41551256-abd6-402c-835b-e87e559b2249" ,
            "links" : [
                {
                    "href" : "http://8.21.28.222:8774/v2/f8828a18c6484624b571e85728780ba8/servers/41551256-abd6-402c-835b-e87e559b2249" ,
                    "rel" : "self"
                },
                {
                    "href" : "http://8.21.28.222:8774/f8828a18c6484624b571e85728780ba8/servers/41551256-abd6-402c-835b-e87e559b2249" ,
                    "rel" : "bookmark"
                }
            ],
            "name" : "test-server"
        }
    ]
}


Часть информации взята из источника https://developer.openstack.org/api-guide/quick-start/ .

Также смотрите статью https://developer.openstack.org/api-guide/quick-start/api-quick-start.html .

Также смотрите статью с подробным описанием всех возможных действий с инстансами через API https://developer.openstack.org/api-ref/compute/