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
434 lines
41 KiB
Markdown
434 lines
41 KiB
Markdown
# 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.
|