# openstack/glance architecture

> Architecture diagram of the GitHub repository openstack/glance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openstack/glance
- Repository: https://github.com/openstack/glance

## Overview

##### Main Components
- API Layer:
- Glance API service. Note the separation between v1 and v2 (found under glance/api/v1 and glance/api/v2) as well as the middleware (in glance/api/middleware) that processes requests (e.g., caching, gzip, context extraction, and version negotiation).
- WSGI interface (in glance/common/wsgi and glance/wsgi/api) and configuration files (such as those in the “httpd” directory and etc/glance-api-paste.ini).
- Business Logic and Domain:
- This encompasses the “glance/common”, “glance/domain”, and “glance/api” directories where core processing, property protections, policies (see glance/policies), and client helper functions exist.
- Database Layer:
- Database interaction implemented via SQLAlchemy within the “glance/db” directory.
- Migration and metadata management components (e.g., alembic_migrations in glance/db/sqlalchemy/alembic_migrations) that show how the project handles schema evolutions.
- Caching and Image Store:
- Cover the “glance/image_cache” directory which contains drivers (e.g., centralized_db, sqlite, xattr) and logic for managing image caching to speed up delivery.
- Asynchronous Processing:
- Asynchronous flows located in the “glance/async_” module. These manage tasks like image import, conversion, and processing using internal plugins and flows.
- Configuration/Policies & External Integration:
- Configuration layer (found across config files in etc/, glance/opts.py, and the oslo-config-generator in etc/oslo-config-generator) and policy definitions (in glance/policies).
- Also, it’s good to indicate external integrations with other OpenStack services (such as Keystone authentication and Nova) even though they may be referenced indirectly via the project’s client libraries and API endpoints.

