# openstack/octavia architecture

> Architecture diagram of the GitHub repository openstack/octavia, 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/octavia
- Repository: https://github.com/openstack/octavia

## Overview

##### Main Components
- API Layer: Represented in the octavia/api directory. This layer receives and validates client requests (e.g., creating or updating load balancers) and then passes them downstream.
- Controller/Worker: The core orchestration logic is found under octavia/controller (including subdirectories for worker processes, housekeeping, queue consumers, and task flows) that manages asynchronous operations.
- Load Balancer Drivers & Amphora Agents: The octavia/amphorae directory holds the code for handling the “amphora” based load balancing backend and related driver implementations (such as haproxy, keepalived, and noop drivers). Include also the “elements” directory that contains configuration management and agent setup for amphibious load balancers.
- Database: The octavia/db directory holds models, migration scripts, and repository logic for persistent state.
- Network & Compute Integrations: Directories like octavia/network and octavia/compute indicate integration with OpenStack Neutron and Nova to provision network interfaces and compute nodes for the amphora instances.
- Certificate Management: A group of components under octavia/certificates deals with certificate generation, management, and integration with Barbican.

##### Relationships and Data Flow
- From the API, show flow into the Controller/Worker which schedules tasks (e.g., amphora provisioning and health checks).
- Further detail the drivers by indicating that the amphora agents (and other provider drivers) interact with the actual compute infrastructure, provisioning individual load balancing instances.
- Communication channels between the Network/Compute components and the Controller to capture network provisioning and instance management.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize how Octavia is organized into logically separated modules (API, controller, drivers).
- Asynchrony: Show that the controller uses task queues (e.g., taskflow-based workers) for asynchronous operations.
- Extensibility: Note the “provider driver” model allowing new load balancing implementations to be integrated with minimal impact on core components.
- Open Integration: Mention that integrations with external OpenStack services (Keystone, Neutron) are achieved through clearly defined APIs and adapter patterns.

##### Incorporate Relevant Technologies and Libraries
- Python-based REST API (octavia/api).
- Taskflow (for orchestrating long-running flows in octavia/controller/worker).
- Database migration tools (reflected under octavia/db/migration).
- Jinja templating (used heavily in configuration file generation for amphora agents).
- Use of configuration, logging, and certificate management utilities distributed across the project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Clients("Clients"):::external

    %% API Layer
    subgraph "API Layer"
        API1["API Server"]:::api
    end

    %% Controller/Worker Layer
    subgraph "Controller/Worker Layer"
        CW["Controller/Worker Cluster"]:::controller
        DB["Database"]:::db
        CW -->|"state_transactions"| DB
    end

    %% Load Balancer Drivers & Amphora Agents Layer
    subgraph "Load Balancer Drivers"
        LA["Amphora Agents"]:::drivers
        DA["Driver (amphora-agent)"]:::drivers
        LA -->|"driver_setup"| DA
    end

    %% Integrations Layer
    subgraph "Integrations"
        NI["Network Integration"]:::integration
        CI["Compute Integration"]:::integration
        CM["Certificate Management"]:::cert
    end

    %% External Services
    subgraph "External Services"
        EXT["Keystone/Neutron/Barbican"]:::external
    end

    %% Data Flow Connections
    Clients -->|"send_request"| API1
    API1 -->|"REST_API"| CW
    CW -->|"provisioning"| LA
    CW -->|"networking"| NI
    CW -->|"compute_calls"| CI
    CW -->|"certificates"| CM
    DA -->|"instance_provisioning"| CI
    DA -->|"network_config"| NI

    %% External dashed connections
    EXT -.->|"auth"| API1
    EXT -.->|"auth"| CW
    EXT -.->|"certificates"| CM

    %% Styles and Classes
    classDef api fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef controller fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef drivers fill:#ffa500,stroke:#000,stroke-width:2px;
    classDef db fill:#d8bfd8,stroke:#000,stroke-width:2px;
    classDef integration fill:#87cefa,stroke:#000,stroke-width:2px;
    classDef cert fill:#ffb6c1,stroke:#000,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:2px;

    %% Click Events
    click API1 "https://github.com/openstack/octavia/tree/master/octavia/api"
    click CW "https://github.com/openstack/octavia/tree/master/octavia/controller"
    click LA "https://github.com/openstack/octavia/tree/master/octavia/amphorae"
    click DA "https://github.com/openstack/octavia/tree/master/elements/amphora-agent"
    click DB "https://github.com/openstack/octavia/tree/master/octavia/db"
    click NI "https://github.com/openstack/octavia/tree/master/octavia/network"
    click CI "https://github.com/openstack/octavia/tree/master/octavia/compute"
    click CM "https://github.com/openstack/octavia/tree/master/octavia/certificates"
    click EXT "https://github.com/openstack/octavia/tree/master/devstack"
```
