Project

General

Profile

Bug #58392

Add ZFS feature flag information to Guide

Added by Stilez y about 3 years ago. Updated over 2 years ago.

Status:
Done
Priority:
No priority
Assignee:
Timothy Moore II
Category:
Documentation
Target version:
Seen in:
Severity:
New
Reason for Closing:
Reason for Blocked:
Needs QA:
No
Needs Doc:
No
Needs Merging:
No
Needs Automation:
No
Support Suite Ticket:
n/a
Hardware Configuration:
ChangeLog Required:
No

Description

When upgrading FreeNAS to 11.2-RC2, the upgrade boots with an alert pre-created: New feature flags are available for volume Main_pool. Refer to the "Upgrading a ZFS Pool" subsection in the User Guide "Installing and Upgrading" chapter and "Upgrading" section for more instructions.

The problem is that nowhere is the user actually told what these upgraded feature flag changes or enhancements are - The referred sections of the docs merely describe feature flags and the upgrade procedure generally.

Especially, when the user goes to the "pools" menu and sees an upgrade is available, the exact details should be linked so they can read before deciding if they want to upgrade their pools. But the GUI just says "An upgrade is available" and that it can't be reversed - again no info.

REQUESTED SOLUTION:

The actual info I'm expecting is "given on the forums"https://forums.freenas.org/index.php?resources/zfs-feature-flags-in-freenas.95 . This is a pretty good way to do it, listing the flags, and what they do. Perhaps it could be formatted as a bullet list/table (FreeNAS version/new flags/what they do), but that's semantics.

What I'd like is:

  1. A page or section "ZFS feature flag upgrades" in the docs, that's also crosslinked as needed from both "ZFS primer" + "Upgrading" sections;
  2. When the user goes to pools -> upgrade, the relevant docs info is linked and the user told to read it before deciding if they want to upgrade their pool.

As this will impact on all users moving to 11.2, and the info isn't obvious, can this be done before 11.2-REL? Thanks.


Related issues

Related to FreeNAS - Feature #62442: Expose un-set zpool features, and allow them to be individually selectedClosed

History

#1 Updated by Dru Lavigne about 3 years ago

  • Category changed from GUI (new) to Documentation
  • Assignee changed from Release Council to Warren Block
  • Target version changed from Backlog to 11.2-RELEASE

#2 Updated by Warren Block about 3 years ago

  • Assignee changed from Warren Block to Samantha Bonham

#3 Updated by Dru Lavigne about 3 years ago

  • Target version changed from 11.2-RELEASE to 11.2-U2

#5 Updated by Stilez y about 3 years ago

If the general fix will be deferred to U1, can some kind of note or link be added to the upgrade docs + user guide for 11.2-REL, so users who see this (which will be almost everyone!) can find that page on the forum, at least?

Thanks.

#6 Updated by Dru Lavigne about 3 years ago

Stilez: the intro (https://www.ixsystems.com/documentation/freenas/11.2/intro.html#new-features-in-release) to the 11.2 series Guide has had this since BETA1:

OpenZFS is up-to-date with Illumos and slightly ahead due to support for sorted scrubs which were ported from ZFS on Linux. Notable improvements include channel programs, data disk removal, more resilient volume import, the ability to import a pool with missing vdevs, pool checkpoints, improved compressed ARC performance, and ZIL batching. As part of this change, the default ZFS indirect block size is reduced to 32 KiB from 128 KiB. Note that many of these improvements need further testing so have not yet been integrated into the UI.

The tooltip itself won't be updated until U1 as the GUI is frozen in prep for RELEASE.

#7 Updated by Stilez y about 3 years ago

Dru - But nothing whatsoever in the text quoted gives a user the info they need to actually make an upgrade decision, when they are told a pool feature flag upgrade is available after 11.2 is released. Providing a list of "notable improvements" does not distinguish which of them are present simply by having upgraded the system to 11.2, and which of them will only be obtained (or fully leveraged) by also upgrading their pool.

An 11.2 upgrader must balance the benefits of an irreversible pool upgrade, against the risk of ever needing to boot or run 11.1 again. That's fine, and the manual explains that choice clearly. But an 11.2-REL upgrader who tries to decide (per docs) whether they are better to upgrade their pool or not, simply can't assess their own use-case unless they know which of these benefits are obtained just by running 11.2 OS (even with a <= 11.1 feature flag pool), and which of these benefits will only be obtained by matching 11.2 OS with an 11.2 feature flag upgraded pool.

That is the problem that I'm raising. I hope this makes it clear and the docs can clarify this aspect before release.

#8 Updated by Stephen Cunningham almost 3 years ago

I agree it would be helpful if more information was given since this is important. Currently the user is forced to research the feature flags or take a leap of faith. I know there are commands you can use to find some info but I don't see it listed in the documentation and information on the forums is limited. I found this ticket trying to find what different feature flags are on 11.3,11.2,11.1.

#9 Updated by Dru Lavigne almost 3 years ago

  • Related to Feature #62442: Expose un-set zpool features, and allow them to be individually selected added

#10 Updated by Warren Block almost 3 years ago

  • Assignee changed from Samantha Bonham to Timothy Moore II

#11 Updated by Dru Lavigne almost 3 years ago

  • Target version changed from 11.2-U2 to Backlog

#14 Updated by Timothy Moore II almost 3 years ago

  • Status changed from Unscreened to Screened

#15 Updated by Dru Lavigne almost 3 years ago

  • Target version changed from Backlog to 11.2-U3

#16 Updated by Timothy Moore II almost 3 years ago

  • Status changed from Screened to In Progress

#18 Updated by Timothy Moore II almost 3 years ago

Testing: Check both the angulargui and legacy UI versions of the guide. Build the guide and verify the ZFS Primer chapter has a new ZFS Feature Flags subsection. Verify there is a link to zpool-features(7) and that it works. Check the Install, Storage, and Alert chapters for working links to "ZFS Feature Flags" section.

#19 Updated by Dru Lavigne almost 3 years ago

  • Subject changed from Pool upgrade/feature flag changes highlighted in alerts on 11.1->11.2, but actual changes are nowhere described to Add ZFS feature flag information to Guide
  • Needs Doc changed from Yes to No
  • Needs Merging changed from Yes to No

Stilez: for now, the Guide contains references to get more info about feature flags. Please follow the related ticket for progress on additional work which will display this info in the UI in a future version.

#20 Updated by Dru Lavigne almost 3 years ago

  • Status changed from In Progress to Ready for Testing

#21 Updated by Dru Lavigne over 2 years ago

  • Status changed from Ready for Testing to Done
  • Needs QA changed from Yes to No

Also available in: Atom PDF