Image Manager

Introduction

The Image Manager is the SM subcomponent responsible for the complete lifecycle of Deployable Item images on a Node. It handles downloading OCI image blobs from the cloud (via CM), unpacking compressed layers into an overlay-compatible filesystem layout, verifying integrity through SHA-256 digest checks, and managing storage space through configurable TTL-based garbage collection.

When CM instructs the SM to deploy a new service version, the Image Manager is the first module involved — it ensures the required image content is present and verified before the Launcher can start an instance.

Architecture

The Image Manager implements two interfaces and depends on several shared infrastructure components:

Interface	Direction	Purpose
ImageManagerItf	Implements	Install and remove Deployable Items; query installed item statuses
ItemInfoProviderItf	Implements	Provide filesystem paths to blobs and unpacked layers for the Launcher
ImageHandlerItf	Depends on	Platform-specific layer unpacking (tar extraction, whiteout conversion)
BlobInfoProviderItf	Depends on	Resolve blob digests to download URLs (provided by SM client from CM)
DownloaderItf	Depends on	Execute file downloads with digest-based identification
SpaceAllocatorItf	Depends on	Allocate and track storage space; trigger eviction when space is constrained
OCISpecItf	Depends on	Parse OCI image manifests and image configs from JSON
StorageItf	Depends on	Persist item metadata (ID, version, state, timestamp) in the SM database

Installation Flow

When InstallUpdateItem is called with an item's ID, type, version, and manifest digest, the Image Manager executes the following sequence:

1. Install manifest blob — download and verify the OCI image manifest identified by its digest
2. Parse manifest — load the manifest JSON to discover the image config and layer descriptors
3. Install item config blob (if present) — download the Aos-specific item configuration
4. Install image config blob (services only) — download the OCI image config containing rootfs diff IDs
5. Install layers — for each layer in the manifest:
   • Download the compressed layer blob
   • Verify the blob's SHA-256 digest
   • Unpack the tar archive to a layer directory
   • Convert OCI whiteout markers to OverlayFS format
   • Compute and store the unpacked layer digest
   • Remove the compressed blob to reclaim space
6. Store item metadata — persist the item record with installed state and current timestamp

For non-service items (components/firmware), layers are stored as raw blobs without unpacking.

Concurrency Control

The Image Manager uses a per-blob in-progress tracking mechanism to prevent duplicate downloads. When a blob installation begins, its digest is added to an in-progress list. Concurrent requests for the same digest block until the first installation completes, then reuse the already-downloaded content. This is important because multiple Deployable Items may share common layers.

Blob and Layer Storage Layout

The Image Manager organizes content under a configurable imagePath directory:

{imagePath}/
├── blobs/
│   └── sha256/
│       ├── {hash1}          ← manifest JSON file
│       ├── {hash2}          ← image config JSON file
│       └── {hash3}          ← item config or raw layer blob
└── layers/
    └── sha256/
        └── {diffID-hash}/
            ├── layer/       ← unpacked filesystem tree
            ├── digest       ← computed digest of unpacked content
            └── size         ← unpacked size in bytes

• Blobs are stored by their content-addressable digest (algorithm/hash)
• Layers are stored by their diff ID (the digest of the unpacked content, as declared in the image config's rootfs.diffIDs)
• The original compressed blob path is repurposed after unpacking — it becomes a small file containing the diff ID, serving as a pointer from the manifest's layer digest to the unpacked layer location

Integrity Verification

The Image Manager performs verification at multiple points:

Check	When	Method
Blob integrity	After download	SHA-256 hash of file content compared against declared digest
Layer integrity	After unpacking	Directory digest of unpacked content compared against stored digest
Item integrity	Periodic background check	Full re-verification of all blobs and layers for each installed item

If any integrity check fails:

• During installation: the operation returns an error and partially-downloaded content is cleaned up
• During background check: the corrupted item is removed from storage and its space is reclaimed

Layer Unpacking

The platform-specific ImageHandler performs layer unpacking with two key operations:

1. Tar extraction — unpacks the layer archive (supports both plain tar and gzip-compressed tar)
2. OCI whiteout conversion — translates OCI-format deletion markers into OverlayFS-compatible format:
   • .wh.<filename> files become character device nodes (mknod with major/minor 0) — signaling file deletion in the overlay
   • .wh..wh..opq files become trusted.overlay.opaque xattr on the parent directory — signaling opaque directory replacement

After unpacking, file ownership is set to the configured UID/GID for the service execution context.

Supported Media Types

Media Type	Description
application/vnd.oci.image.layer.v1.tar	Uncompressed tar layer
application/vnd.oci.image.layer.v1.tar+gzip	Gzip-compressed tar layer

Storage Lifecycle Management

The Image Manager implements automatic storage lifecycle management through several mechanisms:

Version Retention

Each Deployable Item retains at most 2 versions simultaneously. When a new version is installed and the limit is reached, the oldest version (preferring already-removed items) is evicted.

TTL-Based Expiration

When a Deployable Item is removed (via RemoveUpdateItem), it transitions to a removed state with a timestamp. A background thread periodically checks for items whose removal timestamp exceeds the configured TTL (default: 30 days) and permanently deletes them.

Orphan Cleanup

After any item removal, the Image Manager scans for orphaned blobs and layers — files on disk that are no longer referenced by any stored item. Orphans are deleted and their space is freed.

Space Allocator Integration

The Image Manager integrates with the Space Allocator to:

• Reserve space before downloading blobs or unpacking layers
• Accept allocations when operations succeed
• Release allocations when operations fail (triggering cleanup)
• Report freed space when items are removed
• Support eviction callbacks — the Space Allocator can invoke RemoveItem on the Image Manager when storage pressure requires freeing space from outdated items

Configuration

Parameter	Default	Description
imagePath	—	Root directory for blob and layer storage
partLimit	—	Storage partition size limit
updateItemTTL	30 days	Time-to-live for removed items before permanent deletion
removeOutdatedPeriod	24 hours	Interval between background cleanup cycles

Related Pages

• Service Manager — parent component overview and SM architecture
• Architecture Overview — system-wide component relationships
• OCI Image Format — detailed OCI image structure and layer format

• Downloader — download subsystem used for blob retrieval

• Image Deployment Pipeline — end-to-end flow from cloud to running instance

• Key Concepts — terminology including Deployable Item and Verification