docs: add guideline to setup harvester ui extension in air gapped env (#722)

Co-authored-by: Jillian Maroket <[email protected]>
Signed-off-by: Jack Yu <[email protected]>

Author: Yu-Jack

docs/airgap.md

@@ -76,3 +76,97 @@ ssh rancher@<harvester-node-ip>
 sudo -i
 docker load -i /tmp/rancher-agent-<version>.tar
 ```
+
+## Harvester UI extension with Rancher Integration
+
+The Harvester UI Extension is required to access the Harvester UI in Rancher v2.10.x and later versions. However, installing the extension over the network is not possible in air-gapped environments, so you must perform the following workaround:
+
+
+
+1. Pull the image [rancher/ui-plugin-catalog](https://hub.docker.com/r/rancher/ui-plugin-catalog/tags) with the newest tag.
+
+1. On the Rancher UI, go to **Extensions**, and then select **⋮ > Manage Extension Catalogs**.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-01.png)
+
+1. Specify the required information.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-02.png)
+
+    - **Catalog Image Reference**: Specify the private registry URL and image repository.
+    - **Image Pull Secrets**: Specify the secret used to access the registry when a username and password are required. You must create that secret in the `cattle-ui-plugin-system` namespace. Use either `kubernetes.io/dockercfg` or `kubernetes.io/dockerconfigjson` as the value of `type`.
+      Example:
+
+      ```yaml
+      apiVersion: v1
+      kind: Secret
+      metadata:
+        name: my-registry-secret-rancher
+        namespace: cattle-ui-plugin-system
+      type: kubernetes.io/dockerconfigjson
+      data:
+        .dockerconfigjson: {base64 encoded data}
+      ```
+
+1. Click **Load**, and then allow some time for the extension to be loaded.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-03.png)
+
+1. On the **Available** tab, locate the extension named **Harvester**, and then click **Install**.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04.png)
+
+1. Select the version that matches the Harvester cluster, and then click **Install**.
+
+  For more information, see the [Harvester UI Extension Support Matrix](/v1.5/rancher/harvester-ui-extension/#support-matrix).
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-05.png)
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-06.png) 
+
+1. Go to **Virtualization Management > Harvester Clusters**.
+
+  You can now import Harvester clusters and access the Harvester UI.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-07.png)
+
+
+## Troubleshooting
+
+### UI Extensions Do Not Appear
+
+If the **Extensions** screen is empty, go to **Repositories** (**⋮ > Manage Repositories**) and then click **Refresh**.
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04-01.png)
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04-02.png)
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04-03.png)
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04-04.png)
+
+### Installation Failed
+
+If you encounter an error during installation, check the `uiplugins` resource.
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-05-01.png)
+
+Example:
+
+```
+bash-4.4# k get uiplugins -A
+NAMESPACE                 NAME        PLUGIN NAME   VERSION   STATE
+cattle-ui-plugin-system   harvester   harvester     1.0.3     pending
+bash-4.4# k get uiplugins harvester --namespace cattle-ui-plugin-system -o yaml
+apiVersion: catalog.cattle.io/v1
+kind: UIPlugin
+metadata:
+  # skip
+  name: harvester
+  namespace: cattle-ui-plugin-system
+spec:
+  plugin:
+    endpoint: http://ui-plugin-catalog-svc.cattle-ui-plugin-system:8080/plugin/harvester-1.0.3
+```
+
+Ensure that `svc.namespace` is accessible from Rancher. If that endpoint is not accessible, you can directly use a cluster IP such as `10.43.33.58:8080/plugin/harvester-1.0.3`.

docs/rancher/harvester-ui-extension.md

@@ -34,6 +34,7 @@ Versions of the Harvester operating system and the Harvester UI Extension will a
 | v1.4.2                    | v1.0.4                          | Rancher 2.10.1             |
 | v1.5.0                    | v1.5.0                          | Rancher 2.11.0             |
 
+Installing the extension over the network is not possible in air-gapped environments, so you must perform the workaround outlined in [Harvester UI Extension with Rancher Integration](/v1.5/airgap#harvester-ui-extension-with-rancher-integration).
 
 ## Installation on Rancher 2.10
 

static/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-01.png

@@ -76,3 +76,97 @@ ssh rancher@<harvester-node-ip>
 sudo -i
 docker load -i /tmp/rancher-agent-<version>.tar
 ```
+
+## Harvester UI extension with Rancher Integration
+
+The Harvester UI Extension is required to access the Harvester UI in Rancher v2.10.x and later versions. However, installing the extension over the network is not possible in air-gapped environments, so you must perform the following workaround:
+
+
+
+1. Pull the image [rancher/ui-plugin-catalog](https://hub.docker.com/r/rancher/ui-plugin-catalog/tags) with the newest tag.
+
+1. On the Rancher UI, go to **Extensions**, and then select **⋮ > Manage Extension Catalogs**.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-01.png)
+
+1. Specify the required information.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-02.png)
+
+    - **Catalog Image Reference**: Specify the private registry URL and image repository.
+    - **Image Pull Secrets**: Specify the secret used to access the registry when a username and password are required. You must create that secret in the `cattle-ui-plugin-system` namespace. Use either `kubernetes.io/dockercfg` or `kubernetes.io/dockerconfigjson` as the value of `type`.
+      Example:
+
+      ```yaml
+      apiVersion: v1
+      kind: Secret
+      metadata:
+        name: my-registry-secret-rancher
+        namespace: cattle-ui-plugin-system
+      type: kubernetes.io/dockerconfigjson
+      data:
+        .dockerconfigjson: {base64 encoded data}
+      ```
+
+1. Click **Load**, and then allow some time for the extension to be loaded.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-03.png)
+
+1. On the **Available** tab, locate the extension named **Harvester**, and then click **Install**.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04.png)
+
+1. Select the version that matches the Harvester cluster, and then click **Install**.
+
+  For more information, see the [Harvester UI Extension Support Matrix](/v1.3/rancher/harvester-ui-extension/#support-matrix).
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-05.png)
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-06.png) 
+
+1. Go to **Virtualization Management > Harvester Clusters**.
+
+  You can now import Harvester clusters and access the Harvester UI.
+
+  ![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-07.png)
+
+
+## Troubleshooting
+
+### UI Extensions Do Not Appear
+
+If the **Extensions** screen is empty, go to **Repositories** (**⋮ > Manage Repositories**) and then click **Refresh**.
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04-01.png)
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04-02.png)
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04-03.png)
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-04-04.png)
+
+### Installation Failed
+
+If you encounter an error during installation, check the `uiplugins` resource.
+
+![](/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-05-01.png)
+
+Example:
+
+```
+bash-4.4# k get uiplugins -A
+NAMESPACE                 NAME        PLUGIN NAME   VERSION   STATE
+cattle-ui-plugin-system   harvester   harvester     1.0.3     pending
+bash-4.4# k get uiplugins harvester --namespace cattle-ui-plugin-system -o yaml
+apiVersion: catalog.cattle.io/v1
+kind: UIPlugin
+metadata:
+  # skip
+  name: harvester
+  namespace: cattle-ui-plugin-system
+spec:
+  plugin:
+    endpoint: http://ui-plugin-catalog-svc.cattle-ui-plugin-system:8080/plugin/harvester-1.0.3
+```
+
+Ensure that `svc.namespace` is accessible from Rancher. If that endpoint is not accessible, you can directly use a cluster IP such as `10.43.33.58:8080/plugin/harvester-1.0.3`.

