Add resizing note and troubleshooting guide for ZFS snapshotter

[welteki]

Description

Add a note to the ZFS resizing section clarifying that the new volume size only takes effect on newly pulled images, and add a troubleshooting guide for the ZFS zvol snapshotter.

Motivation and Context

Users need clear guidance on how resizing behaves and how to recover from out-of-sync state between containerd and ZFS.

• I have raised an issue to propose this change (required)

How Has This Been Tested?

Reviewed documentation changes manually.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I've read the CONTRIBUTION guide
• I have signed-off my commits with git commit -s

[reviewfn]

AI Pull Request Overview

Summary

• Adds a warning note clarifying that ZFS volume resizing only affects newly pulled images, not existing ones
• Includes steps to resize existing images by wiping data, with clear warnings about data loss
• Introduces a comprehensive troubleshooting section for inspecting ZFS snapshotter state
• Provides two recovery options for out-of-sync states between containerd and ZFS: selective wipe and full reset
• Updates example dataset path to use consistent "slicer_zpool/snapshots" naming
• Covers inspection commands using ctr, zfs list, and journalctl for diagnostics
• Documents destructive recovery procedures with proper sequencing

Approval rating (1-10)

8 - Solid documentation addition with clear warnings, but contains a minor formatting error in numbered steps.

Summary per file

Summary per file

File path	Summary
docs/storage/zfs.md	Added resizing behavior note and troubleshooting guide for ZFS snapshotter out-of-sync issues

Overall Assessment

The PR successfully adds essential documentation for ZFS volume resizing behavior and troubleshooting procedures. The content provides clear guidance with appropriate warnings about data loss risks. The troubleshooting section offers practical diagnostic and recovery steps. However, there is a formatting inconsistency in the numbered steps that should be corrected for clarity.

Detailed Review

Detailed Review

docs/storage/zfs.md

• The resizing warning note is well-placed and clearly explains the limitation that volume size changes only apply to new images, not existing ones. The provided commands for applying changes to existing images include proper warnings about data loss.
• The troubleshooting section is comprehensive, covering state inspection with ctr snapshots, ZFS dataset listing, and log checking via journalctl.
• Recovery Option 1 (selective wipe) correctly targets only ZFS-based storage while preserving other data, with proper sequencing of stopping services, wiping images/snapshots, and restarting.
• Recovery Option 2 (full reset) provides a more destructive but complete recovery path. However, the step numbering contains an error: steps are numbered 1, 2, 3, 3 instead of 1, 2, 3, 4. This should be corrected to avoid confusion during troubleshooting.
• The full containerd wipe step removes /var/lib/containerd/, which is appropriately drastic for complete reset scenarios but correctly placed after snapshotter cleanup.
• Dataset path updates from generic "your-zpool" to specific "slicer_zpool" improve example consistency but may need verification that this matches actual defaults.
• No security concerns identified in the documented procedures, as they require root access and are appropriately destructive for recovery purposes.
• The documentation assumes users understand ZFS and containerd concepts, which seems reasonable for this technical audience.

AI agent details.

Agent processing time: 55.4s
Environment preparation time: 3.614s
Total time from webhook: 1m2.316s