Migration Guide: Legacy Alerts to Unified Alerting in Visualizer (Grafana)

ThingsHub uses a modified installation of Grafana to power it's visualizer service.

This guide provides Kubernetes operators with the necessary steps for migrating from legacy alerting to Unified Alerting in ThingsHub for Grafana/Visualizer-based alerts.

Since Grafana 11 will remove legacy alerting entirely, performing this migration in Grafana 10.4 (used in ThingsHub 6.x) is mandatory to avoid losing existing alerts in further thingsHub upgrades.

While most legacy alerts should be automatically migrated, some complex and old alerts might require manual intervention to ensure that they function properly with the new grafana version.

Who Needs to Perform This Migration?

Migration is relevant for:

• On-prem ThingsHub customer tenants using Grafana alerts that were first installed with ThingsHub version 4.x or older.

Tenants that were first installed with ThingsHub version 5.x and above already use Unified Alerting by default and do not require this migration.

Why Migrate?

• Legacy alerting is deprecated: Grafana introduced a Unified Alerting system in Grafana 8, offering a single view for managing alerts across dashboards.

• Grafana 11 will remove legacy alerts altogether: Once ThingsHub upgrades to Grafana 11, all legacy alerts will be lost if they haven’t been migrated. Grafana 10.4 and thingsHub 6 is the final version which will allow this migration to be done.

For more details on unified alerting, see Grafana’s official blog.

Checking for Legacy Alerts in ThingsHub 6.x

In ThingsHub version 6.0 or higher, legacy alerts are hidden by default. To view and see the status of these alerts:

1. Enable legacy alerts by adjusting these environment variables in the Visualizer deployment:

   CODE

   kubectl set env deployment/visualizer -n {tenant_name} GF_UNIFIED_ALERTING_ENABLED="false" GF_ALERTING_ENABLED="true"

2. This will make the Alerting (legacy) menu appear in the sidebar.
   

   

3. Go to the Alerting Upgrade section to see a list of legacy alerts eligible for migration.

Upgrading Legacy Alerts and Notification Channels

The Alerting Upgrade section provides a preview environment for safely upgrading legacy alerts and notification channels. The steps below outline the process based on Grafana's official documentation.

1. Preview the Upgrade

• Initiate the process: Navigate to the Alerting upgrade page in the Alerting (legacy) section.

• Review the summary table: This table will show how legacy alert rules and notification channels will map to Grafana’s new alerting system.
  

  

2. Investigate and Resolve Errors

• Identify issues: The upgrade preview will flag rules that can’t be automatically upgraded with error or warning indicators.

• Address errors:

  • Fix issues in legacy alerts: Where possible, resolve the problems in the legacy system and retry the upgrade.

  • Create new resources: If fixing legacy issues isn’t viable, note the relevant alerts and notification policies, and manually re-create new alert rules, notification policies, and/or contact points in the unified alerting system.
    Grafana has great documentation on how to create alert rules from scratch: https://grafana.com/docs/grafana/latest/alerting/set-up/

3. Upgrading Notification Channels

• When upgrading legacy alert rules, you will also need to upgrade the Notification Channels from the Upgraded Notification Channels, as shown in the above screenshot:

  • Notification channels in legacy alerting are upgraded to Contact Points in Grafana's unified system.

  • Review the mappings in the Alerting Upgrade section.

    • Identify issues: The upgrade preview will flag channels that can’t be automatically upgraded with error or warning indicators.

    • If errors arise, you can either fix the issues within the legacy system and retry, or create new contact points manually in the Alerting section under Contact Points.

Important: Post-Migration Step: Enabling Unified Alerting

Once legacy alerts and notification channels are successfully migrated, you can enable Unified Alerting by running:

kubectl set env deployment/visualizer -n {tenant_name} GF_UNIFIED_ALERTING_ENABLED="true" GF_ALERTING_ENABLED="false"

This final step ensures that Grafana uses the new unified alerting system, preventing any further reliance on legacy alerts. You are now ready for future ThingsHub and Grafana upgrades!

If you encounter any unexpected issues while following these steps, please contact Smartmakers Support.