From c59164ac5cf5f7b720863bbed66da00d9809c816 Mon Sep 17 00:00:00 2001 From: martyav Date: Fri, 5 Apr 2024 11:04:41 -0400 Subject: [PATCH 1/5] Include documentation on how to make UI extensions work in airgap mode in the official Rancher Docs --- .../rancher-extensions.md | 71 ++++++++++++++++++- 1 file changed, 69 insertions(+), 2 deletions(-) diff --git a/docs/integrations-in-rancher/rancher-extensions.md b/docs/integrations-in-rancher/rancher-extensions.md index 2c56082fc53..499d0f81711 100644 --- a/docs/integrations-in-rancher/rancher-extensions.md +++ b/docs/integrations-in-rancher/rancher-extensions.md @@ -53,9 +53,76 @@ In v2.7.0, the built-in extensions aren't displayed under the **Available** tab. ![Reload button](/img/reload-button.png) -### Importing and Installing Extensions in an Air-Gapped Environment +### Accessing Rancher UI Extensions in Air-Gapped Environments -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. +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. If you're trying to install these extensions in an air-gapped environment, you must make the `ui-plugin-catalog` accessible. + +1. Mirror the `ui-plugin-catalog` image to a private registry: +```bash +export REGISTRY_ENDPOINT="my-private-registry.com" +docker pull rancher/ui-plugin-catalog:1.0.0 +docker tag rancher/ui-plugin-catalog:1.0.0 $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 +docker push $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 +``` +1. Use the mirrored image to create a Kubernetes [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/): +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: ui-plugin-catalog + namespace: cattle-ui-plugin-system + labels: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog +spec: + replicas: 1 + selector: + matchLabels: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + template: + metadata: + namespace: cattle-ui-plugin-system + labels: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + spec: + containers: + - name: server + image: my-private-registry.com/rancher/ui-plugin-catalog:1.0.0 + imagePullPolicy: Always + imagePullSecrets: + - name: my-registry-credentials +``` +1. Expose the deployment by creating a [ClusterIP service](https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip): +```yaml +apiVersion: v1 +kind: Service +metadata: + name: ui-plugin-catalog-svc + namespace: cattle-ui-plugin-system +spec: + ports: + - name: catalog-svc-port + port: 8080 + protocol: TCP + targetPort: 8080 + selector: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + type: ClusterIP +``` +1. Create a [ClusterRepo](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) that targets the ClusterIP service: +```yaml +apiVersion: catalog.cattle.io/v1 +kind: ClusterRepo +metadata: + name: ui-plugin-catalog-repo +spec: + url: http://ui-plugin-catalog-svc.cattle-ui-plugin-system:8080 +``` + +After you successfully set up these resources, you can install the extensions from the `ui-plugin-charts` manifest into your air-gapped environment. + +### 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. From 3bd7e533e80cdc0b12c8505ed0a2fea7da4c7e6e Mon Sep 17 00:00:00 2001 From: martyav Date: Fri, 5 Apr 2024 11:31:19 -0400 Subject: [PATCH 2/5] reorganize air-gapped subsections into single parent section --- .../rancher-extensions.md | 104 +++++++++--------- 1 file changed, 54 insertions(+), 50 deletions(-) diff --git a/docs/integrations-in-rancher/rancher-extensions.md b/docs/integrations-in-rancher/rancher-extensions.md index 499d0f81711..e3c29b18a3b 100644 --- a/docs/integrations-in-rancher/rancher-extensions.md +++ b/docs/integrations-in-rancher/rancher-extensions.md @@ -53,7 +53,60 @@ In v2.7.0, the built-in extensions aren't displayed under the **Available** tab. ![Reload button](/img/reload-button.png) -### Accessing Rancher UI Extensions in Air-Gapped Environments +## Updating and Upgrading Extensions + +1. Click **☰ > Extensions** under **Configuration**. +1. Select the **Updates** tab. +1. 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 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**. + +## 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) + +1. On the extensions management page, click **⋮ > Disable Extension Support**. This will disable all installed extensions. + + ![Disable extensions](/img/disable-extension-support.png) + +:::caution + +You must reload the page after disabling extensions or display issues may occur. + +::: + +## 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. + +## Working with Extensions in an Air-gapped Environment + +If you intend to work with extensions in an air-gapped environment, you must perform some extra steps before you can complete certain tasks. + +### Accessing Rancher UI Extensions in an Air-Gapped Environment 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. If you're trying to install these extensions in an air-gapped environment, you must make the `ui-plugin-catalog` accessible. @@ -144,32 +197,6 @@ After you successfully set up these resources, you can install the extensions fr 1. Find the extension you just added, and click the **Install** button. -## 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) - -1. On the extensions management page, click **⋮ > Disable Extension Support**. This will disable all installed extensions. - - ![Disable extensions](/img/disable-extension-support.png) - -:::caution - -You must reload the page after disabling extensions or display issues may occur. - -::: - -## Updating and Upgrading Extensions - -1. Click **☰ > Extensions** under **Configuration**. -1. Select the **Updates** tab. -1. 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. - ### Updating and Upgrading an Extensions Repository in an Air-gapped Environment Extensions repositories that aren't air-gapped are automatically updated. If the repository is air-gapped, you must update it manually. @@ -186,26 +213,3 @@ After you mirror the latest changes, follow these steps: 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 - -To learn how to develop your own extensions, refer to the official [Getting Started](https://rancher.github.io/dashboard/extensions/extensions-getting-started) guide. From 35702127cb7c91ac85007aa35050f226bc820fde Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Fri, 5 Apr 2024 13:38:17 -0400 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Lucas Saintarbor --- .../rancher-extensions.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/integrations-in-rancher/rancher-extensions.md b/docs/integrations-in-rancher/rancher-extensions.md index e3c29b18a3b..55e48ea9aeb 100644 --- a/docs/integrations-in-rancher/rancher-extensions.md +++ b/docs/integrations-in-rancher/rancher-extensions.md @@ -78,7 +78,7 @@ If there is a new version of the extension, there will also be an **Update** but 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**. +1. Find the name of the container image you want to delete, then click **⋮ > Uninstall**. ## Uninstalling Extensions @@ -111,12 +111,12 @@ If you intend to work with extensions in an air-gapped environment, you must per 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. If you're trying to install these extensions in an air-gapped environment, you must make the `ui-plugin-catalog` accessible. 1. Mirror the `ui-plugin-catalog` image to a private registry: -```bash -export REGISTRY_ENDPOINT="my-private-registry.com" -docker pull rancher/ui-plugin-catalog:1.0.0 -docker tag rancher/ui-plugin-catalog:1.0.0 $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 -docker push $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 -``` + + ```bash + export REGISTRY_ENDPOINT="my-private-registry.com" + docker pull rancher/ui-plugin-catalog:1.0.0 + docker tag rancher/ui-plugin-catalog:1.0.0 $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 + docker push $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 1. Use the mirrored image to create a Kubernetes [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/): ```yaml apiVersion: apps/v1 @@ -187,7 +187,7 @@ After you successfully set up these resources, you can install the extensions fr 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. + * **(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**. From ebdaa578d2b7bedd248472e3f40ae21a079dcc5d Mon Sep 17 00:00:00 2001 From: martyav Date: Fri, 5 Apr 2024 13:50:54 -0400 Subject: [PATCH 4/5] spacing --- .../rancher-extensions.md | 112 ++++++++---------- 1 file changed, 51 insertions(+), 61 deletions(-) diff --git a/docs/integrations-in-rancher/rancher-extensions.md b/docs/integrations-in-rancher/rancher-extensions.md index 55e48ea9aeb..ea732372654 100644 --- a/docs/integrations-in-rancher/rancher-extensions.md +++ b/docs/integrations-in-rancher/rancher-extensions.md @@ -117,84 +117,74 @@ Rancher provides some extensions, such as Kubewarden and Elemental, through the docker pull rancher/ui-plugin-catalog:1.0.0 docker tag rancher/ui-plugin-catalog:1.0.0 $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 docker push $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 -1. Use the mirrored image to create a Kubernetes [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/): -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ui-plugin-catalog - namespace: cattle-ui-plugin-system - labels: - catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog -spec: - replicas: 1 - selector: - matchLabels: +2. Use the mirrored image to create a Kubernetes [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/): + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: ui-plugin-catalog + namespace: cattle-ui-plugin-system + labels: catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog - template: - metadata: - namespace: cattle-ui-plugin-system - labels: + spec: + replicas: 1 + selector: + matchLabels: catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog - spec: - containers: - - name: server - image: my-private-registry.com/rancher/ui-plugin-catalog:1.0.0 - imagePullPolicy: Always - imagePullSecrets: - - name: my-registry-credentials -``` -1. Expose the deployment by creating a [ClusterIP service](https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip): -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ui-plugin-catalog-svc - namespace: cattle-ui-plugin-system -spec: - ports: - - name: catalog-svc-port - port: 8080 - protocol: TCP - targetPort: 8080 - selector: - catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog - type: ClusterIP -``` -1. Create a [ClusterRepo](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) that targets the ClusterIP service: -```yaml -apiVersion: catalog.cattle.io/v1 -kind: ClusterRepo -metadata: - name: ui-plugin-catalog-repo -spec: - url: http://ui-plugin-catalog-svc.cattle-ui-plugin-system:8080 -``` + template: + metadata: + namespace: cattle-ui-plugin-system + labels: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + spec: + containers: + - name: server + image: my-private-registry.com/rancher/ui-plugin-catalog:1.0.0 + imagePullPolicy: Always + imagePullSecrets: + - name: my-registry-credentials + ``` +3. Expose the deployment by creating a [ClusterIP service](https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip): + ```yaml + apiVersion: v1 + kind: Service + metadata: + name: ui-plugin-catalog-svc + namespace: cattle-ui-plugin-system + spec: + ports: + - name: catalog-svc-port + port: 8080 + protocol: TCP + targetPort: 8080 + selector: + catalog.cattle.io/ui-extensions-catalog-image: ui-plugin-catalog + type: ClusterIP + ``` +4. Create a [ClusterRepo](../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md) that targets the ClusterIP service: + ```yaml + apiVersion: catalog.cattle.io/v1 + kind: ClusterRepo + metadata: + name: ui-plugin-catalog-repo + spec: + url: http://ui-plugin-catalog-svc.cattle-ui-plugin-system:8080 + ``` After you successfully set up these resources, you can install the extensions from the `ui-plugin-charts` manifest into your air-gapped environment. ### 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. - 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. ### Updating and Upgrading an Extensions Repository in an Air-gapped Environment From 7cb319d340191d89b3449602b66bd3ec19cf2162 Mon Sep 17 00:00:00 2001 From: Marty Hernandez Avedon Date: Fri, 5 Apr 2024 15:56:51 -0400 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Billy Tat Co-authored-by: Lucas Saintarbor --- .../rancher-extensions.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/integrations-in-rancher/rancher-extensions.md b/docs/integrations-in-rancher/rancher-extensions.md index ea732372654..18fa4f2e549 100644 --- a/docs/integrations-in-rancher/rancher-extensions.md +++ b/docs/integrations-in-rancher/rancher-extensions.md @@ -61,7 +61,7 @@ In v2.7.0, the built-in extensions aren't displayed under the **Available** tab. 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 Helm Charts +## Deleting Extensions 1. Click **☰**, then click on the name of your local cluster. 1. From the sidebar, select **Apps > Installed Apps**. @@ -108,15 +108,15 @@ If you intend to work with extensions in an air-gapped environment, you must per ### Accessing Rancher UI Extensions in an Air-Gapped Environment -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. If you're trying to install these extensions in an air-gapped environment, you must make the `ui-plugin-catalog` accessible. +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. If you're trying to install these extensions in an air-gapped environment, you must make the `ui-plugin-catalog` image accessible. 1. Mirror the `ui-plugin-catalog` image to a private registry: ```bash - export REGISTRY_ENDPOINT="my-private-registry.com" - docker pull rancher/ui-plugin-catalog:1.0.0 - docker tag rancher/ui-plugin-catalog:1.0.0 $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 - docker push $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog:1.0.0 + export REGISTRY_ENDPOINT= # e.g. "my-private-registry.com" + docker pull rancher/ui-plugin-catalog: + docker tag rancher/ui-plugin-catalog: $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog: + docker push $REGISTRY_ENDPOINT/rancher/ui-plugin-catalog: 2. Use the mirrored image to create a Kubernetes [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/): ```yaml apiVersion: apps/v1 @@ -139,10 +139,10 @@ Rancher provides some extensions, such as Kubewarden and Elemental, through the spec: containers: - name: server - image: my-private-registry.com/rancher/ui-plugin-catalog:1.0.0 + image: /rancher/ui-plugin-catalog: imagePullPolicy: Always imagePullSecrets: - - name: my-registry-credentials + - name: ``` 3. Expose the deployment by creating a [ClusterIP service](https://kubernetes.io/docs/concepts/services-networking/service/#type-clusterip): ```yaml @@ -176,7 +176,7 @@ 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. @@ -184,8 +184,8 @@ After you successfully set up these resources, you can install the extensions fr * **(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. +1. Select the **Available** tab, and click **Reload** to make sure that the list of extensions is up to date. +1. Find the extension you just added, and click **Install**. ### Updating and Upgrading an Extensions Repository in an Air-gapped Environment