first commit
This commit is contained in:
commit
f8dbd22c4f
5 changed files with 1921 additions and 0 deletions
215
README.md
Normal file
215
README.md
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue