Skip to main content

​
Overview

The Polystack Image Service consists of an API tier, a registry database, and a pluggable storage backend. Upload and download traffic flows through the API, while metadata queries are handled by the registry backed by MariaDB. Understanding the architecture is essential for sizing deployments, selecting the right storage backend, and troubleshooting performance issues.
Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.

​
Service Topology

​
Component Reference

​
Upload Data Flow

​
Storage Backend Selection

For production deployments with Polystack Distributed Storage, use RBD as both the image and volume backend. This enables zero-copy RBD cloning — instances launch in seconds regardless of image size.

​
High Availability Considerations

Multiple API nodes

Deploy two or more Image API nodes for redundancy. HAProxy distributes upload and download requests across all healthy nodes. All nodes must share the same storage backend — RBD or Swift — to ensure images uploaded to one node are readable from another.
The file store writes to a local directory. In a multi-node Image API deployment, all nodes must mount the same NFS directory. If NFS is unavailable, all image operations fail. Use RBD for true HA without NFS dependencies.

​
Next Steps

Storage Backends

Configure RBD, file store, or Swift as the image storage backend.

Image Cache

Enable per-node caching to accelerate instance launch times.

Admin Troubleshooting

Diagnose backend connectivity and API-level failures.

Security

Configure image signing and property protections.