bootc-docs/rollback/bootc-rollback-flowchart.md

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.