#773: Add steps to install Rancher Extensions in an air-gapped environment (#807)

* Add steps to install Rancher Extensions in an air-gapped environment * added link from install guide * added notes to import/install steps as suggested by rohitsakala * minor copyedits * updating extensions explicitly given own section * tightened up note * updated note for v2.7 * ensuring all 3 versions have same text * versioning install-rancher-ha * del extension repos + (partially) upgrade * fixed comment syntax * Apply suggestions from code review Co-authored-by: Billy Tat <btat@suse.com> * Apply suggestions from code review * completed update instructions * no dropdown, text input * more explanation + delete * Apply suggestions from code review * extensions repo container image delete * versioning * revert changes to v2.7 --------- Co-authored-by: Billy Tat <btat@suse.com>
2026-09-25 12:38:05 +00:00 · 2023-12-06 14:48:47 -05:00
parent 03ea6163fb
commit 3d8918839e
4 changed files with 132 additions and 18 deletions
@@ -245,6 +245,7 @@ If you don't intend to send telemetry data, opt out [telemetry](../../../../faq/

 These resources could be helpful when installing Rancher:

+- [Importing and installing extensions in an air-gapped environment](../../../../integrations-in-rancher/rancher-extensions.md#importing-and-installing-extensions-in-an-air-gapped-environment)
 - [Rancher Helm chart options](../../installation-references/helm-chart-options.md)
 - [Adding TLS secrets](../../resources/add-tls-secrets.md)
 - [Troubleshooting Rancher Kubernetes Installations](../../install-upgrade-on-a-kubernetes-cluster/troubleshooting.md)
@@ -30,7 +30,7 @@ Examples of built-in Rancher extensions are Fleet, Explorer, and Harvester. Exam

 :::info

-In v2.7.0, the built-in extensions will not be displayed under the **Available** tab. Therefore, you will need to manually add the desired repos to install extensions. We will update the community once these extensions have been pulled out to be available for selection.
+In v2.7.0, the built-in extensions aren't displayed under the **Available** tab. Therefore, you'll need to manually add the desired repos to install extensions.

 :::
 <br/>
@@ -45,7 +45,7 @@ In v2.7.0, the built-in extensions will not be displayed under the **Available**

    ![Manage repositories](/img/manage-repos.png)

-5. Under the **Available** tab, click **Install** on the desired extension and version as in the example below. Note that you can easily update your extension as the button to **Update** will appear on the extension if one is available.
+5. Under the **Available** tab, click **Install** on the desired extension and version as in the example below. You can also update your extension from this screen, as the button to **Update** will appear on the extension if one is available.

    ![Install Kubewarden](/img/install-kubewarden.png)

@@ -53,9 +53,33 @@ In v2.7.0, the built-in extensions will not be displayed under the **Available**

    ![Reload button](/img/reload-button.png)

+### Importing and Installing Extensions in an Air-Gapped Environment
+
+1. Find the address of the container image repository  that you want to import as an extension. Rancher provides some extensions, such as Kubewarden and Elemental, through the `ui-plugin-catalog` container image at https://hub.docker.com/r/rancher/ui-plugin-catalog/tags. You should import and use the latest tagged version of the image to ensure you receive the latest features and security updates.
+
+    * **(Optional)** If the container image is private: [Create](../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md) a registry secret within the `cattle-ui-plugin-system` namespace. Enter the domain of the image address in the **Registry Domain Name** field.
+
+1. Click **☰**, then select **Extensions**, under **Configuration**.
+
+1. On the top right, click **⋮ > Manage Extension Catalogs**.
+
+1. Select the **Import Extension Catalog** button.
+
+1. Enter the image address in the **Catalog Image Reference** field. 
+
+    * **(Optional)** If the container image is private: Select the secret you just created from the **Pull Secrets** drop-down menu.
+
+1. Click **Load**. The extension will now be **Pending**.
+
+1. Return to the **Extensions** page.
+
+1. Select the **Available** tab, and click the **Reload** button to make sure that the list of extensions is up to date.
+
+1. Find the extension you just added, and click the **Install** button.
+
 ## Uninstalling Extensions

-There are two ways in which you can uninstall or disable your extensions:
+There are two ways to uninstall or disable an extension:

 1. Under the **Installed** tab, click the **Uninstall** button on the extension you wish to remove.

@@ -71,17 +95,49 @@ You must reload the page after disabling extensions or display issues may occur.

 :::

-## Rolling Back Extensions
+## Updating and Upgrading Extensions

-Under the **Installed** tab, click the **Rollback** button on the extension you wish to roll back.
+1. Click **☰ > Extensions** under **Configuration**.
+1. Select the **Updates** tab. 
+1. Click **Update**.

-![Roll back extensions](/img/roll-back-extension.png)
+If there is a new version of the extension, there will also be an **Update** button visible on the associated card for the extension in the **Available** tab.

-:::caution
+### Updating and Upgrading an Extensions Repository in an Air-gapped Environment

-You must reload the page after rolling back extensions or display issues may occur.
+Extensions repositories that aren't air-gapped are automatically updated. If the repository is air-gapped, you must update it manually.

-:::
+First, mirror the latest changes to your private registry by following the same steps for initially [importing and installing an extension repository](#importing-and-installing-extensions-in-an-air-gapped-environment).
+
+After you mirror the latest changes, follow these steps:
+
+1. Click **☰ > Local**.
+1. From the sidebar, select **Workloads > Deployments**.
+1. From the namespaces dropdown menu, select **cattle-ui-plugin-system**.
+1. Find the **cattle-ui-plugin-system** namespace. 
+1. Select the `ui-plugin-catalog` deployment.
+1. Click **⋮ > Edit config**.
+1. Update the **Container Image** field within the deployment's container with the latest image.
+1. Click **Save**.
+
+## Deleting Helm Charts
+
+1. Click **☰**, then click on the name of your local cluster.
+1. From the sidebar, select **Apps > Installed Apps**.
+1. Find the name of the chart you want to delete and select the checkbox next to it. 
+1. Click **Delete**.
+
+## Deleting Extension Repositories
+
+1. Click **☰ > Extensions** under **Configuration**.
+1. On the top right, click **⋮ > Manage Repositories**.
+1. Find the name of the extension repository you want to delete. Select the checkbox next to the repository name, then click **Delete**.
+
+## Deleting Extension Repository Container Images
+
+1. Click **☰**, then select **Extensions**, under **Configuration**.
+1. On the top right, click **⋮ > Manage Extension Catalogs**.
+1. Find the name of the container image you want to delete. Click **⋮ > Uninstall**.

 ## Developing Extensions