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

Fedora Kickstart Approach for Bootc Installation

Overview

Fedora uses a sophisticated kickstart-based approach for bootc installation that is fundamentally different from traditional package-based installations. The key insight is that bootc installations are container-first, not package-first.

Key Technical Concepts

1. The ostreecontainer Directive

The ostreecontainer kickstart directive is the core mechanism for bootc installation:

ostreecontainer --url quay.io/centos-bootc/centos-bootc:stream9

Key characteristics:

• No %packages section - the entire system is container-based
• Registry URL specifies the container image to install
• Authentication handled separately via registry configuration
• Partitioning still required, but no package management

1.1. Complete ostreecontainer Parameters

Based on analysis of the Fedora COSMIC Atomic ISO, the full parameter set is:

ostreecontainer --url="quay.io/exampleos/foo:latest" \
                --stateroot="default" \
                --remote="default" \
                --transport="registry" \
                --no-signature-verification

Parameter details:

• --url (required): Container image URL (e.g., quay.io/exampleos/foo:latest)
• --stateroot: Name for the state directory (default: default)
• --remote: Name of the OSTree remote (default: same as stateroot)
• --transport: Transport method (default: registry)
• --no-signature-verification: Disable signature verification (optional)

1.2. Implementation Details

Python-based implementation in PyKickstart:

• File: /usr/lib/python3.13/site-packages/pykickstart/commands/ostreecontainer.py
• Class: F38_OSTreeContainer (available in Fedora 38+)
• Conflicts: Cannot be used with ostreesetup directive
• Experimental: Marked as experimental in documentation

2. Kickstart Infrastructure

Based on analysis of the Fedora COSMIC Atomic ISO, the kickstart system includes:

2.1. Dracut Hooks

• 50-kickstart-genrules.sh: Generates udev rules for fetching kickstarts
• 11-fetch-kickstart-net.sh: Fetches kickstart files from network
• 26-parse-anaconda-kickstart.sh: Handles kickstart command line parsing

2.2. Anaconda Integration

• PyKickstart library: Python-based kickstart parsing
• Command handlers: Including ostreecontainer and ostreesetup
• Version support: Fedora 38+ includes ostreecontainer support

2.3. Kickstart Fetching Methods

• Network: HTTP, HTTPS, FTP, NFS
• Local: CDROM, hard disk
• Multiple URLs: Support for fallback kickstart locations

3. Registry Authentication

Fedora handles registry access through kickstart %pre sections:

Basic Authentication

%pre
mkdir -p /etc/ostree
cat > /etc/ostree/auth.json << 'EOF'
{
        "auths": {
                "quay.io": {
                        "auth": "<your secret here>"
                }
        }
}
EOF
%end

Insecure Registry Support

%pre
mkdir -p /etc/containers/registries.conf.d/
cat > /etc/containers/registries.conf.d/local-registry.conf << 'EOF'
[[registry]]
location="[IP_Address]:5000"
insecure=true
EOF
%end

4. Complete Kickstart Example

# Basic setup
text
network --bootproto=dhcp --device=link --activate

# Basic partitioning
clearpart --all --initlabel --disklabel=gpt
reqpart --add-boot
part / --grow --fstype xfs

# Container installation - NO %packages section!
ostreecontainer --url quay.io/centos-bootc/centos-bootc:stream9

# System configuration
firewall --disabled
services --enabled=sshd
rootpw --iscrypted locked
sshkey --username root "<your key here>"
reboot

Installation Methods Analysis

Fedora COSMIC Atomic vs Fedora CoreOS

Key Discovery: Different Fedora variants use different approaches:

Variant	Configuration System	Container Support	Use Case
Fedora COSMIC Atomic	Kickstart + ostreecontainer	Native	Traditional server/workstation
Fedora CoreOS	Ignition	Native	Container-first, immutable
Fedora Server/Workstation	Kickstart + ostreecontainer	Native	Traditional Linux

Three Installation Methods

1. Stock Anaconda ISO/PXE (Network-based)

• Uses standard Fedora installer with custom kickstart
• Requires network access during installation
• Container image fetched from registry
• Advantage: Uses existing installer infrastructure
• Disadvantage: Requires network connectivity

2. Custom Installer ISO (bootc-image-builder generated)

