From b47b1c2fda6c03d926fc8604c138d59b7fbb702c Mon Sep 17 00:00:00 2001 From: Yuliia Horbenko <31223054+yuliiiah@users.noreply.github.com> Date: Thu, 23 May 2024 22:00:38 +0200 Subject: [PATCH] Airgap VMware upgrade: Add missing steps (#2892) * docs: Add missing steps to the Palette and VerteX upgrade guides (airgap VMware) * docs: Implement peer review --- .../upgrade/upgrade-vmware/airgap.md | 148 +++++++++++------ .../vertex/upgrade/upgrade-vmware/airgap.md | 151 ++++++++++++------ 2 files changed, 204 insertions(+), 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 index 77353cf01e..52dd4f1f0f 100644 --- 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 support@spectrocloud.com 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 ubuntu@ - ``` +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 ubuntu@palette.example.com - ``` +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 `` with the Palette version you are downloading. +4. At the **Select a name and folder** step: - ```shell - curl --user : --output airgap-.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 : --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-.bin && ./airgap-.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 ubuntu@ + ``` + + Consider the following command example for reference. + + ```shell + ssh -identity_file /docs/ssh-private-key.pem ubuntu@palette.example.com + ``` + +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 + `` with the Palette version you are downloading. + + ```shell + curl --user : --output airgap-.bin + ``` + + Consider the following command example for reference. + + ```shell + curl --user : --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-.bin && ./airgap-.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. diff --git a/docs/docs-content/vertex/upgrade/upgrade-vmware/airgap.md b/docs/docs-content/vertex/upgrade/upgrade-vmware/airgap.md index c168a5def2..da2cb14b6c 100644 --- a/docs/docs-content/vertex/upgrade/upgrade-vmware/airgap.md +++ b/docs/docs-content/vertex/upgrade/upgrade-vmware/airgap.md @@ -30,61 +30,116 @@ Palette VerteX upgrade. installation. - Refer to [Access Palette VerteX](../../vertex.md#access-palette-vertex) to download the new airgap Palette VerteX - installation bin. + installation bin and, if necessary, receive a link to the new OS and Kubernetes OVA. + +- Contact our Support Team at support@spectrocloud.com to learn if the new version of Palette VerteX 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 VerteX 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 ubuntu@ - ``` +If the new version of VerteX 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 ubuntu@palette.example.com - ``` +1. Log in to vCenter. +2. Right-click the cluster or resource group that hosts your self-hosted VerteX 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 VerteX airgap installation bin. Enter the username, - password, and the Palette VerteX airgap installation URL you received from our support team. In the output file - name, replace `` with the Palette VerteX version you are downloading. +4. At the **Select a name and folder** step: - ```shell - curl --user : --output airgap-.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 : --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-vertex/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 VerteX airgap installation bin. + It is important that you follow this naming convention. Otherwise, VerteX will not be able to identify the OS and + Kubernetes OVA and you will not be able to upgrade your VerteX instance. - ```shell - chmod +x airgap-.bin && ./airgap-.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 VerteX 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 ubuntu@ + ``` + + Consider the following command example for reference. + + ```shell + ssh -identity_file /docs/ssh-private-key.pem ubuntu@palette.example.com + ``` + +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 VerteX airgap installation bin. Enter the username, + password, and the Palette VerteX airgap installation URL you received from our support team. In the output file name, + replace `` with the Palette VerteX version you are downloading. + + ```shell + curl --user : --output airgap-.bin + ``` + + Consider the following command example for reference. + + ```shell + curl --user : --output airgap-4.2.12.bin https://software.spectrocloud.com/airgap-v4.2.12.bin + ``` + +8. Refer to the [Additional Packs](../../install-palette-vertex/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 VerteX airgap installation bin. + + ```shell + chmod +x airgap-.bin && ./airgap-.bin + ``` + + Consider the following example for reference. + + ```shell + chmod +x airgap-v4.2.13.bin && ./airgap-v4.2.13.bin + ``` -6. After the Palette VerteX airgap binary is verified and uncompressed, it uploads the updates to your existing Palette +10. After the Palette VerteX airgap binary is verified and uncompressed, it uploads the updates to your existing Palette VerteX instance. This step takes some time to complete. ```shell @@ -101,11 +156,11 @@ Palette VerteX upgrade. Once the airgap binary is executed, you will receive a **Setup Completed** success message. -7. Log in to the Palette VerteX system console. +11. Log in to the Palette VerteX 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 @@ -116,19 +171,19 @@ Palette VerteX upgrade. ![Self-hosted Palette VerteX 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 VerteX 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 VerteX will +15. From the left **Main Menu**, select **Update Management**. Once the registry sync is done, Palette VerteX will prompt you to update to the new version. Click **Update**. ![Self-hosted Palette VerteX 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 @@ -137,22 +192,22 @@ Palette VerteX 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 VerteX +18. From your current configuration, transfer only those differences that are custom to your self-hosted Palette VerteX instance (for example, the `podCIDR` and `serviceClusterIpRange` values). Do not override any other changes or upgrades. ![Self-hosted Palette VerteX 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 VerteX system console. ![Self-hosted Palette VerteX 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.