Backstage Grafana plugin: dashboards and alerts setup

How the Backstage Grafana plugin puts dashboards and alerts on service pages

Platform teams that want service owners to see Grafana dashboards and firing alerts on the Backstage entity page can build this with a community Grafana plugin for Backstage. Before you plan the work, confirm the plugin's current package name, maintainer and the entity annotation it reads by checking its repository, because those details decide which catalog fields you must populate. The plugin calls Grafana through a server-side path, either a Backstage backend proxy route or a backend plugin, so the Grafana credential stays on the Backstage backend and never reaches the browser. DeployOpen plans and builds this integration inside your infrastructure, against the Grafana instance and Backstage deployment you already run or intend to run.

Confirm three versions before you commit to a design. First, the Backstage release line you run and the Node.js versions that line supports, since the plugin must match the @backstage packages in your app. The latest release in the supplied project record is v1.55.3, published September 29, 2026, so check whether the plugin tracks that line or an older one. Second, the Grafana version. Grafana 13.2.4 is among the current patch releases listed on the Grafana releases page, and you should verify that the plugin supports your Grafana major version and the dashboard search and alert rule API endpoints it calls. Third, the authentication method for Grafana access, such as a service account token with read-only scope, and whether your Grafana edition supports the auth model you intend to use.

The integration depends on consistent catalog ownership and labels. Each component entity needs an accurate spec.owner and the annotation the plugin uses to match it to Grafana dashboards or folders, and the Grafana side needs a stable tagging or folder convention so the same service maps to the same dashboards. If labels drift, owners see empty panels and may conclude that no monitoring exists. Decide early who maintains the mapping, usually the platform team through software templates, and who can see alert states, since firing alerts can reveal operational detail to readers who are not on the owning team. Test the mapping with a small set of services before you roll it out across the catalog.

What must be in place before the Grafana plugin is installed

The Grafana plugin only works when both systems are stable on their own first. Confirm the Backstage deployment, the Grafana deployment, the access it will use, and the network and certificate path between them before touching plugin configuration.

A current Backstage release line

Run a release line from the current monthly main line or the weekly next line, and confirm the team can move to a newer one within the support window. Check the Node.js version against the versioning policy, which currently names Node.js 22 and 24 for Backstage 1.46.0. Pin the @backstage packages together so the Grafana plugin version matches the core packages it depends on.

PostgreSQL and working sign-in

Confirm Backstage runs on PostgreSQL rather than SQLite, since SQLite is intended for development. Sign-in must already resolve each user to a catalog identity through a sign-in resolver, and guest access should be off. The Grafana plugin inherits who the user is from this setup, so an unresolved identity will produce confusing permission results later.

A Grafana deployment with the right database

Choose an installation method that your team can patch on a regular cadence, such as packages, Docker images or Helm charts. SQLite is not suitable for production, so use MySQL or PostgreSQL if Grafana serves more than a small team or must be highly available. If you run two or more active-active nodes, confirm alert notification deduplication is configured before the plugin shows alert states from them.

A read-only Grafana service account

Create a dedicated service account or token in Grafana that can read dashboards, folders, data source metadata and alert rule states, and nothing more. Avoid reusing a personal admin token. Record who owns the token, when it expires and how it will be rotated, because every catalog user who views Grafana panels through Backstage depends on it. Confirm the exact permissions required with the plugin's documentation for your chosen version.

Network paths from Backstage to Grafana

Decide whether the Backstage backend calls Grafana directly or through the Backstage proxy, and open only that path. The browser should not need a route to the Grafana API. Confirm that the Backstage backend can reach the Grafana host and port from the same network zone as its other outbound calls, and that firewall rules and any egress proxy allow it.

The certificate trust chain

If Grafana is served over HTTPS with an internal certificate authority, the Backstage backend must trust that chain in its runtime environment, not only in a browser. Confirm the full chain, including intermediates, is available to the Node.js process and that certificate renewal is tracked. A missing intermediate usually shows up as a connection error that looks like a plugin fault.

Proxy or backend plugin: choosing how Backstage reaches Grafana

The Backstage backend can forward requests from the frontend to Grafana's HTTP API through a proxy configured in the app configuration. The browser calls a Backstage path, and the backend attaches the Grafana credential before the request leaves the server. This path suits teams that already run a Backstage backend, want one place to manage outbound rules, and need only read access to dashboards and alert state.

