particle-os/deb-bootc-image-builder-new
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

first commit

Browse source
This commit is contained in:
robojerk 2025-09-05 07:10:12 -07:00
commit 7584207f76
72 changed files with 12801 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

239
fedora-bootc-image-builder.md Normal file
View file

@ -0,0 +1,239 @@
# 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**:
```yaml
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.