526f1c1afd
- Complete documentation for all bootc commands and subcommands - Debian-specific adaptations and workarounds - Manual installation methods to bypass bootc reliability issues - Technical guides with Rust source code analysis - Flowcharts and external command references - Hidden command documentation (bootc internals, state, etc.) - Composefs integration analysis - Base image creation guides (with and without bootc binary) - Management scripts and automation - Comprehensive troubleshooting and examples
456 lines
42 KiB
Markdown
456 lines
42 KiB
Markdown
# 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.
|