Credential owner: The platform team holds a Grafana service account token in the backend's secret store, so no Grafana credential reaches the browser.
Alert data: Alert state arrives through proxied API calls, so entity views depend on the proxy path being allowed and on the token having the right read scope.
README checks: Confirm which Grafana endpoints the plugin calls, whether it expects a named proxy configuration key, and whether it reads alerts through the proxy or through its own backend module.
Operational cost: Your team owns proxy path allowlisting, token rotation, and the mapping from catalog entities to Grafana folders, labels or dashboard identifiers.

Before relying on this route, check that the proxy forwards only the read methods and paths the plugin documents.

Configuring the Grafana plugin in seven steps

This sequence connects one Backstage instance to one Grafana instance so that a pilot component shows its dashboards and alert states on the entity page, with the Grafana credential kept on the server. Each step ends with a check you can run before moving on.

Confirm the plugin version for your release line
Start by reading your installed Backstage version with the Backstage CLI and matching it to the Grafana plugin release published for that line in the community plugins repository. Confirm that the frontend and backend packages you plan to install declare compatible @backstage dependencies, and record the chosen versions in your change ticket. Done means you have one written pair of package versions that your team has reviewed against your current Backstage release. Check the release line again before any future upgrade, because plugin packages often move with the core framework. Ask the plugin maintainer which Backstage versions they test against if the compatibility statement is unclear.
Create a read-only Grafana service account
A Grafana administrator creates a dedicated service account with the Viewer role, or the narrowest role that can read the dashboards and alert states your pilot needs, and generates a token for it. Do not reuse a personal account or an admin token. Store the token in your secret store, such as your Kubernetes secret mechanism or an external vault, and never place it in a source repository. Done means the service account exists, its token is stored under a named key, and a direct API call made with that token returns the dashboards it should see and nothing it should not. Repeat the check with a dashboard outside the permitted folder to confirm access is restricted.
Add the Grafana URL and token reference to configuration
Add the Grafana base URL and a reference to the stored token to the Backstage backend configuration file, using the environment variable or secret reference pattern your deployment already uses. Keep the token value itself out of app-config files that the frontend bundle or version control can read. Set the URL to the address the Backstage backend can reach, which may differ from the address your browsers use. Done means the backend starts without configuration errors and the config loader shows the token as a masked or referenced value rather than plain text. Confirm this in the startup log and in a rendered configuration dump with secrets hidden.
Install the frontend and backend packages
From the Backstage repository root, a developer installs the frontend and backend plugin packages using the Backstage CLI, so the package versions are added to the correct workspaces and the wiring files are updated. Register the backend module in the backend index file and add the entity card or tab component to the entity page in the frontend app. Run the type check and the build to catch mismatched dependencies early. Done means the install completes, the build passes, and the frontend app starts locally with the new tab visible on a catalog entity, even if the tab shows no data yet.
Annotate a pilot component
Choose one catalog component with a clear owner and a known Grafana dashboard, then add the plugin's annotation to its catalog-info descriptor. The annotation key and the value format are defined in the plugin documentation, so copy them exactly and confirm the name against the version you installed in step one. Limit the pilot to one entity so that any mapping problem is easy to trace. Done means the descriptor is merged, the catalog ingests the updated entity, and the entity page shows the annotation value in the catalog view. Verify ingestion in the catalog API or the catalog UI before continuing.
Confirm dashboard and alert identifiers
Work with the team that owns the pilot service to confirm the dashboard identifiers, folder paths or tags, and the alert rule names or labels that should appear on the entity. Where the plugin relies on labels or tags for mapping, add those to the dashboard or alert rule in Grafana, or provision them through your Grafana provisioning files so the mapping survives a rebuild. Record each identifier in the pilot's runbook. Done means each identifier can be found through the Grafana API using the service account from step two, and the team has signed off on the mapping. Note any dashboard that cannot be mapped cleanly, because it will need a separate decision later.
Verify the pilot end to end
Test the integration from the backend first, then from the browser. Send a request to the plugin's backend route for the pilot entity and confirm the response returns dashboard metadata, such as titles and links, and the current alert states for that entity. Then open the entity page in a browser signed in as a normal user and confirm the same data appears, with no Grafana token visible in the browser developer tools or network responses. Also test with a user who lacks Grafana access to confirm the page does not reveal restricted dashboards. Done means the backend response matches Grafana for the same identifiers and the browser shows no credential.

Mapping catalog entities, Grafana folders, dashboards and alert labels

