---
component: dashboard-bundle
version: "2.4"
slug: dashboard-bundle/athena
canonical_url: "https://docs.develocity.ai/dashboard-bundle/2.4/athena/"
title: "Installing the Dashboard Bundle for Amazon Athena"
description: "Install and upgrade the Gradle-provided Grafana dashboards for a Develocity Reporting via Amazon Athena deployment, including Amazon Managed Grafana."
keywords:
- "Grafana"
- "Terraform"
- "Helm"
- "cluster"
status: current
---
# Installing the Dashboard Bundle for Amazon Athena
The Amazon Athena variant of the dashboard bundle contains Grafana dashboard definitions that query build data through Amazon Athena, together with the Athena schema statements and the Terraform modules that provision an Amazon Managed Grafana instance.
This page covers importing and upgrading those dashboards. Setting up the Athena schema and the Athena data export itself is covered in the [Develocity Reporting via Amazon Athena User Manual](https://docs.develocity.ai/reporting-aws/2.1/user-manual/).
Contact your technical contact at Gradle for assistance integrating the dashboards into your on-premises or cloud Grafana instance.
## Prerequisites
Before importing the dashboards, you need:
* A working Athena setup, as described in [Setup](https://docs.develocity.ai/reporting-aws/2.1/user-manual/#setup).
* A Grafana Athena data source, as described in [Connect to Amazon Athena](https://docs.develocity.ai/reporting-aws/2.1/user-manual/#connect_to_athena).
* A downloaded and unzipped bundle from [Downloads](https://docs.develocity.ai/dashboard-bundle/2.4/downloads/).
> [!NOTE]
> Throughout the following steps, all shell commands are expected to run in the root directory of the extracted bundle.
The dashboard JSON files reference the Grafana Athena data source by a fixed `UID`. Bundle 1.10.1 and later reference `develocity-reporting-athena`, while earlier bundles reference `athena-datasource-uid-placeholder`.
If your Grafana Athena data source already uses the `UID` that your bundle references, the dashboards work without modification. Otherwise, insert the `UID` of your Grafana Athena data source into the dashboard JSON files. The following command inserts the UID into all JSON files at once:
```shell
find ./dashboards -type f -name '*.json' -exec sed -i.bak 's/develocity-reporting-athena/YOUR-DATASOURCE-UID/g' {} \; \
&& find ./dashboards -type f -name '*.json.bak' -exec rm {} \;
```
> [!NOTE]
> For bundles earlier than 1.10.1, replace `develocity-reporting-athena` with `athena-datasource-uid-placeholder` in the command above.
> [!TIP]
> You can find your data source’s UID in the Grafana UI by navigating to Connections → Data Sources and clicking the Athena data source. The UID is displayed in the URL.
## Compatibility
For the Grafana versions the dashboards are tested against, see [Grafana dashboard compatibility](https://docs.develocity.ai/2026.3/miscellaneous/compatibility/#develocity_reporting_and_visualization_grafana).
For the Athena schema version each bundle version requires, see [Amazon Athena dashboard bundle compatibility](https://docs.develocity.ai/2026.3/miscellaneous/compatibility/#develocity_reporting_and_visualization_athena_bundle).
Most of the Gradle-provided dashboards rely on specific [tags](https://docs.develocity.ai/gradle/4.6/gradle-plugin/#adding_tags) and [custom values](https://docs.develocity.ai/gradle/4.6/gradle-plugin/#adding_custom_values) being present on Build Scan records to render the intended visualizations.
Tags used within the dashboards:
1. `CI`: classifies builds as either CI builds (the tag is present) or local builds (the tag is absent)
Custom values used within the dashboards:
1. `Git repository`: the URI of the Git repository the build ran in, for example `git@github.com:gradle/gradle.git`
2. `CI provider`: the name of the CI provider that ran the build, for example `GitHub Actions`
> [!TIP]
> If you use the Common Custom User Data Gradle plugin or the Common Custom User Data Maven extension, this information is added to every Build Scan automatically.
## Installation Methods
The steps for importing the dashboards differ depending on the type of Grafana installation. Besides manual import and the built-in [provisioning mechanism](https://grafana.com/docs/grafana/latest/administration/provisioning/#dashboards), Grafana also offers a [variety](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/) of _infrastructure as code_ options for managing dashboards.
### Using the Built-in Grafana Provisioning Mechanism
**Use if** you have access to the file system of the Grafana server.
Grafana has a [provisioning mechanism](https://grafana.com/docs/grafana/latest/administration/provisioning/#dashboards) that lets you point it at a directory containing dashboard definitions in JSON format. Grafana watches that directory for changes and automatically imports new dashboards or updates existing ones.
**Steps:**
1. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in [Prerequisites](#prerequisites).
2. Copy the contents of the `dashboards` folder from the bundle into a directory on your Grafana server. This guide assumes you copied the contents into `/var/lib/grafana/dashboards`, so that you end up with the following directory structure:
```
/var/lib/grafana/dashboards/
├─ 00 - Overview/
│ ├─ global-volume.json
│ ├─ project-volume.json
├─ 10 - Environment/
│ ├─ build-tools.json
│ ├─ ...
├─ ...
```
3. Place a `dashboards.yaml` file with the following content into Grafana’s provisioning directory at `/etc/grafana/provisioning/dashboards/`.
```yaml
apiVersion: 1
providers:
- name: 'Gradle Develocity Dashboards'
type: file
allowUiUpdates: false
disableDeletion: true
updateIntervalSeconds: 60
options:
path: /var/lib/grafana/dashboards
foldersFromFilesStructure: true
```
### Using Grafana Provisioning With Helm and Kubernetes
**Use if** you are self-hosting Grafana in a Kubernetes cluster and you manage your Grafana deployment with Helm.
The Grafana Helm chart contains an option that allows Grafana to discover and collect dashboards stored in ConfigMaps within the cluster.
**Steps:**
1. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in [Prerequisites](#prerequisites).
2. Place the dashboards into ConfigMaps with the label `grafana_dashboard: "1"`. Grafana recommends creating one ConfigMap per dashboard. You can create ConfigMaps individually per dashboard using the following `kubectl` command:
```shell
kubectl create configmap overview-global-volume-dashboard \
-n \
--from-file='./dashboards/00 - Overview/global-volume.json' \
--dry-run=client \
-o yaml \
| kubectl label -f- --dry-run=client -o yaml --local grafana_dashboard=1 \
| kubectl annotate -f- --dry-run=client -o yaml --local 'grafana_folder=/tmp/dashboards/00 - Overview' \
| kubectl apply --server-side=true -f -
```
To help you import all the dashboards while preserving the recommended folder structure, a kustomize file is included in the bundle. Apply it with this command:
```shell
kubectl kustomize ./ | kubectl apply -n --server-side=true -f -
```
3. Enable and configure the `dashboards` sidecar container in Grafana’s `values.yaml` file:
```yaml
sidecar:
dashboards:
enabled: true
label: grafana_dashboard
label_value: '1'
folderAnnotation: grafana_folder
provider:
name: 'Gradle Develocity Dashboards'
type: file
allowUiUpdates: false
disableDeletion: true
foldersFromFilesStructure: true
```
For more information, refer to Grafana’s [Helm installation guide](https://grafana.com/docs/grafana/latest/setup-grafana/installation/helm/) and the [Helm chart documentation](https://github.com/grafana/helm-charts/tree/main/charts/grafana).
### Manually Importing Dashboards via the Grafana UI
**Use if** you only need a small subset of the provided dashboards, and you can’t use any of the more automated methods described above.
> [!NOTE]
> You need the `Editor` role in Grafana to import dashboards via the UI.
**Steps:**
1. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in [Prerequisites](#prerequisites).
2. Go to your Grafana’s dashboard view at `https://grafana.example.com/dashboards`.
3. Optional: create a new folder for the Gradle dashboards by clicking **New** and selecting **Create Folder**.
4. Click **New** and select **Import**.
5. Drag the JSON file of the dashboard you want to import into the drop zone, or click the drop zone to open a file dialog, then click **Load**.
6. Confirm the name of the dashboard and the folder you want to import it into, then click **Import**.
### Using Amazon Managed Grafana With Terraform
**Use if** you want to use Amazon Managed Grafana, and you manage your infrastructure with Terraform.
> [!IMPORTANT]
> This only deploys the Amazon Managed Grafana instance and imports the dashboards. It requires an already working Athena setup to succeed. Amazon Managed Grafana uses either AWS IAM Identity Center or SAML. The provided Terraform scripts only support IAM Identity Center. If you want to use SAML, adjust the Terraform modules in terraform/modules/develocity-drv-aws-grafana-athena/grafana.tf accordingly.
The bundle includes a set of Terraform modules and scripts that create and populate an Amazon Managed Grafana instance along with the required permissions, buckets, and other ancillary resources. These modules live in the `terraform/modules` directory and can be integrated into your existing infrastructure as code pipeline.
> [!TIP]
> The shell scripts used in the following steps are provided as a convenience. You can also use them as a reference for integrating the Terraform modules into your existing infrastructure as code pipeline.
**Steps:**
* Ensure you have the AWS CLI installed and configured with the necessary [permissions](#required-aws-permissions).
* Make sure you have Terraform installed.
* **Decompress the bundle and navigate to the `terraform` directory. Every subsequent step should be executed in this directory.**
* The `terraform` directory contains three shell scripts used in the steps below:
* `provision-grafana.sh` deploys the Amazon Managed Grafana instance and its required resources.
* `provision-grafana-datasources.sh` installs the Athena plugin and creates the Athena data source.
* `provision-drv-dashboards.sh` imports the dashboards.
#### Prepare Your Environment
```shell
unzip gradle-dashboards-bundle-X-X-X.zip
```
Change your working directory to the `terraform` directory of the unzipped bundle:
```shell
cd terraform
```
#### Provision the Amazon Managed Grafana Instance
> [!IMPORTANT]
> The provided modules assume you use AWS IAM Identity Center to manage the users and groups that have access to the Amazon Managed Grafana instance. In that case, a set of user and group SSO IDs is required to set up the Grafana instance. These IDs aren’t the same as AWS user IDs: they must be retrieved from the AWS SSO console. Contact your AWS SSO administrator to get them.
Run the `provision-grafana.sh` script to deploy the Amazon Managed Grafana instance and its required resources.
```shell
provision-grafana.sh \
--bucket-name develocity \(1)
--aws-region eu-west-1 \(2)
--aws-profile my-profile \(3)
--develocity-drv-grafana-admin-user-ids my-sso-id \(4)
--develocity-drv-grafana-admin-group-ids my-sso-id \(4)
--prefix develocity \(5)
--apply \ (6)
--destroy (6)
```
1. The bucket name where your build models are stored. This is usually the same bucket as the one configured for Develocity.
2. The region where you want to deploy the Amazon Managed Grafana instance.
3. The name of the AWS CLI profile you want to use to deploy the resources.
4. The SSO IDs of the groups or users you want to have admin access to the Grafana instance. This is a repeatable argument. At least one of these arguments must be provided.
5. An optional prefix for the resources created by the script. This is useful for avoiding naming conflicts when deploying to the same AWS account.
6. To apply or destroy the resources respectively. If neither is provided, the script defaults to creating a Terraform plan. In either case you still need to interactively approve the plan before it is applied.
#### Install the Athena Plugin and Create the Athena Data Source
Once the Amazon Managed Grafana instance is deployed, install the Athena plugin and create the Athena data source by running `provision-grafana-datasources.sh`:
```shell
provision-grafana-datasources.sh \
--db-name develocity-db \(1)
--grafana-URL https://my-grafana-URL.com \(2)
--grafana-token my-grafana-token \(3)
--workgroup develocity-wg \(4)
--aws-region eu-west-1 \(5)
--apply \(6)
--destroy (6)
```
1. The name of the Glue database where the Athena tables were created.
2. Optional parameter, normally provided by the previous script automatically. The URL of the Amazon Managed Grafana instance.
3. Optional parameter, normally provided by the previous script automatically. The API token for the Amazon Managed Grafana instance.
4. Optional parameter, normally provided by the previous script automatically. The name of the Athena workgroup.
5. Optional parameter, normally provided by the previous script automatically. The region where the Amazon Managed Grafana instance was deployed.
6. To apply or destroy the resources respectively. If neither is provided, the script defaults to creating a Terraform plan. In either case you still need to interactively approve the plan before it is applied.
#### Import the Provided Dashboards
Finally, import the dashboards into the provisioned Grafana instance by running `provision-drv-dashboards.sh`:
```shell
provision-drv-dashboards.sh \
--dashboard-folder-path ../../../dashboards \(1)
--grafana-URL https://my-grafana-URL.com \(2)
--grafana-token my-grafana-token \(3)
--datasource-id my-datasource-id \(4)
--apply \(5)
--destroy (5)
```
1. The path to the directory containing the dashboard JSON files. If you are using the provided bundle, this is ../dashboards.
2. Optional parameter, normally provided by the previous script automatically. The URL of the Amazon Managed Grafana instance.
3. Optional parameter, normally provided by the previous script automatically. The API token for the Amazon Managed Grafana instance.
4. Optional parameter, normally provided by the previous script automatically. The ID of the data source created in the previous stage.
5. To apply or destroy the resources respectively. If neither is provided, the script defaults to creating a Terraform plan. In either case you still need to interactively approve the plan before it is applied.
> [!TIP]
> For security reasons, the lifetime of the Grafana token used to configure the Amazon Managed Grafana instance is limited. If the token expires, AWS returns Access denied errors when applying the Terraform plans. To fix this, rerun the provision-grafana-datasources.sh script with the --apply flag to generate a new token. This doesn’t affect any of the previously deployed resources.
If the script executions fail for some reason, run `terraform output stages/stage_name` to get the outputs of the executed stage. Alongside the Grafana URL and the administrator token, this provides valuable information for investigating the failures.
#### Required AWS Permissions
Deploying an Amazon Managed Grafana instance requires many permissions, because it’s a complex operation involving several resource types. The permissions and AWS-managed policies that must be attached to the user or role executing the Terraform scripts are listed below.
* Permissions required for managing IAM resources
* These permissions are required to manage the role that can be assumed by the managed Grafana instance, which has access to the bucket storing the build-model data used by Athena.
* `iam:ListRoles`
* `iam:CreateRole`
* `iam:GetRole`
* `iam:DeleteRole`
* `iam:ListRolePolicies`
* `iam:ListAttachedRolePolicies`
* `iam:ListInstanceProfilesForRole`
* `iam:AttachRolePolicy`
* `iam:PutRolePolicy`
* `iam:GetRolePolicy`
* `iam:DeleteRolePolicy`
* `iam:DetachRolePolicy`
* AWS managed policy required to manage S3 connections
* This policy is required to create and manage a bucket that stores the query results executed by Athena.
* `AmazonS3FullAccess`
* AWS managed policy required to manage Athena resources
* This policy is required to create and manage the Athena workgroup and the Athena database.
* `AmazonAthenaFullAccess`
* AWS managed policy required to administer the Amazon Managed Grafana instance
* This policy is required to create and manage the Amazon Managed Grafana instance.
* `AWSGrafanaAccountAdministrator`
* AWS managed policies to manage the SSO settings
* These policies are required to manage the SSO settings for the Amazon Managed Grafana instance.
* `AWSOrganizationsFullAccess`
* `AWSSSODirectoryAdministrator`
* `AWSSSOMasterAccountAdministrator`
## Upgrading
When you upgrade Develocity, new data becomes available and new dashboards may be added to surface more insights.
> [!IMPORTANT]
> Upgrading replaces every Gradle-provided dashboard. If you have created your own dashboards, or imported the bundle into a Grafana instance that holds other dashboards, make sure you only remove the dashboards supplied by Gradle.
How you deploy the new set of dashboards depends on how you originally installed them, so follow the instructions for your Grafana installation type.
### Upgrading Dashboards Provisioned With the Built-in Mechanism
If you installed the dashboards as described in [Using the Built-in Grafana Provisioning Mechanism](#using-the-built-in-grafana-provisioning-mechanism), upgrade them as follows:
1. Open your Grafana provisioning folder.
2. Delete all folders and files you want to update within the folder.
In a Docker Desktop environment, this may cause Docker to stop syncing changes. If that happens, restart the container, delete the files one by one, or enable **File Sharing** in your Docker Desktop settings.
3. Open Grafana and log in with an account that has edit privileges.
4. Open the Dashboards view and select the checkbox next to the **Name** header to select all folders.
Example of Selecting All Dashboard Folders by Name
5. Click **Delete**. This removes all dangling folders from the Grafana UI that can’t be automatically unprovisioned.
6. Download the latest bundle from [Downloads](https://docs.develocity.ai/dashboard-bundle/2.4/downloads/).
7. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in [Prerequisites](#prerequisites).
8. Copy the contents of the `dashboards` folder from the bundle into a directory on your Grafana server.
9. Restart your Grafana instance to apply the changes.
### Upgrading Dashboards Provisioned With Helm and Kubernetes
If you installed the dashboards as described in [Using Grafana Provisioning With Helm and Kubernetes](#using-grafana-provisioning-with-helm-and-kubernetes), upgrade them as follows:
1. Delete the ConfigMaps containing the dashboards.
```shell
kubectl --namespace delete configmap -l grafana_dashboard=1
```
2. Open Grafana and log in with an account that has edit privileges.
3. Open the Dashboards view and select the checkbox next to the **Name** header to select all folders.
Example of Selecting All Dashboard Folders by Name
4. Click **Delete**.
5. Download the latest bundle from [Downloads](https://docs.develocity.ai/dashboard-bundle/2.4/downloads/).
6. Replace the data source UID in the dashboard files with the UID of your Amazon Athena data source, as described in [Prerequisites](#prerequisites).
7. Run the kustomize file included in the bundle to re-import the dashboards.
```shell
kubectl kustomize ./ | kubectl apply -n --server-side=true -f -
```
### Upgrading Manually Imported Dashboards
If you imported the dashboards as described in [Manually Importing Dashboards via the Grafana UI](#manually-importing-dashboards-via-the-grafana-ui), upgrade them as follows:
1. Open Grafana and log in with an account that has edit privileges.
2. Open the Dashboards view and select the checkbox next to the **Name** header to select all folders.
Example of Selecting All Dashboard Folders by Name
3. Click **Delete**.
4. Download the latest bundle from [Downloads](https://docs.develocity.ai/dashboard-bundle/2.4/downloads/) and follow the installation procedure again.
### Upgrading Amazon Managed Grafana Installed With Terraform
If you installed Amazon Managed Grafana as described in [Using Amazon Managed Grafana With Terraform](#using-amazon-managed-grafana-with-terraform), download the latest bundle from [Downloads](https://docs.develocity.ai/dashboard-bundle/2.4/downloads/) and follow the installation procedure again, using the path of the newly downloaded dashboards.
> [!NOTE]
> Upgrading the Athena tables and views is a separate step, covered in [Upgrading Athena Tables](https://docs.develocity.ai/reporting-aws/2.1/user-manual/#upgrading-athena-tables) in the Amazon Athena user manual.