Skip to main content

​
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 Xloud 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 XDeploy:
Restart Image API
xavs-ansible deploy --tags glance
Cause: HAProxy is enforcing an upload size limit smaller than the image file.Resolution: Adjust the timeout and body size settings in XDeploy globals:
Increase HAProxy upload limits
haproxy_client_body_timeout: 300s
haproxy_http_request_timeout: 600s
Apply:
Apply HAProxy configuration
xavs-ansible deploy --tags haproxy

​
Storage Backend Issues

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
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

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
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 XDeploy globals and redeploy:
Increase cache size limit
glance_cache_max_size: 21474836480  # 20 GB

​
Service Log Reference

ComponentLog command
Image APIdocker logs glance_api --tail 100
HAProxydocker logs haproxy --tail 100 | grep 9292
Image API configdocker 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.