# microsoft/azure-linux-image-tools architecture

> Architecture diagram of the GitHub repository microsoft/azure-linux-image-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/azure-linux-image-tools
- Repository: https://github.com/microsoft/azure-linux-image-tools

## Overview

Step 1: Identify Project Type and Purpose
- This is an open-source monorepo of CLI utilities (primarily “Image Customizer”) for customizing Azure Linux images via configuration files.

Step 2: Analyze the File Structure
- Top level
- .github/ – GitHub Actions workflows for build, test, release, container publishing
- docs/ – Jekyll-based user and API documentation
- test/ – end-to-end VM tests (pytest)
- toolkit/ – build scripts (Makefiles), resource assets, Go modules and libraries
- Under toolkit/
- scripts/ – Makefile helpers, version bumpers, license collectors
- resources/ – ISO root templates, grub configs, meta-user-data
- tools/ – each subfolder is a Go module that builds a CLI binary:
– imagecustomizer (main tool)
– imagecustomizerschemacli (schema validation)
– imagegen, imager, osmodifier
– container/ – Dockerfiles and helper scripts for each binary
- pkg/ – shared, reusable libraries: imagecustomizerlib, isomakerlib, osmodifierlib, etc.
- internal/ – low-level system-interaction packages: safechroot, safeloopback, safemount, grub parsing, file/directory utils, logger, tarutils, networking, systemd, etc.

Step 3: Examine README Insights
- Core functionality: configuration-driven operations (partitioning, file injection, SELinux settings, bootloader customization, metadata injection)
- Main tool: Image Customizer, powered by JSON schema (imagecustomizerapi) + libraries + internal utilities
- Supported formats, operations detailed under docs/imagecustomizer/api

Step 4: Main Components & Their Interactions
##### Developer & CI/CD Environment
- Developer workstation runs Makefiles and Go toolchain
- GitHub Actions (.github/workflows/) build binaries, run tests, generate docs, publish releases & containers
##### CLI Entry Points (runtime)
- imagecustomizer, imagecustomizerschemacli, imagegen, imager, osmodifier
##### Configuration Layer
- imagecustomizerapi – JSON schema and Go structs for parsing user config
##### Core Service Libraries
- pkg/imagecustomizerlib – customization logic (files, packages, partitions, bootloader, verity)
- pkg/isomakerlib, pkg/osmodifierlib – ISO creation and OS modifications
##### Infrastructure & Utilities
- internal/… – safechroot, loopback mounts, filesystems, GRUB parser, logging, tar utils, OS info, package repo management, telemetry, etc.
- toolkit/resources – templates & static assets (isolinux, grub2, meta-user-data)
##### External Dependencies
- System commands: mkfs, grub2-install, qemu-img, mount, chroot
- Docker engine (for containerized builds/tests)
##### Output Artifacts
- Customized disk images (.vhdx, .iso)
- Logs, test results, published containers, GitHub release packages

Step 5: Architectural Patterns & Principles
- Layered Architecture
- Presentation: CLI binaries
- API: configuration schema (JSON + Go structs)
- Service: core libraries implementing customization tasks
- Infrastructure: internal utils abstracting system interactions
- Monorepo with modular Go modules for each binary, shared pkg for reusable code, internal for encapsulated helpers
- Configuration-driven, declarative design via JSON schema

##### Separation of Concerns
- Visually separate build-time (CI/CD, docs) from run-time (CLI invocation, image customization)

