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
- 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.
- Plugin management requires administrator access. Installing, disabling, uninstalling, and configuring the catalog require KubeOsprey administrator permissions. Regular users can only use enabled plugins.
- 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.
- 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
- Click your avatar in the upper right corner and select Plugin management. This option is only visible to administrators.
- Go to Settings → General, enter the
catalog.jsonURL under Plugin catalog, and save. Leave it empty to use the default catalog of the upstream Kite plugin ecosystem athttps://plugins.kitehq.dev/catalog.json. - Return to Plugin management, select a plugin in the Plugin catalog, and click Install. Click a plugin's name to preview its README.
- 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.
| Repository | Purpose |
|---|---|
| kube-osprey | Host 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
- Quick Start: create and install a plugin from scratch
- Plugin Configuration: configure pages, menus, resource extensions, themes, a settings page, and internationalization
- Resource Queries and Operations: query and modify Kubernetes resources
- Internationalization: support multiple languages
- Debugging: development workflow and troubleshooting
- Publishing Plugins: distribute plugins, host your own catalog, or contribute to the upstream Kite catalog