deb-bootc-image-builder-new/fedora-bootc-image-builder.md

Fedora bootc-image-builder Analysis

Overview

The Fedora bootc-image-builder is a containerized tool that creates bootable disk images from bootc (bootable container) inputs. It's specifically designed for Fedora/CentOS/RHEL systems using DNF/RPM package management and supports various output formats including QCOW2, AMI, VMDK, VHD, GCE, and ISO images.

Architecture

The tool follows a modular architecture with clear separation of concerns:

1. Main Application (bib/cmd/bootc-image-builder/) - Entry point and CLI handling
2. Internal Libraries (bib/internal/) - Core functionality for distro definitions and image types
3. Data Definitions (bib/data/defs/) - Distribution-specific package lists and configurations
4. Build System - Containerfile and build scripts for containerization

File Structure Analysis

z fedora-bootc-image-builder/
├── bib/                                    # Main application directory
│   ├── cmd/                               # Command-line applications
│   │   ├── bootc-image-builder/          # Main application
│   │   │   ├── main.go                   # Entry point, CLI setup, manifest generation
│   │   │   ├── image.go                  # Image manifest creation logic
│   │   │   ├── cloud.go                  # Cloud upload functionality (AWS)
│   │   │   ├── mtls.go                   # mTLS configuration handling
│   │   │   ├── partition_tables.go       # Partition table definitions
│   │   │   ├── workload.go               # Workload-specific configurations
│   │   │   └── *_test.go                 # Test files
│   │   ├── cross-arch/                   # Cross-architecture support
│   │   │   └── canary.go                 # Cross-arch canary functionality
│   │   └── upload/                       # Upload utilities
│   │       └── main.go                   # Upload command implementation
│   ├── data/                             # Data files and definitions
│   │   └── defs/                         # Distribution definitions
│   │       ├── fedora-42.yaml           # Fedora 42 package definitions
│   │       ├── centos-9.yaml            # CentOS 9 definitions
│   │       ├── rhel-10.yaml             # RHEL 10 definitions
│   │       └── [other-distro].yaml      # Other supported distributions
│   ├── internal/                         # Internal libraries
│   │   ├── distrodef/                    # Distribution definition handling
│   │   │   ├── distrodef.go             # Core distro definition logic
│   │   │   └── distrodef_test.go        # Tests
│   │   └── imagetypes/                   # Image type management
│   │       ├── imagetypes.go            # Image type definitions and validation
│   │       └── imagetypes_test.go       # Tests
│   ├── go.mod                            # Go module dependencies
│   └── go.sum                            # Go module checksums
├── build.sh                              # Build script
├── Containerfile                         # Container build definition
├── devel/                                # Development tools and documentation
│   ├── bootc-install                     # Bootc installation script
│   ├── Containerfile                     # Development container
│   ├── Containerfile.hack                # Hack container for development
│   ├── README.md                         # Development documentation
│   └── Troubleshooting.md                # Troubleshooting guide
├── test/                                 # Test suite
│   ├── conftest.py                       # Test configuration
│   ├── containerbuild.py                 # Container build tests
│   ├── test_build_*.py                   # Various build tests
│   ├── test_*.py                         # Other test modules
│   └── vm.py                             # VM testing utilities
├── plans/                                # Test plans
│   ├── integration.fmf                   # Integration test plan
│   └── unit-go.fmf                       # Go unit test plan
├── group_osbuild-osbuild-fedora.repo     # OSBuild repository configuration
├── package-requires.txt                  # Required packages list
├── pytest.ini                           # Python test configuration
├── Makefile                              # Build automation
├── HACKING.md                            # Development guidelines
├── LICENSE                               # License file
└── README.md                             # Main documentation

Key Components Analysis

1. Main Application (main.go)

Purpose: Entry point and CLI interface Key Features:

• Cobra-based CLI with commands: build, manifest, version
• Container image inspection and size calculation
• Manifest generation from container inputs
• Progress reporting and logging
• AWS cloud upload support
• Cross-architecture building support

Hardcoded Values:

• Container size multiplier: containerSizeToDiskSizeMultiplier = 2 (can be configurable)
• Default distro definition paths (can be configurable)
• Default image types and exports (can be configurable)
• Fedora-specific manifest distro: manifest.DISTRO_FEDORA (Fedora-only)

2. Image Manifest Generation (image.go)

Purpose: Core logic for creating OSBuild manifests Key Features:

• Disk image and ISO manifest generation
• Partition table creation with support for ext4, xfs, btrfs
• Filesystem customization handling
• Kernel options and boot configuration
• User and group management
• SELinux policy handling

Hardcoded Values:

