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

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

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

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

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

Предусловия

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

Шаги

В веб-интерфейсе импорт запускают в разделе «Image library», вкладка «Images». Шаги ниже — для роли Cluster master. Администратор ВЦОД импортирует образ в свой ВЦОД вызовом API, указав этот ВЦОД в запросе импорта. Состав запросов и полный разбор ответов — в Справочнике API.

1. Нажмите «Add image» и откройте вкладку «Source»: вкладка «File» пока недоступна. Выберите источник в списке «Source». Кластер прочитает только его manifest.json и покажет «Image showcase» — карточки образов источника. Чтение каталога быстрое и ничего в кластере не меняет.

2. Выберите образ. Карточка в формате, отличном от zfs, неактивна с подписью «The platform cannot import this format»; уже импортированный образ помечен «Already in the cluster catalog». Идентификатор образа для импорта — поле uuid элемента манифеста: он однозначно задаёт и образ, и его версию. Элемент без uuid импортировать нельзя — сначала добавьте поле в манифест источника.

3. Нажмите «Next» и выберите пулы: по умолчанию отмечены все. Чтобы разложить образ на часть пулов, снимите лишние отметки — остальные дораздаются повторным импортом той же версии. Нажмите «Add».

   Импорт асинхронный: уведомление «Image import has started» подтверждает приём задания, а не готовность образа. Раздача продолжается в фоне.

   Тот же импорт можно начать с вкладки «Sources»: панель источника → карточка образа → «Import image» → «Import».

4. Дождитесь окончания раздачи. В колонке «Status» образ проходит от «Importing» к «Available»; «Partially available» и «Failure» разобраны ниже. Колонка «Availability» показывает, на скольких пулах есть копия, а панель образа — результат по каждому пулу.

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

Найдите импортированный образ в «Image library» и сверьте два признака:

Что смотреть	Ожидаемое значение
Статус образа	«Available» (в API — active): образ разложен на все выбранные пулы
Результат по пулам	запись на каждый пул из шага 3

Статус «Importing» (importing) означает, что раздача ещё идёт. Статусы «Partially available» (partial_active) и «Failure» (failed) разобраны ниже.

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

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

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

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

Код отказа	Что означает	Что сделать
-48005	формат образа не пригоден к импорту, требуется zfs	выбрать в каталоге источника образ, пригодный к импорту
-48002	в каталоге источника нет образа с таким идентификатором	переснять каталог источника: манифест мог измениться
-48003	образ уже импортируется	дождаться исхода текущего импорта, повторный запуск не нужен
-48004	образ в состоянии удаления	дождаться завершения удаления
-48006	элемент манифеста не проходит проверку: версия, минимальный размер, размер, размеры сектора, контрольная сумма, путь к файлу, неизвестный тип ОС или гостевой настройки, повтор uuid	исправить манифест на стороне источника
-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
-49005	администратор ВЦОД не указал ВЦОД: общий кластерный образ импортирует только роль Cluster master	указать свой ВЦОД в запросе импорта
-49006	указанный ВЦОД вне области доступа вызывающего	указать ВЦОД, где у вас есть роль
-403	доступ запрещён	проверить доступ к источнику, привилегию и владение: общий кластерный источник открыт только роли Cluster master, администратору ВЦОД нужен источник с привязкой к его ВЦОД; новую версию существующего образа импортирует только его владелец либо роль Cluster master
-503	журнал безопасности не принял запись о намерении	импорт не начат и ничего не изменено; восстановить доступность журнала и повторить
-48001	ошибка базы данных	повторить импорт; при повторе — обратиться в поддержку

См. также

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

Методы API

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