> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xloud.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Service Architecture

> Understand the Xloud Image Service topology, storage backend options, and the upload and download data flow.

## Overview

The Xloud 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.

<Warning>
  **Administrator Access Required** — This operation requires the `admin` role. Contact your
  Xloud administrator if you do not have sufficient permissions.
</Warning>

***

## Service Topology

```mermaid theme={null}
graph TD
    U([User / Dashboard / Compute]) --> HAP[HAProxy<br/>:9292]
    HAP --> G1[Image API<br/>Node 1]
    HAP --> G2[Image API<br/>Node 2]
    G1 --> REG[(Registry DB<br/>MariaDB)]
    G2 --> REG
    G1 --> STORE[Storage Backend]
    G2 --> STORE
    STORE --> FILE[File Store<br/>/var/lib/glance/images]
    STORE --> RBD[Xloud Distributed Storage<br/>RBD pool]
    STORE --> SWIFT[Xloud Object Storage<br/>Swift container]
    G1 --> CACHE[Image Cache<br/>optional per-node]
    style HAP fill:#197560,color:#fff
    style G1 fill:#3F8F7E,color:#fff
    style G2 fill:#3F8F7E,color:#fff
    style REG fill:#145C4C,color:#fff
    style STORE fill:#3F8F7E,color:#fff
```

***

## Component Reference

| Component    | Port     | Description                                               |
| ------------ | -------- | --------------------------------------------------------- |
| Image API    | 9292     | REST API for image CRUD operations and data streaming     |
| HAProxy      | 9292     | Load balances requests across all Image API nodes         |
| Registry     | Internal | Stores image metadata in MariaDB                          |
| File Store   | —        | Local filesystem storage (single-node or NFS)             |
| RBD Store    | —        | Xloud Distributed Storage (Ceph RBD) — recommended for HA |
| Object Store | —        | Xloud Object Storage (Swift)                              |
| Image Cache  | —        | Optional local cache of frequently used image data        |

***

## Upload Data Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User / CLI
    participant H as HAProxy :9292
    participant A as Image API
    participant DB as MariaDB
    participant S as Storage Backend
    U->>H: POST /v2/images (metadata)
    H->>A: Create image record
    A->>DB: INSERT image record (status=queued)
    DB-->>A: Image ID
    A-->>U: Image ID
    U->>H: PUT /v2/images/{id}/file (binary data)
    H->>A: Stream upload
    A->>DB: UPDATE status=saving
    A->>S: Write image data
    S-->>A: Write confirmed
    A->>DB: UPDATE status=active, checksum
    A-->>U: 204 No Content
```

***

## Storage Backend Selection

| Backend            | HA               | Performance | Use Case                           |
| ------------------ | ---------------- | ----------- | ---------------------------------- |
| **RBD (Ceph)**     | Yes              | Highest     | Production HA deployments          |
| **File Store**     | Single-node only | Good        | Single-node dev/test or NFS-backed |
| **Object Storage** | Yes              | Moderate    | When Swift is already deployed     |

<Tip>
  For production deployments with Xloud 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.
</Tip>

***

## High Availability Considerations

<AccordionGroup>
  <Accordion title="Multiple API nodes" icon="server" defaultOpen>
    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.
  </Accordion>

  <Accordion title="File store limitations" icon="circle-x">
    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.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Storage Backends" href="/services/images/storage-backends" color="#197560">
    Configure RBD, file store, or Swift as the image storage backend.
  </Card>

  <Card title="Image Cache" href="/services/images/image-cache" color="#197560">
    Enable per-node caching to accelerate instance launch times.
  </Card>

  <Card title="Admin Troubleshooting" href="/services/images/admin-troubleshooting" color="#197560">
    Diagnose backend connectivity and API-level failures.
  </Card>

  <Card title="Security" href="/services/images/image-security" color="#197560">
    Configure image signing and property protections.
  </Card>
</CardGroup>