Step 7: Tailoring to an Open-Source Tool
- Extensibility: new CLI modules under toolkit/tools can reuse pkg/* and internal/* components
- Integration points with external systems: Azure (image upload), Docker (container builds), local system commands
- How configuration schema (imagecustomizerapi) drives the workflow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & CI/CD
    subgraph "Development & CI/CD"
        direction TB
        Dev["Developer Workstation"]:::external
        CI["CI/CD Workflows"]:::ci
        Docs["Documentation Site"]:::ci
        Tests["End-to-End VM Tests"]:::ci
        Dev -->|"runs Makefiles & Go toolchain"| CI
        CI -->|"generates docs"| Docs
        CI -->|"runs pytest VM tests"| Tests
    end

    %% Runtime CLI Layer
    subgraph "CLI Entry Points"
        direction TB
        IMGC["Image Customizer"]:::cli
        IMGSCH["Schema Validator"]:::cli
        IMGEN["Image Generator"]:::cli
        IMGR["Image R"]:::cli
        OSMOD["OS Modifier"]:::cli
    end

    %% Configuration API Layer
    subgraph "Configuration Schema API"
        direction TB
        API["imagecustomizerapi"]:::api
    end

    %% Core Service Libraries
    subgraph "Core Libraries"
        direction TB
        LIB1["imagecustomizerlib"]:::api
        LIB2["isomakerlib"]:::api
        LIB3["osmodifierlib"]:::api
        PROFILE["profile"]:::api
        SNAP["rpmssnapshot"]:::api
        CHROOT["simpletoolchroot"]:::api
        SPEC["specarchchecker"]:::api
    end

    %% Internal Utilities
    subgraph "Internal Utilities"
        direction TB
        SC["safechroot"]:::internal
        SL["safeloopback"]:::internal
        SM["safemount"]:::internal
        GRUB["grub parsing"]:::internal
        TAR["tarutils"]:::internal
        STORE["storage/filescanner"]:::internal
        LOG["logger"]:::internal
        NET["network"]:::internal
        OSINFO["osinfo"]:::internal
        REPO["packagerepo"]:::internal
        TELE["telemetry"]:::internal
        SYSTD["systemd"]:::internal
        OTHER["others (jsonutils, shell, etc.)"]:::internal
        ISOGEN["isogenerator"]:::internal
    end

    %% Resources & External
    subgraph "Resources & External Systems"
        direction TB
        RES["Resource Assets"]:::resources
        SYS["System Commands"]:::external
        DOCK["Docker Engine"]:::external
        AZ["Azure Upload"]:::external
    end

    %% Output Artifacts
    subgraph "Output Artifacts"
        direction TB
        IMG["Customized Disk Images"]:::output
        LOGS["Logs & Test Results"]:::output
        CNT["Published Containers"]:::output
    end

    %% Relationships
    IMGC -->|"parses config"| API
    IMGSCH -->|"validates schema"| API
    IMGC -->|"executes customization"| LIB1
    API -->|"provides config structs"| LIB1
    LIB1 -->|"uses ISO creation"| LIB2
    LIB1 -->|"uses OS modifications"| LIB3
    LIB2 -->|"invokes isogenerator"| ISOGEN
    LIB1 -->|"calls internal utils"| SC
    LIB1 -->|"calls internal utils"| SL
    LIB1 -->|"calls internal utils"| SM
    LIB1 -->|"calls internal utils"| GRUB
    LIB1 -->|"calls internal utils"| TAR
    LIB1 -->|"calls internal utils"| STORE
    LIB1 -->|"calls internal utils"| LOG
    LIB1 -->|"calls internal utils"| NET
    LIB1 -->|"calls internal utils"| OSINFO
    LIB1 -->|"calls internal utils"| REPO
    LIB1 -->|"calls internal utils"| TELE
    LIB1 -->|"calls internal utils"| SYSTD
    LIB1 -->|"calls internal utils"| OTHER
    IMGEN -->|"uses core libs"| LIB2
    IMGR -->|"uses core libs"| LIB3
    OSMOD -->|"uses core libs"| LIB3
    RES -->|"provides templates"| LIB2
    SYS -->|"executes commands"| SM
    SYS -->|"executes commands"| GRUB
    DOCK -->|"builds containers"| CI
    AZ -->|"uploads images"| IMG

    %% Developer to CLI
    Dev -->|"invokes CLI"| IMGC

    %% Outputs
    IMGC -->|"produces"| IMG
    CI -->|"publishes"| CNT
    CI -->|"generates"| LOGS

    %% Click Events
    click CI "https://github.com/microsoft/azure-linux-image-tools/tree/main/.github/workflows/"
    click Docs "https://github.com/microsoft/azure-linux-image-tools/tree/main/docs/"
    click Tests "https://github.com/microsoft/azure-linux-image-tools/tree/main/test/vmtests/"
    click Dev "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/scripts/"
    click Dev "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/Makefile"
    click RES "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/resources/"
    click IMGC "https://github.com/microsoft/azure-linux-image-tools/blob/main/toolkit/tools/imagecustomizer/main.go"
    click IMGSCH "https://github.com/microsoft/azure-linux-image-tools/blob/main/toolkit/tools/imagecustomizerschemacli/main.go"
    click IMGEN "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/imagegen/"
    click IMGR "https://github.com/microsoft/azure-linux-image-tools/blob/main/toolkit/tools/imager/imager.go"
    click OSMOD "https://github.com/microsoft/azure-linux-image-tools/blob/main/toolkit/tools/osmodifier/main.go"
    click API "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/imagecustomizerapi/"
    click LIB1 "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/pkg/imagecustomizerlib/"
    click LIB2 "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/pkg/isomakerlib/"
    click LIB3 "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/pkg/osmodifierlib/"
    click PROFILE "https://github.com/microsoft/azure-linux-image-tools/blob/main/toolkit/tools/pkg/profile/profile.go"
    click SNAP "https://github.com/microsoft/azure-linux-image-tools/blob/main/toolkit/tools/pkg/rpmssnapshot/rpmssnapshot.go"
    click CHROOT "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/pkg/simpletoolchroot/"
    click SPEC "https://github.com/microsoft/azure-linux-image-tools/blob/main/toolkit/tools/pkg/specarchchecker/specarchchecker.go"
    click SC "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/safechroot/"
    click SL "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/safeloopback/"
    click SM "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/safemount/"
    click GRUB "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/grub/"
    click TAR "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/tarutils/"
    click STORE "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/storage/"
    click STORE "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/filescanner/"
    click LOG "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/logger/"
    click NET "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/network/"
    click OSINFO "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/osinfo/"
    click REPO "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/packagerepo/"
    click TELE "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/telemetry/"
    click SYSTD "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/systemd/"
    click OTHER "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/"
    click ISOGEN "https://github.com/microsoft/azure-linux-image-tools/tree/main/toolkit/tools/internal/isogenerator/"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#3399ff,stroke-width:2px
    classDef api fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef internal fill:#fff3cd,stroke:#ffcc00,stroke-width:2px
    classDef resources fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
    classDef ci fill:#f5c6cb,stroke:#dc3545,stroke-width:2px
    classDef external fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px
    classDef output fill:#d0ecdd,stroke:#20c997,stroke-width:2px
```
