bootc-docs/image/bootc-image-flowchart.md

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.