##### Relationships and Data Flow
- Processed requests are handled by the business logic that invokes database operations in the “glance/db/*” components.
- Caching components interact with both the API server and the database/stores, ensuring fast access to popular images.
- Configuration and policy components govern rules for request authorization, image properties, and store selection.

##### Architectural Patterns and Design Principles
- Modular Design – clear separation of concerns between API handling, business logic, database management, caching, and asynchronous workflows.
- Middleware Chains – demonstrated by the numerous WSGI middleware components that enhance, secure, and modify HTTP flows.
- Layered Architecture – separation between the API layer (presentation), business logic (controller/service), and persistence (data access).
- Use of Plug-ins – asynchronous image processing is implemented using configurable and extensible plugins found in the “glance/async_/flows/plugins” directory.
- Dependency Injection and Configuration Driven – plenty of configuration files (in etc/ and oslo-config-generator) indicate the system is designed to be highly configurable.

## Diagram (Mermaid)

```mermaid
graph TD
    Clients["Clients"]:::client

    subgraph "API Layer"
        API_v1["Glance API v1"]:::api
        API_v2["Glance API v2"]:::api
        Middleware["API Middleware"]:::api
        WSGI_Interface["WSGI Interface"]:::api
        API_Paste_Config["API Paste Config"]:::api
    end

    subgraph "Business Logic & Domain"
        BL_Common["Common Module"]:::logic
        BL_Domain["Domain Module"]:::logic
        BL_APICommon["API Common"]:::logic
        BL_Policies["Policies Directory"]:::logic
        BL_PolicyFile["Policy File"]:::logic
        BL_PropertyProtections["Property Protections"]:::logic
    end

    subgraph "Database Layer"
        DB["DB Directory"]:::database
        DB_SQLAlchemy["SQLAlchemy Module"]:::database
        DB_Alembic["Alembic Migrations"]:::database
        DB_API["DB API"]:::database
        DB_Migration["DB Migration Script"]:::database
    end

    subgraph "Caching & Image Store"
        ImageCache["Image Cache Directory"]:::cache
        Cache_Drivers["Cache Drivers"]:::cache
        Cache_Base["Cache Base"]:::cache
    end

    subgraph "Asynchronous Processing"
        Async_Main["Async Main"]:::async
        Async_Flows["Async Flows"]:::async
        Async_Plugins["Async Plugins"]:::async
        Async_ImageImport["API Image Import"]:::async
        Async_Taskflow["Taskflow Executor"]:::async
    end

    subgraph "Configuration & External Integration"
        Config_ETC["ETC Directory"]:::config
        Config_GlanceAPIConf["Glance API Conf"]:::config
        Config_GlanceCacheConf["Glance Cache Conf"]:::config
        Config_GlancePolicyGen["Glance Policy Generator"]:::config
        Config_Oslo["OSLO Config Generator"]:::config
        GlanceOpts["Glance Opts"]:::config
        External_Services["OpenStack Services"]:::external
    end

    %% Connections
    Clients --> API_v1
    Clients --> API_v2
    API_v1 --> Middleware
    API_v2 --> Middleware
    Middleware --> WSGI_Interface
    WSGI_Interface --> API_Paste_Config
    API_Paste_Config --> BL_Common

    BL_Common --> BL_Domain
    BL_Common --> BL_APICommon
    BL_Common --> DB_SQLAlchemy
    BL_APICommon --> DB_API
    DB_SQLAlchemy --> DB
    DB_SQLAlchemy --> DB_Alembic

    BL_Common --> Async_Main
    Async_Main --> Async_Flows
    Async_Flows --> Async_Plugins
    Async_Main --> Async_ImageImport
    Async_ImageImport --> Async_Taskflow
    Async_Taskflow --> DB

    DB_SQLAlchemy --> Cache_Base
    API_v1 --> Cache_Base

    Config_ETC --> Middleware
    GlanceOpts --> BL_Common
    Config_GlanceAPIConf --> External_Services
    Config_GlanceCacheConf --> External_Services
    Config_GlancePolicyGen --> External_Services
    Config_Oslo --> External_Services

    %% Click Events for API Layer
    click API_v1 "https://github.com/openstack/glance/tree/master/glance/api/v1"
    click API_v2 "https://github.com/openstack/glance/tree/master/glance/api/v2"
    click Middleware "https://github.com/openstack/glance/tree/master/glance/api/middleware"
    click WSGI_Interface "https://github.com/openstack/glance/tree/master/glance/wsgi/api"
    click API_Paste_Config "https://github.com/openstack/glance/blob/master/etc/glance-api-paste.ini"

    %% Click Events for Business Logic & Domain
    click BL_Common "https://github.com/openstack/glance/tree/master/glance/common"
    click BL_Domain "https://github.com/openstack/glance/tree/master/glance/domain"
    click BL_APICommon "https://github.com/openstack/glance/blob/master/glance/api/common.py"
    click BL_Policies "https://github.com/openstack/glance/tree/master/glance/policies"
    click BL_PolicyFile "https://github.com/openstack/glance/blob/master/glance/api/policy.py"
    click BL_PropertyProtections "https://github.com/openstack/glance/blob/master/glance/api/property_protections.py"

    %% Click Events for Database Layer
    click DB "https://github.com/openstack/glance/tree/master/glance/db"
    click DB_SQLAlchemy "https://github.com/openstack/glance/tree/master/glance/db/sqlalchemy"
    click DB_Alembic "https://github.com/openstack/glance/tree/master/glance/db/sqlalchemy/alembic_migrations"
    click DB_API "https://github.com/openstack/glance/blob/master/glance/db/sqlalchemy/api.py"
    click DB_Migration "https://github.com/openstack/glance/blob/master/glance/db/migration.py"

    %% Click Events for Caching and Image Store
    click ImageCache "https://github.com/openstack/glance/tree/master/glance/image_cache"
    click Cache_Drivers "https://github.com/openstack/glance/tree/master/glance/image_cache/drivers"
    click Cache_Base "https://github.com/openstack/glance/blob/master/glance/image_cache/base.py"

    %% Click Events for Asynchronous Processing
    click Async_Main "https://github.com/openstack/glance/tree/master/glance/async_"
    click Async_Flows "https://github.com/openstack/glance/tree/master/glance/async_/flows"
    click Async_Plugins "https://github.com/openstack/glance/tree/master/glance/async_/flows/plugins"
    click Async_ImageImport "https://github.com/openstack/glance/blob/master/glance/async_/flows/api_image_import.py"
    click Async_Taskflow "https://github.com/openstack/glance/blob/master/glance/async_/taskflow_executor.py"

    %% Click Events for Configuration & External Integration
    click Config_ETC "https://github.com/openstack/glance/tree/master/etc"
    click Config_GlanceAPIConf "https://github.com/openstack/glance/blob/master/etc/glance-api.conf"
    click Config_GlanceCacheConf "https://github.com/openstack/glance/blob/master/etc/glance-cache.conf"
    click Config_GlancePolicyGen "https://github.com/openstack/glance/blob/master/etc/glance-policy-generator.conf"
    click Config_Oslo "https://github.com/openstack/glance/tree/master/etc/oslo-config-generator"
    click GlanceOpts "https://github.com/openstack/glance/blob/master/glance/opts.py"

    %% Styles
    classDef client fill:#E0E0FF,stroke:#000,stroke-width:2px;
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef logic fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef database fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef cache fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef async fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef config fill:#FFD1DC,stroke:#000,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
