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
37 KiB
37 KiB
bootc switch - Process Flowchart
Overview
This document provides a visual representation of the bootc switch process flow, showing the decision points, operations, and state transitions involved in switching container image references.
Main Process Flow
┌─────────────────────────────────────────────────────────────────┐
│ bootc switch │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Parse Target Image │
│ │
│ • Parse transport type (registry, oci, oci-archive, etc.) │
│ • Create ImageReference structure │
│ • Configure signature verification policy │
│ • Convert to OSTreeImageReference │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Check Operation Mode │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ In-Place Mutation? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ In-Place ││ │ │ Normal Switch Process ││ │
│ │ │ Switch ││ │ │ ││ │
│ │ │ • Find ││ │ │ • Get system storage ││ │
│ │ │ deployment││ │ │ • Get OSTree repository ││ │
│ │ │ • Update ││ │ │ • Get current system status ││ │
│ │ │ origin ││ │ │ • Create new specification ││ │
│ │ │ • Log ││ │ │ • Check for changes ││ │
│ │ │ operation ││ │ │ • Pull and stage image ││ │
│ │ └─────────────┘│ │ │ • Update system status ││ │
│ │ │ │ │ • Handle soft reboot ││ │
│ │ ┌─────────────┐│ │ │ • Apply changes if requested ││ │
│ │ │ Return ││ │ └─────────────────────────────────┘│ │
│ │ │ Success ││ │ │ │
│ │ └─────────────┘│ │ │ │
│ └─────────────────┘ │ │ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Get System Status │
│ │
│ • Get storage interface │
│ • Get OSTree repository │
│ • Get current system status │
│ • Get booted deployment information │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Create New Specification │
│ │
│ • Clone current host specification │
│ • Update image reference to target │
│ • Preserve other settings (boot order, etc.) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Check for Changes │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ new_spec == host.spec? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Print: ││ │ │ Log Switch Operation ││ │
│ │ │ "Image ││ │ │ • Log old image reference ││ │
│ │ │ specification││ │ │ • Log new image reference ││ │
│ │ │ is ││ │ │ • Log transport type ││ │
│ │ │ unchanged" ││ │ │ • Log to systemd journal ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ │ │ │ │ │ │
│ │ ┌─────────────┐│ │ ▼ │ │
│ │ │ Return ││ │ ┌─────────────────────────────────┐│ │
│ │ │ Success ││ │ │ Pull and Stage Image ││ │
│ │ └─────────────┘│ │ │ • Authenticate with registry ││ │
│ └─────────────────┘ │ │ • Download image layers ││ │
│ │ │ • Convert to OSTree format ││ │
│ │ │ • Validate image compatibility ││ │
│ │ │ • Stage new deployment ││ │
│ │ └─────────────────────────────────┘│ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Handle Image Retention │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ --retain specified? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Keep ││ │ │ Prune Previous Reference ││ │
│ │ │ Previous ││ │ │ • Get booted deployment origin ││ │
│ │ │ Image ││ │ │ • Parse OSTree reference ││ │
│ │ │ Reference ││ │ │ • Update OSTree reference ││ │
│ │ └─────────────┘│ │ │ • Free up disk space ││ │
│ └─────────────────┘ │ └─────────────────────────────────┘│ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Stage New Deployment │
│ │
│ • Create new deployment in OSTree │
│ • Configure bootloader for new deployment │
│ • Update system status │
│ • Preserve /etc and /var state │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Update System Status │
│ │
│ • Update system modification time │
│ • Refresh system status │
│ • Update deployment information │
│ • Log configuration changes │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Handle Soft Reboot │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ --soft-reboot specified? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Configure ││ │ │ Skip Soft Reboot ││ │
│ │ │ Soft Reboot ││ │ │ ││ │
│ │ │ • Check ││ │ │ • Continue to apply check ││ │
│ │ │ availability││ │ │ ││ │
│ │ │ • Configure ││ │ │ ││ │
│ │ │ if needed ││ │ │ ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Apply Changes │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ --apply specified? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Reboot ││ │ │ Changes Staged ││ │
│ │ │ System ││ │ │ ││ │
│ │ │ • Execute ││ │ │ • Changes ready for next boot ││ │
│ │ │ reboot ││ │ │ • No immediate action ││ │
│ │ │ • Apply ││ │ │ • User can reboot manually ││ │
│ │ │ changes ││ │ │ ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Image switch completed successfully │
│ • New image staged for next boot │
│ • System ready for reboot (if --apply) │
└─────────────────────────────────────────────────────────────────┘
In-Place Switch Flow
┌─────────────────────────────────────────────────────────────────┐
│ In-Place Switch │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Log Operation │
│ │
│ • Log to systemd journal with unique message ID │
│ • Include image reference and transport type │
│ • Mark as in-place switch operation │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Find Deployment Directory │
│ │
│ • Search for deployment directory in /sysroot/ostree/deploy │
│ • Locate current booted deployment │
│ • Validate deployment structure │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Update Origin File │
│ │
│ • Read current origin file │
│ • Parse origin configuration │
│ • Update image reference │
│ • Write updated origin file │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Extract Deployment ID │
│ │
│ • Parse deployment directory name │
│ • Extract deployment ID │
│ • Return deployment ID for logging │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • In-place switch completed │
│ │ • Deployment ID updated │
│ │ • Image reference changed │
│ │ • System ready for next boot │
└─────────────────────────────────────────────────────────────────┘
Error Handling Flow
┌─────────────────────────────────────────────────────────────────┐
│ Error Detection │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Classification │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Image │ │ System │ │ Network │ │
│ │ Errors │ │ Errors │ │ Errors │ │
│ │ │ │ │ │ │ │
│ │ • Invalid │ │ • Not bootc │ │ • Registry │ │
│ │ transport │ │ compatible │ │ connectivity │ │
│ │ • Image not │ │ • No deployment │ │ • Authentication│ │
│ │ found │ │ found │ │ failed │ │
│ │ • Signature │ │ • Invalid │ │ • Image pull │ │
│ │ verification │ │ state │ │ failed │ │
│ │ failed │ │ │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Response │
│ │
│ • Display error message │
│ • Provide context information │
│ • Suggest remediation steps │
│ • Return appropriate exit code │
│ • Clean up any partial state │
└─────────────────────────────────────────────────────────────────┘
State Transitions
┌─────────────────────────────────────────────────────────────────┐
│ System States │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Current State │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Image: v1.0 │ │ Image: v1.0 │ │
│ │ Boot: normal │ │ Boot: normal │ │
│ │ Staged: none │ │ Staged: v2.0 │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Switch Operation │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────────────────────┐ │ │
│ │ │ Image │ │ Boot Order │ │ │
│ │ │ Change │ │ Change │ │ │
│ │ │ │ │ │ │ │
│ │ │ • Pull new │ │ • Execute rollback │ │ │
│ │ │ image │ │ • Update boot order │ │ │
│ │ │ • Stage │ │ • Preserve state │ │ │
│ │ │ deployment │ │ │ │ │
│ │ └─────────────────┘ └─────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ New State │ │ New State │ │
│ │ │ │ │ │
│ │ • Image: v2.0 │ │ • Image: v1.0 │ │
│ │ • Boot: normal │ │ • Boot: normal │ │
│ │ • Staged: v2.0 │ │ • Rollback: queued │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Transport Type Flow
┌─────────────────────────────────────────────────────────────────┐
│ Transport Selection │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Parse Transport Type │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ --transport specified? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Use ││ │ │ Use Default (registry) ││ │
│ │ │ Specified ││ │ │ ││ │
│ │ │ Transport ││ │ │ • Set transport to 'registry' ││ │
│ │ │ • registry ││ │ │ • Use registry authentication ││ │
│ │ │ • oci ││ │ │ • Use HTTPS protocol ││ │
│ │ │ • oci- ││ │ │ ││ │
│ │ │ archive ││ │ │ ││ │
│ │ │ • containers││ │ │ ││ │
│ │ │ -storage ││ │ │ ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Create Image Reference │
│ │
│ • Create ImageReference structure │
│ • Set transport type │
│ │ • Set image name/tag │
│ │ • Configure signature verification │
│ │ • Convert to OSTreeImageReference │
└─────────────────────────────────────────────────────────────────┘
This flowchart provides a comprehensive visual representation of the bootc switch process, showing all decision points, operations, and state transitions involved in switching container image references.