This table pairs each Backstage catalog field with its Grafana counterpart and the setup choice that connects them. Read it as a checklist before you write any annotation or alert rule, because a mismatch in one field silently hides dashboards or alerts from the entity page. The main takeaway is that the entity name is the join key, and team ownership in Grafana needs a deliberate mapping on open-source editions.

Catalog or Grafana element	Backstage side	Grafana side	What to confirm or decide
Entity reference and name	metadata.name on a Component, unique within its namespace	Alert label set to the same value, for example service=checkout-api	Pick one naming convention and enforce it in templates so labels match exactly
Owner	spec.owner pointing to a Group or User entity	Folder permissions or a Grafana team assigned to that owner	Team sync from identity providers is an Enterprise or Grafana Cloud feature, so open-source editions need a manual owner-to-team mapping
Dashboard or folder pointer	Annotation that stores the Grafana dashboard UID or folder reference on the entity	Dashboard UID or folder UID taken from the Grafana URL or API	Confirm the annotation key and value format with the plugin version you install, since keys differ between plugin options
Alert labels	Entity name carried in the alert rule labels Grafana evaluates	Alert instances grouped by label and shown per entity	Missing or misspelled labels mean alerts do not appear on the entity page, so test with one known alert first
Folder and team structure	Groups and System entities that own several components	Folders per team or per system, with permissions set at folder level	Decide whether one folder maps to one System or one owning Group, and keep that rule consistent
Service account role	Plugin backend holds the Grafana token, never the browser	Service account with a Viewer role scoped to the folders the plugin reads	Grant Viewer for read-only dashboards and alert states, and add higher roles only if a specific feature requires them
Missing annotation or label	Entity page shows no dashboards or alerts	No match returned, so nothing is displayed	Agree on a default for unannotated entities, for example a catalog check that flags them for the owner
Access scope	Backstage users see only entities their identity can read	Service account sees everything it is granted	Confirm that Backstage access rules, not the shared Grafana token, decide what each signed-in user can view

Keeping Grafana credentials out of the browser

The Grafana plugin needs a credential that can read dashboards and alert states, and that credential must never reach a browser. The cards below cover the service account, where the token lives, how it rotates, how traffic is protected, how Backstage users sign in, how Grafana is hardened, and how both sides keep records.

Read-only service account scope

Create a dedicated Grafana service account with the Viewer role and grant access only to the folders that hold dashboards for catalogued services. Avoid reusing an administrator token or a personal API key, since those carry write and user-management rights the portal does not need. Ask Grafana which permissions a service account token inherits in your version and confirm that folder-level permissions hide alert rules outside the approved folders.

Token storage in the backend

Store the Grafana token in the backend secret store, referenced from the Backstage configuration as a secret variable, and never in app-config.yaml values that ship to the frontend. Only the backend plugin should read it and call Grafana on behalf of signed-in users. Check the built frontend bundle and the browser network panel to confirm the token never appears in a request or response.

Token rotation

Plan a rotation schedule for the service account token and a runbook that creates the new token, updates the secret store, restarts the backend and then revokes the old token. Overlapping old and new tokens for a short window avoids alert gaps during the change. Ask your team who owns the rotation and how a leaked token would be revoked.

TLS between Backstage and Grafana

Require HTTPS on the Grafana URL that the Backstage backend calls, and verify the certificate against your internal certificate authority rather than disabling verification. Traffic between the two services carries the service token and alert data, so it should stay on encrypted, authenticated connections even inside the same cluster or network. Confirm the trust store the Backstage container uses includes your internal CA.

Identity resolution for Backstage users

Configure a sign-in resolver so each Backstage user maps to one catalog user, and that identity decides which catalog entities and Grafana views the user can open. Do not offer guest access in production, because guest sessions would make dashboard access hard to attribute. Test each sign-in provider with a sample account to confirm it resolves to the same catalog user.

Grafana hardening settings

Apply the hardening settings from the Grafana security documentation: secure and SameSite cookies, a Content Security Policy, Trusted Types, hidden version information for unauthenticated users, authentication required on the metrics endpoint and domain verification against DNS rebinding. Review each setting in your version of Grafana, because defaults and available options change between releases.

Audit logging on both sides

Enable and retain Grafana logs that record API calls made with the service account, and keep Backstage backend logs that show which user triggered each Grafana request. Together these logs let a reviewer tie a dashboard view to a named person and a service token. Confirm where each log is shipped, how long it is retained and who can read it.

Why alert states can mislead owners and how to test them

