# bootc image - Process Flowchart ## Overview This document provides a visual representation of the `bootc image` process flow, showing the decision points, operations, and data structures involved in managing container images in the bootc storage system. ## Main Process Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ bootc image │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Parse Command Arguments │ │ │ │ • Parse subcommand (list, copy-to-storage, etc.) │ │ • Parse command-specific options │ │ • Validate arguments │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Route to Subcommand │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Subcommand Type? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ List │ │ Copy-to-Storage│ │ Pull-from-Default│ │ │ │ │ │ │ │ Storage │ │ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ │ │ │ List Images ││ │ │ Copy Image ││ │ │ Pull Image ││ │ │ │ │ • Host ││ │ │ • Source ││ │ │ • From Host ││ │ │ │ │ • Logical ││ │ │ • Target ││ │ │ • To Bootc ││ │ │ │ │ • All ││ │ │ • Export ││ │ │ • Import ││ │ │ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Cmd Wrapper │ │ │ │ │ │ │ │ • List: podman image list │ │ │ │ • Build: podman image build │ │ │ │ • Pull: podman image pull │ │ │ │ • Push: podman image push │ │ │ └─────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • Image operation completed successfully │ │ • Results displayed or returned │ │ • Storage updated if applicable │ └─────────────────────────────────────────────────────────────────┘ ``` ## Image Listing Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Image Listing Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Determine List Type │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ List Type? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ All │ │ Logical │ │ Host │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ │ │ │ List Both ││ │ │ List Only ││ │ │ List Only ││ │ │ │ │ • Host ││ │ │ Logical ││ │ │ Host ││ │ │ │ │ • Logical ││ │ │ Images ││ │ │ Images ││ │ │ │ │ Images ││ │ │ • Bound ││ │ │ • OSTree ││ │ │ │ │ Combined ││ │ │ Images ││ │ │ Repo ││ │ │ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Check System Status │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ System Booted? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────────────────────────┐ │ │ │ Yes │ │ No │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │ │ │ │ Get Storage ││ │ │ Use Root Filesystem ││ │ │ │ │ • OSTree ││ │ │ ││ │ │ │ │ Repo ││ │ │ • Query Bound Images ││ │ │ │ │ • Images ││ │ │ • List Logical Images ││ │ │ │ └─────────────┘│ │ └─────────────────────────────────┘│ │ │ └─────────────────┘ └─────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Query Images │ │ │ │ • Query OSTree repository for host images │ │ • Query bound images for logical images │ │ • Combine results based on list type │ │ • Format results according to output format │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Format Output │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Output Format? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────────────────────────┐ │ │ │ Table │ │ JSON │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │ │ │ │ Format as ││ │ │ Format as JSON ││ │ │ │ │ Table ││ │ │ ││ │ │ │ │ • Headers ││ │ │ • Pretty Print ││ │ │ │ │ • Rows ││ │ │ • Structured Data ││ │ │ │ │ • Columns ││ │ │ • Machine Readable ││ │ │ │ └─────────────┘│ │ └─────────────────────────────────┘│ │ │ └─────────────────┘ └─────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## Image Copying Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Image Copying Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Determine Source and Target │ │ │ │ • Source: Use provided source or current booted image │ │ • Target: Use provided target or default (localhost/bootc) │ │ • Validate source and target formats │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Verify Source Image │ │ │ │ • Check if source image exists in bootc storage │ │ • Verify image integrity │ │ • Get image metadata │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Check Target Storage │ │ │ │ • Verify target storage is available │ │ • Check if target already exists │ │ • Prepare target storage if needed │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Copy Image │ │ │ │ • Use podman to copy image │ │ • Tag image with target name │ │ • Verify copy operation success │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Verify Copy │ │ │ │ • Check if target image exists │ │ • Verify image integrity │ │ • Update metadata │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • Image successfully copied │ │ • Target image available in containers-storage │ │ • Image ready for use with podman │ └─────────────────────────────────────────────────────────────────┘ ``` ## Image Pulling Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Image Pulling Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Validate Source Image │ │ │ │ • Check if source image exists in default storage │ │ • Verify image format and integrity │ │ • Get image metadata │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Prepare Bootc Storage │ │ │ │ • Ensure bootc storage is initialized │ │ • Create storage directories if needed │ │ • Set up storage configuration │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Copy from Host Storage │ │ │ │ • Use podman to copy from default storage │ │ • Set up storage roots and bindings │ │ • Copy image to bootc storage │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Verify Import │ │ │ │ • Check if image exists in bootc storage │ │ │ • Verify image integrity │ │ │ • Update metadata │ │ │ • Register with OSTree if needed │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • Image successfully imported │ │ • Image available in bootc storage │ │ • Image ready for deployment │ └─────────────────────────────────────────────────────────────────┘ ``` ## Podman Command Wrapper Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Podman Command Wrapper │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Parse Command │ │ │ │ • Determine podman subcommand (list, build, pull, push) │ │ • Parse command arguments │ │ • Validate command syntax │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Prepare Podman Command │ │ │ │ • Create podman command instance │ │ • Set up storage roots and bindings │ │ • Configure command arguments │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Execute Command │ │ │ │ • Run podman command with bootc storage │ │ • Capture output and error streams │ │ • Monitor command execution │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Handle Results │ │ │ │ • Check command exit status │ │ • Process output if needed │ │ • Handle errors appropriately │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Return Results │ │ │ │ • Return success or failure status │ │ • Pass through output to user │ │ • Update storage metadata if needed │ └─────────────────────────────────────────────────────────────────┘ ``` ## Storage Management Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Storage Management │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Check Storage Status │ │ │ │ • Verify bootc storage is initialized │ │ • Check storage configuration │ │ • Validate storage permissions │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Initialize Storage if Needed │ │ │ │ • Create storage directories │ │ • Set up storage configuration │ │ • Initialize storage metadata │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Perform Storage Operations │ │ │ │ • List images in storage │ │ • Check image existence │ │ • Pull/push images as needed │ │ • Update storage metadata │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Cleanup and Maintenance │ │ │ │ • Clean up temporary files │ │ • Update storage statistics │ │ • Perform garbage collection if needed │ └─────────────────────────────────────────────────────────────────┘ ``` ## Error Handling Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Error Detection │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Error Classification │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Image │ │ Storage │ │ Podman │ │ │ │ Errors │ │ Errors │ │ Errors │ │ │ │ │ │ │ │ │ │ │ │ • Image not │ │ • Storage not │ │ • Command │ │ │ │ found │ │ available │ │ failed │ │ │ │ • Invalid │ │ • Permission │ │ • Invalid │ │ │ │ format │ │ denied │ │ arguments │ │ │ │ • Corrupted │ │ • Full storage │ │ • Network │ │ │ │ image │ │ • Configuration │ │ error │ │ │ │ │ │ error │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Error Response │ │ │ │ • Display error message │ │ • Provide context information │ │ • Suggest remediation steps │ │ • Return appropriate exit code │ │ • Clean up any partial state │ └─────────────────────────────────────────────────────────────────┘ ``` ## State Transitions ``` ┌─────────────────────────────────────────────────────────────────┐ │ Storage States │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Initial State │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Uninitialized Storage │ │ │ │ │ │ │ │ • No storage directories │ │ │ │ • No configuration │ │ │ │ • No images available │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Initialize Storage │ │ │ │ │ │ │ │ • Create storage directories │ │ │ │ • Set up configuration │ │ │ │ • Initialize metadata │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Initialized Storage │ │ │ │ │ │ │ │ • Storage directories exist │ │ │ │ • Configuration available │ │ │ │ • Ready for operations │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Image Operations │ │ │ │ │ │ │ │ • List images │ │ │ │ • Copy images │ │ │ │ • Pull images │ │ │ │ • Manage storage │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Active Storage with Images │ │ │ │ │ │ │ │ • Images stored and available │ │ │ │ • Operations working │ │ │ │ • Metadata up to date │ │ │ └─────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` This flowchart provides a comprehensive visual representation of the bootc image process, showing all decision points, operations, and state transitions involved in managing container images in the bootc storage system.