bootc-docs/image/bootc-image-technical-guide.md

bootc image - Technical Guide

Overview

bootc image is a command for managing container images in the bootc storage system. It provides operations for listing, copying, and managing container images that are distinct from the standard podman image storage. The command operates on bootc's own container storage and provides integration with the broader container ecosystem.

Purpose

The image command serves several critical functions:

1. Image Listing: List images stored in bootc storage
2. Image Copying: Copy images between storage systems
3. Storage Management: Manage bootc's container storage
4. Podman Integration: Provide wrapper commands for podman operations
5. Image Discovery: Discover and manage host and logical images

Command Syntax

bootc image <COMMAND> [OPTIONS...]

Available Commands

Command	Description	Purpose
list	List fetched images stored in bootc storage	Display available images
copy-to-storage	Copy image from bootc storage to containers-storage	Export images
pull-from-default-storage	Copy image from default containers-storage to bootc storage	Import images
cmd	Wrapper for selected podman image subcommands	Podman integration

Architecture Overview

1. Image Command Structure

pub(crate) enum ImageOpts {
    List {
        list_type: ImageListType,
        list_format: ImageListFormat,
    },
    CopyToStorage {
        source: Option<String>,
        target: Option<String>,
    },
    PullFromDefaultStorage {
        image: String,
    },
    Cmd(ImageCmdOpts),
}

2. Image List Types

pub(crate) enum ImageListType {
    All,      // List all images
    Logical,  // List only logically bound images
    Host,     // List only host images
}

3. Image List Formats

pub(crate) enum ImageListFormat {
    Table,    // Human readable table format
    Json,     // JSON format
}

Image Listing

1. List Command

# List all images
bootc image list

# List with specific type
bootc image list --type=host

# List in JSON format
bootc image list --format=json

2. Image Types

Host Images

• Source: Images stored in OSTree repository
• Location: /sysroot/ostree/repo
• Purpose: Images used by bootc deployments
• Management: Managed by bootc upgrade/switch

Logical Images

• Source: Images referenced by deployments
• Location: Bound image references
• Purpose: Images that can be deployed
• Management: Referenced but not necessarily stored locally

3. List Implementation

pub(crate) async fn list_images(list_type: ImageListType) -> Result<Vec<ImageOutput>> {
    let rootfs = cap_std::fs::Dir::open_ambient_dir("/", cap_std::ambient_authority())?;
    let sysroot = if ostree_booted()? {
        Some(crate::cli::get_storage().await?)
    } else {
        None
    };

    Ok(match (list_type, sysroot) {
        (ImageListType::All, None) => list_logical_images(&rootfs)?,
        (ImageListType::All, Some(sysroot)) => list_host_images(&sysroot)?
            .into_iter()
            .chain(list_logical_images(&rootfs)?)
            .collect(),
        (ImageListType::Logical, _) => list_logical_images(&rootfs)?,
        (ImageListType::Host, None) => {
            bail!("Listing host images requires a booted bootc system")
        }
        (ImageListType::Host, Some(sysroot)) => list_host_images(&sysroot)?,
    })
}

Image Copying

1. Copy to Storage

# Copy current booted image to containers-storage
bootc image copy-to-storage

# Copy specific image to containers-storage
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0

# Copy to specific target
bootc image copy-to-storage --target=localhost/myimage:latest

Purpose: Export images from bootc storage to standard container storage Use Cases:

• Making images available to podman
• Sharing images with other tools
• Backup and migration

2. Pull from Default Storage

# Pull image from default containers-storage
bootc image pull-from-default-storage quay.io/myorg/debian-bootc:v2.0

Purpose: Import images from standard container storage to bootc storage Use Cases:

• Importing images built with podman
• Migrating images from other systems
• Testing with locally built images

3. Copy Implementation

pub(crate) async fn push_entrypoint(
    source: Option<&str>,
    target: Option<&str>,
) -> Result<()> {
    let sysroot = get_storage().await?;
    let imgstore = sysroot.get_ensure_imgstore()?;
    
    let source = source.unwrap_or_else(|| {
        // Get current booted image
        get_current_booted_image(&sysroot)
    });
    
    let target = target.unwrap_or(IMAGE_DEFAULT);
    
    // Copy image from bootc storage to containers-storage
    imgstore.copy_to_containers_storage(&source, &target).await?;
    
    Ok(())
}

Podman Integration

1. Command Wrapper

# List images using podman
bootc image cmd list

