# openstack/ironic architecture

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

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

## Overview

##### Main Components
- API Server – The “ironic/api” layer that exposes REST endpoints, handles client requests, and performs input validation/reply formatting.
- Conductor Service – The “ironic/conductor” layer that receives tasks from the API and orchestrates long-running operations (e.g. cleaning, deployment, inspection) against bare metal nodes.
- Drivers / Plug-ins – A set of modules located under “ironic/drivers” (including vendor-specific subdirectories) which provide the actual hooks to interact with hardware management protocols (IPMI, PXE, DRAC, iLO, Redfish, etc.).
- Database Layer – The persistence layer (likely interfaced using SQLAlchemy, as seen in the “ironic/db/sqlalchemy” directories) that stores state and metadata for nodes, deployments, and configuration.
- Auxiliary Tools & Scripts – CLI commands, test scripts, and development utilities (e.g. “tools” and “devstack”) which are used for configuration, testing, or automated deployments.
- Integration Components – Components for interacting with external services such as Nova (for hypervisor integration), Neutron (for networking), Swift or Glance (for images), and Keystone for authentication/authorization.

##### Relationships and Interactions
- Client Interaction: End users or Nova make requests to the API server. These requests are parsed and passed internally toward the conductor.
- Orchestration: The conductor service schedules tasks and dispatches operations to the various hardware drivers. There are clear directional flows from the API to the conductor and then from the conductor to the drivers.
- Database Access: All components that require persistence (API, conductor, and sometimes drivers for logging or state recovery) interact with a central database.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Different directories (API, conductor, drivers, and database) indicate a clean separation between request management, orchestration, hardware interaction, and state persistence.
- Plugin Architecture: Driver modules are implemented as plug-ins that can be extended for various hardware types and vendor-specific protocols.
- Resilience and Fault Tolerance: The design is meant to be security-aware and fault tolerant; include indications of error handling, logging (see “ironic/common/faults” and “ironic/common/utils”), and retry mechanisms (for IPMI, PXE, etc.).
- Modular & Extensible: With its multiple directories for different aspects, the architecture encourages modularity which simplifies testing (as seen in “ironic/tests”) and development.

##### Relevant Technologies & Frameworks
- Python (the entire project is implemented in Python).
- SQLAlchemy ORM for database models and migrations.
- WSGI components (e.g., “ironic/api/wsgi.py”) for serving the API.
- Middleware (as seen in “ironic/api/middleware”) for request parsing and error handling.
- Devstack integration for deployment testing, likely leveraging configuration templates and plugin hooks.
- Various vendor-specific libraries for hardware interaction (e.g., drac, ipmi, redfish).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Subgraph
    subgraph "Clients"
        Nova["Nova"]:::clients
        CLI["CLI"]:::clients
        UI["User Interface"]:::clients
    end

    %% API Layer Subgraph
    subgraph "API Layer"
        APIServer["Ironic API Server"]:::api
        APIWSGI["WSGI (ironic/api/wsgi.py)"]:::api
        APIControllers["Controllers (ironic/api/controllers/)"]:::api
    end

    %% Conductor Layer Subgraph
    subgraph "Conductor Layer"
        Conductor["Conductor Service"]:::conductor
    end

    %% Driver Layer Subgraph
    subgraph "Driver Layer"
        Drivers["Drivers/Plug-ins"]:::drivers
    end

    %% Persistence Subgraph
    subgraph "Persistence"
        Database["Database (ironic/db/sqlalchemy)"]:::db
    end

    %% Auxiliary Tools Subgraph
    subgraph "Auxiliary Tools"
        Tools["Tools"]:::tools
        Devstack["Devstack"]:::tools
    end

    %% Integration Components Subgraph
    subgraph "Integration Components"
        Config["Config (etc/ironic)"]:::integration
        Documentation["Documentation (doc/source/admin)"]:::integration
    end

    %% Client to API connections
    Nova -->|"requests"| APIServer
    CLI  -->|"requests"| APIServer
    UI   -->|"requests"| APIServer

    %% Internal API components
    APIServer -->|"handles"| APIWSGI
    APIServer -->|"routes_to"| APIControllers

    %% API to Conductor & Database connections
    APIServer -->|"orchestrates"| Conductor
    APIServer -->|"db_access"| Database

    %% Conductor interactions
    Conductor -->|"dispatches"| Drivers
    Conductor -->|"db_access"| Database

    %% Auxiliary Tools interactions (for management and testing)
    Tools -->|"manage"| APIServer
    Tools -->|"manage"| Conductor
    Devstack -->|"deploy_test"| APIServer

    %% Integration Components interactions
    APIServer -->|"integration"| Config
    APIServer -->|"integration"| Documentation

    %% Click Events
    click APIServer "https://github.com/openstack/ironic/tree/master/ironic/api"
    click APIWSGI "https://github.com/openstack/ironic/blob/master/ironic/api/wsgi.py"
    click APIControllers "https://github.com/openstack/ironic/tree/master/ironic/api/controllers/"
    click Conductor "https://github.com/openstack/ironic/tree/master/ironic/conductor"
    click Drivers "https://github.com/openstack/ironic/tree/master/ironic/drivers"
    click Database "https://github.com/openstack/ironic/tree/master/ironic/db/sqlalchemy"
    click Tools "https://github.com/openstack/ironic/tree/master/tools"
    click Devstack "https://github.com/openstack/ironic/tree/master/devstack"
    click Config "https://github.com/openstack/ironic/tree/master/etc/ironic"
    click Documentation "https://github.com/openstack/ironic/tree/master/doc/source/admin"

    %% Classes and Styling
    classDef clients fill:#ffedcc,stroke:#cc6600,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef conductor fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef drivers fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef db fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef tools fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef integration fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
