README.md

Grafonnet example

This repository contains an example of a Grafana dashboard as code, defined with Grafonnet, continuously deployed to a Grafana Cloud instance, thanks to Grizzly and GitHub Actions.

What's here?

• An example dashboard written in Jsonnet with Grafonnet.
  • Are you willing to extend it? Find here the Grafonnet API for dashboards.
• An example of how to use Grizzle to push dashboards to a Grafana instance.
  • Would you like to learn more about Grizzly? Find here the docs.
• An example of how to continuously deploy Grafonnet code to a Grafana instance with GitHub Actions.

Looking for building your own example?

If you're a learning-by-doing kind of person, you can follow the steps below to build your own example.

Pre-requisites

First of all, you need to have these tools up and running before starting:

• Jsonnet (go-jsonnet flavor)
• jsonnet-bundler
• Grafana Cloud instance (with a service account token with enough permissions - e.g. admin)

Step by step

1. Initialize a new project:

   jb init

2. Add Grafonnet as dependency:

   jb install github.com/grafana/grafonnet/gen/grafonnet-latest@main

3. Create an example.jsonnet file with a basic dashboard:

   local g = import 'github.com/grafana/grafonnet/gen/grafonnet-latest/main.libsonnet';
   
   g.dashboard.new('Grafonnet example')
   + g.dashboard.withDescription('Example dashboard built with Grafonnet')

4. Create a dashboards.libsonnet file with the main definition:

   {
     grafanaDashboards+:: {
       'example.json': (import 'example.jsonnet'),
     },
   }

   NOTE: It basically imports the example dashboard we defined in the previous step

5. Set up Grafana auth for Grizzly as Actions secrets:

   • GRAFANA_URL with the root url of your instance
   • GRAFANA_TOKEN with your service account token

6. Set up GitHub Actions to automatically grr apply your changes on every push to main:

   # .github/workflows/deploy.yml
   
   name: deploy
   
   on:
     push:
       branches:
         - main
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       container:
         image: grafana/grizzly:0.2.1-amd64
         env:
           GRAFANA_URL: ${{ secrets.GRAFANA_URL }}
           GRAFANA_TOKEN: ${{ secrets.GRAFANA_TOKEN }}
       steps:
         - name: Check out code
           uses: actions/checkout@v3
         - name: Deploy dashboards
           run: grr apply dashboards.libsonnet -l debug

7. Push new changes on example.jsonnet to main and enjoy!

Contribute

Have you detected a typo or something incorrect, and you are willing to contribute?

Please, open a pull request, and I'll be happy to review it.