# 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.