Image Service Admin Troubleshooting

Overview

This guide covers platform-level Image Service issues that require administrator access — storage backend connectivity, API container failures, cache performance, and upload size limit issues.

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

For user-facing issues such as upload progress, shared image visibility, or launch failures, see the Image User Troubleshooting guide.

API Failures

Image API not responding

Cause: The Image API container is stopped or the service has crashed.Diagnose:

Check Image API container status

docker ps --filter name=glance

If the container is not running:

View container exit logs

docker logs glance_api --tail 50

Resolution: Restart via the deployment console:

Restart Image API

ironcore-ansible deploy --tags glance

Upload fails with 413 Request Entity Too Large

Cause: HAProxy is enforcing an upload size limit smaller than the image file.Resolution: Adjust the timeout and body size settings in the deployment console globals:

Increase HAProxy upload limits

haproxy_client_body_timeout: 300s
haproxy_http_request_timeout: 600s

Apply:

Apply HAProxy configuration

ironcore-ansible deploy --tags haproxy

Storage Backend Issues

Image status remains 'queued' after upload

Cause: The Image API cannot reach the storage backend — RBD cluster unreachable, wrong keyring, or Swift authentication failed.Diagnose:

Check Image API logs for storage errors

docker logs glance_api --tail 100 | grep -i "error\|exception\|ceph\|rbd"

For RBD backend:

Verify RBD pool exists

ceph osd pool ls | grep images

Test glance keyring access

rbd --keyring /etc/ceph/ceph.client.glance.keyring \
  --id glance ls images

Compute cannot download image during instance launch

Cause: The compute node cannot reach the Image API, or the image data is corrupt.Diagnose: Test connectivity from the compute node:

Test image API reachability from compute node

curl -H "X-Auth-Token: $OS_AUTH_TOKEN" \
  https://api.<your-domain>:9292/v2/images/<IMAGE_ID>

For corrupt images, verify the checksum:

Verify image checksum

openstack image show <IMAGE_ID> -c checksum
md5sum /path/to/original-image.qcow2

If checksums differ, re-upload the image.

Cache Issues

Image cache not reducing launch times

Cause: Cache is not enabled, the compute node has insufficient local disk, or the pre-fetcher has not yet run.Diagnose: Verify cache is enabled and check the cache directory:

Check cache directory on Image API node

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

Images appear in the cache directory after the first instance launch from each image. Trigger the pre-fetcher manually:

Trigger cache pre-fetch

docker exec glance_api glance-cache-prefetcher

Cache directory full — disk pressure

Cause: The cache has grown beyond the configured glance_cache_max_size.Resolution: Clear old cached entries:

Clear stale cache entries

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

Then increase the cache size limit in the deployment console globals and redeploy:

Increase cache size limit

glance_cache_max_size: 21474836480  # 20 GB

Service Log Reference

Component	Log command
Image API	`docker logs glance_api --tail 100`
HAProxy	`docker logs haproxy --tail 100 \| grep 9292`
Image API config	`docker exec glance_api cat /etc/glance/glance-api.conf`

Next Steps

Storage Backends

Review backend configuration to prevent connectivity failures.

Image Cache

Tune cache size and pre-fetch settings for optimal performance.

Security

Review security configuration after resolving access-related issues.

Architecture

Understand component relationships to identify the source of failures.

Core Services

Other Services

Overview

API Failures

Storage Backend Issues

Cache Issues

Service Log Reference

Next Steps

Storage Backends

Image Cache

Security

Architecture

​Overview

​API Failures

​Storage Backend Issues

​Cache Issues

​Service Log Reference

​Next Steps

Storage Backends

Image Cache

Security

Architecture

Overview

API Failures

Storage Backend Issues

Cache Issues

Service Log Reference

Next Steps