Image Cache

Overview

The image cache stores a local copy of frequently-used images on each compute node, eliminating repeated downloads from the central image service at instance launch time. Enabling the cache is most impactful when the same image is used to launch many instances on the same compute node — typical in auto-scaling and cluster workloads.

Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.

Cache Configuration

Configure cache settings via the deployment console globals before deploying:

Setting	Default	Description
`glance_enable_image_cache`	`no`	Enable the image cache
`glance_cache_max_size`	10 GB	Maximum total size of the cache directory
`glance_cache_staleness_seconds`	86400	How long a cached entry remains fresh (seconds)
`glance_cache_prefetcher_delay`	300	Seconds between pre-fetch sweep runs

Image cache configuration in the deployment console globals

glance_enable_image_cache: "yes"
glance_cache_max_size: 10737418240      # 10 GB in bytes
glance_cache_staleness_seconds: 86400   # 24 hours
glance_cache_prefetcher_delay: 300      # 5 minutes

Deploy after configuring:

Apply image cache configuration

ironcore-ansible deploy --tags glance

How the Cache Works

Verify Cache Status

Check cache directory on Image API node

docker exec glance_api ls -lh /var/lib/glance/image-cache/

View cached image entries

docker exec glance_api glance-cache-manage list-cached

View pending pre-fetch queue

docker exec glance_api glance-cache-manage list-queued

Manual Cache Management

Pre-fetch an image
Clear the cache
Trigger pre-fetch manually

Queue an image for pre-caching before its first use:

Queue image for pre-fetch

docker exec glance_api glance-cache-manage queue-image <IMAGE_ID>

The pre-fetcher picks it up on the next sweep interval.

Remove all cached entries to free disk space:

Clear the image cache

docker exec glance_api glance-cache-manage delete-all-cached-images

Clearing the cache causes the next instance launch from each image to download from the storage backend. This temporarily increases launch times.

Run the pre-fetcher outside its scheduled interval:

Trigger cache pre-fetch

docker exec glance_api glance-cache-prefetcher

When to Use the Cache

Best case: Many instances from same image

The cache provides the greatest benefit when the same image is repeatedly used on the same compute node — typical patterns include:

Auto-scaling groups launching many identical instances
Development clusters where all developers use the same base image
CI/CD pipelines that launch many ephemeral test instances

After the first launch (cache miss), all subsequent launches are served from the local cache — typically 10-50x faster than fetching from the storage backend.

Limited benefit: RBD-to-RBD cloning

When both the Image Service and Block Storage use Polystack Distributed Storage (RBD), instance launches use zero-copy RBD clones. This already achieves near-instantaneous boot times regardless of image size — the image cache provides minimal additional benefit in this configuration.

Enable the image cache on compute nodes with SSD-backed local storage. Storing the cache on slow HDDs may actually increase launch latency compared to fetching from a fast Ceph cluster.

Next Steps

Storage Backends

Configure the primary storage backend that feeds the cache.

Architecture

Understand where the cache fits in the overall Image Service topology.

Admin Troubleshooting

Diagnose cache effectiveness and storage issues.

Quotas

Control storage consumption to ensure cache space is not exhausted.

Core Services

Other Services

Overview

Cache Configuration

How the Cache Works

Verify Cache Status

Manual Cache Management

When to Use the Cache

Next Steps

Storage Backends

Architecture

Admin Troubleshooting

Quotas

​Overview

​Cache Configuration

​How the Cache Works

​Verify Cache Status

​Manual Cache Management

​When to Use the Cache

​Next Steps

Storage Backends

Architecture

Admin Troubleshooting

Quotas

Overview

Cache Configuration

How the Cache Works

Verify Cache Status

Manual Cache Management

When to Use the Cache

Next Steps