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
321 lines
31 KiB
Markdown
321 lines
31 KiB
Markdown
# 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.
|