An alert shown on a service page is only as accurate as three things working together: the label matching that ties a Grafana alert to a catalog entity, the Grafana alerting setup behind that alert, and the refresh behavior of the plugin that reads it. If any one of these is off, an owner can see a green service that is actually firing, or a red one that resolved an hour ago, and nothing in the portal will say so. Treat the alert panel as a view of Grafana's state at the time of the last fetch, not as a live incident feed. Before rollout, confirm with your Grafana administrator which label or annotation each alert rule carries, how the plugin matches it to an entity, and how often the plugin refreshes. Record those answers in the plugin design so the test results have a reference point.

High availability changes the picture. The Grafana high availability documentation describes running two or more active-active servers behind a load balancer on a shared MySQL or PostgreSQL database, and it notes that alerting needs additional configuration to avoid duplicate notifications and that Grafana Live has limitations in HA. Your portal may query one node while the alert evaluation runs on another, so a test on a single development instance will not show what owners see in production. Run the test plan against the same topology your users reach, including the load balancer and the database, and confirm the alerting HA settings in your own environment rather than assuming them.

The test plan needs three deliberate faults. First, plant a test alert with a known label on a non-production rule, then confirm it appears on the matching entity within the refresh interval you recorded, and that it clears when you resolve it. Second, rename a test entity in the catalog and confirm whether the alert still resolves, or whether the link breaks silently. Third, revoke the Grafana token the plugin uses and confirm the page shows an error state rather than an empty or healthy one. Record for each case the time to appear, the time to clear, the node that served the query, what the owner sees, and whether the failure was visible. A silent failure in any of the three cases is a finding to fix before the portal is trusted.

Common failures when Grafana data does not appear on entity pages

This table lists the failures teams hit most often when Grafana panels or alert states stay empty or wrong on Backstage entity pages. Read each row from the symptom column, confirm the likely cause with the check listed, then apply the fix. Most failures trace back to the entity annotation, the token scope or the proxy path rather than to Grafana itself.

Symptom	Likely cause	How to confirm	Fix
Empty dashboard panels on the entity page	The Grafana annotation is missing from catalog-info.yaml or its key is misspelled	Compare the entity descriptor with the annotation key your plugin version documents, then reload the catalog entity	Add or correct the annotation on the component, commit the change and wait for the catalog to refresh the entity
Panels or alerts return 401 Unauthorized	The Grafana service account token has expired or was never set in the backend configuration	Call the Grafana API from the Backstage backend host with the same token and check the response code	Create a new service account token, store it in your secret manager, inject it into the backend environment and restart Backstage
Panels or alerts return 403 Forbidden	The token is valid but its role cannot read the folders, dashboards or alert rules tied to the entity	Check the service account role and folder permissions in Grafana for the dashboards the entity references	Grant read access to the relevant folders only, rather than widening the role to admin, and retest the entity page
TLS handshake or unknown certificate errors in backend logs	Grafana uses a certificate issued by an internal CA that the Backstage backend does not trust	Run a TLS check from the backend container against the Grafana URL and look for a chain or trust error	Add the internal CA bundle to the backend image or trust store, and avoid disabling certificate verification
Browser console shows CORS errors or dashboards fail to load embedded	The browser calls Grafana directly, so cross-origin rules and SameSite cookie settings block the request	Open browser developer tools on the entity page and check whether requests go to the Grafana host instead of the Backstage backend	Route calls through the Backstage backend or proxy so the browser never holds Grafana credentials or cookies, and confirm the proxy path in configuration
Duplicate or stale alert notifications after moving to two or more Grafana nodes	Alerting runs on every active node without the additional HA configuration Grafana requires	Compare alert states across nodes and check whether the same alert appears from more than one instance	Follow Grafana's high availability alerting guidance before relying on alert states in Backstage, and confirm which node reports state
Entity shows no alerts although dashboards load	Alert rule labels do not match the entity identifier the plugin uses to filter	Inspect the labels on the Grafana alert rules and compare them with the entity name and namespace in the descriptor	Align the alert rule labels with the entity identifier, or document the mapping agreed by your catalog owners
Plugin errors or missing panels after a Backstage upgrade	The Grafana plugin version is not compatible with the upgraded @backstage packages	Check the plugin release notes and the versions of @backstage packages in the backend and frontend packages	Bump the plugin with the same tooling as other @backstage packages, review the upgrade helper changes and retest entity pages before rollout

Questions teams ask before building the Grafana integration

How much effort does a Backstage Grafana integration take?

