My opinons, my understanding of it all, apologies if it gets long:
about the use of gptzfsboot in upgrading root pools.
You do not use gptzfsboot to upgrade root or any other pools.
gptzfsboot is the "bootloader" or "loader" used when your system boots from BIOS or UEFI Compatibility Mode, which based on your gpart show that is how you are booting (no efi partition, freebsd-boot of about 512k)
Sometimes when upgrading a system, the old version of gptzfsboot may be incompatible with newer versions of zfs/zpools. In that case, you may not be able to boot the system.
A lot of people feel it's a "best practice" to update the bootblocks whenever you do an upgrade, at least across versions (say 12 to 13), others will do it every patch release.
zpool upgrade works on a zpool. Why would you ever do that? Because the new version of ZFS has some
new feature that you want to use; the previous version of ZFS did not have that feature.
Typically it is safe to do a zpool upgrade. The warning note you see is a heads up that:
By doing zpool upgrade and enabling a new feature you may not be able to use that zpool on a system that doesn't understand that feature.
Think you have a system running FBSD-12, you create a new BE to upgrade to FBSD-13. There was a change from "native ZFS" in 12 to OpenZFS in 13, bringing in new features and other things. If you are in FBSD-13, zpool upgrade, enable some new OpenZFS feature you may not be able to boot into your FBSD-12 BE.
My experience has been if I've simply used the installer to create the system, root on zfs, never enabled any features just leave the zpools at whatever defaults the system used at the time, it's safe to first update gptzfsboot, then do a zpool upgrade.
My questions are:
- How do I use gptzfsboot after upgrading this zfs root partition (if that's the right way of describing it).
gpart bootcode -p /boot/gptzfsboot -i 1 ada0 where you replace ada0 with your device name
- What is the syntax to gptzfsboot in this case?
You use gpart to put a new version of gptzfsboot on the device, you do not run gptzfsboot.
- Do I upgrade the pool, then run gptzfsboot then reboot?
I prefer to update gptzfsboot using gpart first without doing zpool upgrade, then reboot to make sure the system comes up, then do a zpool upgrade and another reboot. But I'm overly cautious sometimes.
- Do I have to remove lines like zfs_enable="YES" from rc.conf?
No. If you are currently booting with root on ZFS, do not remove any zfs_load or zfs_enable from /boot/loader.conf or /etc/rc.conf
- Are there any other configuration adjustments to be made before I reboot?
Should not need any
- Lastly, if the machine doesn't boot - what are my best recovery options?
Come back here, blame me for giving bad advice? Seriously a copy of the latest install image for your version (FBSD-13.1-RELEASE), boot it, drop to a shell, and run the gpart command to update gptzfsboot often fixes a lot of issues. Other folks here will have other help based on exactly what the problem is.