215 lines
6.5 KiB
Markdown
215 lines
6.5 KiB
Markdown
# bootc-image-builder
|
|
|
|
A tool to convert bootc container images to bootable disk images. This tool creates bootable VM images from bootc-compatible container images, handling the complete bootc workflow including OSTree integration, composefs setup, initramfs creation, and bootloader installation.
|
|
|
|
## Features
|
|
|
|
- ✅ **Multi-format Support**: QCOW2, Raw, VMDK, ISO, AMI
|
|
- ✅ **Bootc Integration**: Full bootc container image support
|
|
- ✅ **OSTree Repository**: Creates and manages OSTree repositories
|
|
- ✅ **Composefs Support**: Efficient container filesystem mounting
|
|
- ✅ **Initramfs Creation**: Uses dracut to create bootc-aware initramfs
|
|
- ✅ **Bootloader Support**: GRUB and systemd-boot installation
|
|
- ✅ **UEFI/BIOS Support**: Both UEFI and BIOS boot modes
|
|
- ✅ **Secure Boot**: Optional secure boot configuration
|
|
- ✅ **Cloud Integration**: AWS, Azure, GCP optimizations
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
You need the following tools installed on your system:
|
|
|
|
```bash
|
|
# Container runtime
|
|
sudo apt install podman
|
|
|
|
# Disk image tools
|
|
sudo apt install qemu-utils parted
|
|
|
|
# OSTree and composefs
|
|
sudo apt install ostree libostree-dev
|
|
|
|
# Bootloader tools
|
|
sudo apt install grub-efi-amd64 systemd-boot
|
|
|
|
# Initramfs tools
|
|
sudo apt install dracut
|
|
|
|
# Build tools
|
|
sudo apt install build-essential
|
|
```
|
|
|
|
### Build from Source
|
|
|
|
```bash
|
|
git clone https://github.com/apt-ostree/bootc-image-builder
|
|
cd bootc-image-builder
|
|
cargo build --release
|
|
sudo cp target/release/bootc-image-builder /usr/local/bin/
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Convert a bootc container image to QCOW2
|
|
bootc-image-builder build localhost/my-debian-server:latest --format qcow2
|
|
|
|
# Convert to raw disk image
|
|
bootc-image-builder build localhost/my-debian-server:latest --format raw --output my-server.img
|
|
|
|
# Convert to VMDK for VMware
|
|
bootc-image-builder build localhost/my-debian-server:latest --format vmdk --output my-server.vmdk
|
|
```
|
|
|
|
### Advanced Usage
|
|
|
|
```bash
|
|
# Build with custom settings
|
|
bootc-image-builder build localhost/my-debian-server:latest \
|
|
--format qcow2 \
|
|
--size 20 \
|
|
--arch x86_64 \
|
|
--bootloader grub \
|
|
--secure-boot \
|
|
--kernel-args "console=ttyS0,115200n8 quiet" \
|
|
--output my-server.qcow2
|
|
|
|
# Build for cloud deployment
|
|
bootc-image-builder build localhost/my-debian-server:latest \
|
|
--format ami \
|
|
--cloud-provider aws \
|
|
--output my-server-ami
|
|
```
|
|
|
|
### Command Line Options
|
|
|
|
```bash
|
|
bootc-image-builder build [OPTIONS] <IMAGE>
|
|
|
|
Arguments:
|
|
<IMAGE> The name of the bootc container image to build from
|
|
|
|
Options:
|
|
-f, --format <FORMAT> The format of the output disk image [default: qcow2] [possible values: qcow2, raw, vmdk, iso, ami]
|
|
-o, --output <OUTPUT> The path to save the generated disk image file [default: bootc-image]
|
|
-s, --size <SIZE> The size of the disk image in GB [default: 10]
|
|
--arch <ARCH> The architecture to build for [default: x86_64] [possible values: x86_64, aarch64, ppc64le]
|
|
--bootloader <BOOTLOADER> The bootloader to use [default: grub] [possible values: grub, systemd-boot]
|
|
--secure-boot Enable secure boot support
|
|
--uefi Enable UEFI boot (default: auto-detect)
|
|
--bios Enable BIOS boot (default: auto-detect)
|
|
--kernel-args <KERNEL_ARGS> Custom kernel command line arguments [default: "console=ttyS0,115200n8 quiet"]
|
|
--cloud-provider <CLOUD_PROVIDER> Cloud provider for cloud-specific optimizations [possible values: aws, azure, gcp]
|
|
-h, --help Print help
|
|
-V, --version Print version
|
|
```
|
|
|
|
## How It Works
|
|
|
|
The bootc-image-builder follows this workflow:
|
|
|
|
1. **Pull and Extract**: Downloads and extracts the bootc container image
|
|
2. **Setup Bootc Support**: Installs bootc binary and configuration
|
|
3. **Create OSTree Repository**: Sets up OSTree repository structure
|
|
4. **Configure Composefs**: Enables composefs for efficient container mounting
|
|
5. **Create Initramfs**: Uses dracut to create bootc-aware initramfs
|
|
6. **Install Bootloader**: Installs GRUB or systemd-boot
|
|
7. **Create Disk Image**: Partitions, formats, and copies files to disk image
|
|
|
|
## Examples
|
|
|
|
### Building a Debian Server Image
|
|
|
|
```bash
|
|
# 1. Create a bootc container image with apt-ostree
|
|
apt-ostree compose tree debian-server.yaml --container
|
|
|
|
# 2. Convert to bootable disk image
|
|
bootc-image-builder build localhost/debian-server:latest \
|
|
--format qcow2 \
|
|
--size 10G \
|
|
--bootloader grub
|
|
|
|
# 3. Boot in QEMU
|
|
qemu-system-x86_64 -drive file=debian-server.qcow2,format=qcow2
|
|
```
|
|
|
|
### Building a Cloud Image
|
|
|
|
```bash
|
|
# 1. Create cloud-optimized bootc image
|
|
apt-ostree compose tree cloud-server.yaml --container
|
|
|
|
# 2. Convert to AMI format
|
|
bootc-image-builder build localhost/cloud-server:latest \
|
|
--format ami \
|
|
--cloud-provider aws \
|
|
--size 8G
|
|
|
|
# 3. Deploy to AWS
|
|
aws ec2 run-instances --image-id ami-12345678 --instance-type t3.micro
|
|
```
|
|
|
|
## Architecture Support
|
|
|
|
- **x86_64**: Intel/AMD 64-bit (default)
|
|
- **aarch64**: ARM 64-bit
|
|
- **ppc64le**: PowerPC 64-bit
|
|
|
|
## Format Support
|
|
|
|
- **QCOW2**: QEMU, KVM, OpenStack (default)
|
|
- **Raw**: Direct disk images
|
|
- **VMDK**: VMware compatibility
|
|
- **ISO**: Bootable CDs/DVDs
|
|
- **AMI**: Amazon Web Services
|
|
|
|
## Bootloader Support
|
|
|
|
- **GRUB**: Traditional bootloader with BLS support
|
|
- **systemd-boot**: Modern UEFI bootloader
|
|
|
|
## Security Features
|
|
|
|
- **Secure Boot**: UEFI secure boot support
|
|
- **Immutable**: Read-only filesystem by default
|
|
- **Atomic Updates**: OSTree-based atomic updates
|
|
- **Container Isolation**: Container-based system management
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Permission Denied**: The tool requires root/sudo privileges for disk operations
|
|
2. **Missing Dependencies**: Ensure all required tools are installed
|
|
3. **Dracut Failures**: Falls back to minimal initramfs if dracut fails
|
|
4. **Loop Device Issues**: May need to unmount existing loop devices
|
|
|
|
### Debug Mode
|
|
|
|
```bash
|
|
# Enable debug logging
|
|
RUST_LOG=debug bootc-image-builder build localhost/my-image:latest
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|
|
|
|
## Related Projects
|
|
|
|
- [apt-ostree](https://github.com/apt-ostree/apt-ostree) - Debian/Ubuntu equivalent of rpm-ostree
|
|
- [bootc](https://github.com/containers/bootc) - Container images that can boot directly
|
|
- [ostree](https://ostreedev.github.io/ostree/) - Operating system and container image management
|
|
- [composefs](https://github.com/containers/composefs) - Efficient read-only filesystem for containers
|