Effort depends mostly on how many catalog entities need dashboard and alert links, how consistently those entities are labeled, how many Grafana instances you run, and which connection path you choose. A small catalog with one Grafana instance and a single, consistent label scheme is a contained piece of work. Effort rises when entities map to dashboards in inconsistent ways, when several Grafana instances or folders need separate access, when Grafana runs as a high availability pair with alerting configured to avoid duplicate notifications, and when the team chooses a backend plugin over the proxy. Ask for a written scope that lists the entity count, the Grafana instances in scope and the connection path before comparing quotes.

Can our internal team build the Grafana integration without a partner?

Yes, a team with Backstage plugin experience and Grafana administration skills can build it in-house. The work involves backend configuration, a Grafana service account with limited read permissions, label conventions on catalog entities, and testing of entity pages against real dashboards and alert states. The skills that are hardest to staff are usually Backstage backend plugin development and secure handling of Grafana credentials, so check whether your engineers already maintain Backstage plugins. A partner is most useful when you want a fixed-scope delivery with written deliverables, tested configuration and handover documentation.

What do we need to provide before the Grafana work starts?

Plan to provide four inputs. First, catalog ownership data, meaning which team owns each service entity, so dashboards and alerts map to accountable owners. Second, Grafana administrator access or a named admin who can create service accounts, folders and provisioning files in a test environment. Third, a test environment with a Grafana instance and a Backstage instance that match production closely enough to test permissions and labels. Fourth, a named owner for alert labels who sets the naming rules that link alerts to entities and keeps them current. Confirm the exact access levels with your security team before the kickoff meeting.

Do we need Grafana Enterprise to connect Grafana to Backstage?

The Grafana authentication documentation lists LDAP, generic OAuth, Entra ID, Okta, GitHub, GitLab, Google OAuth, auth proxy and JWT as available in all editions. SAML, team sync, active sync and SCIM provisioning are available only in Grafana Enterprise and Grafana Cloud. A dashboard and alert link integration does not depend on those Enterprise-only features, so the open-source edition can be enough for this purpose. If your identity policy requires SAML sign-in or team sync from your identity provider, you will need to check the edition requirements with Grafana Labs and your licensing team. Review the Grafana authentication documentation for the current list.

How long does a Grafana plugin integration take to deliver?

Duration depends on the written scope, so no general timeline applies. The main variables are the entity count, the number of Grafana instances, whether high availability and alert routing need configuration, how many approval steps your change process requires, and how quickly your team provides access and test environments. Delays usually come from waiting for access, from unclear ownership data, and from disagreement on label conventions rather than from the plugin configuration itself. Ask for a timeline that separates discovery, build, testing and handover, and confirm which of those steps depend on your team.

Does the Grafana plugin add ongoing maintenance cost?

Yes, the integration is not a one-time task. Backstage releases on a monthly main line and a weekly next line, and the upgrade process moves all @backstage packages together, so plugin code and configuration need regular checks against each Backstage upgrade. Grafana also ships minor releases every other month and patch releases at least monthly, and each minor release is supported for 9 months. Recurring work includes testing plugin compatibility after upgrades, rotating the Grafana service account credential, reviewing label rules when services change, and reviewing the plugin's maintenance status. Ask any partner whether this support is covered by a retainer or by a separate agreement.

How DeployOpen works on this

DeployOpen plans and builds the Backstage Grafana integration inside your own infrastructure, starting from the dashboards and alert states your teams already use. Each engagement begins with a written scope that names the catalog entities, Grafana instances and credential path involved, so the work can be reviewed before it starts.

How we scope

We inventory the Grafana instances, folders and dashboards you want linked to each catalog entity.
We confirm how Grafana is hosted, its database tier and whether a proxy or backend plugin route fits your network.
We agree in writing which credential type Grafana will use, where it is stored and who can rotate it.

How we build

We configure the Backstage entity annotations and the Grafana connection in a non-production environment first.
We keep Grafana tokens on the backend so no Grafana credential is ever sent to the browser.
We test dashboard links and alert state displays against sample entities, including access checks for users without Grafana rights.

How we hand over

You receive the configuration, annotation conventions and a runbook covering token rotation and common alert display issues.
We document the entity-to-dashboard mapping rules so catalog owners can add links without changing the platform.
We walk your platform and on-call teams through the setup and the verification steps before the engagement closes.

How we support

Engagements are fixed-scope, and the written scope sets the deliverables and timelines before work starts.
Ongoing support, Backstage and Grafana upgrade work and continuous testing are available as a retainer.
Retainer support covers reviewing plugin and Grafana version changes, so the integration keeps working after upgrades.

Backstage Grafana plugin for dashboards and alerts