Grafana

Warning

The Grafana instance configuration is stored on a local path. To ensure persistence, this path must be saved to a shared volume instance. See Persistent storage for more details.

Capabilities

Capability

Support

Comment

Configure the insertion of data.

Supported feature

Allows defining how data is stored and inserted in the time-series database. This is a prerequisite for enabling data historization and long-term monitoring. See Value history / analytics.

Basic charts

Supported feature

Enables the use of default visualization tools within OnSphere for common metrics, avoiding the dependency on Grafana for simple use cases. See Chart.

Setup Grafana in the OnSphere stack

Supported feature

Provides instructions to integrate Grafana directly into the OnSphere environment. This includes setting environment variables and service configuration. See Configure Grafana

Setup external Grafana in the OnSphere stack (not in OnSphere)

Partial support

Details the steps required to connect an externally managed Grafana instance to the OnSphere ecosystem, ensuring compatibility and data access. See Grafana as an external service

Access InfluxDB data from Grafana

Supported feature

Describes how to configure Grafana to query and visualize time-series data stored in InfluxDB, including data source setup. See Access InfluxDB data from Grafana

Access to the GUI of Grafana from the stack

Supported feature

Access to the Grafana web interface directly from the OnSphere frontend, using the unified authentication mechanism. See Access the Grafana GUI

Configure Grafana groups linked to Keycloak groups

Supported feature

Explains how to configure user roles and access control in Grafana using Keycloak group mapping for centralized identity management. See Manage users, groups, and permissions with Grafana

Limit access to GUI Grafana resources based on user/groups

Supported feature

Allows fine-grained access control to Grafana dashboards and resources, leveraging Keycloak group-based permissions. See Manage users, groups, and permissions with Grafana

Define only some dashboard to be accessible for a group/user

Supported feature

Extends access control to the dashboard level, allowing configuration of visibility for specific users or groups. See Manage users, groups, and permissions with Grafana

Display graphs in dashboards without requiring re-authentication (uses OnSphere authentication).

Supported feature

Supports embedding Grafana elements in OnSphere without asking users to log in again, by leveraging SSO with Keycloak. See Manage users, groups, and permissions with Grafana

Include graphs inside OnSphere dashboards

Supported feature

Permits the integration of Grafana graphs directly into OnSphere dashboards using the WebView widget and Grafana share URLs. See Display Grafana dashboards and graphs on an Onsphere dashboard

Export graphs or charts from Grafana and include them in a OnSphere report

Supported feature

Provides a method to export Grafana charts and graphs for inclusion in OnSphere reports, enhancing reporting capabilities. See Export graphs or charts from Grafana and include them in a OnSphere report

Concept

Overview

Grafana is a powerful open-source analytics and monitoring platform that allows users to visualize and analyze data from various sources. This is particularly useful for monitoring and analyzing time-series data, such as metrics from servers, applications, and IoT devices.

OnSphere can be used in conjunction with Grafana to provide a comprehensive solution for data visualization and monitoring. By integrating Grafana into the OnSphere stack, users can leverage the capabilities of both platforms to create custom dashboards, visualize data from InfluxDB, and manage user access and permissions.

This chapter describes the most common operations between the two platforms.

Configure Grafana

To ensure Grafana works correctly with the OnSphere stack, proper configuration is required. The grafana.service file must be adjusted according to the environment.

The following environment variables must be set:

Env.

Usage

Example value

GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH

Enables automatic role assignment in Grafana based on Keycloak groups.
See documentation for details
contains(groups[*], ‘administrator’) && ‘GrafanaAdmin’ || contains(groups[*], ‘administrator’) && ‘Admin’ || ‘Viewer’

Example

See Visualize Grafana charts in the OSP web interface for an example to visualize grafana dashboard and charts in the OnSphere web interface.

Access the Grafana GUI

By default, the Grafana web interface is accessible on OnSphere frontend with the suffix /osp/grafana.

Hint

The authentication required is the same authentication than OnSphere. See Manage users, groups, and permissions with Grafana for group mapping and rights.

Display Grafana dashboards and graphs on an Onsphere dashboard

Concept

The OnSphere webview widget allows embedding a Grafana element within an application. By setting the WebView’s source to a Grafana sharing URL, various visual elements such as dashboards and graphs can be displayed.

Use-cases

  • Embedding a Grafana dashboard in an OnSphere dashboard.

  • Displaying a specific graph or panel from Grafana.

  • Integrating Grafana metrics into a custom interface without exposing the full Grafana UI.

Usage

To use the WebView widget with Grafana:

  1. Retrieve the sharing URL of the desired Grafana element (dashboard, graph, etc.).

  2. Set this URL as the source of the WebView widget.

  3. To display only the dashboard without the Grafana interface, append the kiosk parameter to the URL.

Example

See Visualize Grafana charts in the OSP web interface for an example to visualize grafana dashboard and charts in the OnSphere web interface.

Manage users, groups, and permissions with Grafana

Concept

User and group management in Grafana is integrated with Keycloak authentication. To access Grafana, a user must have a Keycloak account.

