#982 Fix Documentation for upgrade steps on a Rancher 2.6 air-gapped (originally installed and upgraded with helm template)

[martyav]

Fixes #982 (SURE-7154)

Addresses a problem that arose with #808

Reminders

• See the README for more details on how to work with the Rancher docs.

• Verify if changes pertain to other versions of Rancher. If they do, finalize the edits on one version of the page, then apply the edits to the other versions.

• If the pull request is dependent on an upcoming release, make sure to target the release branch instead of main.

Description

Adds advice for users who installed Rancher with helm template. The helm template command is known to cause issues with upgrades under certain circumstances, and this is called out in our Release Notes (but see Comments below). #808 replaced commands containing helm template with helm install -- however, that still left users who had previously used helm template on the (web)hook when they attempt to upgrade Rancher and encounter an UPGRADE FAILED error. Since v2.5 wasn't affected by #808, I copied the first two lines of the upgrade command from that document, which includes the --no-hooks flag required to prevent the error from occurring. I included edits for v2.6, v2.7, and v2.8, because presumably this affects all Rancher versions going forward from v2.5.

Comments

Oddly, the information in our release notes about this includes links to dead issues in the docs repo.

Requirements for air gapped environments:
When installing or upgrading Rancher in an air gapped environment, add the flag --no-hooks to the helm template command, to skip rendering files for Helm's hooks. See #3226.
If using a proxy in front of an air-gapped Rancher instance, you must pass additional parameters to NO_PROXY. See the documentation and related issue #2725.

I'm guessing these originally linked to the old repo and got deleted at some point. I'll look into whether they were transferred to this repo later.

[martyav]

typo

[btat]

I copied the first two lines of the upgrade command from that document, which includes the --no-hooks flag required to prevent the error from occurring. I included edits for v2.6, v2.7, and v2.8, because presumably this affects all Rancher versions going forward from v2.5.

Adding those two lines is essentially reverting the changes from #828 (to address #808) and going back to telling users to use helm template, which is not what we want due to the issues the helm template + --no-hooks combo brings. The goal is to document a migration path to allow users that previously used helm template to use helm upgrade. Please ignore. I wasn't aware upgrades aren't affected (since #828 updated the command for upgrades as well), but as @axeal pointed out it's fine for upgrades.

[axeal]

@btat helm template caused a problem for the helm Job that set the bootstrap password on initial install in Rancher v2.6+, but will not cause an issue on upgrade. Pending a migration path, it is therefore OK to advise users to upgrade with helm template where they previously installed Rancher via this method and are unable to use helm upgrade, my only feedback on the PR here is to remove the note The helm template command can cause problems with Helm hooks. since this is not applicable to the upgrade.

[martyav]

I copied the first two lines of the upgrade command from that document, which includes the --no-hooks flag required to prevent the error from occurring. I included edits for v2.6, v2.7, and v2.8, because presumably this affects all Rancher versions going forward from v2.5.

Adding those two lines is essentially reverting the changes from #828 (to address #808) and going back to telling users to use helm template, which is not what we want due to the issues the helm template + --no-hooks combo brings. The goal is to document a migration path to allow users that previously used helm template to use helm upgrade.

@btat
The PR doesn't remove anything. The other code block is left alone.

It adds a section named after the error a user would encounter if they had previously installed Rancher with helm template, and presents the code they would need to resolve it.

[martyav]

@tomleb @cbron (reviewer and author of #808) how do you feel about these changes re: adding instructions that mention helm template for users who previously used helm template to install Rancher, then attempted to upgrade and were blocked by an error?