• Uses anaconda-iso type in bootc-image-builder
• Container image embedded in the ISO
• No network access needed during installation
• Advantage: Air-gapped installation possible
• Disadvantage: Larger ISO size

3. Direct Container Installation (bootc install)

• Uses bootc install to-disk or bootc install to-filesystem
• Container image is the "source of truth"
• Can be run from any Linux environment
• Advantage: Most flexible, container-native
• Disadvantage: Requires existing Linux environment

Technical Implementation Details

Container Runtime Requirements

• Podman or containerd must be available in installer environment
• Registry access configured via /etc/containers/registries.conf.d/
• Authentication handled via /etc/ostree/auth.json

Partitioning Strategy

• GPT partition table required
• Boot partition for EFI/BIOS boot
• Root partition for container installation
• No package management - all content from container

Network Configuration

• DHCP for basic network access
• Registry connectivity for container pull
• Optional: Static IP configuration

Implications for Debian Implementation

Calamares Integration

1. Custom module needed to handle ostreecontainer equivalent
2. Registry authentication must be implemented
3. Container runtime must be available
4. Partitioning handled before container installation

debian-installer Integration

1. Preseed extension needed for container support
2. Container runtime added to installer environment
3. Registry configuration in installer
4. Major architectural change from package-based to container-based

Key Differences from Traditional Installation

• No package management during installation
• Container-first approach
• Registry authentication required
• Partitioning still needed but simpler
• System configuration via kickstart/preseed

Registry Handling Patterns

Authentication Methods

1. Username/password via auth.json
2. Token-based authentication
3. Certificate-based authentication
4. Insecure registry support for development

Configuration Locations

• /etc/ostree/auth.json - authentication credentials
• /etc/containers/registries.conf.d/ - registry configuration
• /etc/pki/ca-trust/source/anchors/ - certificate authorities

Security Considerations

Registry Security

• TLS verification by default
• Insecure registries only for development
• Certificate management for custom CAs
• Authentication required for private registries

Container Security

• Image verification via signatures
• Content trust mechanisms
• Runtime security via container runtime

Advantages of This Approach

1. Container-native - aligns with modern deployment patterns
2. Atomic updates - via ostree/bootc upgrade
3. Immutable systems - reduces configuration drift
4. Registry integration - leverages existing container infrastructure
5. Air-gapped support - via embedded ISO approach

Challenges for Debian

1. Preseed lacks ostreecontainer equivalent - major technical hurdle
2. Container runtime not standard in debian-installer
3. Registry authentication not built into installer
4. Architectural shift from package-based to container-based
5. Tooling gaps - need custom modules/extensions

Real-World Implementation Analysis

Fedora COSMIC Atomic ISO Structure

Fedora-COSMIC-Atomic-ostree-x86_64-42-1.1.iso
├── boot/grub2/grub.cfg          # BIOS boot configuration
├── EFI/BOOT/grub.cfg            # EFI boot configuration
├── images/
│   ├── install.img              # Anaconda installer image
│   ├── pxeboot/
│   │   ├── initrd.img           # XZ-compressed initrd
│   │   └── vmlinuz              # Kernel
│   └── eltorito.img             # El Torito boot image
└── Fedora-Legal-README.txt      # Legal information

Kickstart Processing Pipeline

1. Boot: Kernel loads with kickstart parameters
2. Dracut: Hooks process kickstart fetching
3. Anaconda: PyKickstart parses configuration
4. Installation: ostreecontainer directive triggers container installation
5. Configuration: System setup via kickstart commands

Key Implementation Files

• ostreecontainer.py: Core directive implementation
• f42.py: Fedora 42 handler with ostreecontainer support
• Dracut hooks: Network and disk kickstart fetching
• Anaconda modules: Integration with installer

Next Steps for Implementation

1. Study ostreecontainer implementation in Anaconda
2. Design Calamares module for container installation
3. Extend preseed for container support
4. Implement registry handling in both approaches
5. Test container installation workflows
6. Choose approach: Kickstart (traditional) vs Ignition (modern)

References

• Fedora bootc bare metal installation guide
• Kickstart ostreecontainer documentation
• bootc-image-builder documentation
• bib-kickstart-demo repository