Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

updating extensions doc to match versioned_docs/version-2.9 #1511

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

updating extensions doc to match versioned_docs/version-2.9 #1511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 48 additions & 32 deletions docs/integrations-in-rancher/rancher-extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,83 +14,99 @@ Examples of built-in Rancher extensions are Fleet, Explorer, and Harvester. Exam

## Prerequisites

> You must log in as an admin in order to view and interact with the extensions management page.
> 1. You must log in as an administrator to view and interact with the extensions management page.
> 2. You must enable extension support.

## Installing Extensions
## Enabling Extension Support in Rancher

1. Click **☰ > Extensions** under **Configuration**.
Rancher v2.9.0 and later includes extension support.

You can confirm if extension support is enabled by checking the `uiextension` feature flag. Any changes to this feature flag cause the Rancher pod to restart.

When you enable extension support for the first time, it creates resources, such as the CRDs, so that UI Extensions can work. When extension support is disabled, it disables the endpoints and does not cache any files. However, it does not remove any CRs or delete any extensions that were installed before. If re-enabled, it exposes the required endpoints again and creates CRDs as needed. The extensions that were already installed load after the Rancher pod restarts.

2. If not already installed in **Apps**, you must enable the extension operator by clicking the **Enable** button.
### Caching Extension Files

- Click **OK** to add the Rancher extension repository if your installation is not air-gapped. Otherwise, uncheck the box to do so and click **OK**.
By default, Rancher caches every extension file in the file system. You can change that behavior by setting `plugin.noCache` to `true`.

![Rancher extension repository](/img/add-rancher-extension-repo.png)
Rancher does have a cached file size limit of 30MB. If an extension has a file bigger than that, the cache is disabled and `plugin.noCache` is set to `true`, regardless of user input.

3. On the **Extensions** page, click on the **Available** tab to select which extensions you want to install.

4. If no extensions are showing as available, you may manually add repos as follows:
## Installing Extensions

1. Click **☰ > Extensions** under **Configuration**.

4.1. On the upper right of screen, click on **⋮ > Manage Repositories > Create**.
2. On the **Extensions** page, select the **Available** tab to choose the extensions that you want to install.

4.2. Add the desired repo name, making sure to also specify the Git Repo URL and the Git Branch.
3. If no extensions are listed as available, you can manually add the repos:

4.3. Click **Create** in the lower right again to complete.
3.1. On the upper right, click **⋮ > Manage Repositories > Create**.

![Manage repositories](/img/manage-repos.png)
3.2. Add the desired repo name, making sure to also specify the Git repo URL and the Git branch.

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.
3.3. Click **Create** in the lower right again to complete.

![Install Kubewarden](/img/install-kubewarden.png)
![Manage repositories](/img/manage-repos.png)

6. Click the **Reload** page button that will appear after your extension successfully installs. Note that a logged-in user who has just installed an extension will not see a change to the UI **unless** they reload the page.
4. 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. The button to **Update** appears on the extension card if an update is available.

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

5. Click **Reload** after your extension successfully installs to check its status. Updates to the UI aren't visible until you reload the page.

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

## Updating and Upgrading Extensions

1. Click **☰ > Extensions** under **Configuration**.
1. Select the **Updates** tab.
1. Click **Update**.
2. Select the **Updates** tab.
3. Click **Update**.

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.

## Deleting Extensions

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**.
2. From the sidebar, select **Apps > Installed Apps**.
3. Find the name of the chart you want to delete and select the checkbox next to it.
4. 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**.
2. On the top right, click **⋮ > Manage Repositories**.
3. 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, then click **⋮ > Uninstall**.
2. On the top right, click **⋮ > Manage Extension Catalogs**.
3. Find the name of the container image you want to delete, then click **⋮ > Uninstall**.

## Uninstalling 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.

![Uninstall extensions](/img/uninstall-extension.png)
![Uninstall extensions](/img/uninstall-extension.png)

1. On the extensions management page, click **⋮ > Disable Extension Support**. This will disable all installed extensions.
2. On the extensions management page, click **⋮ > Disable Extension Support**. This will disable all installed extensions.

![Disable extensions](/img/disable-extension-support.png)
![Disable extensions](/img/disable-extension-support.png)

:::caution

You must reload the page after disabling extensions or display issues may occur.

:::

## Enabling Unauthenticated Access to an Extension

In Rancher v2.9.0 and later, you can allow unauthenticated access to an extension. You may want to enable unauthenticated access if the extension enables a new locale or adds custom branding. By default, all extensions require user authentication to load.

To enable unauthenticated access to an extension, set `plugin.noAuth` to `true` in the CR used by the extension.

## Developing Extensions

To learn how to develop your own extensions, refer to the official [Getting Started](https://rancher.github.io/dashboard/extensions/extensions-getting-started) guide.
Expand Down Expand Up @@ -169,12 +185,12 @@ After you successfully set up these resources, you can install the extensions fr
### 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. 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.
- **(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. 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 **Reload** to make sure that the list of extensions is up to date.
Expand All @@ -191,7 +207,7 @@ 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. 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.
Expand Down
3 changes: 2 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,5 +49,6 @@
"last 1 firefox version",
"last 1 safari version"
]
}
},
"packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
}