# openshift/assisted-image-service architecture

> Architecture diagram of the GitHub repository openshift/assisted-image-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-image-service
- Repository: https://github.com/openshift/assisted-image-service

## Overview

##### Project Overview
- Project Type: It is a specialized backend service designed to customize and serve RHCOS images for the Assisted Installer Service. The service downloads images on startup and provides multiple API endpoints for different authentication modes and image variants.
- Key Purpose: It takes in configuration, downloads RHCOS images, and then exposes endpoints to deliver customized images. It also interacts with an external assisted service for information.

##### Identifying the Main Components
a. HTTP API Server:
- Located in the root (main.go) and organized through the internal/handlers directory.
- Exposes multiple endpoints (e.g., /byid, /bytoken, /byapikey, /images, /boot-artifacts, /health, /live, /metrics).
- Handles authentication logic and token transformations between client requests and assisted service requests.

b. Image Customization Modules:
- The pkg/isoeditor package performs image editing functions (e.g., appending ignition, modifying boot parameters).
- The pkg/imagestore package handles storage and retrieval of downloaded RHCOS images.
- Additional supporting packages include pkg/overlay (managing overlays for images) and pkg/servers.

c. Assisted Service Integration:
- The service integrates with an external assisted service (its address and scheme are provided via environment variables).
- The authentication mapping (e.g., api_key, image_token, Authorization) is a key feature.

d. Configuration and Environment:
- Environment variables and configuration files (via README) set parameters like DATA_DIR, CERT paths, ports, version details, etc.
- Directories ‘data’ and ‘data_temp’ play a central role in storing downloaded images and temporary extraction data.

e. Deployment & Build Infrastructure:
- Dockerfiles (multiple, e.g., Dockerfile.image-service, Dockerfile.image-service-mce) and Makefile indicate containerized deployment.
- CI/CD configurations (e.g., .ci-operator.yaml, .github, .tekton) and integration tests in integration_test.
- Package management (go.mod, go.sum) which outlines the service’s dependencies.

##### Components’ Relationships and Interactions
- The HTTP layer (main API server) dispatches requests to the internal handlers.
- Handlers then interact with the image customization (pkg/isoeditor) and image storage logic (pkg/imagestore).
- When a request requires information or token translation, the service establishes outbound connections to the assisted service.
- The system initialization includes a startup process that downloads a set of images based on the provided configuration.
- Health, liveness, and metrics endpoints indicate readiness and performance, connecting to standard observability practices.

##### Architectural Patterns and Design Principles
- Modular design using packages: Handlers separate the web API logic from the business logic in packages like isoeditor and imagestore.
- Clean separation of concerns: API routing, authentication handling, image processing, and external service integration are clearly separated.
- Containerization and CI/CD integration are evident, suggesting a DevOps-friendly deployment pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    client["Client/API Consumers"]:::client

    %% API Layer
    subgraph "API Layer"
        mainAPI["Main API Server"]:::api
        httpHandlers["HTTP Handlers"]:::api
    end

    %% Image Processing Modules
    subgraph "Image Processing Modules"
        isoEditor["ISO Editor Module"]:::processing
        imgStore["Image Storage Module"]:::processing
        overlay["Overlay Management"]:::processing
        serverUtils["Additional Server Utilities"]:::processing
    end

    %% External Integration
    subgraph "External Integration"
        assistedClient["Assisted Service Client"]:::external
    end

    %% Persistent Storage
    subgraph "Persistent Storage"
        persistentData["Persistent Data Directory"]:::storage
        tempData["Temporary Data Directory"]:::storage
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        subgraph "Deployment Build Files"
            dockerImageService["Dockerfile.image-service"]:::infra
            dockerImageServiceMCE["Dockerfile.image-service-mce"]:::infra
            makefile["Makefile"]:::infra
        end
        subgraph "CI/CD Config"
            githubCI["GitHub Config (.github)"]:::infra
            tekton["Tekton Config (.tekton)"]:::infra
            ciOperator["CI Operator Config (.ci-operator.yaml)"]:::infra
        end
        configEnv["Configuration & Environment"]:::infra
    end

    %% Connections between layers
    client --> mainAPI
    mainAPI --> httpHandlers
    httpHandlers --> isoEditor
    httpHandlers --> imgStore
    httpHandlers --> overlay
    httpHandlers --> serverUtils
    httpHandlers --> assistedClient
    mainAPI -->|"startup_download"| imgStore
    imgStore -->|"store_image"| persistentData
    imgStore -->|"temp_extraction"| tempData
    configEnv --> mainAPI
    configEnv --> httpHandlers
    dockerImageService --> mainAPI
    dockerImageServiceMCE --> mainAPI
    makefile --> mainAPI
    githubCI --> dockerImageService
    tekton --> dockerImageService
    ciOperator --> dockerImageService

    %% Click Events
    click mainAPI "https://github.com/openshift/assisted-image-service/blob/main/main.go"
    click httpHandlers "https://github.com/openshift/assisted-image-service/tree/main/internal/handlers"
    click isoEditor "https://github.com/openshift/assisted-image-service/tree/main/pkg/isoeditor"
    click imgStore "https://github.com/openshift/assisted-image-service/tree/main/pkg/imagestore"
    click overlay "https://github.com/openshift/assisted-image-service/tree/main/pkg/overlay"
    click serverUtils "https://github.com/openshift/assisted-image-service/tree/main/pkg/servers"
    click assistedClient "https://github.com/openshift/assisted-image-service/blob/main/internal/handlers/assisted_service_client.go"
    click persistentData "https://github.com/openshift/assisted-image-service/tree/main/data"
    click tempData "https://github.com/openshift/assisted-image-service/tree/main/data_temp"
    click dockerImageService "https://github.com/openshift/assisted-image-service/blob/main/Dockerfile.image-service"
    click dockerImageServiceMCE "https://github.com/openshift/assisted-image-service/blob/main/Dockerfile.image-service-mce"
    click makefile "https://github.com/openshift/assisted-image-service/tree/main/Makefile"
    click githubCI "https://github.com/openshift/assisted-image-service/blob/main/.github"
    click tekton "https://github.com/openshift/assisted-image-service/blob/main/.tekton"
    click ciOperator "https://github.com/openshift/assisted-image-service/blob/main/.ci-operator.yaml"

    %% Styles
    classDef client fill:#ffebcd,stroke:#000,stroke-width:2px;
    classDef api fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef processing fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef external fill:#cce5ff,stroke:#000,stroke-width:2px;
    classDef storage fill:#ffe4e1,stroke:#000,stroke-width:2px;
    classDef infra fill:#e6e6fa,stroke:#000,stroke-width:2px;
```
