Initial commit: Comprehensive Debian bootc documentation
- 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
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
434
rollback/bootc-rollback-flowchart.md
Normal file
434
rollback/bootc-rollback-flowchart.md
Normal file
|
|
@ -0,0 +1,434 @@
|
|||
# bootc rollback - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc rollback` process flow, showing the decision points, operations, and state transitions involved in rolling back to a previous deployment.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc rollback │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize System │
|
||||
│ • Get storage interface │
|
||||
│ • Get OSTree repository │
|
||||
│ • Get current system status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Rollback Operation │
|
||||
│ │
|
||||
│ • Call deploy::rollback() function │
|
||||
│ • Handle rollback logic │
|
||||
│ • Update deployment order │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Handle Soft Reboot │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --soft-reboot specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Configure ││ │ │ Skip Soft Reboot ││ │
|
||||
│ │ │ Soft Reboot ││ │ │ ││ │
|
||||
│ │ │ • Check ││ │ │ • Continue to apply check ││ │
|
||||
│ │ │ capability││ │ │ ││ │
|
||||
│ │ │ • Prepare ││ │ │ ││ │
|
||||
│ │ │ 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 │
|
||||
│ │
|
||||
│ • Rollback completed successfully │
|
||||
│ • Deployment order updated │
|
||||
│ • System ready for next boot (if --apply) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Rollback Operation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Core Rollback Operation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get System Status │
|
||||
│ │
|
||||
│ • Get booted deployment │
|
||||
│ • Get all deployments │
|
||||
│ • Get host status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create New Specification │
|
||||
│ │
|
||||
│ • Clone current host specification │
|
||||
│ • Swap boot order (Default ↔ Rollback) │
|
||||
│ • Preserve other settings │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Transition │
|
||||
│ │
|
||||
│ • Validate state transition is allowed │
|
||||
│ • Check rollback availability │
|
||||
│ • Ensure valid operation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Operation Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ reverting = (boot_order == Default)? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Reverting ││ │ │ Rolling Back ││ │
|
||||
│ │ │ • Print: ││ │ │ ││ │
|
||||
│ │ │ "notice: ││ │ │ • Switch to rollback ││ │
|
||||
│ │ │ Reverting ││ │ │ deployment ││ │
|
||||
│ │ │ queued ││ │ │ • Make rollback first ││ │
|
||||
│ │ │ rollback ││ │ │ in boot order ││ │
|
||||
│ │ │ state" ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validate Rollback Deployment │
|
||||
│ │
|
||||
│ • Check rollback deployment exists │
|
||||
│ • Verify rollback is container-based │
|
||||
│ • Get rollback image information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Log Rollback Operation │
|
||||
│ │
|
||||
│ • Log to systemd journal with unique message ID │
|
||||
│ • Include rollback type (rollback/revert) │
|
||||
│ • Include image digests and commit hashes │
|
||||
│ • Include current image information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Reorder Deployments │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ reverting? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Order: ││ │ │ Order: ││ │
|
||||
│ │ │ [current, ││ │ │ [rollback, current, others] ││ │
|
||||
│ │ │ rollback, ││ │ │ ││ │
|
||||
│ │ │ others] ││ │ │ • Put rollback first ││ │
|
||||
│ │ │ ││ │ │ • Put current second ││ │
|
||||
│ │ │ • Put ││ │ │ • Keep others in order ││ │
|
||||
│ │ │ current ││ │ │ ││ │
|
||||
│ │ │ first ││ │ │ ││ │
|
||||
│ │ │ • Put ││ │ │ ││ │
|
||||
│ │ │ rollback ││ │ │ ││ │
|
||||
│ │ │ second ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Write New Deployment Order │
|
||||
│ │
|
||||
│ • Write new deployment order to OSTree │
|
||||
│ • Update bootloader configuration │
|
||||
│ • Preserve other deployments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Provide User Feedback │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ reverting? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Print: ││ │ │ Print: ││ │
|
||||
│ │ │ "Next boot: ││ │ │ "Next boot: rollback ││ │
|
||||
│ │ │ current ││ │ │ deployment" ││ │
|
||||
│ │ │ deployment" ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Write Reboot Required Marker │
|
||||
│ │
|
||||
│ • Write reboot required marker │
|
||||
│ • Include rollback image digest │
|
||||
│ • Mark system for reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update System Status │
|
||||
│ │
|
||||
│ • Update system modification time │
|
||||
│ • Refresh system status │
|
||||
│ • Update deployment information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Rollback operation completed │
|
||||
│ • Deployment order updated │
|
||||
│ • System ready for next boot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Soft Reboot Rollback Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Soft Reboot Rollback │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Soft Reboot Capability │
|
||||
│ │
|
||||
│ • Verify rollback deployment supports soft reboot │
|
||||
│ • Check system soft reboot support │
|
||||
│ • Validate deployment compatibility │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Prepare Soft Reboot │
|
||||
│ │
|
||||
│ • Get rollback deployment list │
|
||||
│ • Find target rollback deployment │
|
||||
│ • Prepare soft reboot environment │
|
||||
│ • Configure kexec for soft reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Soft Reboot │
|
||||
│ │
|
||||
│ • Load rollback kernel into memory │
|
||||
│ • Prepare rollback initramfs │
|
||||
│ • Execute kexec for soft reboot │
|
||||
│ • Avoid full hardware reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Soft reboot completed │
|
||||
│ • System running rollback deployment │
|
||||
│ • Faster restart achieved │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Rollback │ │ System │ │ Soft Reboot │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • No rollback │ │ • Not bootc │ │ • Soft reboot │ │
|
||||
│ │ available │ │ compatible │ │ not supported │ │
|
||||
│ │ • Rollback not │ │ • Invalid │ │ • No rollback │ │
|
||||
│ │ container- │ │ transition │ │ deployment │ │
|
||||
│ │ based │ │ • Deployment │ │ found │ │
|
||||
│ │ • Invalid │ │ not found │ │ • kexec failed │ │
|
||||
│ │ rollback │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 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 │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Normal │ │ Rollback │ │
|
||||
│ │ State │ │ Queued │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Boot Order: │ │ • Boot Order: Rollback │ │
|
||||
│ │ Default │ │ • Current: Second │ │
|
||||
│ │ • Current: │ │ • Rollback: First │ │
|
||||
│ │ First │ │ • Next Boot: Rollback │ │
|
||||
│ │ • Rollback: │ │ │ │
|
||||
│ │ Second │ │ │ │
|
||||
│ │ • Next Boot: │ │ │ │
|
||||
│ │ Current │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Rollback Operation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────────────────────┐ │ │
|
||||
│ │ │ Rollback │ │ Revert │ │ │
|
||||
│ │ │ (Normal → │ │ (Rollback → │ │ │
|
||||
│ │ │ Rollback) │ │ Normal) │ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ │ • Swap boot │ │ • Swap boot order │ │ │
|
||||
│ │ │ order │ │ • Return to normal │ │ │
|
||||
│ │ │ • Make rollback │ │ • Make current first │ │ │
|
||||
│ │ │ first │ │ • Make rollback second │ │ │
|
||||
│ │ │ • Make current │ │ │ │ │
|
||||
│ │ │ second │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ New State │ │ New State │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Boot Order: │ │ • Boot Order: Default │ │
|
||||
│ │ Rollback │ │ • Current: First │ │
|
||||
│ │ • Current: │ │ • Rollback: Second │ │
|
||||
│ │ Second │ │ • Next Boot: Current │ │
|
||||
│ │ • Rollback: │ │ │ │
|
||||
│ │ First │ │ │ │
|
||||
│ │ • Next Boot: │ │ │ │
|
||||
│ │ Rollback │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Boot Order Management
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Boot Order States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Default Boot Order │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Current │ │ Rollback │ │
|
||||
│ │ Deployment │ │ Deployment │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • First in │ │ • Second in boot order │ │
|
||||
│ │ boot order │ │ • Backup deployment │ │
|
||||
│ │ • Active │ │ • Available for rollback │ │
|
||||
│ │ deployment │ │ │ │
|
||||
│ │ • Next boot │ │ │ │
|
||||
│ │ target │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Rollback Boot Order │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Rollback │ │ Current │ │
|
||||
│ │ Deployment │ │ Deployment │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • First in │ │ • Second in boot order │ │
|
||||
│ │ boot order │ │ • Previous deployment │ │
|
||||
│ │ • Next boot │ │ • Available for future rollback │ │
|
||||
│ │ target │ │ │ │
|
||||
│ │ • Active │ │ │ │
|
||||
│ │ deployment │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc rollback process, showing all decision points, operations, and state transitions involved in rolling back to a previous deployment.
|
||||
Loading…
Add table
Add a link
Reference in a new issue