The Complete Production SOP: How to Deploy and Run Grafana Dashboards as Code with Grafonnet & Terraform in Autonomous AI Agents
Deploy Grafana dashboards as code using Jsonnet, Grafonnet, and Terraform. Step-by-step agent rules for Codex, Claude Code, Cursor, and Windsurf.
Technical Overview & Architectural Context
Autonomous coding agents frequently stumble when provisioning Grafana dashboards as code. Left unconstrained, models hallucinate outdated Grafana JSON schema fields, mix legacy Angular panel definitions with React-based Time Series panels, or manually hardcode multi-thousand-line monolithic JSON structures that exceed LLM output token limits. Furthermore, when writing Jsonnet, agents commonly emit syntax that assumes nonexistent Grafonnet v7 helper methods or forget the transitive dependencies managed by jsonnet-bundler (jb). The `grafana-dashboard-as-code` skill establishes deterministic procedural boundaries. By enforcing modular Jsonnet authoring via Grafonnet libraries, strict separation of dynamic variables (multi-cluster, namespace filtering), and idempotent provisioning through the Terraform Grafana provider (`grafana_dashboard`), autonomous agents avoid structural schema drift. It equips runtimes like Codex, Claude Code, Cursor, and Windsurf to compile and validate dashboards locally before generating pull requests.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your agent's contextual skill registry.
Autonomous runtimes read SKILL.md files from scoped skill paths (`.agents/skills/` or `.cursor/rules/`). Mounting this skill ensures that triggers such as 'write grafana dashboard jsonnet' activate deterministic compile-and-validate workflows rather than raw JSON generation.
mkdir -p .agents/skills/grafana-dashboard-as-code && curl -fsSL https://askills.dev/api/skills/grafana-dashboard-as-code/raw -o .agents/skills/grafana-dashboard-as-code/SKILL.md---
name: "grafana-dashboard-as-code"
description: "Version-control and generate dynamic Grafana dashboards using Jsonnet and Terraform."
metadata:
author: "Grafana Labs"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "write grafana dashboard jsonnet"
- "deploy grafana dashboard terraform"
- "template variable grafana"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: true
net_access: false
---Store vendor dependencies in `.gitignore` and run `jb install` during agent setup to save context window tokens.
Ensure `shell_exec: true` is granted if the agent is responsible for executing `jsonnet` compilation and `terraform validate` directly.
Dependency Initialization & Grafonnet Vendoring
Initialize `jsonnetfile.json` and download official Grafonnet packages.
Agents must establish a local `vendor/` tree using jsonnet-bundler to resolve Grafonnet modules (`github.com/grafana/grafonnet/gen/grafonnet-v10.0.0` or latest). Without this step, compilation fails with missing import errors.
jb init && jb install github.com/grafana/grafonnet/gen/grafonnet-v10.0.0@main{
"version": 1,
"dependencies": [
{
"source": {
"git": {
"remote": "https://github.com/grafana/grafonnet.git",
"subdir": "gen/grafonnet-v10.0.0"
}
},
"version": "main"
}
],
"legacyImports": true
}Pin the Grafonnet version to match your target Grafana major version to avoid deprecated panel properties.
Never allow agents to commit raw vendor directories to version control; verify `.gitignore` contains `vendor/`.
Intent Matching & Declarative Dashboard Authoring
Instruct the agent to write parameterized Jsonnet declarations instead of raw JSON.
When prompted, the agent leverages imported Grafonnet packages to define dashboard metadata, template variables (e.g., Prometheus datasource, namespace, cluster), rows, and time series panels with strict query targets.
local grafonnet = import 'grafonnet-v10.0.0/main.libsonnet';
local dashboard = grafonnet.dashboard;
local variable = dashboard.variable;
local timeSeries = grafonnet.panel.timeSeries;
dashboard.new('Kubernetes Service Metrics')
+ dashboard.withUid('k8s-svc-metrics')
+ dashboard.withTags(['kubernetes', 'services'])
+ dashboard.withRefresh('30s')
+ dashboard.withVariables([
variable.query.new('namespace', 'label_values(kube_pod_info, namespace)')
+ variable.query.withLabel('Namespace')
+ variable.query.withDatasource('prometheus'),
])
+ dashboard.withPanels([
timeSeries.new('HTTP Request Rate')
+ timeSeries.queryOptions.withTargets([
{
expr: 'sum(rate(http_requests_total{namespace="$namespace"}[5m])) by (service)',
legendFormat: '{{service}}',
},
])
+ timeSeries.gridPos.withH(8)
+ timeSeries.gridPos.withW(12)
+ timeSeries.gridPos.withX(0)
+ timeSeries.gridPos.withY(0),
])Structure queries using Prometheus labels matched dynamically to the dashboard's template variables.
Watch for panel overlap; enforce precise `gridPos` coordinates (height `H`, width `W`, coordinates `X` and `Y`).
Compilation & Terraform Harness Integration
Compile Jsonnet to JSON and bind output to `grafana_dashboard` resources.
The agent executes `jsonnet` with library paths (`-J vendor`) and wires the compiled JSON into Terraform via `jsondecode` or direct `config_json` attributes.
jsonnet -J vendor dashboards/kubernetes_service.jsonnet -o compiled/kubernetes_service.json && terraform planterraform {
required_providers {
grafana = {
source = "grafana/grafana"
version = "~> 3.0"
}
}
}
resource "grafana_folder" "observability" {
title = "Kubernetes Observability"
}
resource "grafana_dashboard" "k8s_service" {
folder = grafana_folder.observability.uid
config_json = file("${path.module}/../compiled/kubernetes_service.json")
overwrite = true
}Use `overwrite = true` in Terraform to prevent state lockouts during continuous delivery updates.
Do not hardcode secrets or bearer tokens in Terraform files; ingest via `GRAFANA_AUTH` environment variable.
Real-World Scenario: Automating Multi-Cluster Ingress Dashboards via Jsonnet and Terraform
“Write a Grafana dashboard using Jsonnet for monitoring NGINX Ingress controllers. Include a multi-cluster template variable and a Time Series panel measuring 99th percentile latency. Then generate the Terraform configuration to deploy it to Grafana.”
Runtime Troubleshooting & Failure Modes
Root Cause: The Jsonnet CLI was executed without specifying the vendor directory search path (`-J vendor`), or `jb install` was not executed prior to compilation.
jb install && jsonnet -J vendor dashboards/kubernetes_service.jsonnet -o compiled/kubernetes_service.jsonRoot Cause: The Jsonnet specification omitted the mandatory `dashboard.new('<Title>')` root constructor, or the compiled JSON was evaluated as an empty payload.
Ensure dashboard declaration begins with: `local dashboard = grafonnet.dashboard; dashboard.new('Production Service Dashboard')`Frequently Asked Questions (Grafana Dashboards as Code with Grafonnet & Terraform SOP)
Q:Can I use Grafana Dashboards as Code with Grafonnet & Terraform across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. Runtimes automatically detect the manifest triggers ('write grafana dashboard jsonnet', 'deploy grafana dashboard terraform') and enforce identical validation pipelines.
Q:How does Grafana Dashboards as Code with Grafonnet & Terraform prevent context window overflow during long agent sessions?
Instead of generating 5,000+ line raw Grafana JSON strings directly in the LLM context, the skill guides the agent to write compact, modular Jsonnet templates (~50 lines) and delegates raw JSON generation to the local Jsonnet compiler.
Q:Does this skill require escalated root or container permissions?
No. The skill has an audited security score of 98/100. It requires only standard workspace filesystem write permissions (`fs_write: workspace`) and local CLI execution rights for `jb`, `jsonnet`, and `terraform`.
Ready to equip your autonomous agent with Grafana Dashboards as Code with Grafonnet & Terraform?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.