Skip to main content
Version: 1.10

Rancher UI extension quickstart

This section describes how to install the Kubewarden UI as an extension of Rancher Manager.


This requires a running instance of Rancher Manager v2.7.0 or greater.

Install Kubewarden UI Extension

The Kubewarden UI is installed as a global extension, however, the Kubewarden controller will be installed through the Rancher UI as a cluster scoped resource.


For air-gapped installations, follow these steps.

Within the Extensions page, click on the "Enable" button and select the option to add the Rancher Extensions Repository. Once enabled the "Kubewarden" extension item will appear automatically. Click on this item to install the extension. Once installed, you will then be able to install Kubewarden into your desired Cluster.

Install Kubewarden

Within your cluster a new menu item will appear in the side-menu for Kubewarden, this dashboard page will guide you through the installation process by completing some prerequisites.


During the "App Install" step of the installation wizard, the "Install Kubewarden" button may remain grayed out. If this is the case, just refresh the page and navigate back to this step.


After the installation is complete the dashboard page and side menu will contain new items, namely Policy Servers, Cluster Admission Policies, and Admission Policies. From here you can create Policy Servers and Policies to control behavior within your cluster.

Dashboard view UI Dashboard

Enabling the default Policy Server and policies

Within the dashboard page you can follow the "Install Chart" button to install the kubewarden-defaults Helm chart, which includes the default Policy Server and a few currated policies.

After installing the chart you can view the default Policy Server details with the related policies in a sortable table.

Policy Server detail view UI PolicyServer Detail

Creating Policies

When creating policies you will initially be given a "Custom Policy" option from the Policy Grid. Provide the required information for your policy's Name, Module, and Rules.

Creating a custom policy UI Policy Whitelist

If you wish to leverage policies from ArtifactHub you will need to add to the setting. This allows your Rancher instance to retieve package information from ArtifactHub. Use the "Add ArtifactHub To Whitelist" button to automatically add the domain, the Policy Grid will refresh with the fetched policies.

ArtifactHub whitelist banner UI Policy Whitelist

Policy Grid UI Policy Create

Additional Features

For installing additional features, follow the instructions in these docs to include Metrics or Tracing.

Airgap Installation


This requires Rancher Manager version v2.8.0 or greater.

As Kubewarden is considered a Rancher Official Extension, the Rancher team provides a mechanism to automatically generate an Extension Catalog Image. This will be added to the rancher-images.txt file when installing Rancher Manager for air-gapped instances.

Once this image has been mirrored to a registry that is accessible to your air-gapped cluster, you will be able to import the image within the Rancher UI. This creates a local Helm repository with the Kubewarden UI chart for installation.

Installation Steps

  1. Create a registry secret within the cattle-ui-plugin-system namespace. Enter the domain of the image address in the Registry Domain Name field.

  2. Navigate back to the Extensions page (for example, https://cluster-ip/dashboard/c/local/uiplugins).

  3. On the top right, click ⋮ > Manage Extension Catalogs. Manage Catalogs

  4. Select the Import Extension Catalog button. Import Catalogs

  5. Enter the image address in the Catalog Image Reference field.

  6. Select the secret you just created from the Pull Secrets drop-down menu. Enter Catalog Info

  7. Click Load. The extension will now be Pending.

  8. Return to the Extensions page.

  9. Select the Available tab, and click the Reload button to make sure that the list of extensions is up to date. Install Kubewarden

  10. Find the Kubewarden extension you just added, and click the Install button.