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

Руководство по REST API для миграции ВМ между ЦД

Добавлено в zVirt 5.0

1. Введение

Для автоматизации процесса миграции виртуальных машин между разными центрами данных предоставляется специализированный API миграции. Этот API является частью сервиса 'zvirt-engine-backend' и позволяет инициировать миграцию как работающих, так и выключенных виртуальных машин, а также выполнять предварительную проверку параметров миграции.

Данный API дополняет оригинальный REST API zVirt и придерживается основных принципов его построения, но в отличие от оригинального реализует доступ по HTTP(S) протоколу без реализации SDK.

Данная документация служит справочником по REST API для миграции ВМ между ЦД. Она предназначена для разработчиков и администраторов, желающих автоматизировать процессы миграции, и содержит инструкции и примеры для эффективного использования этого функционала.

2. Предварительные требования к API

Предварительные требования для использования REST API для миграции ВМ между ЦД:

  • Клиент или программная библиотека, которая инициирует и получает HTTP-запросы от сервера API. Например:

    • Инструмент командной строки cURL.

    • RESTClient — отладчик для веб-служб RESTful.

    • Postman — HTTP-клиент для тестирования API.

  • Знание протокола передачи гипертекста (HTTP), протокола, используемого для взаимодействия с REST API. Инженерная рабочая группа Интернета публикует запрос комментариев (RFC) с объяснением протокола передачи гипертекста по адресу http://www.ietf.org/rfc/rfc2616.txt.

  • Знание расширяемого языка разметки (XML) или нотации объектов JavaScript (JSON), которые API использует для создания представлений ресурсов. W3C предоставляет полную спецификацию XML на http://www.w3.org/TR/xml. ECMA International предоставляет бесплатную публикацию по JSON на http://www.ecma-international.org.

3. Аутентификация и безопасность

Предпочтительным механизмом аутентификации является OAuth 2.0, как описано в RFC 6749.

OAuth — это сложный протокол с несколькими механизмами получения токенов авторизации и доступа. Для использования с API поддерживается только предоставление учетных данных владельца ресурса, как описано в разделе 4.3 RFC 6749.

Сначала необходимо получить токен, отправив имя пользователя и пароль в службу единого входа Менеджера управления:

POST /ovirt-engine/sso/oauth/token HTTP/1.1
Host: myengine.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

Тело запроса должно содержать параметры grant_type, scope, username и password:

Таблица 1. Параметры запроса токена OAuth
Имя Значение

grant_type

password

scope

ovirt-app-api

username

admin@internal

password

mypassword

Эти параметры должны быть представлены в URL кодировке. Например, символ @ в имени пользователя должен быть закодирован как %40. Результирующее тело запроса будет примерно таким:

grant_type=password&scope=ovirt-app-api&username=admin%40internal&password=mypassword
Параметр scope описан как необязательный в OAuth RFC, но при использовании его с API он является обязательным, и его значение должно быть ovirt-app-api.

Если имя пользователя и пароль верны, служба единого входа Менеджера управления ответит документом JSON, подобным этому:

{
  "access_token": "fqbR1ftzh8wBCviLxJcYuV5oSDI=",
  "token_type": "bearer",
  "scope": "...",
  ...
}

Для целей аутентификации API единственной подходящей парой имя/значение является access_token. Ни в коем случае не манипулируйте этим; используйте его точно так, как это предусмотрено службой единого входа.

После получения токена его можно использовать для выполнения запросов к API, включив его в заголовок HTTP Authorization и используя схему Bearer. Например, чтобы получить список виртуальных машин, отправьте такой запрос:

GET /ovirt-engine/api/vms HTTP/1.1
Host: myengine.example.com
Accept: application/xml
Authorization: Bearer fqbR1ftzh8wBCviLxJcYuV5oSDI=

Токен можно использовать несколько раз для нескольких запросов, но в конечном итоге срок его действия истечет. По истечении этого срока сервер отклонит запрос с кодом ответа HTTP 401:

HTTP/1.1 401 Unauthorized