Additionally, Keycloak groups can be automatically mapped to one of Grafana’s three roles (Admin, Editor, Viewer) through the OAuth authentication configuration. This ensures centralized identity and access management while simplifying user role assignment.

Use Cases

  • Centralized user management

  • Role-based access control

  • Simplified user onboarding and offboarding

  • Customizable role mapping

Usage

Grafana retrieves authentication and user roles from Keycloak, meaning users must have a Keycloak account to log in. The mapping between Keycloak groups and Grafana roles is configured in the Role attribute path field of the OAuth authentication settings. For example, to assign users from the administrator group in Keycloak to the GrafanaAdmin and Admin roles in Grafana, and also to assign all users to the Viewer role, the following rule can be used:

contains(groups[*], 'administrator') && 'GrafanaAdmin' || contains(groups[*], 'administrator') && 'Admin' || 'Viewer'

Defaults Grafana roles

See https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control for default role description.

Role

Description

Example

GrafanaAdmin

Full administrative access to Grafana must be given to administrator only

All permissions, including user management and data source configuration.

Admin

Administrative access to Grafana, but with limited permissions compared to GrafanaAdmin.

Can manage dashboards and data sources, but not users.

Editor

Can create and edit dashboards and panels.

Cannot manage data sources or users.

Viewer

Read-only access to Grafana.

Can view dashboards and panels but cannot make any changes.

The Grafana documentation provides more details about role mapping, available at this link. Keycloak groups are automatically made available during authentication.

Once users are authenticated, permissions can be managed at different levels. Grafana allows defining access rights either by role or on a per-user basis, at the dashboard or folder level. This flexibility ensures that users only have access to the data relevant to them while maintaining security and control over the platform.

Access InfluxDB data from Grafana

Concept

To access InfluxDB data in Grafana, a new data source must be configured. This operation requires the user to have the Admin role within Grafana. The official documentation provides detailed instructions on how to add and configure an InfluxDB data source: Configure InfluxDB data source.

In the OnSphere environment, the default URL for the InfluxDB instance is http://osp-influxdb:8086. The password field corresponds to the token defined in the analytics module.

Note

InfluxQL is the recommended query language. The Flux language will no longer be supported starting from InfluxDB version 3.

Use Cases

  • Visualizing InfluxDB data in Grafana dashboards.

  • Creating custom queries to extract specific metrics from InfluxDB.

  • Combining InfluxDB data with other data sources in Grafana for comprehensive analysis.

  • Using Grafana’s visualization capabilities to present InfluxDB data in various formats (graphs, tables, etc.).

Usage

Once the data sources have been successfully added, it is possible to query InfluxDB data directly from a Grafana dashboard by selecting the relevant data source.

Example

See Visualize Grafana charts in the OSP web interface for an example to visualize grafana dashboard and charts in the OnSphere web interface.

Grafana as an external service

Concept

A Grafana instance external to the OnSphere stack can be used. By default, Keycloak authentication is not available in this case. If authentication is required, Keycloak must be configured accordingly. Grafana also supports sharing resources publicly, without authentication.

Use Cases

  • Use external Grafana instances

  • Share Grafana resources publicly

  • Embed Grafana resources into another application without authentication

Usage

To display a public Grafana resource, use the WebView widget.

Warning

When embedding a resource from a different domain using an iframe, it may fail due to CORS policies. The domain hosting Grafana must be properly configured to allow embedding and cross-origin access.

CORS Considerations

If the external Grafana instance is hosted on a different origin than the application, browser-enforced Cross-Origin Resource Sharing (CORS) policies may block the graph from loading. This typically manifests as a blank iframe or console errors such as Blocked by CORS policy.

Export graphs or charts from Grafana and include them in a OnSphere report

Concept

It’s possible to export Grafana charts and graphs for inclusion in OnSphere reports. This feature allows users to generate reports that include visualizations from Grafana, enhancing the reporting capabilities of OnSphere.

Use Cases

  • Generate reports that include Grafana visualizations.

  • Create comprehensive reports that combine data from multiple sources, including Grafana.

  • Automate the generation of reports with Grafana charts for regular updates.

Usage

To export a Grafana chart or panel, use its direct URL, which typically includes parameters defining the time range and visualization settings.

Start by creating a Grafana service account with appropriate permissions to access the required dashboards. The associated service account token can then be used to authenticate and programmatically retrieve chart data.

Each Grafana URL can be rendered as an image by using the /render endpoint. For instance, given the following dashboard URL:

http://{stack_ip}/osp/grafana/d/1a2b3c4d5/dashboard-name?orgId=1&from=now-6h&to=now&timezone=browser

The corresponding URL to export the chart as an image is:

http://{stack_ip}/osp/grafana/render/d/1a2b3c4d5/dashboard-name?orgId=1&from=now-6h&to=now&timezone=browser

Use osp-scripts to retrieve the rendered image from the Grafana endpoint and embed it into the report by converting it to a Base64-encoded string.

Example

See Generate reports with Grafana charts for an example to export grafana charts and include them in a OnSphere report.