Configuring Dashboards and Playlists
This guide provides comprehensive documentation for configuring dynamic dashboards and playlists in SPOG. Dashboards provide customizable views of your DNS infrastructure, while playlists enable automated rotation through multiple screens for NOC displays and monitoring stations.
Table of Contents
- Overview
- Default Dashboard and Navigation
- Dashboard Configuration
- URL Parameters
- Playlist Configuration
- Dynamic Screen Expansion
- URL Parameters vs Template Variables
- Graph Widgets Reference
- Filter Query Syntax
- Access Control
- Examples
Overview
SPOG's dashboard and playlist system provides flexible, role-based views of your DNS infrastructure. Key features include:
- Dynamic Filtering: Use powerful filter queries to select and organize clusters
- Role-Based Access: Control dashboard visibility with REGO policies
- Multiple Visualizations: Tree tables, heatmaps, pie charts, and network topology graphs
- Automated Rotation: Playlists for NOC displays with dynamic screen expansion
- Template Variables: Create dynamic content based on query results
Default Dashboard and Navigation
The glass-ui Helm chart provides a default dashboard and navigation out-of-the-box, so you can deploy SPOG without any configuration:
Default Dashboard
SPOG includes a global overview dashboard at / featuring tree-table, heatmap, pie-charts, and cytoscape widgets showing all clusters.
Default Navigation
SPOG provides a default Tools menu with cache management, DNS operations, and AI assistant actions.
Extending the Defaults
Custom dashboards and navigation menus are merged with the defaults:
- Dashboards: Custom dashboards are added alongside the default. If you define a dashboard with the same URL (e.g.,
/), your custom dashboard overrides the default. - Navigation: Custom menus appear before the default menus.
Disabling Defaults
To disable the default dashboard and navigation entirely:
| YAML | |
|---|---|
Dashboard Configuration
Dashboards are configured in your Helm values under globalConfig.dashboards. Each dashboard represents a unique view of your infrastructure.
Dashboard Structure
| YAML | |
|---|---|
Dashboard Properties
| Property | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | Display title shown in the UI |
description |
string | No | Brief description of the dashboard's purpose |
url |
string | Yes | URL path for accessing this dashboard |
requires |
array | No | List of REGO policy flags required for access |
graphs |
array | Yes | List of graph configurations to display |
Graph Configuration
Each graph in a dashboard has the following structure:
| YAML | |
|---|---|
| Property | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | Display title for the graph |
widget |
string | Yes | Widget type (see Graph Widgets Reference) |
args |
object | Yes | Widget-specific configuration |
args.filter |
string | Yes | Filter query to select clusters |
URL Parameters
Dashboard and playlist configurations support URL parameters that can be referenced in titles, descriptions, and filter queries. This allows you to create reusable configurations that adapt based on the URL.
URL Parameter Syntax:
Use :parameterName in the URL path to define a parameter:
| YAML | |
|---|---|
Referencing URL Parameters:
In your configuration, reference URL parameters using :parameterName:
| YAML | |
|---|---|
Example with Multiple Parameters:
Access URLs:
- /dashboards/region/us-east/env/production → Shows US East production clusters
- /dashboards/region/eu-west/env/staging → Shows EU West staging clusters
Common Use Cases:
- Regional dashboards:
/dashboards/regional/:region - Environment-based views:
/dashboards/env/:environment - Combined parameters:
/dashboards/:region/:role/:environment
Notes:
- Parameter names must match exactly between URL and references
- Parameters are case-sensitive
- Use quotes around parameter references in filter queries: ":region" not :region
- Undefined parameters remain as literal text (e.g., :region if not provided)
Example: Regional Dashboard
Playlist Configuration
Playlists enable automated rotation through multiple screens, ideal for NOC displays and monitoring stations. They support both static graphs and dynamic screens that expand based on query results.
Playlist Structure
Playlist Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string | Yes | - | Display name for the playlist |
description |
string | No | - | Brief description |
url |
string | Yes | - | URL path for accessing the playlist |
interval |
string | No | - | Default time to show each screen (e.g., "15s") |
requires |
array | No | - | REGO policy flags required for access |
animatedBackground |
boolean | No | false | Enable animated background effects |
showCountdown |
boolean | No | true | Show countdown timer |
screens |
array | Yes | - | List of static or dynamic screens |
Static Screens
Static screens display a single graph:
| YAML | |
|---|---|
Dynamic Screens
Dynamic screens expand based on query results, creating multiple screens from templates:
| YAML | |
|---|---|
Dynamic Screen Expansion
Dynamic screens use template variables that are replaced based on query results.
Non-Grouped Queries
For queries without group by, the system creates one screen per matching cluster. This is useful in playlists for rotating through individual cluster details:
| YAML | |
|---|---|
Available variables:
- {{cluster.name}} - Cluster name
- {{cluster.id}} - Cluster ID
Note: Non-grouped queries work well in playlists but are not recommended for dashboards.
Single-Level Grouping
For queries with a single group by field, the system creates screens for each unique value:
| YAML | |
|---|---|
Available variables: Each group field becomes a variable (e.g., {{region}}, {{role}})
Multi-Level Grouping
For multi-level grouping, screens are created for each leaf node in the hierarchy:
| YAML | |
|---|---|
Available variables: All group fields (e.g., {{region}}, {{role}})
URL Parameters vs Template Variables
It's important to understand the difference between URL parameters and template variables:
| Feature | URL Parameters | Template Variables |
|---|---|---|
| Syntax | :parameter |
{{variable}} |
| Source | Extracted from URL path | Generated from query results |
| Use Case | User-driven navigation | Dynamic screen expansion |
| Scope | Entire dashboard/playlist | Individual dynamic screens |
| Example | /dashboard/:region |
{{cluster.name}} from query |
URL Parameters (:region) are defined in the URL and set when users navigate:
| YAML | |
|---|---|
Template Variables ({{region}}) are populated from query results in dynamic screens:
| YAML | |
|---|---|
Can be used together:
Example: NOC Monitoring Playlist
Example: Regional Rotation Playlist
Playlist Token Authentication
For NOC displays and kiosk screens that need to show playlists without interactive login, SPOG supports playlist tokens - simple bearer tokens that grant access to specific playlists.
Configuring Playlist Tokens
Define tokens in your Helm values:
| YAML | |
|---|---|
Using Playlist Tokens
Access playlists using the token in one of two ways:
URL Parameter:
| Text Only | |
|---|---|
Authorization Header:
| Text Only | |
|---|---|
Access Control with Playlist Tokens
Playlist tokens work with the requires field in playlist configuration. The token's claims are available in REGO as input.playlist:
| YAML | |
|---|---|
REGO policy to control access:
Retrieving Auto-Generated Tokens
For tokens created with the generate mode:
| Bash | |
|---|---|
Token Security
Auto-generated tokens are recommended for production. They're stored in Kubernetes secrets and never exposed in Helm values.
Graph Widgets Reference
SPOG provides several visualization widgets for displaying infrastructure state.
cc-state-tree-table
Hierarchical tree table showing cluster structure with expandable nodes.
Widget ID: cc-state-tree-table
Arguments:
| Argument | Type | Required | Description |
|---|---|---|---|
filter |
string | Yes | Filter query to select and organize clusters |
Example:
| YAML | |
|---|---|
Features: - Expandable tree structure (Cluster → Product → Instance Set → Pod → Container) - Readiness indicators for each level - Inline actions (Clear Cache, etc.) - Supports grouping for organized hierarchy
cc-state-readiness-heatmap
Heatmap visualization showing readiness status across clusters.
Widget ID: cc-state-readiness-heatmap
Arguments:
| Argument | Type | Required | Description |
|---|---|---|---|
filter |
string | Yes | Filter query to select and organize clusters |
Example:
| YAML | |
|---|---|
Features: - Color-coded cells (green=ready, yellow=degraded, red=unhealthy) - Supports grouping for hierarchical organization - Hover details showing exact readiness counts - Click-through to cluster details
cc-state-readiness-pie-charts
Pie chart visualization showing readiness distribution.
Widget ID: cc-state-readiness-pie-charts
Arguments:
| Argument | Type | Required | Description |
|---|---|---|---|
filter |
string | Yes | Filter query to select and organize clusters |
Example:
| YAML | |
|---|---|
Features: - Shows ready vs. not-ready container counts - Supports grouping (creates one pie chart per group) - Interactive legends - Color-coded segments
cc-state-cytoscape
Network topology graph showing relationships between infrastructure components.
Widget ID: cc-state-cytoscape
Arguments:
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
filter |
string | Yes | - | Filter query to select clusters |
depth |
string | No | "cluster" |
Detail level: "cluster", "product", "instance_set", "pod", "container" |
layout |
string | No | "Hierarchical" |
Layout algorithm: "Hierarchical", "Radial" |
Example:
| YAML | |
|---|---|
Features: - Interactive network diagram - Multiple layout algorithms - Configurable depth level - Node colors indicate health status - Zoom and pan controls - Click nodes for details
Layout Descriptions:
- Hierarchical: Top-down tree layout, ideal for showing organizational structure
- Radial: Concentric circles radiating from center, good for highlighting central nodes
Filter Query Syntax
Filter queries use a SQL-like syntax to select and organize clusters. This section assumes familiarity with filter terms but provides examples for clarity.
Basic Filtering
Select clusters by label values:
Multiple Values
Select clusters matching any value in a list:
Combining Conditions
Use logical operators:
| Text Only | |
|---|---|
Grouping
Organize results hierarchically:
How grouping works:
- Single level:
group by regioncreates a single level of organization (e.g., us-east, us-west, eu-east) - Multi-level:
group by region, rolecreates a hierarchy (e.g., us-east → authoritative, us-east → recursor) - In tree tables: Groups become parent nodes in the tree
- In heatmaps: Groups become rows and columns
- In pie charts: One pie chart is created per group
- In playlists: Each unique combination creates separate screens
Empty Filters
An empty filter selects all accessible clusters:
| Text Only | |
|---|---|
Filter Examples
All authoritative DNS servers in Americas:
| Text Only | |
|---|---|
Production clusters grouped by service type:
| Text Only | |
|---|---|
All recursors grouped by region and environment:
| Text Only | |
|---|---|
Access Control
Dashboards and playlists use REGO policies to control access. Define access rules in your policy configuration.
Dashboard Access
| YAML | |
|---|---|
Playlist Access
| YAML | |
|---|---|
Multiple Permissions
Require multiple roles with OR logic:
| YAML | |
|---|---|
No Access Control
Omit requires for dashboards accessible to all authenticated users:
| YAML | |
|---|---|
Dynamic Permission Arguments
For parameterized routes, use object format with arguments to pass route values to REGO:
| YAML | |
|---|---|
Argument Value Syntax:
| Syntax | Description | Example |
|---|---|---|
:param |
Extract from URL route parameter | :team from /team/:team |
{{ param }} |
Template expression | {{ team }}_suffix |
"value" |
Static string | "production" |
REGO Policy:
| Rego | |
|---|---|
When user visits /team/devops, REGO receives input.arguments.team = "devops" and checks if "devops" is in the user's roles.
Benefits of Dynamic Permissions
- One dashboard definition serves all teams
- One REGO rule handles all teams
- Adding a new team requires only navigation links and user role assignments
Examples
Example 1: Executive Dashboard
A high-level dashboard for executives showing global infrastructure status:
Example 2: Service-Specific Dashboard
Dashboard focusing on a specific DNS service type:
Example 3: Multi-Region Playlist with Dynamic Screens
Playlist that rotates through regional overviews and expands to show individual clusters:
This playlist expands to: 1. Authoritative DNS Status (static) 2. Recursor DNS Status (static) 3. All Services by Region (static) 4. authoritative Service Infrastructure (dynamic, from template 1) 5. authoritative Service Health (dynamic, from template 2) 6. recursor Service Infrastructure (dynamic, from template 1) 7. recursor Service Health (dynamic, from template 2)
Navigation Integration
Dashboards should be added to the navigation menu for easy access:
| YAML | |
|---|---|
Playlists are typically accessed via direct URL (bookmarked for NOC displays) but can also be added to navigation if desired.
Best Practices
Dashboard Design
- Start simple: Begin with basic tree table and heatmap views
- Group logically: Use grouping to organize clusters by region, role, or environment
- Multiple perspectives: Provide different graph types for the same data
- Performance: Avoid overly complex filters on large deployments
- Consistent naming: Use clear, descriptive titles
Playlist Design
- Timing: Balance information density with readability (15-30s per screen)
- Static first: Start with overview screens, then drill into details
- Limit expansion: Be mindful of how many screens dynamic queries create
- Test rotation: Watch full playlist cycle to verify flow
Access Control
- Least privilege: Grant minimum required access
- Role-based: Align with organizational roles
- Test thoroughly: Verify access with different user accounts
- Document requirements: Clearly state who should access each dashboard
Performance
- Filter specificity: Use specific filters to reduce data processing
- Depth control: Use appropriate depth in cytoscape graphs
- Grouping levels: Limit group nesting to 2-3 levels
- Playlist timing: Ensure screens have time to render before rotation
Summary
SPOG's dashboard and playlist system provides flexible, powerful visualization of your DNS infrastructure:
- Dashboards offer customizable views with multiple graph types
- Playlists enable automated rotation for monitoring displays
- Dynamic screens expand based on query results for detailed drill-down
- Template variables create context-specific content
- Filter queries provide powerful cluster selection and organization
- REGO policies control access based on user roles