static/img/v1.5/air-gapped/air-gappted-harvester-ui-extension-02.png

@@ -0,0 +1,111 @@
+---
+sidebar_position: 9
+sidebar_label: Harvester UI Extension
+title: Harvester UI Extension
+keywords:
+  - Harvester
+  - harvester
+  - Harvester UI Extension
+  - Rancher Integration
+---
+
+<head>
+  <link rel="canonical" href="https://docs.harvesterhci.io/v1.4/rancher/rancher-integration"/>
+</head>
+
+
+Rancher 2.10.0 and later versions integrate with Harvester using the [Harvester UI Extension](https://github.com/harvester/harvester-ui-extension), which is built on the[@rancher/shell](https://www.npmjs.com/package/@rancher/shell) library.
+
+:::note
+The current [Harvester UI](https://github.com/harvester/dashboard) will continue to support Harvester v1.3.x and v1.4.x releases. New features in later releases will be implemented in the Harvester UI Extension.
+:::
+
+
+
+## Support Matrix
+
+Versions of the Harvester operating system and the Harvester UI Extension will align starting with v1.5.0.
+
+
+| Harvester Cluster         | Harvester UI Extension          | Minimum supported Rancher  |
+| --------------------------| ------------------------------- | ------------------------   |
+| v1.3.0, v1.3.1,  v1.3.2   | v1.0.2                          | Rancher 2.10.1             |
+
+Installing the extension over the network is not possible in air-gapped environments, so you must perform the workaround outlined in [Harvester UI Extension with Rancher Integration](/v1.3/airgap#harvester-ui-extension-with-rancher-integration).
+
+## Installation on Rancher 2.10
+
+### Automatic Installation
+
+You can install the Harvester UI Extension with a single click.
+
+1. On the Rancher UI, go to **Virtualization Management**.
+    ![](/img/v1.5/rancher/auto-install-ui-extension.png)
+
+1. On the **Harvester Clusters** tab, click **Install**.
+  
+    Allow some time for the extension to be installed. The screen is automatically refreshed once the installation is completed.
+
+    :::info important
+    Do not navigate away from the screen during the installation process.
+    :::
+
+    ![](/img/v1.5/rancher/auto-install-ui-extension.png)
+
+
+### Manual Installation
+If the automatic installation fails, you can specify the Harvester UI Extension repository URL and then install the extension.
+
+![](/img/v1.5/rancher/ui-extension-install-failed.png)
+
+1. On the Rancher UI, go to **local > Apps > Repositories**, and then click **Create**.
+
+  ![](/img/v1.5/rancher/ui-extension-app-repository-setup.png)
+
+1. Configure the following settings:
+    - Name: Specify a name for the repository.
+    - Target: Select **Git repository containing Helm chart or cluster template definitions**.
+    - Git Repo URL: Specify **https://github.com/harvester/harvester-ui-extension**.
+    - Git Branch: Specify **gh-pages**.
+
+2. Click **Create**.
+
+3. Go to **Extensions > Available**.
+  ![](/img/v1.5/rancher/ui-extension-available-tab.png)
+
+4. Locate the extension named **Harvester**, and then click **Install**.
+
+
+## Upgrades
+
+### Automatic Upgrade
+
+The **Update** button appears whenever a new version of the extension is available.
+
+1. On the Rancher UI, go to **Virtualization Management**.
+
+    ![](/img/v1.5/rancher/ui-extension-update.png)
+
+1. Click **Update**.
+    Allow some time for the extension to be upgraded. The screen is automatically refreshed once the upgrade is completed.
+
+### Manual Upgrades
+
+1. On the Rancher UI, go to **local > Apps > Repositories**.
+
+1. Locate the repository with the following settings, and then select **⋮ > Refresh**.
+
+    - URL: **https://github.com/harvester/harvester-ui-extension**
+    - Branch: **gh-pages**
+
+    ![](/img/v1.4/upgrade/rancher-2.10.1-repository-page.png)
+
+1. Go to **Extensions > Installed**.
+
+1. Locate the extension named **Harvester**, and then click **Update**.
+
+1. Select the new version, and then click **Update**.
+
+    ![](/img/v1.4/upgrade/update-harvester-ui-extension-modal.png)
+
+1. Allow some time for the extension to be upgraded, and then refresh the screen.