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 Metrics → Grafana sub-tab
  • 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 — KubeManta must reach your Grafana URL (typically http://grafana.monitoring:3000 for in-cluster, or a public URL for managed Grafana).
  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. Under Configure sources, select Grafana from the dropdown.
  4. Paste your Grafana URL (e.g., http://grafana.monitoring:3000).
  5. Paste the API key in the API key field.
  6. Click Test to verify KubeManta can reach Grafana and list dashboards.
  7. Click Save.

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. Still in Admin → Observability, scroll down to Overview embed.
  2. A dropdown appears listing your Grafana dashboards.
  3. Pick one and click Set as Overview.

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
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

"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: Configuration → Settings → Security section. 2. Ensure allow_embedding = true is set (it often is 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: http://grafana.monitoring:3000 (in-cluster service DNS) - ✅ Correct: https://grafana.example.com (managed Grafana, public) - ❌ Wrong: grafana.monitoring:3000 (missing protocol) - ❌ Wrong: http://grafana.monitoring:3000/ (trailing slash)

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.