# Build image using podman
bootc image cmd build -t myimage:latest .

# Pull image using podman
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0

# Push image using podman
bootc image cmd push myimage:latest

2. Supported Commands

Command	Description	Podman Equivalent
list	List images	podman image list
build	Build image	podman image build
pull	Pull image	podman image pull
push	Push image	podman image push

3. Command Implementation

pub(crate) async fn imgcmd_entrypoint(
    imgstore: &CStorage,
    cmd: &str,
    args: &[OsString],
) -> Result<()> {
    let mut cmd = imgstore.new_image_cmd()?;
    cmd.arg(cmd);
    cmd.args(args);
    
    let status = cmd.status()?;
    if !status.success() {
        std::process::exit(status.code().unwrap_or(1));
    }
    
    Ok(())
}

Storage Management

1. Bootc Storage

Location: /var/lib/bootc/containers/ Purpose: Bootc's dedicated container storage Features:

• Isolated from system podman storage
• Optimized for bootc operations
• Integrated with OSTree

2. Storage Operations

List Images

pub(crate) async fn list_images(&self) -> Result<Vec<ImageListEntry>> {
    let mut cmd = self.new_image_cmd()?;
    cmd.args(["list", "--format=json"]);
    cmd.stdin(Stdio::null());
    
    let mut stdout = tempfile::tempfile()?;
    cmd.stdout(stdout.try_clone()?);
    
    let status = cmd.status()?;
    if !status.success() {
        // Handle error
    }
    
    // Parse JSON output
    stdout.rewind()?;
    let images: Vec<ImageListEntry> = serde_json::from_reader(stdout)?;
    Ok(images)
}

Check Image Exists

pub(crate) async fn exists(&self, image: &str) -> Result<bool> {
    let mut cmd = AsyncCommand::from(self.new_image_cmd()?);
    cmd.args(["exists", image]);
    Ok(cmd.status().await?.success())
}

Pull Image

pub(crate) async fn pull(&self, image: &str, mode: PullMode) -> Result<bool> {
    match mode {
        PullMode::IfNotExists => {
            if self.exists(image).await? {
                return Ok(false);
            }
        }
        PullMode::Always => {}
    };
    
    let mut cmd = self.new_image_cmd()?;
    cmd.args(["pull", image]);
    
    let status = cmd.status()?;
    Ok(status.success())
}

Image Types and Sources

1. Host Images

Definition: Images stored in the OSTree repository Location: /sysroot/ostree/repo Management: Managed by bootc operations Use Cases: Deployed images, system images

fn list_host_images(sysroot: &crate::store::Storage) -> Result<Vec<ImageOutput>> {
    let ostree = sysroot.get_ostree()?;
    let repo = ostree.repo();
    let images = ostree_ext::container::store::list_images(&repo)?;
    
    Ok(images
        .into_iter()
        .map(|img| ImageOutput {
            image_type: ImageListTypeColumn::Host,
            image: img,
        })
        .collect())
}

2. Logical Images

Definition: Images referenced by deployments but not necessarily stored Location: Bound image references Management: Referenced by deployment configurations Use Cases: Available for deployment, referenced images

fn list_logical_images(rootfs: &Dir) -> Result<Vec<ImageOutput>> {
    let bound_images = query_bound_images(rootfs)?;
    
    Ok(bound_images
        .into_iter()
        .map(|img| ImageOutput {
            image_type: ImageListTypeColumn::Logical,
            image: img.image,
        })
        .collect())
}

Image Operations

1. Image Copying Process

pub(crate) async fn copy_to_containers_storage(
    &self,
    source: &str,
    target: &str,
) -> Result<()> {
    // 1. Verify source image exists
    if !self.exists(source).await? {
        bail!("Source image not found: {}", source);
    }
    
    // 2. Create target storage if needed
    self.ensure_storage_exists()?;
    
    // 3. Copy image using podman
    let mut cmd = self.new_image_cmd()?;
    cmd.args(["tag", source, target]);
    
    let status = cmd.status()?;
    if !status.success() {
        bail!("Failed to copy image: {}", source);
    }
    
    Ok(())
}

2. Image Pulling Process