• Default size: DEFAULT_SIZE = uint64(10 * GibiByte) (can be configurable)
• Kernel options: "rw", "console=tty0", "console=ttyS0" (can be configurable)
• Platform-specific configurations (BIOS, UEFI, etc.) (can be configurable)
• Distribution-specific labels and configurations (Fedora-only)

3. Distribution Definitions (distrodef.go)

Purpose: Load and manage distribution-specific package lists Key Features:

• YAML-based package definition loading
• Version matching (exact and fuzzy)
• Image type-specific package sets
• Support for multiple definition directories

Hardcoded Values:

• Definition file naming convention: {distro}-{version}.yaml (can be configurable)
• Image type keys in YAML files (can be configurable)
• Version comparison logic (can be configurable)

4. Image Types (imagetypes.go)

Purpose: Define and validate supported image output formats Key Features:

• Support for: ami, qcow2, raw, vmdk, vhd, gce, debian-installer, calamares
• Export type mapping
• ISO vs disk image validation
• Cannot mix ISO and disk types in single build

Hardcoded Values:

• Image type to export mapping (can be configurable)
• ISO flag for each image type (can be configurable)
• Validation rules for image type combinations (can be configurable)

5. Distribution Data Files (data/defs/)

Purpose: Store distribution-specific package lists and configurations Structure:

anaconda-iso:
  packages:
    - package1
    - package2
    # ... more packages

Key Files:

• fedora-42.yaml - Fedora 42 package definitions
• centos-9.yaml, centos-10.yaml - CentOS definitions
• rhel-9.yaml, rhel-10.yaml - RHEL definitions
• Various other distribution definitions

6. Container Build (Containerfile)

Purpose: Multi-stage container build for the tool Stages:

1. Builder: Fedora 42 base, installs Go and dependencies, builds binary
2. Runtime: Fedora 42 base, installs runtime dependencies, copies binary

Hardcoded Values:

• Base image: registry.fedoraproject.org/fedora:42 (Fedora-only)
• Package repository: group_osbuild-osbuild-fedora.repo (Fedora-only)
• Binary location: /usr/bin/bootc-image-builder (can be configurable)
• Data location: /usr/share/bootc-image-builder (can be configurable)

Package Management Integration

The tool is deeply integrated with RPM/DNF ecosystem:

1. DNF Solver: Uses dnfjson.Solver for package dependency resolution
2. RPM Metadata: Caches RPM metadata in /rpmmd volume
3. Librepo Support: Optional librepo backend for faster downloads
4. Repository Configuration: Uses Fedora/CentOS/RHEL repositories

Key Dependencies

• osbuild/images: Core image building library
• osbuild/blueprint: Configuration and customization handling
• containers/image: Container image handling
• spf13/cobra: CLI framework
• sirupsen/logrus: Logging

Debian-Specific Installer Options

For the Debian version, we will replace Fedora's Anaconda installer with Debian-native options:

1. Debian Installer (debian-installer)

• Purpose: Traditional Debian installation system
• Use Case: Minimal, text-based installation
• Advantages: Lightweight, fast, well-tested
• Package Requirements: debian-installer packages, kernel, initramfs

2. Calamares

• Purpose: Modern, graphical installer
• Use Case: User-friendly installation with GUI
• Advantages: Modern interface, flexible partitioning
• Package Requirements: calamares, desktop environment packages

Both options will be implemented as separate image types, similar to how the Fedora version handles anaconda-iso.

Limitations and Hardcoded Values

1. Distribution Support: Only supports RPM-based distributions (Fedora, CentOS, RHEL)
2. Package Manager: Hardcoded to DNF/RPM
3. Repository URLs: Hardcoded Fedora/CentOS/RHEL repositories
4. Container Registry: Hardcoded to quay.io/centos-bootc/
5. Default Configurations: Many default values are hardcoded in Go source
6. Architecture Support: Limited to x86_64, aarch64, ppc64le, s390x, riscv64
7. Installer System: Anaconda is Fedora-specific and not applicable to Debian

Configuration System

The current configuration system uses:

• Blueprint format: TOML/JSON configuration files
• Command-line flags: Extensive CLI options
• Container metadata: Extracts some configuration from container images
• Environment variables: For AWS credentials and other settings

Build Process

1. Container Inspection: Analyzes input container image
2. Manifest Generation: Creates OSBuild manifest
3. Package Resolution: Resolves dependencies using DNF
4. Image Building: Uses OSBuild to create final images
5. Optional Upload: Can upload to cloud providers (AWS)

Testing Infrastructure

• Python-based tests: Integration and functional tests
• Go unit tests: Component-level testing
• Container testing: Tests run in containers
• VM testing: Can test resulting images in VMs
• Test plans: FMF-based test organization

This analysis provides the foundation for creating a Debian equivalent that adapts these concepts to the APT/DEB ecosystem while maintaining the same overall architecture and functionality.