В этом случае требуется новый токен, так как служба единого входа Менеджера управления в настоящее время не поддерживает обновление токенов. Новый токен можно запросить тем же способом, который описан выше.

3.1. Ролевая модель

При использовании API миграции ВМ между центрами данных необходимо обладать ролью Миграция между центрами данных (MigrateVmBetweenDataCentersManager). Данная роль включает все необходимые разрешения.

Подробное описание разрешений и ролей см. в Технический справочник. Разрешения и роли.

3.2. TLS/SSL-сертификация

API zVirt требует защищенного протокола передачи гипертекста (HTTPS) для безопасного взаимодействия с клиентским программным обеспечением. Это включает в себя получение сертификата ЦС, используемого сервером, и его импорт в хранилище сертификатов вашего клиента.

3.2.1. Получение CA сертификата

Вы можете получить CA сертификат от Менеджера управления zVirt и передать его на клиентскую машину одним из следующих способов:

Способ 1

Предпочтительный метод получения CA сертификата — использовать инструмент командной строки openssl s_client для выполнения реального рукопожатия TLS с сервером, а затем извлечь сертификаты, которые он представляет. Запустите команду следующим образом:

$ openssl s_client \
-connect myengine.example.com:443 \
-showcerts \
< /dev/null

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

CONNECTED(00000003)
depth=1 C = US, O = Example Inc., CN = myengine.example.com.23416
verify error:num=19:self signed certificate in certificate chain
---
Certificate chain
 0 s:/C=US/O=Example Inc./CN=myengine.example.com
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIEaTCCA1GgAwIBAgICEAQwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
SVlJe7e5FTEtHJGTAeWWM6dGbsFhip5VXM0gfqg=
-----END CERTIFICATE-----
 1 s:/C=US/O=Example Inc./CN=myengine.example.com.23416
   i:/C=US/O=Example Inc./CN=myengine.example.com.23416
-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----

Текст между маркерами -----BEGIN CERTIFICATE----- и -----END CERTIFICATE----- показывает сертификаты, представленные сервером. Первый — это сертификат самого сервера, а последний — CA сертификат. Скопируйте CA сертификат вместе с метками в файл ca.crt. Результат должен выглядеть так:

-----BEGIN CERTIFICATE-----
MIIDxjCCAq6gAwIBAgICEAAwDQYJKoZIhvcNAQEFBQAwSTELMAkGA1UEBhMCVVMx
FTATBgNVBAoTDEV4YW1wbGUgSW5jLjEjMCEGA1UEAxMaZW5naW5lNDEuZXhhbXBs
Pkyg1rQHR6ebGQ==
-----END CERTIFICATE-----
Это самый надежный способ получить CA сертификат, используемый сервером. Остальные описанные здесь способы сработают в большинстве случаев, но они не дадут правильный CA сертификат, если он был вручную заменен администратором сервера.
Способ 2

Если вы не можете использовать описанный выше метод openssl s_client, вы можете вместо этого использовать инструмент командной строки для загрузки CA сертификата из Менеджера управления zVirt.

Примеры инструментов командной строки включают curl и wget, оба из которых доступны на нескольких платформах.

При использовании curl:

$ curl \
--output ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'

При использовании wget:

$ wget \
--output-document ca.crt \
'http://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA'
Способ 3

С помощью веб-браузера перейдите к сертификату, расположенному по адресу:

https://myengine.example.com/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA

В зависимости от выбранного браузера сертификат загружается или импортируется в хранилище ключей браузера.

  • Если браузер загружает сертификат: сохраните файл как ca.crt.

  • Если браузер импортирует сертификат: экспортируйте его из параметров сертификации браузера и сохраните как ca.crt.

Способ 4

Войдите в Менеджер управления, экспортируйте сертификат из хранилища доверенных сертификатов и скопируйте его на свой клиентский компьютер.

  1. Войдите на машину с Менеджером управления как root.

  2. Экспортируйте сертификат из хранилища доверенных сертификатов с помощью утилиты keytool:

    keytool \
