Skip to content

Grafana

Embed your Grafana dashboards directly in KubeManta's Metrics tab, so operators never have to switch contexts between the two tools.

What it gives you

  • Dashboard picker — browse your Grafana dashboards from within KubeManta
  • Embedded dashboards — view any dashboard in the Grafana tab beside Metrics
  • Optional Overview embed — show one dashboard as the default landing view (instead of KubeManta's built-in health summary)

Tier: Free

Prerequisites

  1. Grafana running — already deployed and accessible.
  2. Network path — the URL must be reachable both by KubeManta (to list dashboards) and by each operator's browser (the dashboard is embedded in an iframe), e.g. https://grafana.example.com. In-cluster Service DNS such as grafana.monitoring:3000 does not work for the embed, and an http:// Grafana cannot be embedded in an https:// KubeManta.
  3. API key or service account token — Grafana requires authentication to list dashboards. We recommend a viewer-only API key with no write permissions.
  4. In Grafana: Configuration → API keys or Service accounts (for Grafana v9+)
  5. Create a key with role Viewer (read-only)
  6. Dashboards exist — at least one dashboard in Grafana that you want to embed

Configure in KubeManta

Step 1 — Create a Grafana API key

In your Grafana instance:

  1. Open Configuration → API keys (or Grafana → Service accounts on newer versions).
  2. Click New API key (or Create service account).
  3. Name it something like kubemanta-viewer.
  4. Set the role to Viewer (read-only).
  5. Click Create and copy the token immediately (you won't see it again).

Step 2 — Register with KubeManta

In KubeManta:

  1. In the sidebar, click Admin (gear icon).
  2. Open the Observability tab.
  3. Open the Grafana tab.
  4. Paste your Grafana URL (e.g., https://grafana.example.com).
  5. Paste the key in the API Token field (optional if Grafana allows anonymous access).
  6. Click Test to verify KubeManta can reach Grafana and list dashboards.
  7. Click Save.
  8. Reload the page. KubeManta only lets the browser frame the Grafana URL that was configured when the page loaded, so an embed needs a reload after you set or change the URL.

The API key is stored encrypted at rest and never exposed in the UI.

Step 3 (optional) — Set a dashboard as the Overview

To replace KubeManta's built-in home screen with a Grafana dashboard:

  1. In Admin → Observability → Grafana, click Load dashboards.
  2. Pick a Default Dashboard.
  3. Tick Replace the Overview with this dashboard, then click Save.

Operators will now see that dashboard on login instead of the built-in health summary.

Verify

  1. Click Metrics in the sidebar (OBSERVE group).
  2. You should see a Grafana sub-tab (only appears when Grafana is configured).
  3. Click it — you'll see a dropdown labeled "Select a dashboard".
  4. Pick any dashboard from your list.
  5. The dashboard should load and refresh normally.

Expected states

State Meaning Next step
No Grafana sub-tab Grafana isn't configured yet Follow "Configure in KubeManta" above
Grafana sub-tab present, dropdown empty KubeManta reached Grafana but it has no dashboards Create a dashboard in Grafana first
The panel asks you to reload the page The Grafana URL was set or changed after this page loaded, or Grafana redirected the frame to another origin See The panel says to reload the page
Grafana sub-tab present, dropdown full, but dashboard won't load API key works, but Grafana denied the browser's embedded request (CORS / iframe framing) See troubleshooting below
Dashboard loads and auto-refreshes Success! You can now set it as the Overview (optional)

Troubleshooting

Dashboard picker dropdown is empty

Did you create a dashboard in Grafana first? Even a blank dashboard counts — go to Grafana and create one, then refresh the KubeManta Metrics tab.

Is the API key valid? In Grafana, go to Configuration → API keys and verify the key isn't expired or revoked. If in doubt, create a new one and update KubeManta.

Check KubeManta logs: 

kubectl logs -n kubemanta-system deploy/kubemanta-agent | grep observability

The panel says to reload the page

KubeManta's Content-Security-Policy allows frames from exactly one other origin: the Grafana URL configured in Admin → Observability, read when the page loads. After you configure or change the Grafana URL, reload the page before the embed can render; the panel says so instead of staying blank.

A Grafana that redirects the frame to a single sign-on provider on another origin is refused for the same reason. Sign in to Grafana in another browser tab first, or use anonymous access for the embedded dashboards.

The embedded frame is sandboxed. Grafana's scripts, its own session cookies and storage, its login form, and links that open in a new tab all work, but the embedded page cannot navigate the KubeManta tab itself, and it is not told which KubeManta page embedded it (no Referer). Use Open in new tab for anything that needs the whole window, such as a CSV export.

Serve Grafana from its own origin — its own hostname, or at least its own port. A Grafana served from the same origin as KubeManta could lift its own sandbox.

"Dashboard won't load" or iframe is blocked

Grafana requires explicit permission to be framed in a cross-origin iframe. This is a Grafana feature, not a KubeManta issue.

If Grafana is self-hosted: 1. In grafana.ini set [security] allow_embedding = true (or the environment variable GF_SECURITY_ALLOW_EMBEDDING=true). 2. Restart Grafana. Embedding is off by default. 3. Optionally, set cookie_samesite = None and run Grafana over HTTPS if you want the iframe to work in some edge cases (this is an advanced setting).

If you're using managed Grafana (e.g., Grafana Cloud): 1. Grafana Cloud usually allows iframe embedding by default. 2. If the embed still fails, contact Grafana support — they may have additional CORS/embedding policies.

"Can't reach Grafana" error

Check the URL format: - ✅ Correct: https://grafana.example.com (managed Grafana, public) - ❌ Wrong: grafana.monitoring:3000 (missing protocol)

A trailing slash is fine — KubeManta strips it when the URL is saved and again when it is used, so http://grafana.monitoring:3000/ and http://grafana.monitoring:3000 behave identically.

Check the network path: - For in-cluster Grafana: ensure KubeManta's pod can reach the Grafana namespace (no NetworkPolicy blocking it). - For managed Grafana: ensure the firewall allows outbound HTTPS to that host.