Plugin System & SDK
Relevant source files
The following files were used as context for generating this wiki page:
- apps/plugins/pkg/apis/plugins_manifest.go
- packages/grafana-data/src/types/plugin.ts
- packages/grafana-plugin-configs/webpack.config.ts
- pkg/plugins/plugins_test.go
- public/app/features/plugins/admin/pages/PluginDetails.test.tsx
- public/app/features/plugins/admin/components/PluginDetailsPage.test.tsx
- contribute/style-guides/frontend.md
The Plugin System and SDK provide the foundational architecture for extending Grafana's core functionality. This system allows developers to integrate new data sources, create custom visualizations (panels), and build comprehensive applications that run within the Grafana environment. The SDK defines the standard interfaces, metadata structures, and build configurations required for a plugin to be discovered, loaded, and executed by the Grafana server and frontend.
The system is designed around a strictly defined manifest and lifecycle, ensuring that plugins are securely signed, versioned, and managed. It supports various plugin types, including data sources, panels, apps, and renderers, each with specific requirements for backend logic and frontend presentation.
Sources: packages/grafana-data/src/types/plugin.ts:16-21, apps/plugins/pkg/apis/plugins_manifest.go:50-70
Plugin Architecture and Types
Grafana categorizes plugins into distinct types, each serving a specific role in the ecosystem. The core types are defined by the PluginType enum.
Core Plugin Types
| Type | Description |
|---|---|
panel | Custom visualizations for dashboards. |
datasource | Integrations that fetch data from external databases or APIs. |
app | Complex integrations that can include custom pages, dashboards, and multiple components. |
renderer | Service-side components used for rendering panels as images. |
Sources: packages/grafana-data/src/types/plugin.ts:16-21, pkg/plugins/plugins_test.go:44-50
Plugin Lifecycle States
Plugins move through various states during their lifecycle, which determines their visibility and availability in the UI.
- Alpha: Experimental features, only visible if explicitly enabled in configuration.
- Beta: Feature-complete but may contain bugs; displays a warning banner.
- Stable: Fully supported and recommended for production use.
- Deprecated: Continued functionality for existing installations but hidden from new selection lists.
Sources: packages/grafana-data/src/types/plugin.ts:7-13
Plugin Metadata and Manifests
The plugin.json file is the central manifest for every plugin. It contains metadata, dependency information, and configuration for how the plugin integrates with Grafana.
The Metadata Structure
The PluginMeta interface defines the properties required for a plugin to be registered. This includes the plugin's unique ID, module entry point, and base URL for assets.
The diagram shows the relationship between core plugin metadata and its associated info/dependency structures.
Sources: packages/grafana-data/src/types/plugin.ts:68-100
Signature and Security
Security is enforced through a signature system. Plugins are categorized by their signature status and type to indicate their origin and trustworthiness.
- Signature Statuses:
internal(core),valid(signed),invalid,modified(content mismatch), andmissing. - Signature Levels:
grafana,commercial,community,private, andcore.
Sources: packages/grafana-data/src/types/plugin.ts:24-40, public/app/features/plugins/admin/pages/PluginDetails.test.tsx:129-150
Plugin Build Configuration
The SDK provides a standardized Webpack configuration for bundling frontend assets. This configuration handles TypeScript transpilation, asset copying, and variable injection.
Webpack Integration
The build process utilizes webpack.config.ts to ensure plugins are compatible with Grafana's runtime environment. Key features include:
- Externals: Standard libraries like
react,lodash, and@grafana/dataare treated as externals to prevent bundling duplicates. - Build Mode Injection: The
BuildModeWebpackPluginautomatically adds the compilation mode (development/production) to theplugin.jsonin the distribution folder. - Template Replacement: Template variables such as
%VERSION%,%TODAY%, and%PLUGIN_ID%are replaced in theREADME.mdandplugin.json.
The diagram illustrates the transformation of source files and manifests into the final distribution package.
Sources: packages/grafana-plugin-configs/webpack.config.ts:32-60, packages/grafana-plugin-configs/webpack.config.ts:108-140
Extensions and Inclusion
Plugins can extend the Grafana UI through "includes" and "extensions."
Plugin Includes
Includes allow plugins to register dashboards, custom pages, or panels. These can be restricted by user roles (Admin, Editor, Viewer).
| Field | Type | Description |
|---|---|---|
type | PluginIncludeType | Type of resource (dashboard, page, panel, etc.). |
name | string | Human-readable name shown in navigation. |
role | string | Minimum role required to view the include. |
addToNav | boolean | Whether to add the item directly to the sidebar. |
Sources: packages/grafana-data/src/types/plugin.ts:167-190, pkg/plugins/plugins_test.go:81-86
UI Extensions
The modern extension system allows plugins to "hook" into specific targets within the Grafana UI, such as dashboard menus or user profile tabs.
- AddedLinks: Links added to specific menu targets.
- AddedComponents: React components rendered at specified extension points.
- ExposedComponents: Components a plugin makes available for other plugins to use.
Sources: packages/grafana-data/src/types/plugin.ts:140-165, pkg/plugins/plugins_test.go:142-178
Plugin Management and Administration
The Plugin Admin interface manages the installation, update, and uninstallation of plugins.
Installation Flow
Plugins can be installed from the Grafana Store (GCOM) or managed locally. The UI provides controls based on the plugin's status.
This flow illustrates how Grafana merges local installation data with remote registry data to provide install and update actions.
Sources: public/app/features/plugins/admin/pages/PluginDetails.test.tsx:75-90, public/app/features/plugins/admin/pages/PluginDetails.test.tsx:287-310
Admin Controls and Constraints
- Permissions: Only users with
isAdminorisOrgAdminpermissions can typically manage plugin installations. - Managed Plugins: Plugins marked as
managed(e.g., in cloud environments) may have install/update buttons disabled. - Core Plugins: Core plugins (built-in) cannot be uninstalled or updated through the UI.
Sources: public/app/features/plugins/admin/pages/PluginDetails.test.tsx:244-255, public/app/features/plugins/admin/pages/PluginDetails.test.tsx:430-445
Summary
The Grafana Plugin System & SDK establishes a rigid yet flexible framework for ecosystem growth. By enforcing strict manifest schemas, signature verification, and standardized build pipelines, it ensures that third-party extensions maintain the security and performance standards of the core platform. The introduction of the UI extension system further allows plugins to integrate deeply into the user experience, moving beyond simple data visualization into full-featured application development.