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
381 lines
37 KiB
Markdown
381 lines
37 KiB
Markdown
# 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.
|