Skip to content
HomeGetting StartedIntroduction to Plugins

Introduction to Plugins ​

Plugins are available starting with KubeOsprey v0.16.0.

A KubeOsprey plugin is a React frontend module that runs inside KubeOsprey. It can add pages, sidebar menus, and dedicated management interfaces for custom resources without rebuilding KubeOsprey.

Plugins are written and built with @kite-dev/plugin-sdk, packaged as .tar.gz archives, and installed by a KubeOsprey administrator on the Plugin management page. Once installed and enabled, they are available to all signed-in users.

What Plugins Can Do ​

  • Register pages and routes
  • Register sidebar menus
  • Extend resource lists and details
  • Provide custom resource pages
  • Provide color themes
  • Provide plugin settings pages

The cert-manager plugin from the upstream Kite ecosystem is a typical example. It provides management interfaces for custom resources such as Certificate, Issuer, CertificateRequest, Order, and Challenge, including resource lists, detail pages, status badges, and YAML editing.

What Plugins Cannot Do ​

  • Run backend code. Plugins contain only frontend modules. They cannot register new backend APIs or extend Kubernetes controller or operator behavior.

Runtime and Security Model ​

  1. Plugins run as the signed-in user. All Kubernetes requests from plugins go through the KubeOsprey backend and are subject to that user's RBAC permissions. Users cannot access resources they are not authorized to see, just as on native KubeOsprey pages. Plugins receive no additional permissions.
  2. Plugin management requires administrator access. Installing, disabling, uninstalling, and configuring the catalog require KubeOsprey administrator permissions. Regular users can only use enabled plugins.
  3. Plugins are trusted code. Plugin JavaScript executes in your browser with the same capabilities you have in KubeOsprey. Only install plugins from authors you trust.
  4. The runtime is shared. Plugins and KubeOsprey share React, React Router, TanStack Query, and SDK implementations. Do not create another React root, Router, or QueryClient.

Use host capabilities through @kite-dev/plugin-sdk. Do not import KubeOsprey's internal modules directly.

Installing and Using Plugins ​

  1. Click your avatar in the upper right corner and select Plugin management. This option is only visible to administrators.
  2. Go to Settings → General, enter the catalog.json URL under Plugin catalog, and save. Leave it empty to use the default catalog of the upstream Kite plugin ecosystem at https://plugins.kitehq.dev/catalog.json.
  3. Return to Plugin management, select a plugin in the Plugin catalog, and click Install. Click a plugin's name to preview its README.
  4. Open the plugin from the sidebar. Newly installed plugins are enabled automatically.

You can also use Install from file to upload a plugin's .tar.gz archive directly. Under Installed plugins, you can disable, enable, or uninstall a plugin.

Plugin persistence

The Helm Chart stores plugins in /data/plugins. Enabling SQLite persistence also preserves plugins with the default paths; MySQL/PostgreSQL deployments need separate plugin storage. Without persistent storage, recreating the Pod loses plugin files: plugins installed from a catalog are downloaded again, while manually uploaded plugins must be uploaded again. Automatic downloads require the installation records in the database to be preserved. See Plugin Storage for configuration.

Plugin Ecosystem ​

KubeOsprey is compatible with the upstream Kite plugin ecosystem: plugins built with the SDK install and run unchanged in KubeOsprey. The SDK, the scaffolding tool, the official plugins, and the default plugin catalog are maintained by the upstream kite-org/kite-plugins repository. The KubeOsprey host application lives at fadewalk/kube-osprey.

RepositoryPurpose
kube-ospreyHost application: plugin loading, asset serving, and management APIs
kite-plugins (upstream Kite)SDK, scaffolding tool, official plugins, and plugin catalog; the SDK is in packages/plugin-sdk

Next Steps ​

Released under the Apache License.