Airgap VMware upgrade: Add missing steps (#2892)

* docs: Add missing steps to the Palette and VerteX upgrade guides (airgap VMware) * docs: Implement peer review
spectrocloud · May 23, 2024 · b47b1c2 · b47b1c2
1 parent 4a330f3
commit b47b1c2
Show file tree

Hide file tree

Showing 2 changed files with 204 additions and 95 deletions.
diff --git a/docs/docs-content/enterprise-version/upgrade/upgrade-vmware/airgap.md b/docs/docs-content/enterprise-version/upgrade/upgrade-vmware/airgap.md
@@ -30,59 +30,113 @@ Palette upgrade.
 - Refer to [Access Palette](../../enterprise-version.md#access-palette) to download the new airgap Palette installation
   bin.
 
+- Contact our Support Team at [email protected] to learn if the new version of Palette requires a new OS and
+  Kubernetes OVA. If necessary, they will provide you with a link to the OVA, which you will use to upgrade Palette.
+
 - A diff or text comparison tool of your choice.
 
 ## Upgrade
 
-1.  Use the following command template to SSH into the Palette airgap support VM. Enter the path to your private SSH
-    key, your username, and the IP or domain of the airgap support VM. The default username is `ubuntu`.
+:::info
 
-    ```shell
-    ssh -identity_file </path/to/private/key> ubuntu@<vm-ip-or-domain>
-    ```
+If the new version of Palette requires you to update the underlying OS or Kubernetes distribution, proceed with the
+steps one through four. Otherwise, start at step five.
 
-    Consider the following command example for reference.
+:::
 
-    ```shell
-    ssh -identity_file /docs/ssh-private-key.pem [email protected]
-    ```
+1. Log in to vCenter.
+2. Right-click the cluster or resource group that hosts your self-hosted Palette instance and select **Deploy OVF
+   Template**.
+3. In the **Deploy OVF Template** wizard, at the **Select an OVF template** step, enter the link to the new OS and
+   Kubernetes OVA that you received from our support.
 
-2.  Use the following command to switch to the `root` user account, which you need to proceed with the upgrade.
+   Consider the following example for reference.
 
-    ```shell
-    sudo --login
-    ```
+   ```shell
+   https://vmwaregoldenimage-console.s3.us-east-2.amazonaws.com/u-2204-0-k-12610-0.ova
+   ```
 
-3.  Use the following command template to download the new Palette airgap installation bin. Enter the username,
-    password, and the Palette airgap installation URL you received from our support team. In the output file name,
-    replace `<version>` with the Palette version you are downloading.
+4. At the **Select a name and folder** step:
 
-    ```shell
-    curl --user <username>:<password> --output airgap-<version>.bin <url-to-airgap-installation-bin>
-    ```
+   - In the **Virtual machine name** field, append the `r_` prefix to the prepopulated OVA name and remove the `.ova`
+     extension.
 
-    Consider the following command example for reference.
+     Consider the following example for reference.
 
-    ```shell
-    curl --user <username>:<password> --output airgap-4.2.12.bin https://software.spectrocloud.com/airgap-v4.2.12.bin
-    ```
+     ```shell
+     u-2204-0-k-12610-0.ova >>> r_u-2204-0-k-12610-0
+     ```
 
-4.  Refer to the [Additional Packs](../../install-palette/airgap/supplemental-packs.md) page and update the packages you
-    are currently using. You must update each package separately.
+     :::info
 
-5.  Use the following command template to execute the new Palette airgap installation bin.
+     It is important that you follow this naming convention. Otherwise, Palette will not be able to identify the OS and
+     Kubernetes OVA and you will not be able to upgrade your Palette instance.
 
-    ```shell
-    chmod +x airgap-<version>.bin && ./airgap-<version>.bin
-    ```
+     :::
 
-    Consider the following example for reference.
+   - Under the **Select a location for the virtual machine** selector, choose the **spectro-templates** folder you
+     created during installation.
 
-    ```shell
-    chmod +x airgap-v4.2.13.bin && ./airgap-v4.2.13.bin
-    ```
+   Once the OS and Kubernetes OVA is available in your **spectro-templates** directory, you can terminate its
+   deployment. Refer to the
+   [Deploy an OVF or OVA Template](https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-AFEDC48B-C96F-4088-9C1F-4F0A30E965DE.html)
+   guide for more information on deploying OVAs in vCenter.
+
+   :::tip
+
+   If, during the OVA deployment, you encounter an error message stating **Unable to retrieve manifest or certificate**,
+   refer to this [known issue](https://kb.vmware.com/s/article/79986) from the VMware knowledge base for a guide on how
+   to resolve it.
+
+5. In your terminal, use the following command template to SSH into the Palette airgap support VM. Enter the path to
+   your private SSH key, your username, and the IP or domain of the airgap support VM. The default username is `ubuntu`.
+
+   ```shell
+   ssh -identity_file </path/to/private/key> ubuntu@<vm-ip-or-domain>
+   ```
+
+   Consider the following command example for reference.
+
+   ```shell
+   ssh -identity_file /docs/ssh-private-key.pem [email protected]
+   ```
+
+6. Use the following command to switch to the `root` user account, which you need to proceed with the upgrade.
+
+   ```shell
+   sudo --login
+   ```
+
+7. Use the following command template to download the new Palette airgap installation bin. Enter the username, password,
+   and the Palette airgap installation URL you received from our support team. In the output file name, replace
+   `<version>` with the Palette version you are downloading.
+
+   ```shell
+   curl --user <username>:<password> --output airgap-<version>.bin <url-to-airgap-installation-bin>
+   ```
+
+   Consider the following command example for reference.
+
+   ```shell
+   curl --user <username>:<password> --output airgap-4.2.12.bin https://software.spectrocloud.com/airgap-v4.2.12.bin
+   ```
+
+8. Refer to the [Additional Packs](../../install-palette/airgap/supplemental-packs.md) page and update the packs you are
+   currently using. You must update each pack separately.
+
+9. Use the following command template to execute the new Palette airgap installation bin.
+
+   ```shell
+   chmod +x airgap-<version>.bin && ./airgap-<version>.bin
+   ```
+
+   Consider the following example for reference.
+
+   ```shell
+   chmod +x airgap-v4.2.13.bin && ./airgap-v4.2.13.bin
+   ```
 
-6.  After the Palette airgap binary is verified and uncompressed, it uploads the updates to your existing Palette
+10. After the Palette airgap binary is verified and uncompressed, it uploads the updates to your existing Palette
     instance. This step takes some time to complete.
 
     ```shell
@@ -99,11 +153,11 @@ Palette upgrade.
 
     Once the airgap binary is executed, you will receive a **Setup Completed** success message.
 
-7.  Log in to the Palette system console.
+11. Log in to the Palette system console.
 
-8.  From the left **Main Menu**, select **Enterprise Cluster** and then select the **Profile** tab.
+12. From the left **Main Menu**, select **Enterprise Cluster** and then select the **Profile** tab.
 
-9.  Copy the configurations for your CSI, CNI, and Kubernetes layers to an external location for backup.
+13. Copy the configurations for your CSI, CNI, and Kubernetes layers to an external location for backup.
 
     :::tip
 
@@ -114,19 +168,19 @@ Palette upgrade.
 
     ![Self-hosted Palette system console with the highlighted Enterprise Cluster profile configuration values.](/enterprise-version_upgrade-upgrade_vmware_non-airgap_copy_configurations.webp)
 
-10. From the left **Main Menu**, select **Administration** > **Pack Registries**. Then, next to your **spectro-packs**
+14. From the left **Main Menu**, select **Administration** > **Pack Registries**. Then, next to your **spectro-packs**
     registry, select the **three-dot Menu** > **Sync**.
 
     Palette initiates a registry sync, which can take up to 30 minutes to complete.
 
-11. From the left **Main Menu**, select **Update Management**. Once the registry sync is done, Palette will prompt you
+15. From the left **Main Menu**, select **Update Management**. Once the registry sync is done, Palette will prompt you
     to update to the new version. Click **Update**.
 
     ![Self-hosted Palette system console with Update Management open and the Update button highlighted.](/enterprise-version_upgrade-upgrade_vmware_non-airgap_update.webp)
 
-12. In the **Palette version update** preview modal, from the left menu, select the **Kubernetes** layer. The **Incoming
-    changes** pane displays the changes that the upgrade introduces. The **Current configuration** pane displays your
-    current layer configuration.
+16. In the **Palette version update** preview modal, from the left **Main Menu**, select the **Kubernetes** layer. The
+    **Incoming changes** pane displays the changes that the upgrade introduces. The **Current configuration** pane
+    displays your current layer configuration.
 
     :::info
 
@@ -135,22 +189,22 @@ Palette upgrade.
 
     :::
 
-13. Copy the configurations from both **Incoming changes** and **Current configuration** panes to your comparison tool.
+17. Copy the configurations from both **Incoming changes** and **Current configuration** panes to your comparison tool.
 
-14. From your current configuration, transfer only those differences that are custom to your self-hosted Palette
+18. From your current configuration, transfer only those differences that are custom to your self-hosted Palette
     instance (for example, the `podCIDR` and `serviceClusterIpRange` values). Do not override any other changes or
     upgrades.
 
     ![Self-hosted Palette system console with the upgrade preview pane.](/enterprise-version_upgrade-upgrade_vmware_diff-checker.webp)
 
-15. After you finish merging the configurations, copy the resulting configuration, and then paste it to the **Current
+19. After you finish merging the configurations, copy the resulting configuration, and then paste it to the **Current
     configuration** pane in the Palette system console.
 
     ![Self-hosted Palette system console with the upgrade preview pane.](/enterprise-version_upgrade-upgrade_vmware_palette-upgrade-preview.webp)
 
-16. Repeat steps six through eight for each Enterprise Cluster profile layer.
+20. Repeat steps six through eight for each Enterprise Cluster profile layer.
 
-17. In the bottom-right corner of the **Palette version update** preview modal, select **Confirm**.
+21. In the bottom-right corner of the **Palette version update** preview modal, select **Confirm**.
 
     The system console locks for a couple of minutes while the upgrade is applied.