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
31 KiB
31 KiB
bootc edit - Process Flowchart
Overview
This document provides a visual representation of the bootc edit process flow, showing the decision points, operations, and state transitions involved in editing bootc host specifications.
Main Process Flow
┌─────────────────────────────────────────────────────────────────┐
│ bootc edit │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Initialize System │
│ • Get storage interface │
│ • Get OSTree repository │
│ • Get current system status │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Load Configuration │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Filename │ │ Interactive Mode │ │
│ │ Provided? │ │ │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Load from File │ │ • Create temporary file │ │
│ │ • Open file │ │ • Write current config to temp │ │
│ │ • Parse YAML │ │ • Spawn editor with temp file │ │
│ │ • Validate │ │ • Wait for editor completion │ │
│ └─────────────────┘ │ • Read modified config │ │
│ │ └─────────────────────────────────────┘ │
│ │ │ │
│ └───────────┬───────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Parse and Validate YAML │ │
│ │ • Deserialize to Host structure │ │
│ │ • Validate schema │ │
│ │ • Check required fields │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Compare Configurations │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ new_host.spec == host.spec? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Print: ││ │ │ Validate Transition ││ │
│ │ │ "Edit ││ │ │ • Check image changes ││ │
│ │ │ cancelled, ││ │ │ • Validate boot order ││ │
│ │ │ no changes ││ │ │ • Verify system state ││ │
│ │ │ made" ││ │ └─────────────────────────────────┘│ │
│ │ └─────────────┘│ │ │ │ │
│ │ │ │ ▼ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Return ││ │ │ Create RequiredHostSpec ││ │
│ │ │ Success ││ │ │ • Extract image reference ││ │
│ │ └─────────────┘│ │ │ • Validate required fields ││ │
│ └─────────────────┘ │ └─────────────────────────────────┘│ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Determine Change Type │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ boot_order changed? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Execute ││ │ │ Image Change Process ││ │
│ │ │ Rollback ││ │ │ ││ │
│ │ │ • Call ││ │ │ ┌─────────────────────────────┐││ │
│ │ │ rollback ││ │ │ │ Pull New Image │││ │
│ │ │ • Update ││ │ │ │ • Authenticate with │││ │
│ │ │ boot ││ │ │ │ registry │││ │
│ │ │ order ││ │ │ │ • Download image layers │││ │
│ │ └─────────────┘│ │ │ │ • Convert to OSTree │││ │
│ │ │ │ │ │ • Validate image │││ │
│ │ ┌─────────────┐│ │ │ └─────────────────────────────┘││ │
│ │ │ Return ││ │ │ │ ││ │
│ │ │ Success ││ │ │ ▼ ││ │
│ │ └─────────────┘│ │ │ ┌─────────────────────────────┐││ │
│ └─────────────────┘ │ │ │ Stage New Deployment │││ │
│ │ │ │ • Create new deployment │││ │
│ │ │ │ • Configure bootloader │││ │
│ │ │ │ • Update system status │││ │
│ │ │ │ • Preserve /etc and /var │││ │
│ │ │ └─────────────────────────────┘││ │
│ │ └─────────────────────────────────┘│ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Update System Status │
│ │
│ • Update system modification time │
│ • Refresh system status │
│ • Update deployment information │
│ • Log configuration changes │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Success │
│ │
│ • Configuration applied successfully │
│ • System ready for next boot │
│ • Changes staged for application │
└─────────────────────────────────────────────────────────────────┘
Editor Integration Flow
┌─────────────────────────────────────────────────────────────────┐
│ Editor Selection │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Check Environment │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ $EDITOR set? │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Yes │ │ No │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Use $EDITOR ││ │ │ Check Backup Editors ││ │
│ │ │ • Split ││ │ │ • nano ││ │
│ │ │ command ││ │ │ • vim ││ │
│ │ │ • Extract ││ │ │ • vi ││ │
│ │ │ program ││ │ │ • Check /usr/bin/ ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ └─────────────────┘ │ │ │ │
│ │ │ ▼ │ │
│ │ │ ┌─────────────────────────────────┐│ │
│ │ │ │ Editor Found? ││ │
│ │ │ └─────────────────────────────────┘│ │
│ │ │ │ │ │
│ │ │ ▼ │ │
│ │ │ ┌─────────────────┐ ┌─────────┐│ │
│ │ │ │ Yes │ │ No ││ │
│ │ │ │ │ │ ││ │
│ │ │ │ ┌─────────────┐│ │ ┌─────┐││ │
│ │ │ │ │ Use Backup ││ │ │Error│││ │
│ │ │ │ │ Editor ││ │ │ │││ │
│ │ │ │ └─────────────┘│ │ └─────┘││ │
│ │ │ └─────────────────┘ └─────────┘│ │
│ │ └─────────────────────────────────────┘ │
│ │ │ │
│ └───────────┬───────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Launch Editor │ │
│ │ • Create command with editor program │ │
│ │ • Add editor arguments │ │
│ │ • Add temporary file path │ │
│ │ • Execute with lifecycle binding │ │
│ │ • Wait for completion │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Error Handling Flow
┌─────────────────────────────────────────────────────────────────┐
│ Error Detection │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Classification │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Editor │ │ Configuration │ │ System │ │
│ │ Errors │ │ Errors │ │ Errors │ │
│ │ │ │ │ │ │ │
│ │ • $EDITOR │ │ • Invalid YAML │ │ • Not bootc │ │
│ │ unset │ │ • Schema │ │ compatible │ │
│ │ • Editor not │ │ validation │ │ • Image not │ │
│ │ found │ │ • Missing │ │ found │ │
│ │ • Editor │ │ fields │ │ • Registry │ │
│ │ execution │ │ • Invalid │ │ error │ │
│ │ failed │ │ values │ │ • OSTree error │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Response │
│ │
│ • Display error message │
│ • Provide context information │
│ • Suggest remediation steps │
│ • Return appropriate exit code │
│ • Clean up temporary files │
└─────────────────────────────────────────────────────────────────┘
State Transitions
┌─────────────────────────────────────────────────────────────────┐
│ System States │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Current State │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Normal │ │ Rollback │ │
│ │ Boot │ │ Queued │ │
│ │ │ │ │ │
│ │ • Image: v1.0 │ │ • Image: v1.0 │ │
│ │ • Boot: normal │ │ • Boot: rollback │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Edit 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 │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Configuration Validation Flow
┌─────────────────────────────────────────────────────────────────┐
│ Configuration Input │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ YAML Parsing │
│ │
│ • Parse YAML syntax │
│ • Deserialize to Host structure │
│ • Validate required fields │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Schema Validation │
│ │
│ • Validate Host structure │
│ • Check HostSpec fields │
│ • Verify ImageReference format │
│ • Validate BootOrder values │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Transition Validation │
│ │
│ • Compare with current configuration │
│ • Check for valid state transitions │
│ • Verify image accessibility │
│ • Validate boot order changes │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Validation Result │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ Valid │ │ Invalid │ │
│ │ │ │ │ │
│ │ • Proceed with │ │ • Display error message │ │
│ │ changes │ │ • Provide context │ │
│ │ • Apply │ │ • Suggest fixes │ │
│ │ configuration │ │ • Return error │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
This flowchart provides a comprehensive visual representation of the bootc edit process, showing all decision points, operations, and state transitions involved in editing bootc host specifications.