Folders, Playlists, & Search
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Folders, Playlists, and Search represent the core organizational and discovery mechanisms within Grafana. Folders provide a hierarchical structure for managing resources like dashboards and alert rules, while Playlists allow users to automate the rotation of these resources for continuous monitoring. The Search service provides a unified interface for locating these entities across the platform.
These systems are currently undergoing a transition from a legacy SQL-based architecture to a Kubernetes-inspired, resource-oriented model. This architectural shift aims to provide consistent APIs, machine-readable schemas, and enhanced extensibility through Resource APIs.
Sources: contribute/architecture/k8s-inspired-backend-arch.md, public/app/features/alerting/unified/AGENTS.md
Resource API Architecture
Grafana is adopting a resource-oriented model for core entities like Folders and Playlists. This model uses a declarative state approach where users define the desired state of a resource via structured objects.
Unified Storage & Kubernetes Integration
The Resource API follows Kubernetes conventions for URL structures and versioning. Internal persistence is handled by the Unified Storage layer, which translates Kubernetes-style operations (Create, Get, List, Watch) into SQL queries against Grafana's database.
The diagram above illustrates how the Resource API interacts with Unified Storage to provide optimistic concurrency and Watch capabilities using standard SQL backends.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:1-50, contribute/architecture/k8s-inspired-backend-arch.md:120-145
Folders System
Folders serve as the primary container for dashboards and alerting rules. In the new architecture, Folders are defined as specific "Kinds" within the folder.grafana.app API group.
Key Components
- Folder Service: Manages the lifecycle of folder entities, including creation, updates, and deletion.
- Namespacing: Folders in the Resource API use explicit namespaces that map to Grafana Organization IDs.
| Feature | Legacy API | Resource API |
|---|---|---|
| URL Path | /api/folders | /apis/folder.grafana.app/v1/namespaces/:ns/folders |
| Schema | Variable | Strict CUE-defined spec |
| Versioning | Implicit | Explicit (e.g., v1alpha1, v1) |
Sources: contribute/architecture/k8s-inspired-backend-arch.md:30-45, pkg/services/folder/service.go, public/app/features/alerting/unified/AGENTS.md:140-150
Playlists System
Playlists enable the sequential display of dashboards. The implementation is moving toward the "Apps Approach," where the playlist logic is encapsulated as a modular app with its own reconcilers.
Data Model and Logic
A Playlist resource consists of a list of items (dashboards or tags) and an interval setting for rotation.
This class diagram shows the relationship between a Playlist and its constituent items as defined in the system metadata.
Sources: pkg/api/playlist.go, contribute/architecture/k8s-inspired-backend-arch.md:150-165
Search Service
The Search service provides a centralized mechanism to query Folders, Dashboards, and other resources. It is critical for the "Alert Triage" and "Combined Rule Views" which require aggregating rules from multiple namespaces and folders.
Search Flow and Integration
The search logic often utilizes the useCombinedRuleNamespaces hook on the frontend to aggregate results from Prometheus and Grafana's internal Ruler.
The sequence diagram demonstrates the aggregation of internal Grafana resources and external data source entities during a search operation.
Sources: pkg/services/search/service.go, public/app/features/alerting/unified/AGENTS.md:275-290
Conclusion
The integration of Folders, Playlists, and Search forms a cohesive management layer in Grafana. By transitioning these modules to a Kubernetes-inspired architecture, Grafana provides developers with a standardized, schema-backed environment that supports advanced features like resource watching and declarative provisioning across all organizational entities.
Sources: contribute/architecture/k8s-inspired-backend-arch.md:300-320