PD-2231 / 25.10 / PD-2231-we-should-set-user-expectations-appropriately-for-managing-co… (by linzi-ix)

content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md

@@ -89,6 +89,16 @@ Each boot environment entry contains this information:
 
 Use the icons row to take different actions for a boot environment.
 
+### Following Best Practices
+
+Boot environments do not share all system information. TrueNAS carries over central database and configuration elements into a new environment during an update, but not all state changes made in an environment appear in another.
+
+Changes made in a new boot environment do not subsequently appear in older environments of earlier releases. Similarly, changes made while booted into a previous environment do not automatically appear in the upgraded boot environment.
+
+The isolation among different boot environments means that frequent switching between environments can lead configuration divergence and missing audit information.
+
+We recommend only reverting to an earlier boot environment when a pool upgrade in the new version introduces a problem, or to recover from a broken configuration if the system console or IPMI is unavailable.
+
 ### Activating a Boot Environment
 
 The option to activate a boot environment only displays for boot entries not set to **Active**
@@ -102,6 +112,10 @@ Click **Confirm**, and then click **Activate**.
 
 The **System Boot** screen status changes to **Reboot** and the current **Active** entry changes from **Now/Reboot** to **Now**, indicating that it is the current boot environment but it is not used on the next system restart (boot operation).
 
+{{< hint warning >}}
+Activating and booting into an older environment restores only that environment state. Any changes made there do not carry forward into newer environments.
+{{< /hint >}}
+
 ### Cloning a Boot Environment
 
 Cloning copies the selected boot environment into a new inactive boot environment that preserves the **boot-pool** state at the clone-creation time.

content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md

@@ -9,6 +9,10 @@ tags:
 The **Boot Environment** screen lists boot environments created by updates performed on the system.
 It has options for monitoring and maintaining the TrueNAS install pool and disks, and includes managing OS restore points(called boot environments) for the TrueNAS system.
 
+{{< hint warning >}}
+System updates create a new boot environment and carry forward core configuration, but other state changes do not carry forward to new environments. Switching between environments frequently creates configuration divergence and splits audit logs between environments.
+{{< /hint >}}
+
 {{< trueimage src="/images/SCALE/SystemSettings/BootEnvironmentListingSCALE.png" alt="System Boot Screen" id="System Boot Screen" >}}
 
 Screen options shown at the top right of the screen are:

static/includes/BootPoolRecoveryProcess.md

@@ -20,7 +20,7 @@ When the TrueNAS boot pool fails and cannot be repaired, reinstall TrueNAS and r
 ### Important Considerations
 
 {{< hint type=warning >}}
-This recovery process depends entirely on having a current configuration backup saved externally. Boot pool failures result in a complete loss of system configuration if no backup exists.
+By default, TrueNAS creates a new boot environment when you update or reinstall the system, but if you revert to an earlier environment and make changes, those changes do not carry into the newer environment. Because of this, the recovery process depends entirely on having a current configuration backup saved externally. Boot pool failures result in a complete loss of system configuration if no backup exists.
 {{< /hint >}}
 
 - **Keep external backups** - Always maintain current configuration backups stored outside the TrueNAS system