Как импортировать образ ОС в кластер

Когда использовать

Когда в кластере нужен новый образ ОС или новая версия уже привезённого. Импорт скачивает образ из зарегистрированного источника библиотеки и раскладывает его по пулам хранения. Только после этого из образа можно создавать виртуальные машины.

Инструкция подходит и для второго случая — дораздачи. Если предыдущий импорт разложил образ не на все пулы, повторный импорт той же версии довозит недостающие копии.

Не подходит, если образ в источнике лежит в формате, отличном от zfs: такой образ импорт не берёт. Не подходит и для смены владельца образа — принадлежность ВЦОД (виртуальному центру обработки данных) выводится из прав вызывающего и параметром не задаётся.

Предусловия

привилегия Import Golden Image в области целевого ВЦОД; у роли Cluster master область глобальная;
привилегия Sync Image Library — без неё не прочитать каталог источника и не узнать идентификатор образа;
в кластере развёрнут сервис раздачи vstack-center-image-distributor с обязательным vhost imgdistr_vhost; без него импорт двигать байты некому;
источник библиотеки зарегистрирован, и его идентификатор известен из списка источников;
источник доступен вызывающему: администратору ВЦОД открыт источник с привязкой к его ВЦОД, а общий кластерный источник — только роли Cluster master; проверка идёт до чтения каталога и до импорта, поэтому без доступа к источнику ответом будет -403 даже при полностью выданных привилегиях;
в кластере есть хотя бы один пул хранения с владельцем;
версия vStack Center — 3.0.5.

Шаги

Экранов библиотеки образов в веб-интерфейсе vStack Center нет: импортом управляют программно — вызовами API кластера или системой автоматизации, которая их делает. Шаги ниже задают порядок операций; состав запросов и полный разбор ответов — в Справочнике API.

Прочитайте каталог источника. Синхронизация скачивает только manifest.json, поэтому проходит быстро и ничего в кластере не меняет. В ответ приходит паспорт каждого образа источника: имя и версия, формат, путь к файлу, размер и контрольная сумма, тип гостевой ОС, минимальный размер диска, идентификатор образа и признак пригодности к импорту.
Выберите образ и проверьте признак пригодности. Непригодный образ лежит в источнике в формате, отличном от zfs, — импорт его отклонит. Идентификатор для импорта берётся из поля uuid выбранного элемента манифеста: он однозначно задаёт и образ, и его версию. Поле опциональное — если источник его не заполнил, импортировать образ нечем: сначала добавьте uuid элементу в манифесте источника.
Запустите импорт, указав источник и образ. Больше ничего не требуется: без явного списка пулов образ уходит на все пулы с владельцем. Чтобы разложить образ на часть пулов, перечислите нужные — остальные дораздаются повторным импортом той же версии.

Импорт асинхронный: он сразу подтверждает приём задания, а раздачу продолжает в фоне. Подтверждение приёма — не готовность образа.
Дождитесь окончания раздачи. Стадию и карту пулов показывает каталог образов кластера: стадия образа — общий исход, карта раздачи — результат по каждому пулу отдельно.

Проверка результата

Найдите импортированный образ в каталоге кластера и сверьте два признака:

Что смотреть	Ожидаемое значение
Стадия образа	`active` — образ разложен на все выбранные пулы
Карта раздачи по пулам	запись на каждый пул из шага 3

Стадия importing означает, что раздача ещё идёт. Стадии partial_active и failed разобраны ниже.

Финальная проверка — создание машины. Копия образа на пуле, выбранном при создании ВМ, обязана быть активна, иначе создание отклоняется с кодом -259.

Если не получилось

Импорт делает одну попытку без автоповторов. Любой сбой — скачивания, контрольной суммы, раздачи или потери задания сервисом раздачи — переводит образ в failed и оставляет запись в журнале безопасности. Повтор запускает администратор, тем же импортом. Перезапуск диспетчера в середине работы незавершённый импорт не переигрывает, а закрывает как неуспешный.

Частичный исход (partial_active) откату не подлежит: пулы с копией её сохраняют. Посмотрите в карте раздачи, каким пулам копия не досталась, и повторите импорт той же версии — он довезёт недостающие.

Код отказа	Что означает	Что сделать
`-48005`	формат образа не пригоден к импорту, требуется `zfs`	выбрать в каталоге источника образ, пригодный к импорту
`-48002`	в каталоге источника нет образа с таким идентификатором	переснять каталог источника: манифест мог измениться
`-48003`	образ уже импортируется	дождаться исхода текущего импорта, повторный запуск не нужен
`-48004`	образ в состоянии удаления	дождаться завершения удаления
`-48006`	элемент манифеста не проходит проверку: минимальный размер, размер, контрольная сумма или путь к файлу	исправить манифест на стороне источника
`-48007`	указан несуществующий пул либо в кластере нет пулов с владельцем	сверить перечень пулов; проверить, что в кластере есть пул с владельцем
`-48008`	образ с таким идентификатором уже есть в каталоге под другим источником или версией	идентификатор образа глобально уникален: выдать образу в манифесте свой `uuid`
`-46002`	источника с таким идентификатором нет	взять действующий идентификатор из списка источников
`-46012` (см. примечание)	хост источника разрешается в запрещённый диапазон	перенести библиотеку на адрес вне loopback, link-local, приватных диапазонов RFC 1918, CGNAT, «нулевой сети» и широковещательного адреса
`-46020`	источник недоступен: сетевой сбой, таймаут или ответ не 2xx	проверить доступность адреса библиотеки из сети кластера
`-46021`	`manifest.json` не разбирается как JSON	починить синтаксис манифеста
`-46022`	версия схемы манифеста выше поддерживаемой	привести манифест к поддерживаемой версии схемы
`-46023`	манифест не проходит схему: у элемента нет обязательных полей	добавить `name`, `version`, `format`, `url_path`, `size`, `sha256`
`-403`	доступ запрещён	проверить доступ к источнику, привилегию и владение: общий кластерный источник открыт только роли Cluster master, администратору ВЦОД нужен источник с привязкой к его ВЦОД; администратор ВЦОД не импортирует общий кластерный образ и не пишет в чужой ВЦОД, а новую версию существующего образа импортирует только его владелец либо роль Cluster master
`-503`	журнал безопасности не принял запись о намерении	импорт не начат и ничего не изменено; восстановить доступность журнала и повторить
`-48001`	ошибка базы данных	повторить импорт; при повторе — обратиться в поддержку

Примечание к -46012. В перечне ошибок импорта в каноне API этого кода нет, но импорт его возвращает: перед обращением к источнику адрес библиотеки проходит ту же проверку на запрещённые диапазоны, что и при регистрации источника. Перечень в каноне неполный; поведение — как описано в таблице.

См. также

Библиотека образов ОС — модель источника, каталога и раздачи по пулам.
Как удалить образ ОС — обратная операция с проверкой зависимостей.
Как создать, удалить и перенести виртуальную машину — создание ВМ из импортированного образа.

Методы API

Операции этой страницы в API: os-library-list, os-library-sync, os-image-import, golden-images-list — см. Справочник API.

Когда использовать​

Предусловия​

Шаги​

Проверка результата​

Если не получилось​

См. также​

Методы API​