pub(crate) async fn pull_from_host_storage(&self, image: &str) -> Result<()> {
    let mut cmd = Command::new("podman");
    cmd.stdin(Stdio::null());
    cmd.stdout(Stdio::null());
    
    // Set up storage roots
    let temp_runroot = TempDir::new(cap_std::ambient_authority())?;
    bind_storage_roots(&mut cmd, &self.storage_root, &temp_runroot)?;
    
    // Copy from host storage to bootc storage
    let storage_dest = &format!(
        "containers-storage:[overlay@{}+/proc/self/fd/{}]",
        STORAGE_ALIAS_DIR, STORAGE_RUN_FD
    );
    
    cmd.args(["tag", image, storage_dest]);
    
    let status = cmd.status()?;
    if !status.success() {
        bail!("Failed to pull image from host storage: {}", image);
    }
    
    Ok(())
}

Error Handling

1. Common Errors

Image Not Found

Error: Source image not found: quay.io/myorg/debian-bootc:v2.0

Solution: Verify image exists in bootc storage

bootc image list

Storage Not Available

Error: Bootc storage not available

Solution: Check storage initialization

bootc status

Permission Denied

Error: Permission denied

Solution: Run with appropriate privileges

sudo bootc image list

2. Error Recovery

Storage Corruption

# Reinitialize storage
bootc image cmd prune -a

# Rebuild storage
bootc image cmd build --no-cache

Image Corruption

# Remove corrupted image
bootc image cmd rmi corrupted-image

# Re-pull image
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0

Integration Patterns

1. Development Workflow

# Build image with podman
bootc image cmd build -t myimage:latest .

# Copy to bootc storage
bootc image copy-to-storage --source=myimage:latest

# Deploy image
bootc switch myimage:latest

2. Production Workflow

# Pull production image
bootc image cmd pull quay.io/myorg/debian-bootc:v2.0

# Copy to bootc storage
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0

# Deploy image
bootc switch quay.io/myorg/debian-bootc:v2.0

3. Backup and Migration

# List all images
bootc image list --format=json > images.json

# Copy images to standard storage
bootc image copy-to-storage --source=image1
bootc image copy-to-storage --source=image2

# Export with podman
podman save -o backup.tar localhost/bootc

Performance Considerations

1. Storage Efficiency

Image Deduplication: Bootc storage uses OSTree for efficient storage Layer Sharing: Common layers are shared between images Compression: Images are compressed for storage efficiency

2. Operation Performance

Parallel Operations: Multiple operations can run in parallel Caching: Frequently accessed images are cached Lazy Loading: Images are loaded on demand

3. Storage Management

Cleanup: Regular cleanup of unused images Garbage Collection: Automatic garbage collection of unused layers Space Monitoring: Monitor storage usage

Security Considerations

1. Image Verification

Signature Verification: Images are verified using container signatures Integrity Checks: Image integrity is verified during operations Access Control: Proper access control for storage operations

2. Storage Isolation

Separate Storage: Bootc storage is isolated from system storage Permission Management: Proper permissions for storage access Audit Logging: Operations are logged for audit purposes

Troubleshooting

1. Common Issues

Images Not Listed

# Check storage status
bootc status

# Verify storage initialization
ls -la /var/lib/bootc/containers/

Copy Operations Fail

# Check source image
bootc image list

# Check target storage
podman images

Podman Commands Fail

# Check podman installation
podman --version

# Check storage configuration
podman info

2. Debug Commands

# Enable debug logging
RUST_LOG=debug bootc image list

# Check storage details
bootc image cmd list --format=json

# Verify image integrity
bootc image cmd inspect image-name

Best Practices

1. Image Management

• Regular Cleanup: Clean up unused images regularly
• Image Tagging: Use meaningful tags for images
• Version Control: Keep track of image versions
• Backup Strategy: Implement backup strategy for important images

2. Storage Management

• Monitor Usage: Monitor storage usage regularly
• Optimize Storage: Use efficient storage configurations
• Cleanup Policies: Implement cleanup policies
• Backup Storage: Backup storage configurations

3. Integration

• Automation: Automate image operations where possible
• Monitoring: Monitor image operations
• Documentation: Document image management procedures
• Testing: Test image operations regularly

Future Enhancements

1. Planned Features

• Image Signing: Enhanced image signing capabilities
• Image Encryption: Image encryption support
• Advanced Filtering: More advanced image filtering
• Bulk Operations: Bulk image operations

2. Integration Improvements

• Registry Integration: Better registry integration
• CI/CD Integration: Enhanced CI/CD integration
• Monitoring Integration: Better monitoring integration
• API Support: REST API for image operations

This technical guide provides comprehensive understanding of the bootc image system's architecture, implementation, and usage patterns.