> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Grafana

> Grafana wired to the cluster's Qovery-managed Prometheus (Thanos), Loki and Alertmanager, with Kubernetes dashboards preloaded

Qovery creates it as a Helm release on the environment's own cluster, as a [Blueprint](https://www.qovery.com/docs/configuration/blueprints.md) service in one of your environments.

| | |
| - | - |
| Catalog name | `helm-grafana` |
| Category | Observability |
| Provider | HELM |
| Engine | helm |
| Major versions (latest release) | `13` (1.1.1) |
| Source | [HELM/grafana/13](https://github.com/Qovery/service-catalog/tree/HELM/grafana/13/1.1.1/HELM/grafana/13) |

> [!TIP]
>
> **New to this?** You don't need to know Kubernetes or Helm. Qovery installs Grafana on your cluster with Helm and runs it for you: you fill in a form, or paste the prompt below into your coding agent. The values it publishes, listed under Outputs, reach your other services as environment variables. Qovery tells you when a newer version of the Blueprint is available. Check the requirements in the Reference section before you start, and try it first in a development environment.

## Create it

> [tab] Console
>
> 1. Open the environment, then **New service** › **Blueprint**.
> 2. Find **Grafana** in the catalog and pick the major version.
> 3. Fill in the variables. Required ones are marked; the others use their defaults.
> 4. Create the service, and deploy it now or later.

> [tab] CLI and API
>
> List the catalog to get the latest tag, then create the service from it. `qovery api` signs the requests with your CLI session.
>
> ```bash theme={null}
> ORG_ID="REPLACE_WITH_ORGANIZATION_ID"
> ENV_ID="REPLACE_WITH_ENVIRONMENT_ID"
>
> qovery api "organization/$ORG_ID/blueprint/catalog" | jq '.. | objects | select(.name? == "helm-grafana")'
>
> cat > blueprint.json <<'EOF'
> {
>   "name": "helm-grafana",
>   "tag": "HELM/grafana/13/1.1.1",
>   "icon": "app://qovery-console/grafana",
>   "variables": [
>     {
>       "name": "admin_password",
>       "value": "REPLACE_WITH_ADMIN_PASSWORD",
>       "is_secret": true
>     }
>   ]
> }
> EOF
> BLUEPRINT_ID=$(qovery api "environment/$ENV_ID/blueprint" --method POST --input - < blueprint.json | jq -r .id)
> rm blueprint.json   # it can hold secret values
> qovery api "blueprint/$BLUEPRINT_ID/deploy" --method POST
> qovery api "blueprint/$BLUEPRINT_ID"   # status of the latest deployment
> ```
>
> Replace each `REPLACE_WITH_` value. Add optional variables to `variables` the same way.

> [tab] Coding agent
>
> Paste this into Claude Code, Cursor, Codex or another coding agent with the [Qovery agent skills](https://www.qovery.com/docs/getting-started/quickstart/agent-skills.md) installed (`curl -fsSL https://skill.qovery.com/install.sh | bash`).
>
> ```text Prompt wrap theme={null}
> Add the Qovery Blueprint Grafana (helm-grafana) to one of my Qovery environments and deploy it. Ask me for admin_password.
> Ask me before deploying to a production environment.
> Docs: https://www.qovery.com/docs/configuration/blueprints/helm-grafana.md
> ```

You don't add any file to your repository. Qovery creates the Blueprint from the Console or the API.

## Variables and outputs

Generated from `qbm.yml` at `HELM/grafana/13/1.1.1`, the manifest the Console form is built from.

> [accordion] All 26 variables
>
> | Name | Type | Required | Default | Secret | Description |
> | - | - | - | - | - | - |
> | `admin_user` | string | | `admin` | | Set at creation: later changes have no effect (rename in Grafana). Letters, digits, . - \_ and @. |
> | `admin_password` | string | Yes | | Yes | At least 12 characters. Changing it and redeploying resets the admin password. |
> | `root_url` | string | | | | Unset = Grafana's own address. Set it (e.g. [https://grafana.example.com](https://grafana.example.com)) behind a custom domain or path prefix. |
> | `anonymous_access` | string | | `false` | | Let anyone who reaches Grafana browse dashboards without logging in, with the Viewer role |
> | `metrics_url` | string | | `http://thanos-query.prometheus.svc.cluster.local:9090` | | Leave the default (Qovery's Thanos) on AWS and Scaleway. On GKE and AKS use [http://thanos-query.qovery.svc.cluster.local:9090](http://thanos-query.qovery.svc.cluster.local:9090). |
> | `prometheus_url` | string | | `http://prometheus-operated.prometheus.svc.cluster.local:9090` | | Leave the default (in-cluster Prometheus, no Thanos history) on AWS and Scaleway. On GKE and AKS use [http://prometheus-operated.qovery.svc.cluster.local:9090](http://prometheus-operated.qovery.svc.cluster.local:9090). |
> | `loki_url` | string | | `http://loki.logging.svc.cluster.local:3100` | | Leave the default: it is the Loki Qovery installs with cluster logs. Set it only to read logs from another Loki. |
> | `alertmanager_url` | string | | `http://alertmanager-operated.prometheus.svc.cluster.local:9093` | | Leave the default on AWS and Scaleway clusters. On GKE and AKS use [http://alertmanager-operated.qovery.svc.cluster.local:9093](http://alertmanager-operated.qovery.svc.cluster.local:9093). |
> | `default_datasource` | string | | `thanos` | | Datasource new panels and Explore open on |
> | `enable_prometheus_datasource` | string | | `true` | | Add the direct Prometheus datasource next to Thanos |
> | `enable_loki_datasource` | string | | `true` | | Add the Loki datasource (cluster logs) |
> | `enable_alertmanager_datasource` | string | | `true` | | Add the Alertmanager datasource (active alerts, silences) |
> | `scrape_interval` | string | | `30s` | | Scrape interval of the cluster's Prometheus; Grafana uses it as the minimum query step. Whole units, combinable: 30s, 1m, 1m30s. |
> | `loki_max_lines` | number | | `5000` | | Maximum log lines a Loki query returns |
> | `kubernetes_dashboards` | string | | `true` | | Preload Kubernetes, Node Exporter and Loki dashboards from grafana.com at pod start |
> | `dashboards_folder` | string | | `Kubernetes` | | Holds the preloaded and extra dashboards. Letters, digits, spaces, hyphens, underscores; max 40 chars. |
> | `extra_dashboards` | string | | | | Unset = none. Else grafana.com dashboards as id:revision, comma-separated (e.g. 7249:1,14584:2), using the default datasource. |
> | `plugins` | string | | | | Unset = none. Else comma-separated grafana.com plugin ids (e.g. grafana-clock-panel), installed at pod start. |
> | `default_theme` | string | | `system` | | UI theme for users who have not picked one |
> | `default_timezone` | string | | `browser` | | For users who have not picked one: browser, utc, or an IANA name (e.g. Europe/Paris). |
> | `log_level` | string | | `info` | | Grafana server log level |
> | `persistence` | string | | `true` | | Keep users, dashboards and alert rules on a volume; false loses them on restart |
> | `storage_size` | string | | `10Gi` | | Kubernetes quantity (e.g. 10Gi). Can only grow after creation, on a storage class that allows expansion. |
> | `storage_class` | string | | | | Unset = the cluster's default. Set at creation: a volume cannot change class, so a later change fails the deploy. |
> | `cpu_request` | string | | `100m` | | Kubernetes quantity, e.g. 100m or 1 |
> | `memory` | string | | `512Mi` | | Request and limit, as a Kubernetes quantity (e.g. 512Mi, 1Gi) |

Outputs become environment variables that other services in the environment can use. By default Qovery also creates an alias for each output, prefixed with the Blueprint's name; see [Aliases Qovery creates for outputs](https://www.qovery.com/docs/configuration/environment-variables.md#aliases-qovery-creates-for-outputs) for the naming rules and the cases where no alias is created.

> [accordion] All 1 outputs
>
> | Name | Secret | Description |
> | - | - | - |
> | `grafana_service` | | In-cluster Grafana service name (port 80) |

## Reference

From the Blueprint's [README](https://github.com/Qovery/service-catalog/blob/HELM/grafana/13/1.1.1/HELM/grafana/13/README.md).

Deploys [Grafana](https://grafana.com/docs/grafana/latest/) 13 with the community `grafana-community/grafana` Helm chart (`13.2.5`), already connected to the observability stack Qovery installs on the cluster:

| Datasource | Default URL | Notes |
| - | - | - |
| Thanos | `http://thanos-query.prometheus.svc.cluster.local:9090` | Default datasource. Same PromQL as Prometheus, with long-term history |
| Prometheus | `http://prometheus-operated.prometheus.svc.cluster.local:9090` | Recent data only |
| Loki | `http://loki.logging.svc.cluster.local:3100` | Pod logs |
| Alertmanager | `http://alertmanager-operated.prometheus.svc.cluster.local:9093` | Silences and active alerts |

With `kubernetes_dashboards=true` (the default), a folder (`dashboards_folder`, default **Kubernetes**) is preloaded with the Kubernetes Views dashboards (global, namespaces, nodes, pods) and Node Exporter Full, plus a Loki logs dashboard when `enable_loki_datasource=true`. All of them read the metrics kube-prometheus-stack exposes, so they work on any Qovery cluster with metrics enabled.

### Credentials

The admin login is `admin_user` (default `admin`) and the sensitive `admin_password`, both entered in the Qovery console when creating the service.

* **Changing `admin_password`** and redeploying resets the admin password: an init container runs `grafana cli admin reset-admin-password` on every start, because Grafana otherwise reads the password only on its very first start.
* **`admin_user` is set once.** Grafana creates the admin account on first start and never renames it; changing the variable later has no effect. Rename the user in Grafana (Administration → Users) instead.

### Variables

#### Required

| Name | Type | Sensitive | Description |
| - | - | - | - |
| `admin_password` | string | yes | Grafana admin password, at least 12 characters. Changing it and redeploying resets the admin password. |

#### Optional

| Name | Type | Default | Description |
| - | - | - | - |
| `admin_user` | string | `admin` | Grafana admin login, set once at creation: changing it later has no effect (rename the user in Grafana). Letters, digits, dots, hyphens, underscores and @. |
| `root_url` | string | — | Unset = links and redirects use the address Grafana is reached on. Set it (e.g. [https://grafana.example.com](https://grafana.example.com)) when Grafana sits behind a custom domain or a path prefix. |
| `anonymous_access` | string | `false` | Let anyone who reaches Grafana browse dashboards without logging in, as Viewer (`true`/`false`). |
| `metrics_url` | string | `http://thanos-query.prometheus.svc.cluster.local:9090` | Leave the default on AWS and Scaleway clusters: it is the Thanos query endpoint Qovery installs with cluster metrics. On GKE and AKS use [http://thanos-query.qovery.svc.cluster.local:9090](http://thanos-query.qovery.svc.cluster.local:9090). Any Prometheus-compatible URL works. |
| `prometheus_url` | string | `http://prometheus-operated.prometheus.svc.cluster.local:9090` | Leave the default on AWS and Scaleway clusters: it is the in-cluster Prometheus (recent data only, no Thanos history). On GKE and AKS use [http://prometheus-operated.qovery.svc.cluster.local:9090](http://prometheus-operated.qovery.svc.cluster.local:9090). |
| `loki_url` | string | `http://loki.logging.svc.cluster.local:3100` | Leave the default. Set it only to read logs from another Loki. |
| `alertmanager_url` | string | `http://alertmanager-operated.prometheus.svc.cluster.local:9093` | Leave the default on AWS and Scaleway. On GKE and AKS use `http://alertmanager-operated.qovery.svc.cluster.local:9093`. |
| `default_datasource` | string | `thanos` | Datasource new panels and Explore open on (`thanos`/`prometheus`). |
| `enable_prometheus_datasource` | string | `true` | Add the direct Prometheus datasource next to Thanos. |
| `enable_loki_datasource` | string | `true` | Add the Loki datasource. `false` also drops the Loki logs dashboard. |
| `enable_alertmanager_datasource` | string | `true` | Add the Alertmanager datasource. |
| `scrape_interval` | string | `30s` | Scrape interval of the cluster's Prometheus, used as the minimum query step. Whole units, combinable: `30s`, `1m`, `1m30s`. |
| `loki_max_lines` | number | `5000` | Maximum log lines a Loki query returns (100–50000). |
| `kubernetes_dashboards` | string | `true` | Preload the Kubernetes (cluster, namespaces, nodes, pods), Node Exporter and Loki logs dashboards, downloaded from grafana.com when the pod starts |
| `dashboards_folder` | string | `Kubernetes` | Folder for the preloaded and extra dashboards. Letters, digits, spaces, hyphens, underscores, max 40 chars. Renaming it moves the dashboards. |
| `extra_dashboards` | string | — | Unset = no extra dashboard. Otherwise grafana.com dashboards as id:revision, comma-separated (e.g. 7249:1,14584:2). They use the default datasource. |
| `plugins` | string | — | Unset = no extra plugin. Otherwise plugin ids, comma-separated (e.g. grafana-piechart-panel,grafana-clock-panel), installed from grafana.com at pod start. |
| `default_theme` | string | `system` | UI theme for users who have not picked one (`system`/`dark`/`light`). |
| `default_timezone` | string | `browser` | Timezone dashboards display, for users who have not picked one: browser, utc, or an IANA name such as Europe/Paris or UTC. |
| `log_level` | string | `info` | Grafana server log level (`debug`/`info`/`warn`/`error`). |
| `persistence` | string | `true` | Keep Grafana's database on a volume. `false` = users, saved dashboards and alert rules are lost on every restart; switching an existing service to `false` deletes the volume. |
| `storage_size` | string | `10Gi` | Size of the data volume. Use a number with an Ei, Pi, Ti, Gi, Mi, or Ki suffix (e.g. 10Gi). It can only grow after creation, on a storage class that allows expansion. |
| `storage_class` | string | — | Unset = the cluster's default storage class. Choose it when creating the service: a volume cannot change class, so changing it later fails the deploy. |
| `cpu_request` | string | `100m` | CPU request for the Grafana container. Valid Kubernetes quantity (e.g. 100m, 1). |
| `memory` | string | `512Mi` | Memory request and limit for the Grafana container. Valid Kubernetes quantity (e.g. 512Mi, 1Gi). |

### Outputs

| Name | Description |
| - | - |
| `grafana_service` | In-cluster Grafana service name (`grafana`, port 80) |

### Accessing Grafana

The Grafana UI is published on the URL Qovery generates for the service (Helm service → Overview → Links), over HTTPS. Log in with `admin_user` and `admin_password`. Set `root_url` to that URL, or to your custom domain, so links in alert notifications point to it.

On a Qovery engine older than the one that added blueprint ports (QOV-2335), the service is created without a public URL. Reach it with a port-forward instead:

```sh theme={null}
kubectl port-forward -n <environment namespace> svc/grafana 3000:80
```

### Notes

* **Turning things off removes them.** A datasource switched off is deleted from Grafana (`deleteDatasources`), and a dashboard dropped from the form, or a renamed folder, has its downloaded file removed by the `blueprint-maintenance` init container, so Grafana stops provisioning it. A renamed folder leaves the old one behind, empty: Grafana never deletes folders. That container uses the plain `grafana/grafana:13.2.2` image, pinned to the chart's appVersion.

* **Volume settings are creation-time.** Kubernetes forbids changing a bound volume's class, so an update that changes `storage_class` fails with `spec is immutable after creation`, and Helm's automatic rollback fails for the same reason. Grafana keeps running on the previous release; set `storage_class` back to its original value and redeploy. `storage_size` can only grow.

* **Data sources depend on the cluster.** Thanos, Prometheus, Loki and Alertmanager exist only when metrics and logs are enabled on the Qovery cluster. Without them Grafana starts normally and the datasources report a connection error.

* **GKE and AKS** host the metrics stack in the `qovery` namespace rather than `prometheus`; set `metrics_url`, `prometheus_url` and `alertmanager_url` accordingly. Loki lives in `logging` on every provider.

* **Dashboards and plugins are downloaded from grafana.com** at each pod start, so the pod needs outbound HTTPS. On clusters without egress set `kubernetes_dashboards=false` and leave `extra_dashboards` and `plugins` unset.

* `deploymentStrategy: Recreate`: the data volume is ReadWriteOnce, so a rolling update would leave the new pod waiting on a multi-attach error.

* `fullnameOverride: grafana` gives a stable Service name. Deploy one Grafana blueprint per environment.

* One replica, no replica variable: Grafana's embedded SQLite database sits on a ReadWriteOnce volume, which one pod at a time can mount.

* `extra_dashboards` entries are `id:revision`; the revision must exist on grafana.com (the dashboard page lists them). A dashboard that cannot be downloaded, for a bad revision or because grafana.com is unreachable, does not block Grafana: it is skipped and logged as invalid, the others load.

* Sign-up is disabled and usage reporting to grafana.com is off.

* The rendered values, admin password included, are stored in the Helm service's values override, like every Helm blueprint's inputs.

* Chart pinned to `13.2.5` (Grafana `13.2.2`). The `grafana/grafana` chart is deprecated upstream; this is its community successor, not Bitnami.


## Related topics

- [Generate a Grafana snapshot report showing build runner pod usage for a specific deployment](https://www.qovery.com/docs/api-reference/environment-deployment-history/generate-a-grafana-snapshot-report-showing-build-runner-pod-usage-for-a-specific-deployment.md)
- [Blueprints](https://www.qovery.com/docs/configuration/blueprints.md)
- [Qovery Console AI Copilot](https://www.qovery.com/docs/copilot/console.md)
- [Deploy](https://www.qovery.com/docs/getting-started/guides/qovery-101/deploy.md)
- [Logs](https://www.qovery.com/docs/configuration/deployment/logs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.