# openshift/assisted-service architecture

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

- Interactive diagram: https://gitdiagram.com/openshift/assisted-service
- Repository: https://github.com/openshift/assisted-service

## Overview

##### Main Components
- Assisted Service Core: This is the heart of the system. It offers both a REST API (with swagger-generated code under the “restapi” directory) and the operator mode via CRDs and related controllers (see “config/crd” and “deploy/operator”).
- Business Logic and Domain Modules: Under “internal” you see modules for cluster management, host management, state machines (under “cmd/graphstatemachine”), networking, DNS, ISO/image generation (internal/ignition, pkg/generator), migrations, validations, and more.
- Client Libraries: The “client” folder contains autogenerated and hand-written clients for different API endpoints (installer, events, managed domains, manifests, operators, etc.). These clients are used by both the UI (in a separate repository) and possibly CLI tools.
- API Layer & Webhooks: The “pkg/webhooks” subdirectories (for agentinstall and hiveextension) indicate dynamic admission control/webhook functionality used when running as an operator or within a Kubernetes environment.
- External Integrations: The project relies on several external components:
– Database (PostgreSQL in deploy/postgres)
– Object storage (S3/MinIO in deploy/s3)
– Monitoring components such as Prometheus and Grafana (deploy/monitoring)
– Possibly external identity providers (see “pkg/auth”).
- Auxiliary Tools: Under “cmd” there are various executables like the agent-based installer, operator, and web admission entry points; and under “tools” scripts for deployments, migrations, and debugging.

##### Relationships and Data Flows
- Client (UI/CLI) initiates cluster creation by calling the Assisted Service via its REST API.
- The Service processes the request using internal packages for cluster and host management. It uses state machines (see “cmd/graphstatemachine”) to handle state transitions during discovery and installation.
- Once a cluster is defined, the service triggers the ISO generation (via components in “internal/ignition” and “pkg/generator”), caches installation binaries (in “internal/installercache”), and uploads images to S3.
- Concurrently, agent processes (running on booted hosts) use the API (and the webhook endpoints) to report inventory, connectivity, and validation details.
- The system writes state to a PostgreSQL database (“deploy/postgres” files) and may use additional persistent storage.
- Monitoring and logging components (see “deploy/monitoring” and “pkg/log”) are used for observability.
- The entire service can be deployed either as containers on a local host (refer to “deploy/podman”) or on Kubernetes/OpenShift clusters using provided manifests.

##### Important Architectural Patterns and Design Principles
- Layered Architecture: Separation between API (REST/Operator), business logic (internal packages), and infrastructure (database, storage, deployment manifests).
- State Machines: The use of state machines for processing cluster and host transitions (as shown by the “cmd/graphstatemachine” components) is central.
- Modularization and Code Generation: A separation between generated code (API definitions, swagger, CRDs) and hand-written business logic.
- Deployment Flexibility: The project supports multiple deployment targets (k8s, OpenShift, local containers) via specific manifests under “deploy” and build scripts in Makefile and CI scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    CLIENT["Client (UI/CLI)"]:::client
    AGENT["Agent Hosts"]:::client

    %% Assisted Service Core
    subgraph "Assisted Service Core"
        RA["REST API Endpoints"]:::operator
        OP["Operator Mode (CRDs)"]:::operator
        OP2["Operator Controllers"]:::operator
    end

    %% Business Logic & Domain Modules
    subgraph "Business Logic & Domain Modules"
        BL["Business Logic (Cluster & Host)"]:::logic
        SM["State Machine Manager"]:::logic
        IG["Image/ISO Generator"]:::logic
        GEN["Generator Module"]:::logic
    end

    %% API Layer & Webhooks
    subgraph "API Layer & Webhooks"
        APIW["Webhooks & API Extensions"]:::logic
    end

    %% Client Libraries
    subgraph "Client Libraries"
        CL["Client Libraries"]:::client
    end

    %% External Integrations
    subgraph "External Integrations"
        DB["Database (PostgreSQL)"]:::integration
        S3["Object Storage (S3/MinIO)"]:::storage
        MON["Monitoring (Prometheus/Grafana)"]:::integration
        AUTH["Auth Service"]:::integration
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        CMD["Executables (Agent, Operator, Web Admission)"]:::tools
        TOOLS["Deployment & Debug Scripts"]:::tools
    end

    %% Connections
    CLIENT -->|"calls"| RA
    CLIENT -->|"uses"| CL

    RA -->|"routes_to"| BL

    BL -->|"triggers"| SM
    BL -->|"initiates"| IG
    BL -->|"invokes"| GEN
    BL -->|"writes_to"| DB
    BL -->|"authenticates_with"| AUTH
    BL -->|"sends_metrics_to"| MON

    IG -->|"uploads_to"| S3

    AGENT -->|"communicates_via"| APIW
    APIW -->|"updates"| BL

    CMD -->|"manages"| RA
    CMD -->|"controls"| BL
    TOOLS -->|"deploys"| RA

    %% Click Events
    click RA "https://github.com/openshift/assisted-service/tree/master/restapi"
    click OP "https://github.com/openshift/assisted-service/tree/master/config/crd"
    click OP2 "https://github.com/openshift/assisted-service/tree/master/deploy/operator"
    click BL "https://github.com/openshift/assisted-service/tree/master/internal"
    click SM "https://github.com/openshift/assisted-service/tree/master/cmd/graphstatemachine"
    click IG "https://github.com/openshift/assisted-service/tree/master/internal/ignition"
    click GEN "https://github.com/openshift/assisted-service/tree/master/pkg/generator"
    click APIW "https://github.com/openshift/assisted-service/tree/master/pkg/webhooks"
    click CL "https://github.com/openshift/assisted-service/tree/master/client"
    click DB "https://github.com/openshift/assisted-service/tree/master/deploy/postgres"
    click S3 "https://github.com/openshift/assisted-service/tree/master/deploy/s3"
    click MON "https://github.com/openshift/assisted-service/tree/master/deploy/monitoring"
    click AUTH "https://github.com/openshift/assisted-service/tree/master/pkg/auth"
    click CMD "https://github.com/openshift/assisted-service/tree/master/cmd"
    click TOOLS "https://github.com/openshift/assisted-service/tree/master/tools"

    %% Styles
    classDef client fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef operator fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;
    classDef logic fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef integration fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef storage fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef tools fill:#F5CBA7,stroke:#BA4A00,stroke-width:2px;
```
