How to remove an OS image

When to use

When an OS image is no longer needed and its copies should be removed from all cluster pools. The operation is irreversible and requires explicit confirmation: the image can only be restored by importing it again from the library source.

Removal has two steps: a read-only dependency check, followed by removal itself. The first step is safe and can be repeated as often as needed: it changes nothing on the nodes or in the catalog.

This procedure does not apply if you only need to restrict an image for one VDC: removal deletes the entire image from all cluster pools. It also does not apply to revoking a version: image versions cannot be addressed as separate catalog objects; the image is removed by its identifier.

Prerequisites

• The View Image Dependencies privilege scoped to the target VDC for dependency checks;
• The Remove OS Image privilege scoped to the target VDC for removal itself; this is a separate right, and membership in visibility grants does not provide it;
• Image ownership: a VDC administrator can remove only images belonging to their VDC. They cannot remove a shared cluster image or an image merely made visible to their VDC; the Cluster master role performs that removal;
• Cluster nodes are reachable: an unavailable node cannot remove its copy, and removal will have a partial outcome;
• vStack Center version 4.0.0.

Steps

In the web interface, removal starts in the «Image library» section, «Images» tab: «Delete image» in the image panel or «Delete» in the row menu, then «Delete» in the «Delete image?» dialog — this is the explicit irreversibility confirmation. The interface runs no separate check beforehand. If the image has dependencies, the «The image cannot be deleted» dialog lists «Virtual machines from this image», «Clones on nodes», and the number of skipped nodes. A partial outcome opens «The image has been removed partially» with «Removed from», «Failed on», and «Skipped» groups and a «Retry» button. A VDC administrator cannot remove a shared cluster image or another VDC's image: the button is inactive with the hint «The image belongs to another virtual data center».

The steps below give the operation order through the cluster API; request structures and complete response details are in the API reference.

1. Retrieve the image dependency map. The check queries all online nodes and simultaneously searches for machines that reference the image. The result arrives when querying is complete.

2. Read the map, checking four things.

   What to check	How to interpret it
   Aggregate dependency flag	"Present" means removal will be blocked
   Clone map	"Node → pool → clones": the child dataset is on the left, and its parent snapshot (origin) is on the right. An indication that the image is absent on a pair means "there is no image copy on this pool"; this is neither a dependency nor a failure
   Dependent machines	Machines that reference the image: each machine's identifier and name
   Skipped nodes	Nodes that could not be queried: the check is incomplete

   A nonempty list of skipped nodes means clones may have gone undetected. Wait for the node to return and retrieve the map again.

3. Remove dependencies. As long as the image has at least one ZFS clone or dependent machine, removal is rejected with code -48012, and the nodes are left untouched. Resolve the dependent machines in the map. A holder can also be another catalog image — this happens with an image made from a VM: the map names it too, and such an image can be removed only after its holder. See The image cannot be removed.

4. Remove the image. Explicitly confirm that the operation is irreversible: without confirmation, removal is rejected. Before removal, vStack Center checks dependencies again to guard against a race in which a new image clone appeared between the check and removal.

   The result is final: it arrives after the online nodes respond and immediately contains the outcome: the image stage, nodes from which the copy was removed, nodes with errors, and skipped nodes.

Verify the result

Complete removal is identified by three aspects of the outcome:

What to check	Expected value
Image stage	removed — the catalog row has been deleted
Nodes with errors	The list is empty
Skipped nodes	The list is empty

The image then disappears from the cluster catalog. Verify that its row is no longer in the image catalog.

Troubleshooting

Some nodes did not remove their copies

Removal returns success, but with the partial_active stage: some nodes did not remove their copies. The outcome lists nodes with errors and the reason for each, such as a busy dataset.

Successful nodes are not rolled back, and the catalog row remains. Resolve the cause and retry removal: it idempotently removes the remainder. A nonempty list of skipped nodes means the same thing: removal of the remaining copies is unconfirmed because a node did not respond.

The service restarted during removal

No images remain stuck after a restart. Complete removal is recorded in the security log strictly before the image row disappears from the catalog, so committed removals are completed at startup, while uncommitted ones are set to partial_active. Retrying removal completes the operation.

Failures by code

Failure code	Meaning	Action
-48011	Irreversibility has not been confirmed	Explicitly confirm that removal is irreversible
-48012	The image has ZFS clones or dependent machines	Retrieve the dependency map and remove the dependent objects; the nodes are untouched
-48009	The image was not found: the catalog row does not exist, or the image is not visible to the caller	Check the image identifier; the response is the same for someone else's restricted image, so its existence is not confirmed
-48004	A concurrent operation is already removing the image	Wait for the first operation's outcome
-48010	The nodes could not be queried: cluster status or transport is unavailable	Check the cluster state and retry
-403	Access denied	Check the removal privilege and ownership: only the Cluster master role can remove a shared image, someone else's image, or an image made visible through a grant
-503	The security log did not accept the intent record	Removal has not started, and nothing has changed; restore log availability and retry
-48001	Database error	Retry removal; if the error recurs, contact support

An invalid or missing image identifier, as well as missing confirmation, is rejected during request parsing, before any action on the catalog or nodes.

See also

• OS image library — the catalog model, image ownership, and visibility scope.
• How to import an OS image into the cluster — the reverse operation: importing an image and distributing it across pools.

API methods

The API operations covered on this page are golden-image-clones, golden-image-remove, and golden-images-list; see the API reference.