How to import an OS image into the cluster

When to use

When the cluster needs a new OS image or a new version of an image already imported. Import downloads the image from a registered library source and distributes it across storage pools. Only then can virtual machines be created from the image.

This procedure also applies to completing distribution. If a previous import did not distribute the image to every pool, importing the same version again delivers the missing copies.

This procedure does not apply if the source image is in a format other than zfs: import does not accept such images. It also does not apply to changing the image owner: importing again does not rewrite the image's VDC (virtual data center) ownership.

Prerequisites

• The Import Golden Image privilege scoped to the target VDC; the Cluster master role has global scope;
• The Sync Image Library privilege: without it, you cannot read the source catalog or obtain the image identifier;
• The vstack-center-image-distributor distribution service is deployed in the cluster with the required vhost imgdistr_vhost; without it, nothing can transfer the bytes during import;
• The library source is registered, and its identifier is known from the source list;
• The source is accessible to the caller: a VDC administrator can access a source assigned to their VDC, while a shared cluster source is available only to the Cluster master role. This check occurs before reading the catalog and before import, so without source access the response is -403, even when all required privileges have been granted;
• The cluster has at least one storage pool with an owner;
• vStack Center version 4.0.0.

Steps

In the web interface, import starts in the «Image library» section, «Images» tab. The steps below are for the Cluster master role. A VDC administrator imports an image into their own VDC through an API call, specifying that VDC in the import request. Request structures and complete response details are in the API reference.

1. Click «Add image» and open the «Source» tab: the «File» tab is not available yet. Pick a source in the «Source» list. The cluster reads only its manifest.json and shows the «Image showcase» with cards of the source's images. Reading the catalog is fast and changes nothing in the cluster.

2. Select an image. A card in a format other than zfs is inactive with the caption «The platform cannot import this format»; an image already imported is marked «Already in the cluster catalog». The import identifier is the uuid field of the manifest entry: it uniquely identifies both the image and its version. An entry without uuid cannot be imported — add the field to the source manifest first.

3. Click «Next» and choose pools: all are selected by default. To distribute the image to only some pools, clear the others — the remaining copies can be delivered by importing the same version again. Click «Add».

   Import is asynchronous: the «Image import has started» notification acknowledges the job, not image readiness. Distribution continues in the background.

   The same import can start from the «Sources» tab: source panel → image card → «Import image» → «Import».

4. Wait for distribution to finish. In the «Status» column the image moves from «Importing» to «Available»; «Partially available» and «Failure» are covered below. The «Availability» column shows how many pools hold a copy, and the image panel shows the result per pool.

Verify the result

Find the imported image in «Image library» and check two things:

What to check	Expected value
Image status	«Available» (active in the API): the image has been distributed to all selected pools
Result per pool	An entry for each pool from step 3

The «Importing» (importing) status means that distribution is still in progress. The «Partially available» (partial_active) and «Failure» (failed) statuses are discussed below.

The final check is creating a machine. The image copy on the pool selected for VM creation must be active; otherwise, creation is rejected with code -259.

Troubleshooting

Import makes one attempt with no automatic retries. Any failure, whether in download, checksum, distribution, or the distribution service losing the job, sets the image to failed and creates a security log entry. The administrator initiates a retry with the same import operation. Restarting the dispatcher mid-operation does not retry an incomplete import; it marks it as failed.

A partial outcome (partial_active) is not rolled back: pools that have a copy keep it. Check the distribution map to see which pools did not receive a copy, then import the same version again to deliver the missing copies.

Failure code	Meaning	Action
-48005	The image format is not eligible for import; zfs is required	Select an image eligible for import in the source catalog
-48002	The source catalog contains no image with this identifier	Retrieve the source catalog again: the manifest may have changed
-48003	The image is already being imported	Wait for the current import outcome; there is no need to restart it
-48004	The image is being removed	Wait for removal to finish
-48006	The manifest entry fails validation: version, minimum size, size, sector sizes, checksum, file path, an unknown OS or guest customization type, a repeated uuid	Correct the manifest at the source
-48007	A specified pool does not exist, or the cluster has no pools with an owner	Check the pool list; verify that the cluster has a pool with an owner
-48008	An image with this identifier already exists in the catalog under a different source or version	The image identifier is globally unique: assign the image its own uuid in the manifest
-46002	No source with this identifier exists	Use a current identifier from the source list
-46012	The source host resolves to a prohibited range	Move the library to an address outside loopback, link-local, private RFC 1918 ranges, CGNAT, the "zero network", and the broadcast address
-46020	The source is unavailable: network failure, timeout, or a non-2xx response	Check that the library URL is reachable from the cluster network
-46021	manifest.json cannot be parsed as JSON	Fix the manifest syntax
-46022	The manifest schema version is higher than the supported version	Update the manifest to a supported schema version
-46023	The manifest fails schema validation: an entry lacks required fields	Add name, version, format, url_path, size, sha256
-49005	A VDC administrator did not specify a VDC: only the Cluster master role imports a shared cluster image	Specify your VDC in the import request
-49006	The specified VDC is outside the caller's scope	Specify a VDC where you hold a role
-403	Access denied	Check source access, the privilege, and ownership: a shared cluster source is available only to the Cluster master role; a VDC administrator needs a source assigned to their VDC; only the image owner or the Cluster master role can import a new version of an existing image
-503	The security log did not accept the intent record	Import has not started, and nothing has changed; restore log availability and retry
-48001	Database error	Retry import; if the error recurs, contact support

See also

• OS image library — the model of the source, catalog, and distribution across pools.
• How to remove an OS image — the reverse operation, with dependency checks.
• How to create, remove, and migrate a virtual machine — creating a VM from an imported image.

API methods

The API operations covered on this page are os-library-list, os-library-sync, os-image-import, and golden-images-list; see the API reference.