Designing Atomic OS Updates with openSUSE Transactional-Update: Requirements, Architecture, and Operational Practices

Problem and Takeaway

When an OS is updated in place, any failure during the process can leave the machine unusable. openSUSE’s transactional-update turns the host into an immutable artifact: the root filesystem is read‑only, updates are applied to a new Btrfs snapshot, and the new snapshot is activated only after a reboot. The key takeaway is that this model guarantees that an update either completes fully or never takes effect, and a previous snapshot can be booted instantly for rollback.

Architectural Requirements

• Btrfs root – The design relies on copy‑on‑write snapshots. A non‑Btrfs filesystem cannot provide atomic switching.
• Free space for snapshots – Each update creates a new root snapshot while the prior one remains bootable. The disk must have enough headroom for the expected number of concurrent snapshots (default is two).
• Reboot‑centric workflow – The system must tolerate a reboot to activate changes. In‑place kernel or library changes are not possible until the next boot.
• State isolation – Mutable data must live outside the immutable root, typically in a dedicated /var subvolume or an external volume.

The Minimal Viable Design

A single host can be configured with the following components:

1. Root filesystem (/) is a Btrfs subvolume mounted read‑only.
2. Writable /var is a separate Btrfs subvolume (or loopback image) mounted with rw.
3. transactional-update.timer runs transactional-update --apply at a scheduled time.
4. Optional rebootmgr or manual reboot during a maintenance window.
5. Snapper cleanup policy to keep only the last N snapshots (default 2).

Example /etc/snapper/config.d/transactional.conf:

# Snapper configuration for transactional-update
# /etc/snapper/config.d/transactional.conf

config
{
    subvolume = "/"
    number_of_snapshots = 5
    cleanup_interval = 7
}

Trust and Data Boundaries

• Package authenticity – transactional-update requires root and verifies GPG signatures of all packages from the configured repositories.
• Bootloader access – The GRUB submenu exposes all snapshots. Physical or console access can boot any snapshot, bypassing OS‑level permissions.
• /var boundary – Changes to /var survive a rollback. Therefore, database migrations or application state changes must be backward‑compatible or managed separately.

Operational Checks

Verify the active snapshot after a reboot

Run on the host:

# List snapshots
snapper list

# Confirm the kernel matches the snapshot
uname -r

Health‑checker service

On MicroOS and Leap Micro, health-checker.service starts after boot. It can be configured to trigger transactional-update rollback if a critical service fails.

Disk hygiene

Periodically monitor Btrfs usage:

btrfs filesystem df /

Ensure number_of_snapshots in Snapper does not exceed available space.

Failure Modes and Recovery

• Bad update – Boot the previous snapshot via GRUB or run transactional-update rollback and reboot.
• Snapshot exhaustion – If snapshots consume all free space, the next update fails. Mitigate by reducing number_of_snapshots or expanding the root partition.
• Mutable writes to read‑only paths – Applications writing to /usr or /opt break the model. Move such data to /var or external volumes.
• Out‑of‑tree kernel modules – They must be re‑installed after a rollback because the module files exist in the snapshot and are not preserved.

When the Design Should Change

Consider a different layout if:

• You must run live patching or deploy kernel modules without a reboot.
• Reboot windows are too restrictive for your workload.
• Storage is limited and you cannot keep multiple snapshots.
• Your applications rely heavily on mutable system directories like /usr or /opt.
• You need in‑place updates for compliance or regulatory reasons.

In those cases, a traditional Leap or Tumbleweed installation with a mutable root is more appropriate.

Practical Example: Installing a Package Transactionally

Assuming the host is running MicroOS 15.6:

1. Start a transaction:

# Perform the installation in a new snapshot
transactional-update --apply
zypper install vim

2. End the transaction and schedule a reboot:

# Commit changes
transactional-update --continue

# Schedule reboot
rebootmgr --schedule

3. After reboot, verify:

snapper list | grep "active"
uname -r
vim --version

4. If the new state is undesirable, rollback:

# Rollback to previous snapshot
transactional-update rollback
reboot

All operations above change system state and must be performed as root.

Limitations and Verification

• The snapshot mechanism only covers the root filesystem. Data in /var or external volumes is not rolled back automatically.
• Snapper cleanup policies can be overridden by manual snapper delete commands, which may inadvertently remove a needed snapshot.
• Always test the rollback path on a disposable VM before deploying to production.

By following these guidelines, engineers can confidently adopt openSUSE’s transactional‑update for reliable, atomic OS updates.