-keystore /etc/pki/ovirt-engine/.truststore \
-storepass mypass \
-exportcert \
-alias cacert \
-rfc \
-file ca.crt

    Это создает файл сертификата с именем ca.crt.

  3. Скопируйте сертификат на клиентскую машину с помощью команды scp:

    $ scp ca.crt myuser@myclient.example.com:/home/myuser/.

Каждый из этих методов приводит к созданию файла сертификата с именем ca.crt на клиентском компьютере. Затем вы должны импортировать этот файл в хранилище сертификатов клиента.

3.2.2. Импорт сертификата в клиент

Импорт сертификата клиенту зависит от того, как клиент хранит и интерпретирует сертификаты. Дополнительную информацию об импорте сертификата см. в документации вашего клиента.

4. Общие понятия

4.1. Типы

API использует концепцию типов для описания различных видов принимаемых и возвращаемых объектов.

Существует три соответствующих вида типов:

  • Примитивные типы — описывают простые виды объектов, такие как string (строки) или integer (целые числа).

  • Перечисляемые типы — описывают списки допустимых значений, таких как status или DiskFormat.

  • Структурированные типы — описывают структурированные объекты с несколькими атрибутами и ссылками, например subnet или network.

4.2. Идентифицируемые типы

Многие из типов, используемых API, представляют собой идентифицируемые объекты, объекты, которые имеют уникальный идентификатор и существуют независимо от других объектов.

4.3. Объекты

Объекты — это отдельные экземпляры типов, поддерживаемых API. Например, виртуальная машина с идентификатором ac64bdd8-3c66-4e47-b66b-e66117831b62 является объектом типа Vm.

4.4. Коллекции

Коллекция — это набор объектов одного типа.

4.5. Представления

Состояние объектов должно быть представлено при их передаче между клиентом и сервером. API поддерживает XML и JSON в качестве представления состояния объектов как для ввода, так и для вывода.

5. Методы миграции ВМ между ЦД

API миграции ВМ между ЦД предоставляет два основных метода.

Каждый метод доступен по определенному пути:

URL Метод Описание

/zvirt-engine-backend/v1/migration/between-datacenters

POST

Запуск миграции одной или нескольких виртуальных машин между центрами данных

/zvirt-engine-backend/v1/migration/between-datacenters/validate

POST

Проверка возможности миграции одной или нескольких виртуальных машин между центрами данных

5.1. Описание интерфейса отображения методов

Описанные ниже методы расположены во фрейме, который содержит интерактивные элементы, обеспечивающие удобное представление.

base interface
Общие элементы управления

  1. Инструменты управления отображением:

    • Expand all - позволяет развернуть все категории.

    • Collapse all - позволяет свернуть все категории.

  2. Список категорий. При клике на заголовок категории можно свернуть/развернуть ее содержимое.

  3. Список методов в категории. При клике на строку метода можно свернуть/развернуть его описание.

requests
Элементы управления в описании методов

  1. Общее и подробное описание метода.

  2. Поле параметров запроса:

    • query-string parameters - параметры, передаваемые в строке запроса (например, /ovirt-engine/api/datacenters?max=3)

    • request body - содержимое тела запроса. На вкладке Example представлен пример, на вкладке Schema - схема данных.

      Тело запроса применяется только в POST- и PUT-запросах.

      На вкладке Schema представлено подробное описание параметров объекта. По умолчанию описание отображается в однострочном формате, поэтому часть описания может быть не видна. Для отображения полного формата нажмите Multiline description.

    • request headers - список специфических параметров, которые необходимо включить в заголовок запроса.

  3. Поле параметров ответа:

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

      codes

    • На вкладке Example представлен пример, на вкладке Schema - схема данных.

      На вкладке Schema представлено подробное описание параметров объекта. По умолчанию описание отображается в однострочном формате, поэтому часть описания может быть не видна. Для отображения полного формата нажмите Multiline description.

6. Описание методов миграции ВМ между ЦД