How microsoft/azure-linux-image-tools works
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