public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[release-12.3.0] Restructure As code and developer resources (#113969)

Browse Source 
Co-authored-by: Roberto Jiménez Sánchez <roberto.jimenez@grafana.com>
Co-authored-by: Anna Urbiztondo <anna.urbiztondo@grafana.com>
This commit is contained in:
Jack Baldry
2025-11-16 19:06:56 +00:00
committed by GitHub
parent 0898ec6045
commit 047da1442e
96 changed files with 8186 additions and 230 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/as-code/_index.md
+43
View File
@@ -0,0 +1,43 @@
---
aliases:
description: Deploy, configure and provision Grafana with as-code workflows.
menuTitle: As code
title: Deploy, configure and provision Grafana with as-code workflows
hero:
title: Configure and provision Grafana with as-code workflows
level: 1
width: 100
height: 100
description: Manage resources, including folders and dashboards, and configurations with as-code workflows.
cards:
items:
- description: Using Observability as code, you can version, automate, and scale Grafana configurations, including dashboards and observability workflows.
height: 24
href: ./observability-as-code/
title: Observability as code
- description: Using Infrastructure as code, you can declaratively manage what Grafana resources to use.
height: 24
href: ./infrastructure-as-code/
title: Infrastructure as code
weight: 850
canonical: https://grafana.com/docs/grafana/latest/as-code/
---
{{< docs/hero-simple key="hero" >}}
---
## Overview
**Observability as code** lets you apply code management best practices to your observability resources. By representing Grafana resources as code, you can integrate them into existing infrastructure-as-code workflows and apply standard development practices. Instead of manually configuring dashboards or settings through the Grafana UI, you can:
- Write configurations in code: Define dashboards in JSON or other supported formats.
- Sync your Grafana setup to GitHub: Track changes, collaborate, and roll back updates using Git and GitHub, or other remote sources.
- Automate with CI/CD: Integrate Grafana directly into your development and deployment pipelines.
- Standardize workflows: Ensure consistency across your teams by using repeatable, codified processes for managing Grafana resources.
In Grafana Cloud, you can use **Infrastructure as code** to declaratively create and manage dashboards via configuration files in source code, and incorporate them efficiently into your own use cases. This enables you to review code, reuse it, and create better workflows. Infrastructure as code tools include Terraform, Ansible, the Grafana Operator, and Grizzly.
## Explore
{{< card-grid key="cards" type="simple" >}}
docs/sources/as-code/infrastructure-as-code/_index.md
+200
View File
@@ -0,0 +1,200 @@
---
keywords:
- Infrastructure as code
- Quickstart
- Grafana Cloud
menuTitle: Infrastructure as code
title: Provision Grafana Cloud with infrastructure as code
weight: 800
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/
---
# Provision Grafana Cloud with infrastructure as code
With Grafana Cloud, you can create dashboards via configuration files in source code. This enables you to review code, reuse it, and create better workflows.
Via code, you can _declaratively_ manage _what_ Grafana resources to use.
The as-code tools and tutorials that follow show you what do to, to declaratively manage Grafana resources, and incorporate them efficiently into your own use cases.
## Grafana Terraform provider
Grafana administrators can manage dashboards, alerts and collectors, add synthetic monitoring probes and checks, manage identity and access, and more using the [Terraform provider for Grafana](https://registry.terraform.io/providers/grafana/grafana/latest).
The following example shows a Terraform configuration for creating a dashboard:
```terraform
resource "grafana_dashboard" "metrics" {
config_json = jsonencode({
title = "as-code dashboard"
uid = "ascode"
})
}
```
This example dashboard only creates the dashboard and does not add any panels or rows.
To get started, see the [Grafana Terraform provider guides](/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/) or refer to the [Terraform Grafana Provider documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
### Who is this recommended for?
Grafana Terraform provider is best suited for users who are already using Terraform for non-Grafana use cases.
To manage the entire Grafana ecosystem of resources on either Grafana Cloud or OSS deployments of Grafana, it’s best to use the Terraform Grafana provider because it supports the most Grafana resources compared to Grafana’s other as-code solutions.
For Grafana Fleet Management users, the Grafana Terraform provider is best used to preregister new collectors before they are operational or add remote attributes to collectors already registered with the service.
### Known limitations
Managing dashboards isn’t the simplest process—you have to work with long JSON files, which can become difficult to review and update, as well. Grafonnet can help with generating dashboard JSONs that can be used in Terraform, but Grafonnet requires knowing Jsonnet.
## Grafana Ansible collection
Resources for configuration management are available for Grafana through the [Ansible collection for Grafana](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html#plugins-in-grafana-grafana). The Grafana Ansible collection can be used to manage a variety of resources, including folders, cloud stacks, and dashboards. You can programmatically manage resources on Grafana that aren’t currently part of the Grafana Ansible collection by writing Ansible playbooks that use the HTTP APIs to manage resources for Grafana.
The following example shows an Ansible configuration for creating a dashboard:
```yaml
- name: dashboard as code
grafana.grafana.dashboard:
dashboard: { 'title': 'as-code dashboard', 'uid': 'ascode' }
stack_slug: '{{ stack_slug }}'
grafana_api_key: '{{ grafana_api_key }}'
state: present
```
This example dashboard creates only the dashboard and does not add any panels or rows.
To get started, see the [quickstart guides for the Grafana Ansible Collection](/docs/grafana-cloud/as-code/infrastructure-as-code/ansible/) or check out the [collections's documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html#plugins-in-grafana-grafana).
### Who is this recommended for?
Like Terraform, the Grafana Ansible collection is best suited for people already using Ansible for non-Grafana use cases. The collection only works for Grafana Cloud right now, so it makes the most sense for Grafana Cloud customers who want to manage resources declaratively using Ansible.
### Known limitations
The Grafana Ansible collection only works for Grafana Cloud and only supports eight resources: API keys, cloud stacks, plugins, dashboards, folders, data sources, alert contact points, and notification policies. This can be a drawback if you want to manage the entire Grafana ecosystem as code with Ansible. As with Terraform, building dashboards is a challenging process.
## Grafana Operator
The Grafana Operator is a Kubernetes operator that can provision, manage, and operate Grafana instances and their associated resources within Kubernetes through Custom Resources. This Kubernetes-native tool eases the administration of Grafana, offering a declarative approach to managing dashboards, data sources, and folders. It also automatically syncs the Kubernetes Custom resources and the actual resources in the Grafana Instance. It supports leveraging Grafonnet for generating Grafana dashboard definitions for seamless dashboard configuration as code.
To get started, see the [quickstart guides for the Grafana Operator](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/) or check out the [Grafana Operator's documentation](https://grafana.github.io/grafana-operator/).
A sample Kubernetes configuration for creating a dashboard using the Grafana operator looks like this:
```yaml
apiVersion: integreatly.org/v1alpha1
kind: GrafanaDashboard
metadata:
name: simple-dashboard
labels:
app: grafana
spec:
instanceSelector:
matchLabels:
dashboards: <Grafana-custom-resource-name>
json: >
{
"title": "as-code dashboard",
“uid” : “ascode”
}
```
### Who is this recommended for?
The Grafana Operator is particularly fitting for:
- Teams seeking integrated solutions to manage Grafana resources within the Kubernetes cluster ecosystem.
- Teams employing a GitOps approach, allowing them to treat Grafana configurations as code, stored alongside application manifests for versioned and automated deployments.
### Known limitations
While the Grafana Operator simplifies many aspects of operating Grafana and its resources on Kubernetes, its current support is mainly focused on managing dashboards, folders, and data sources. Advanced features like alerting and plugins (only works for OSS) are not supported yet.
## Grizzly
[Grizzly](https://grafana.github.io/grizzly/) is a command line tool that allows you to manage your observability resources with code. Grizzly supports Kubernetes-inspired YAML representation for the Grafana resource, which makes it easier to learn. With Grizzly, you can move dashboards within Grafana instances and also retrieve information about already provisioned Grafana resources. Grizzly currently supports:
- Grafana dashboards and dashboard folders
- Grafana data sources
- Prometheus recording rules and alerts in Grafana Cloud
- Grafana Cloud Synthetic Monitoring checks
Grizzly can also deploy dashboards built in Jsonnet using Grafonnet. (Learn more in the [Grafonnet documentation](https://grafana.github.io/grafonnet-lib/api-docs/).)
The following example shows a Kubernetes-style Grizzly configuration for creating a dashboard:
```yaml
apiVersion: grizzly.grafana.com/v1alpha1
kind: Dashboard
metadata:
name: as-code-dashboard
spec:
title: as-code dashboard
uid: ascode
```
To get started, see the [Grizzly guides](grizzly/dashboards-folders-datasources/) or refer to the [Grizzly’s documentation](https://grafana.github.io/grizzly/).
### Who is this recommended for?
Grizzly is best suited for users who are either using Jsonnet to manage Grafana resources or those who prefer a Kubernetes-style YAML definition of their Grafana resources.
### Known limitations
Grizzly currently doesn’t support Grafana OnCall and Grafana Alerting resources.
## Grafana Crossplane provider
[Grafana Crossplane provider](https://github.com/grafana/crossplane-provider-grafana) is built using Terrajet and provides support for all resources supported by the Grafana Terraform provider. It enables users to define Grafana resources as Kubernetes manifests and it also help users who build their GitOps pipelines around Kubernetes manifests using tools like ArgoCD.
To get started with the Grafana Crossplane provider, install Crossplane in the Kubernetes cluster and use this command to install the provider:
```shell
kubectl crossplane install provider grafana/crossplane-provider-grafana:v0.1.0
```
During installation of the provider, CRDs for all the resources supported by the Terraform provider are added to the cluster so users can begin defining their Grafana resources as Kubernetes custom resources. The Crossplane provider ensures that whatever is defined in the custom resource definitions is what is visible in Grafana UI. If any changes are made directly in the UI, the changes will be discarded when the provider resyncs. This helps ensure that whatever is defined declaratively in the cluster will be the source of truth for Grafana resources.
To get started, refer to the examples folder in the Grafana Crossplane repository.
The following example shows a Kubernetes custom resource definition for creating a dashboard:
```yaml
apiVersion: grafana.jet.crossplane.io/v1alpha1
kind: Dashboard
metadata:
name: as-code-dashboard
spec:
forProvider:
configJson: |
{
"title": "as-code dashboard",
"uid": "ascode"
}
providerConfigRef:
name: grafana-crossplane-provider
```
### Who is this recommended for?
The Grafana Crossplane provider is intended for existing Crossplane users looking to manage Grafana resources from within Kubernetes and as Kubernetes manifests for the GitOps pipelines.
### Known limitations
To use the Crossplane provider, you must have the Crossplane CLI and Crossplane installed in the Kubernetes cluster. Note that the Crossplane provider is in an alpha stage, so it has not reached a stable state yet.
## Grafana as code comparison
Most of the tools defined here can be used with one another.
The following chart compares the properties and tools mentioned above.
| Property/Tool | Grafana Terraform Provider | Grafana Ansible Collection | Grafana Operator | Grizzly | Grafana Crossplane Provider |
| -------------------------------------- | --------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Grafana resources supported | All major Grafana resources | Grafana Cloud stack, plugins, API keys, dashboards, data sources, and folders | Dashboards, Datasources, Folders | Synthetic Monitoring checks, dashboards, data sources, folders, and Prometheus rules | All major Grafana resources |
| Tool format | HCL/JSON | YAML | YAML | Jsonnet/YAML/JSON | YAML/JSON |
| Follows Kubernetes-style manifests | | | ✓ | ✓ | ✓ |
| Easy dashboard building process | | | ✓ | ✓ | |
| Manage resources using Kubernetes | | | ✓ | | ✓ |
| Retrieves Grafana resource information | ✓ | | | | |
| Built-in resource sync process | | | ✓ | ✓ | ✓ |
| Recommended for | Existing Terraform users | Existing Ansible users | Users looking to manage Grafana resources from within Kubernetes | Users looking to define Grafana resources in a Kubernetes-style YAML and users looking to get built-in workflow support and sync process | Users looking to manage Grafana resources from within Kubernetes |
docs/sources/as-code/infrastructure-as-code/ansible/_index.md
+29
View File
@@ -0,0 +1,29 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Ansible
menuTitle: Ansible
title: Grafana Ansible collection
weight: 110
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/
---
# Grafana Ansible collection
The [Grafana Ansible collection](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/) provides configuration management resources for Grafana. You can use it to manage resources such as dashboards, Cloud stacks, folders, and more.
The collection also houses the [Grafana Agent role](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent) which can be used to deploy and manage Grafana Agent across various Linux machines.
{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
For resources currently not available in the Grafana Ansible collection, you can manage those resources on Grafana Cloud programmatically by writing Ansible playbooks that use the [Ansible's builtin uri module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/uri_module.html) to call the [HTTP APIs](/docs/grafana/latest/developers/http_api/) to manage resources for the Grafana Cloud portal, as well as those within a stack.
Use the following guides to get started using Ansible to manage your Grafana Cloud stack:
| Topic | Description |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [Create and manage a Grafana Cloud stack using Ansible](ansible-cloud-stack/) | Describes how to create a Grafana Cloud stack and add a data source and dashboard using [Ansible](https://www.ansible.com/). |
| [Install Grafana Agent on a Linux host using Ansible](ansible-grafana-agent-linux/) | Describes how to install the Grafana Agent on a Linux node using Ansible and use it to push logs to Grafana Cloud. |
| [Monitor multiple Linux hosts with Grafana Agent Role](ansible-multiple-agents/) | Describes how to use the Grafana Ansible collection to manage agents across multiple Linux hosts. |
docs/sources/as-code/infrastructure-as-code/ansible/ansible-cloud-stack/index.md
+259
View File
@@ -0,0 +1,259 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Ansible
title: Create and manage a Grafana Cloud stack using Ansible
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-cloud-stack/
---
# Create and manage a Grafana Cloud stack using Ansible
Learn how to add a data source, a dashboard, and a folder to a Grafana Cloud stack using Ansible collection for Grafana.
## Before you begin
Before you begin, you should have the following available:
- A Grafana Cloud account.
- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html) installed on your machine
## Create a Cloud stack
1. Create a Grafana Cloud Access Policy and get a token.
You'll need this for the Ansible playbook to be able to create a Grafana Cloud stack.
Refer to [Create a Grafana Cloud Access Policy](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies/).
1. Create an Ansible playbook file.
This Ansible playbook will create a Grafana Cloud stack by using the [Cloud stack module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/cloud_stack_module.html#ansible-collections-grafana-grafana-cloud-stack-module).
Create a file named `cloud-stack.yml` and add the following:
```yaml
- name: Create Grafana Cloud stack
connection: local
hosts: localhost
vars:
grafana_cloud_api_key: '<Your Cloud Access Policy token>'
stack_name: '<stack-name>'
org_name: '<org-name>'
tasks:
- name: Create a Grafana Cloud stack
grafana.grafana.cloud_stack:
name: '{{ stack_name }}'
stack_slug: '{{ stack_name }}'
cloud_api_key: '{{ grafana_cloud_api_key }}'
org_slug: '{{ org_name }}'
delete_protection: true
state: present
```
1. Replace the following field values:
- `<token>` with a token from the Cloud Access Policy you created in the Grafana Cloud portal.
- `<stack-name>` with the name of your stack.
- `<org-name>` with the name of the organization in Grafana Cloud.
## Create an API key in the Grafana stack
Create an API key in the Grafana stack.
You'll need this key to configure Ansible to be able to create data source, folders, and dashboards.
1. Log into your Grafana Cloud instance.
2. Click **Administration** and select **API keys**.
3. Click **Add API key**.
4. In **Key name**, enter a name for your API key.
5. In **Role**, select **Admin** or **Editor** to associate the role with this API key.
6. Click **Copy** to save it for later use.
## Add a data source
This guide uses the InfluxDB data source.
The required arguments vary depending on the type of data source you select.
1. Create a file named `data-source.yml` and add the following:
```yaml
- name: Add/Update data source
connection: local
hosts: localhost
vars:
data_sources:
[
{
name: '<data-source-name>',
type: 'influxdb',
url: '<data-source-url>',
user: '<username>',
secureJsonData: { password: '<password>' },
database: '<db-name>',
id: <id>,
uid: '<uid>',
access: 'proxy',
},
]
grafana_api_key: '<API-Key>'
stack_name: '<stack-name>'
tasks:
- name: Create/Update Data sources
grafana.grafana.datasource:
datasource: '{{ item }}'
stack_slug: '{{ stack_name }}'
grafana_api_key: '{{ grafana_api_key }}'
state: present
loop: '{{ data_sources }}'
```
1. Replace the following field values:
- `<data-source-name>` with the name of the data source to be added in Grafana.
- `<data-source-url>` with URL of your data source.
- `<username>` with the username for authenticating with your data source.
- `<password>` with the password for authenticating with your data source.
- `<db-name>` with name of your database.
- `<id>` with the ID for your data source in Grafana.
- `<uid>` wth the UID for your data source in Grafana.
- `<stack-name>` with the name of your stack.
- `<API-key>` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack).
## Add a folder
This Ansible playbook creates a folder in your Grafana instance by using the [Folder module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/folder_module.html#ansible-collections-grafana-grafana-folder-module).
1. Create a file named `folder.yml` and add the following:
```yaml
- name: Add/Update Folders
connection: local
hosts: localhost
vars:
folders: [{ title: '<folder-name>', uid: '<uid>' }]
stack_name: '<stack-name>'
grafana_api_key: <API-key>
tasks:
- name: Create/Update a Folder in Grafana
grafana.grafana.folder:
title: '{{ item.title }}'
uid: '{{ item.uid }}'
stack_slug: '{{ stack_name }}'
grafana_api_key: '{{ grafana_api_key }}'
state: present
loop: '{{ folders }}'
```
1. Replace the following field values:
- `<folder-name>` with the name of the folder to be added in Grafana.
- `<uid>` with the UID for your folder in Grafana.
- `<stack-name>` with the name of your stack.
- `<API-key>` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack).
## Add a dashboard to the folder
This Ansible playbook iterates through the dashboard JSON source code files in the folder referenced in `dashboards_path` and adds them in the Grafana instance by using the [Dashboard module](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/dashboard_module.html#ansible-collections-grafana-grafana-dashboard-module).
1. Create a file named `dashboard.yml` and add the following:
```yaml
- name: Add/Update Dashboards
connection: local
hosts: localhost
vars:
dashboards_path: <path-to-dashboard-files> # Example "./dashboards"
stack_name: "<stack-name>"
grafana_api_key: <API-key>
tasks:
- name: Find dashboard files
find:
paths: "{{ dashboards_path }}"
file_type: file
recurse: Yes
patterns: "*.json"
register: files_matched
no_log: True
- name: Create list of dashboard file names
set_fact:
dashboard_file_names: "{{ dashboard_file_names | default ([]) + [item.path] }}"
loop: "{{ files_matched.files }}"
no_log: True
- name: Create/Update a dashboard
grafana.grafana.dashboard:
dashboard: "{{ lookup('ansible.builtin.file','{{ item }}' ) }}"
stack_slug: "{{ stack_name }}"
grafana_api_key: "{{ grafana_api_key }}"
state: present
loop: "{{ dashboard_file_names }}"
```
1. Replace the following field values:
- `<path-to-dashboard-files>` with the path to the folder containing dashboard JSON source code files.
- `<stack-name>` with the name of your stack.
- `<API-key>` with the [API key created in the Grafana instance](#create-an-api-key-in-the-grafana-stack).
## Run the Ansible playbooks
In a terminal, run the following commands from the directory where all of the Ansible playbooks are located.
1. To create the Grafana Cloud stack.
```shell
ansible-playbook cloud-stack.yml
```
1. To add a data source to the Grafana stack.
```shell
ansible-playbook data-source.yml
```
1. To add a folder to the Grafana stack
```shell
ansible-playbook folder.yml
```
1. To add a dashboard to the folder in your Grafana stack.
```shell
ansible-playbook dashboard.yml
```
## Validation
Once you run the Ansible playbooks, you should be able to verify the following:
- The new Grafana stack is created and visible in the Cloud Portal.
![Cloud Portal](/static/img/docs/grafana-cloud/terraform/cloud_portal_tf.png)
- A new data source (InfluxDB in this example) is visible in the Grafana stack.
![InfluxDB datasource](/media/docs/grafana-cloud/screenshot-influxdb_datasource_tf.png)
- A new folder in Grafana.
In the following image, a folder named `Demos` was added.
![Folder](/media/docs/grafana-cloud/screenshot-folder_tf.png)
- A new dashboard in the Grafana stack.
In the following image a dashboard named `InfluxDB Cloud Demos` was created inside the "Demos" folder.
![InfluxDB dashboard](/static/img/docs/grafana-cloud/terraform/influxdb_dashboard_tf.png)
## Summary
In this guide, you created a Grafana Cloud stack along with a data source, folder, and dashboard imported from a JSON file using Ansible.
To learn more about managing Grafana using Ansible, refer to the [Grafana Ansible collection](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/).
docs/sources/as-code/infrastructure-as-code/ansible/ansible-grafana-agent-linux/index.md
+156
View File
@@ -0,0 +1,156 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Ansible
title: Install Grafana Agent on a Linux host using Ansible
weight: 200
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-grafana-agent-linux/
---
# Install Grafana Agent on a Linux host using Ansible
{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
This guide shows how to install Grafana Agent on a Linux host using [Ansible](https://www.ansible.com/) and to use it to push logs to Grafana Cloud.
## Before you begin
Before you begin, you should have the following available:
- A Grafana Cloud account.
- A Linux machine
- Command line (terminal) access to that Linux machine with `unzip` binary installed
- Account permissions sufficient to install and use Grafana Agent on the Linux machine
- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/index.html) installed on the Linux machine
## Choose your Grafana Agent installation method
This guide covers two methods for installing and configuring Grafana Agent using Ansible:
- Installing Grafana Agent in Flow mode
- Installing Grafana Agent in static mode
Depending on your specific needs and the configuration of your environment, you may choose one method over the other for better compatibility or ease of setup.
<!-- vale Grafana.Spelling = NO -->
### Install Grafana Agent in flow mode using Ansible
This Ansible playbook installs Grafana Agent in Flow mode and also creates a systemd service to manage it.
It creates a user named `grafana-agent` on the Linux machine for running Grafana Agent.
1. Create a file named `grafana-agent.yml` and add the following:
```yaml
- name: Install Grafana Agent Flow
hosts: all
become: true
tasks:
- name: Install Grafana Agent Flow
ansible.builtin.include_role:
name: grafana.grafana.grafana_agent
vars:
grafana_agent_mode: flow
# Change config file on the host to .river
grafana_agent_config_filename: config.river
# Change config file to be copied
grafana_agent_provisioned_config_file: '<path-to-config-file>'
# Remove default flags
grafana_agent_flags_extra:
server.http.listen-addr: '0.0.0.0:12345'
```
1. Replace the following field values:
- `<path-to-config-file-on-localhost>` with the path to river configuration file on the Ansible Controller (Localhost).
### Install Grafana Agent in static mode using Ansible
This Ansible playbook installs Grafana Agent in static mode and also creates a systemd service to manage it.
It creates a user named `grafana-agent` on the Linux machine for running Grafana Agent.
1. Create a file named `grafana-agent.yml` and add the following:
```yaml
- name: Install Grafana Agent in static mode
hosts: all
become: true
vars:
grafana_cloud_api_key: <Your Cloud Access Policy token>
logs_username: <loki-username> # Example - 411478
loki_url: <loki-push-url> # Example - https://logs-prod-017.grafana.net/loki/api/v1/push
tasks:
- name: Install Grafana Agent in static mode
ansible.builtin.include_role:
name: grafana_agent
vars:
grafana_agent_logs_config:
configs:
- clients:
- basic_auth:
password: '{{ grafana_cloud_api_key }}'
username: '{{ logs_username }}'
url: '{{ loki_url }}'
name: default
positions:
filename: /tmp/positions.yaml
scrape_configs:
- job_name: integrations/node_exporter_direct_scrape
static_configs:
- targets:
- localhost
labels:
instance: hostname
__path__: /var/log/*.log
job: integrations/node_exporter
target_config:
sync_period: 10s
```
1. Replace the following field values:
- `<Your Cloud Access Policy token>` with a token from the Cloud Access Policy you created in the Grafana Cloud portal.
- `<loki-username>` with the Loki Username
- `<loki-push-url>` with the push endpoint URL of Loki Instance
## Run the Ansible playbook on the Linux machine
In the Linux machine's terminal, run the following command from the directory where the Ansible playbook is located.
```shell
ansible-playbook grafana-agent.yml
```
## Validate
<!-- vale Grafana.ReferTo = NO -->
1. Grafana Agent service on the Linux machine should be `active` and `running`. You should see a similar output:
<!-- vale Grafana.ReferTo = NO -->
```shell
$ sudo systemctl status grafana-agent.service
grafana-agent.service - Grafana Agent
Loaded: loaded (/etc/systemd/system/grafana-agent.service; enabled; vendor preset: enabled)
Active: active (running) since Wed 2022-07-20 09:56:15 UTC; 36s ago
Main PID: 3176 (agent-linux-amd)
Tasks: 8 (limit: 515)
Memory: 92.5M
CPU: 380ms
CGroup: /system.slice/grafana-agent.service
└─3176 /usr/local/bin/agent-linux-amd64 --config.file=/etc/grafana-cloud/agent-config.yaml
```
1. In a Grafana Cloud stack, click **Explore** in the left-side menu.
1. At the top of the page, use the dropdown menu to select your Loki logs data source. In the Log Browser, run the query `{job="integrations/node_exporter"}`
![Loki Logs](/static/img/docs/grafana-cloud/ansible/ansible-agent-logs.png)
## Summary
In this guide, you installed Grafana Agent on a Linux node using Ansible and used it to pushed logs to Grafana Cloud.
To learn more about the Grafana Ansible collection, refer to the [GitHub repository](https://github.com/grafana/grafana-ansible-collection) or its [documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html).
docs/sources/as-code/infrastructure-as-code/ansible/ansible-multiple-agents/index.md
+207
View File
@@ -0,0 +1,207 @@
---
menuTitle: Monitor multiple Linux hosts with the grafana_agent role
title: Monitor multiple Linux hosts with grafana_agent role
weight: 300
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/ansible/ansible-multiple-agents/
---
# Monitor multiple Linux hosts with the `grafana_agent` role
{{< docs/shared lookup="agent-deprecation.md" source="alloy" version="next" >}}
Monitoring multiple Linux hosts can be difficult.
To make it easier, you can use the `grafana_agent` role with the [Grafana Ansible collection](../).
This guide shows how to use the `grafana_agent` Ansible role to deploy and manage Grafana Agent across multiple Linux hosts so you can monitor them using Grafana Cloud.
## Before you begin
Before you begin, you should have:
- Linux hosts
- SSH access to the Linux hosts
- Account permissions sufficient to install and use Grafana Agent on the Linux hosts
## Install the Grafana Ansible collection
The [`grafana_agent` role](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent) is available in the Grafana Ansible collection as of the 1.1.0 release.
To install the Grafana Ansible collection, run this command:
```
ansible-galaxy collection install grafana.grafana
```
## Create an Ansible inventory file
Next, you will set up your hosts and create an inventory file.
1. Create your hosts and add public SSH keys to them.
This example uses eight Linux hosts: two Ubuntu hosts, two CentOS hosts, two Fedora hosts, and two Debian hosts.
1. Create an Ansible inventory file.
The Ansible inventory, which resides in a file named `inventory`, looks similar to this:
```
146.190.208.216 # hostname = ubuntu-01
146.190.208.190 # hostname = ubuntu-02
137.184.155.128 # hostname = centos-01
146.190.216.129 # hostname = centos-02
198.199.82.174 # hostname = debian-01
198.199.77.93 # hostname = debian-02
143.198.182.156 # hostname = fedora-01
143.244.174.246 # hostname = fedora-02
```
1. Create an `ansible.cfg` file within the same directory as `inventory`, with the following values:
```
[defaults]
inventory = inventory # Path to the inventory file
private_key_file = ~/.ssh/id_rsa # Path to my private SSH Key
remote_user=root # username
```
{{< admonition type="note" >}}
If you are copying the previously listed files, remove the comments (#).
{{< /admonition >}}
## Use the `grafana_agent` Ansible role
Next you will create an Ansible playbook that calls the `grafana_agent` role from the `grafana.grafana` Ansible collection.
To use the `grafana_agent` Ansible role:
1. Create a file named `deploy-agent.yml` in the same directory as `ansible.cfg` and `inventory` and add the configuration below.
```yaml
- name: Install Grafana Agent
hosts: all
become: true
vars:
grafana_cloud_api_key: <Your Cloud Access Policy token>
metrics_username: <prometheus-username> # Example - 825019
logs_username: <loki-username> # Example - 411478
prometheus_url: <prometheus-push-url> # Example - https://prometheus-us-central1.grafana.net/api/prom/push
loki_url: <loki-push-url> # Example - https://logs-prod-017.grafana.net/loki/api/v1/push
tasks:
- name: Install Grafana Agent
ansible.builtin.include_role:
name: grafana.grafana.grafana_agent
vars:
grafana_agent_metrics_config:
configs:
- name: integrations
remote_write:
- basic_auth:
password: '{{ grafana_cloud_api_key }}'
username: '{{ metrics_username }}'
url: '{{ prometheus_url }}'
global:
scrape_interval: 60s
wal_directory: /tmp/grafana-agent-wal
grafana_agent_logs_config:
configs:
- name: default
clients:
- basic_auth:
password: '{{ grafana_cloud_api_key }}'
username: '{{ logs_username }}'
url: '{{ loki_url }}'
positions:
filename: /tmp/positions.yaml
target_config:
sync_period: 10s
scrape_configs:
- job_name: varlogs
static_configs:
- targets: [localhost]
labels:
instance: ${HOSTNAME:-default}
job: varlogs
__path__: /var/log/*log
grafana_agent_integrations_config:
node_exporter:
enabled: true
instance: ${HOSTNAME:-default}
prometheus_remote_write:
- basic_auth:
password: '{{ grafana_cloud_api_key }}'
username: '{{ metrics_username }}'
url: '{{ prometheus_url }}'
grafana_agent_env_vars:
HOSTNAME: '%H'
```
The playbook calls the `grafana_agent` role from the `grafana.grafana` Ansible collection.
The Agent configuration in this playbook send metrics and logs from the Linux hosts to Grafana Cloud along with the hostname of each instance
Refer to the [Grafana Ansible documentation](https://github.com/grafana/grafana-ansible-collection/tree/main/roles/grafana_agent#role-variables) to understand the other variables you can pass to the `grafana_agent` role.
When deploying the Agent across multiple instances for monitoring them, It is essential that the Agent is able to auto-detect the hostname for ease in monitoring.
Notice that the label `instance` has been set to the value `${HOSTNAME:-default}`, which is substituted by the value of the HOSTNAME environment variable in the Linux host.
To read more about the variable substitution, refer to the Grafana Agent [node_exporter_config](/docs/grafana-cloud/send-data/agent/static/configuration/integrations/node-exporter-config/) documentation.
1. To run the playbook, run this command:
```
ansible-playbook deploy-agent.yml
```
{{< admonition type="note" >}}
You can place the `deploy-agent.yml`, `ansible.cfg` and `inventory` files in different directories based on your needs.
{{< /admonition >}}
## Check that logs and metrics are being ingested into Grafana Cloud
Logs and metrics will soon be available in Grafana Cloud.
To test this, use the Explore feature.
Click the **Explore** icon (compass icon) in the vertical navigation bar.
### Check logs
To check logs:
1. Use the drop-down menu at the top of the page to select your Loki logs data source.
1. In the log browser, run the query `{instance="centos-01"}` where `centos-01` is the hostname of one of the Linux hosts.
If you see log lines (shown in the example below), logs are being received.
{{< figure alt="Grafana Explore showing a graph and log output from the preceding query" src="/static/assets/img/blog/ansible-to-manage-agent1.png" >}}
If no log lines appear, logs aren't being collected.
### Check metrics
To check metrics:
1. Use the drop-down menu at the top of the page to select your Prometheus data source.
1. Run the query `{instance="centos-01"}` where `centos-01` is the hostname of one of the Linux hosts.
If you see a metrics graph and table (shown in the example below), metrics are being received.
{{< figure alt="Grafana Explore showing a graph and metrics table output from the preceding query" src="/static/assets/img/blog/ansible-to-manage-agent2.png" >}}
If no metrics appear, metrics aren't being collected.
### View dashboards
Now that you have logs and metrics in Grafana, you can use dashboards to view them.
Here's an example of one of the prebuilt dashboards included with the Linux integration in Grafana Cloud:
{{< figure alt="The Grafana Node Exporter integration dashboard showing panels of visualizations" src="/static/assets/img/blog/ansible-to-manage-agent3.png" >}}
Using the **Instance** drop-down in the dashboard, you can select from the hostnames where you deployed Grafana Agent and start monitoring them.
## Summary
The `grafana_agent` Ansible role makes it easy to deploy and manage Grafana Agent across multiple machines.
This example showed Grafana Agent deployments across eight Linux hosts, but it's possible to monitor more hosts using the`grafana_agent` role.
To add monitor more Linux hosts, update the `inventory` file and re-run the Ansible playbook.
To learn more about the Grafana Ansible collection, see its [GitHub repository](https://github.com/grafana/grafana-ansible-collection) or its [documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/index.html).
docs/sources/as-code/infrastructure-as-code/grafana-operator/_index.md
+33
View File
@@ -0,0 +1,33 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Grafana Operator
menuTitle: Grafana Operator
title: Grafana Operator
weight: 120
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grafana-operator/
---
# Grafana Operator
[Grafana Operator](https://grafana.github.io/grafana-operator/) is a Kubernetes operator built to help you manage your Grafana instances and its resources from within Kubernetes. The Operator can install and manage local Grafana instances, Dashboards and Datasources through Kubernetes/OpenShift Custom resources. The Grafana Operator Automatically syncs the Kubernetes Custom resources and the actual resources in the Grafana Instance.
## Installing the Grafana Operator
To install the Grafana Operator in your Kubernetes cluster, Run the following command in your terminal:
```
helm repo add grafana https://grafana.github.io/helm-charts
helm upgrade -i grafana-operator grafana/grafana-operator
```
For other installation methods, Refer [Grafana Operator Installation Documentation](https://grafana.github.io/grafana-operator/docs/installation/).
## Getting Started
Use the following guide to get started with using Grafana Operator to manage your Grafana instance:
- [Manage data sources, and dashboards with folders using the Grafana Operator](operator-dashboards-folders-datasources/) describes how to add a folders, data sources, and dashboards, using the [Grafana Operator](https://grafana.github.io/grafana-operator/).
- [Manage Dashboards with GitOps Using ArgoCD](manage-dashboards-argocd/) describes how to create and manage dashboards using ArgoCD and [Grafana Operator](https://grafana.github.io/grafana-operator/).
docs/sources/as-code/infrastructure-as-code/grafana-operator/manage-dashboards-argocd.md
+299
View File
@@ -0,0 +1,299 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Grafana Operator
- ArgoCD
title: Manage Dashboards with GitOps Using ArgoCD
weight: 110
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grafana-operator/manage-dashboards-argocd/
---
# Managing Grafana Dashboards with GitOps Using ArgoCD
This guide will walk you through setting up a continuous deployment pipeline using ArgoCD to synchronize your Grafana dashboards with a Git repository. We'll use the Grafana Dashboard Custom Resource provided by the Grafana Operator to manage dashboard configurations declaratively.
## Prerequisites
- An existing Grafana Cloud stack
- A Kubernetes cluster with Grafana Operator installed, as shown in [Grafana Operator Installation](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/#installing-the-grafana-operator).
- ArgoCD installed on your Kubernetes cluster. Refer the [Installation Guide](https://argo-cd.readthedocs.io/en/stable/getting_started/).
- Git repository to store your dashboard configurations.
## Set Up Your Git Repository
Within the repository, create a directory structure to organize your grafana and dashboard configurations. For this tutorial, lets create a folder named `grafana`.
## Grafana Operator Setup
The Grafana Operator allows us to authenticate with the Grafana instance using the Grafana Custom Resource (CR).
1. **Create the Grafana API Token Secret:**
Store the Grafana API Token in a secret with the following content in a file named `grafana-token.yml` in the `grafana` folder in your Git repo:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: grafana-cloud-credentials
namespace: <grafana-operator-namespace>
stringData:
GRAFANA_CLOUD_INSTANCE_TOKEN: <Grafana-API-Key>
type: Opaque
```
Replace the following field values:
- `<Grafana-API-Key>` with API key from the Grafana instance. To create an API key, refer [Grafana API Key Documentation](/docs/grafana/latest/administration/api-keys/).
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
2. **Configure the Grafana Custom Resource:**
Set up connection to your Grafana Cloud instance by creating a file named `grafana-cloud.yml` in the `grafana` folder in your Git repo with the following contents:
```yaml
apiVersion: grafana.integreatly.org/v1beta1
kind: Grafana
metadata:
name: <Grafana-cloud-stack-name>
namespace: <grafana-operator-namespace>
labels:
dashboards: <Grafana-cloud-stack-name>
spec:
external:
url: https://<Grafana-cloud-stack-name>.grafana.net/
apiKey:
name: grafana-cloud-credentials
key: GRAFANA_CLOUD_INSTANCE_TOKEN
```
Replace the following field values:
- `<Grafana-API-Key>` with API key from the Grafana instance.
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
## Add Dashboards to a Git repository
In your `grafana` directory, Create a sub-folder called `dashboards`. For this tutorial, we will create 3 seperate dashboards.
1. Under `dashboards` folder, Create a file named `simple-dashboard.yaml` with the following content for the first dashboard:
```yaml
apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
name: grafanadashboard-sample
namespace: <grafana-operator-namespace>
spec:
resyncPeriod: 30s
instanceSelector:
matchLabels:
dashboards: <Grafana-cloud-stack-name>
json: >
{
"id": null,
"title": "Simple Dashboard",
"tags": [],
"style": "dark",
"timezone": "browser",
"editable": true,
"hideControls": false,
"graphTooltip": 1,
"panels": [],
"time": {
"from": "now-6h",
"to": "now"
},
"timepicker": {
"time_options": [],
"refresh_intervals": []
},
"templating": {
"list": []
},
"annotations": {
"list": []
},
"refresh": "5s",
"schemaVersion": 17,
"version": 0,
"links": []
}
```
Replace the following field values:
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
1. Under `dashboards` folder, Create a file named `dashboard-from-cm.yaml` with the following content for the second dashboard:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: dashboard-definition
namespace: <grafana-operator-namespace>
spec:
resyncPeriod: 30s
instanceSelector:
matchLabels:
dashboards: <Grafana-cloud-stack-name>
json: >
{
"id": null,
"title": "Simple Dashboard from ConfigMap",
"tags": [],
"style": "dark",
"timezone": "browser",
"editable": true,
"hideControls": false,
"graphTooltip": 1,
"panels": [],
"time": {
"from": "now-6h",
"to": "now"
},
"timepicker": {
"time_options": [],
"refresh_intervals": []
},
"templating": {
"list": []
},
"annotations": {
"list": []
},
"refresh": "5s",
"schemaVersion": 17,
"version": 0,
"links": []
}
---
apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
name: grafanadashboard-from-configmap
namespace: <grafana-operator-namespace>
spec:
instanceSelector:
matchLabels:
dashboards: <Grafana-cloud-stack-name>
configMapRef:
name: dashboard-definition
key: json
```
Replace the following field values:
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
1. Under `dashboards` folder, Create a file named `dashboard-from-id.yaml` with the following content for the third dashboard:
```yaml
apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
name: node-exporter-latest
namespace: <grafana-operator-namespace>
spec:
instanceSelector:
matchLabels:
dashboards: <Grafana-cloud-stack-name>
grafanaCom:
id: 1860
```
Replace the following field values:
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
## Configure Argo CD to Sync the Git Repository
Once all changes are committed to Git, Log in to the Argo CD user interface or use the CLI.
2. Create an Argo CD application to manage the synchronization:
**Using UI**:
- Navigate to 'New App' and fill out the form with your Git repository details and the path to your `grafana` folder.
- Make sure to tick mark directory Recurse.
- Set the sync policy to `Automatic`.
**Using CLI**:
- Prepare an application manifest named `argo-application.yaml` with the configuration pointing to your Git repository:
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: Grafana
namespace: <argocd-namespace>
spec:
destination:
name: ''
namespace: ''
server: 'https://kubernetes.default.svc'
source:
path: <Path-to-grafana-folder>
repoURL: '<Git-repo-url>'
targetRevision: HEAD
directory:
recurse: true
sources: []
project: default
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
retry:
limit: 2
backoff:
duration: 5s
maxDuration: 3m0s
factor: 2
```
Replace the following field values:
- `<Git-repo-url>` with the URL of your GIT Repository.
- `<Path-to-grafana-folder>` with the path to the `grafana` folder.
- `<argocd-namespace>` with the namespace where ArgoCD is deployed in Kubernetes Cluster.
- Create the application in Argo CD:
```shell
kubectl apply -f argo-application.yaml
```
## Verify Sync Status in Argo CD
1. Monitor the newly created Argo CD application, ensuring that it successfully syncs your dashboard configuration.
2. Visit the Argo CD dashboard and check the sync status. If it's successful, your Grafana dashboard should be up to date with the configuration from your Git repository.
## Updating the Dashboards
To update an existing dashboard:
1. Make changes to the dashboard JSON configuration in your Git repository.
2. Commit and push the changes.
3. Argo CD will detect the update and synchronize the changes to your Cutom Resource.
4. Grafana Operator will then sync changes to the Grafana Instance.
## Validating the Grafana Dashboard Update
Log in to your Grafana dashboard and confirm that the changes have been applied. You should see the dashboard update reflected in the Grafana UI.
## Additional Tips
- You can also install the Grafana Operator's Helm Chart using ArgoCD to manage your setup with GitOps.
- You can follow a similar setup for Grafana Dashboards and Folders.
## Conclusion
You've set up a GitOps workflow to manage Grafana dashboards using Argo CD and the Grafana Operator. Your dashboards are now version-controlled and can be consistently deployed across environments. This approach provides a reliable and auditable way to manage observability dashboards and scale your operations.
To learn more about managing Grafana using Grafana Operator, see the [Grafana Operator documentation](https://grafana.github.io/grafana-operator/docs/).
docs/sources/as-code/infrastructure-as-code/grafana-operator/operator-dashboards-folders-datasources.md
+168
View File
@@ -0,0 +1,168 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Grafana Operator
title: Manage folders, data sources, and dashboards using Grafana Operator
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grafana-operator/operator-dashboards-folders-datasources/
---
# Creating and managing folders, data sources, and dashboards using the Grafana Operator
Learn how to manage data sources, folders and dashboard, using Grafana Operator.
## Prerequisites
Before you begin, you should have the following available:
- An existing Grafana Cloud stack.
- Grafana Operator Installed in your Cluster, as shown in [Grafana Operator Installation](/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/#installing-the-grafana-operator).
## Grafana Operator Setup
The Grafana Operator allows us to authenticate with the Grafana instance using the Grafana Custom Resource (CR).
1. **Create the Grafana API Token Secret:**
Store the Grafana API Token in a secret with the following content in a file named `grafana-token.yml`:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: grafana-cloud-credentials
namespace: <grafana-operator-namespace>
stringData:
GRAFANA_CLOUD_INSTANCE_TOKEN: <Grafana-API-Key>
type: Opaque
```
Replace the following field values:
- `<Grafana-API-Key>` with API key from the Grafana instance. To create an API key, refer [Grafana API Key Documentation](/docs/grafana/latest/administration/api-keys/).
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
2. **Configure the Grafana Custom Resource:**
Set up connection to your Grafana Cloud instance by creating a file named `grafana-cloud.yml` with the following contents:
```yaml
apiVersion: grafana.integreatly.org/v1beta1
kind: Grafana
metadata:
name: <Grafana-cloud-stack-name>
namespace: <grafana-operator-namespace>
labels:
dashboards: <Grafana-cloud-stack-name>
spec:
external:
url: https://<Grafana-cloud-stack-name>.grafana.net/
apiKey:
name: grafana-cloud-credentials
key: GRAFANA_CLOUD_INSTANCE_TOKEN
```
Replace the following field values:
- `<Grafana-API-Key>` with API key from the Grafana instance.
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
## Add a data source
The following steps use the Prometheus data source. The required arguments vary depending on the data source you select.
1. **Create the Data Source Configuration:**
Save a new YAML file `datasource.yml` with the following content:
```yaml
apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDatasource
metadata:
name: <data-source-name>
namespace: <grafana-operator-namespace>
spec:
instanceSelector:
matchLabels:
dashboards: <Grafana-cloud-stack-name>
allowCrossNamespaceImport: true
datasource:
access: proxy
database: prometheus
jsonData:
timeInterval: 5s
tlsSkipVerify: true
name: <data-source-name>
type: prometheus
url: <data-source-url>
```
Replace the following field values:
- `<data-source-name>` with the name of the data source to be added in Grafana.
- `<data-source-url>` with URL of your data source.
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
## Add a dashboard to a folder
Use the following YAML definition to create a simple dashboard in the Grafana instance under a custom folder. If the folder defined under spec.folder fields doesnt not exist, The operator will create it before placing the dashboard inside the folder.
1. **Prepare the Dashboard Configuration File:**
In `dashboard.yml`, define the dashboard and assign it to a folder:
```yaml
apiVersion: grafana.integreatly.org/v1beta1
kind: GrafanaDashboard
metadata:
name: <folder-name>
namespace: <grafana-operator-namespace>
spec:
instanceSelector:
matchLabels:
dashboards: <Grafana-cloud-stack-name>
folder: "<folder-name>"
json: >
{
"title": "as-code dashboard",
“uid” : “ascode”
}
```
Replace the following field values:
- `<folder-name>` with the name of the folder in which you want the Dashboard to be created.
- `<Grafana-cloud-stack-name>` with the name of your Grafana Cloud Stack.
- `<grafana-operator-namespace>` with the namespace where the grafana-operator is deployed in Kubernetes Cluster.
## Apply Kubernetes Manifests
In a terminal, run the following commands from the directory where all of the above Kubernetes YAML definitions are located.
1. Create Kubernetes Custom resources for all of the above configurations.
```shell
kubectl apply -f grafana-token.yml grafana-cloud.yml datasource.yml dashboard.yml
```
## Validation
Once you apply the configurations, you should be able to verify the following:
- A new data source is visible in Grafana. In the following image a datasource named `InfluxDB` was created.
![InfluxDB datasource](/static/img/docs/grafana-cloud/terraform/influxdb_datasource_tf.png)
- A new dashboard and folder in Grafana. In the following image a dashboard named `InfluxDB Cloud Demos` was created inside the `Demos` folder.
![InfluxDB dashboard](/static/img/docs/grafana-cloud/grizzly/grizzly-folder-dashboard-datasource.png)
## Conclusion
In this guide, you created a data source, folder, and dashboard using the Grafana Operator.
To learn more about managing Grafana using Grafana Operator, see the [Grafana Operator documentation](https://grafana.github.io/grafana-operator/docs/).
docs/sources/as-code/infrastructure-as-code/grizzly/_index.md
+22
View File
@@ -0,0 +1,22 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Grizzly
- CLI
menuTitle: Grizzly
title: Grizzly
weight: 130
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grizzly/
---
# Grizzly (deprecated)
{{< admonition type="warning" >}}
Grizzly has been removed. It is no longer deployed, enhanced, or supported.
Use the [Grafana CLI](/docs/grafana/<GRAFANA_VERSION>/observability-as-code/grafana-cli/) instead.
{{< /admonition >}}
[Grizzly](https://grafana.github.io/grizzly/) is a command line tool that allows you to manage your observability resources with code. You can use it to manage dashboards, data sources, Prometheus rules, and Synthetic monitoring.
docs/sources/as-code/infrastructure-as-code/grizzly/dashboards-folders-datasources.md
+149
View File
@@ -0,0 +1,149 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Grizzly
title: Creating and managing folders, data sources, and dashboards using Grizzly
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/grizzly/dashboards-folders-datasources/
---
# Creating and managing folders, data sources, and dashboards using Grizzly
Learn how to add a data sources, folders and dashboard, using Grizzly.
## Prerequisites
Before you begin, you should have the following available:
- A Grafana Cloud account
- An existing Grafana Cloud stack with a Grafana API Key
- [Grizzly](https://grafana.github.io/grizzly/installation/) installed on your machine
## Authentication Setup
To authenticate with the Grizzly API, you must create environment variables. Run the following commands to create environment variables named `GRAFANA_URL` and `GRAFANA_TOKEN`:
```shell
export GRAFANA_URL=<Grafana-instance-url>
export GRAFANA_TOKEN=<Grafana-API-Key>
```
Replace the following field values:
- `<Grafana-instance-url>` with the URL of your Grafana instance.
- `<Grafana-API-Key>` with API key from the Grafana instance.
## Add a data source
The following steps use the InfluxDB data source. The required arguments vary depending on the data source you select.
1. Create a file named `data-source.yml` and add the following:
```yaml
apiVersion: grizzly.grafana.com/v1alpha1
kind: Datasource
metadata:
name: <data-source-name>
spec:
name: <data-source-name>
type: influxdb
url: <data-source-url>
database: <db-name>
user: <username>
secureJsonData:
password: '<password>'
uid: <uid>
id: <id>
access: proxy
```
1. Replace the following field values:
- `<data-source-name>` with the name of the data source to be added in Grafana.
- `<data-source-url>` with URL of your data source.
- `<username>` with the username for authenticating with your data source.
- `<password>` with the password for authenticating with your data source.
- `<db-name>` with name of your database.
- `<id>` with the ID for your data source in Grafana.
- `<uid>` wth the UID for your data source in Grafana.
## Add a folder
The following YAML definition creates a folder in your Grafana instance.
1. Create a file named `folder.yml` and add the following:
```yaml
apiVersion: grizzly.grafana.com/v1alpha1
kind: DashboardFolder
metadata:
name: <folder-name>
spec:
title: <folder-name>
uid: <uid>
```
1. Replace the following field values:
- `<folder-name>` with the name of the folder to be added in Grafana.
- `<uid>` with the UID for your folder in Grafana.
## Add a dashboard to the folder
Use the following YAML definition to create a simple dashboard in the Grafana instance folder from the previous step. To add more than a title and UID to the dashboard, you can convert your dashboard JSON config to YAML and paste it under `spec`.
1. Create a file named `dashboard.yml` and add the following:
```yaml
apiVersion: grizzly.grafana.com/v1alpha1
kind: Dashboard
metadata:
folder: <folder-name>
name: influxdb-cloud-demos
spec:
title: InfluxDB Cloud Demos
uid: influxdb-cloud-demos
```
1. Replace the following field values:
- `<folder-name>` with the name of the folder created in the previous step.
## Using Grizzly CLI
In a terminal, run the following commands from the directory where all of the YAML definitions are located.
1. Add the data source.
```shell
grr apply data-source.yml
```
1. Add a folder.
```shell
grr apply folder.yml
```
1. Add a dashboard to the folder.
```shell
grr apply dashboard.yml
```
## Validation
Once you apply the configurations using the Grizzly CLI, you should be able to verify the following:
- A new data source (InfluxDB in this example) is visible in Grafana.
![InfluxDB datasource](/static/img/docs/grafana-cloud/terraform/influxdb_datasource_tf.png)
- A new dashboard and folder in Grafana. In the following image a dashboard named `InfluxDB Cloud Demos` was created inside the `Demos` folder.
![InfluxDB dashboard](/static/img/docs/grafana-cloud/grizzly/grizzly-folder-dashboard-datasource.png)
## Conclusion
In this guide, you created a data source, folder, and dashboard using Grizzly.
To learn more about managing Grafana using Grizzly, see the [Grizzly documentation](https://grafana.github.io/grizzly/).
docs/sources/as-code/infrastructure-as-code/terraform/_index.md
+26
View File
@@ -0,0 +1,26 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
menuTitle: Terraform
title: Grafana Terraform provider
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/
---
# Grafana Terraform provider
The [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest) provisions configuration management resources for Grafana. You can use it to manage resources such as dashboards, data sources, plugins, folders, organizations or alert notification channels.
Use the following guides to get started using Terraform to manage your Grafana Cloud stack:
- [Creating and managing a Grafana Cloud stack using Terraform](terraform-cloud-stack/) describes how to create a Grafana Cloud stack and add a data source and dashboard using [Terraform](https://www.terraform.io/).
- [Creating and managing dashboards using Terraform and GitHub Actions](dashboards-github-action/) describes how to create and manage multiple dashboards represented as JSON source code for Grafana using [Terraform](https://www.terraform.io/) and [GitHub Actions](https://github.com/features/actions).
- [Managing IRM on Grafana Cloud using Terraform](terraform-oncall/) describes how to connect an integration to Grafana IRM, configure escalation policies, and add your on-call schedule using [Terraform](https://www.terraform.io/).
- [Managing Fleet Management in Grafana Cloud using Terraform](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/terraform-fleet-management/) describes how to create collectors and pipelines in Grafana Fleet Management using [Terraform](https://www.terraform.io/).
- [Managing Frontend Observability in Grafana Cloud using Terraform](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/terraform-frontend-observability/) describes how to manage resources in Frontend Observability using [Terraform](https://www.terraform.io/).
- [Manage Cloud Provider Observability in Grafana Cloud using Terraform](terraform-cloud-provider-o11y/) describes how to manage Amazon CloudWatch and Microsoft Azure resources in Cloud Provider Observability using Terraform.
- [Manage Knowledge Graph in Grafana Cloud using Terraform](terraform-knowledge-graph/) describes how to create and manage notification alerts, suppressed assertions, custom model rules, log configurations, and threshold configurations in Grafana Cloud Knowledge Graph using [Terraform](https://www.terraform.io/).
- [Install plugins in Grafana Cloud using Terraform](terraform-plugins) describes how to install plugins in Grafana Cloud using [Terraform](https://www.terraform.io/).
docs/sources/as-code/infrastructure-as-code/terraform/dashboards-github-action.md
+250
View File
@@ -0,0 +1,250 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
- GitHub Actions
title: Creating and managing dashboards using Terraform and GitHub Actions
weight: 110
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/dashboards-github-action/
---
# Creating and managing dashboards using Terraform and GitHub Actions
Learn how to create and manage multiple dashboards represented as JSON source code for Grafana using [Terraform](https://www.terraform.io/) and [GitHub Actions](https://github.com/features/actions).
## Prerequisites
Before you begin, you should have the following available:
- A Grafana Cloud account, as shown in [Get started](/docs/grafana-cloud/get-started/)
- A [GitHub](https://github.com/) repository
## Add Dashboards to a GitHub repository
For this guide, we are adding dashboards for ElasticSearch, InfluxDB, and AWS EC2. You can use different dashboards according to your configured data sources.
1. In your GitHub repository, create a folder named `dashboards` in the root directory.
1. In the `dashboards` folder create three sub-folders. For this guide, we will create three sub-folders named `elasticsearch`, `influxdb`, and `aws`.
1. Add dashboard JSON source code to each of the three sub-folders.
## Terraform configuration for Grafana provider
This Terraform configuration configures the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when creating folders and dashboards in the Grafana instance.
1. Create a service account and token in the Grafana instance by following these steps:
1. [Create a service account in Grafana](/docs/grafana-cloud/account-management/authentication-and-permissions/service-accounts/#create-a-service-account-in-grafana)
1. [Add a token to a service account](/docs/grafana-cloud/account-management/authentication-and-permissions/service-accounts/#add-a-token-to-a-service-account-in-grafana)
1. Create a file named `main.tf` in the Git root directory and add the following code block:
```terraform
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
version = ">= 2.9.0"
}
}
}
provider "grafana" {
alias = "cloud"
url = "<Grafana-instance-url>"
auth = "<Grafana-Service-Account-token>"
}
```
1. Replace the following field values:
- `<Grafana-instance-url>` with the URL of your Grafana instance, for example `"https://my-stack.grafana.net/"`.
- `<Grafana-Service-Account-token>` with a Service Account token from the Grafana instance.
## Terraform configuration for folders
This Terraform configuration creates three folders named `ElasticSearch`, `InfluxDB` and `AWS` in the Grafana instance using [grafana_folder (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/folder).
Create a file named `folders.tf` in the Git root directory and add the following code block:
```terraform
resource "grafana_folder" "ElasticSearch" {
provider = grafana.cloud
title = "ElasticSearch"
}
resource "grafana_folder" "InfluxDB" {
provider = grafana.cloud
title = "InfluxDB"
}
resource "grafana_folder" "AWS" {
provider = grafana.cloud
title = "AWS"
}
```
## Terraform configuration for dashboards
This Terraform configuration iterates through the Json files in the three folders (`elasticsearch`, `influxdb` and `aws`) you created in the GitHub repository and adds them to the respective folders in the Grafana instance using [grafana_dashboard (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/dashboard).
For example, the dashboard represented as JSON source code in the `elasticsearch` folder in the GitHub repository will be created in the `ElasticSearch` folder in the Grafana instance.
Create a file named `dashboards.tf` in the Git root directory and add the following code block:
```terraform
resource "grafana_dashboard" "elasticsearch" {
provider = grafana.cloud
for_each = fileset("${path.module}/dashboards/elasticsearch", "*.json")
config_json = file("${path.module}/dashboards/elasticsearch/${each.key}")
folder = grafana_folder.ElasticSearch.id
}
resource "grafana_dashboard" "influxdb" {
provider = grafana.cloud
for_each = fileset("${path.module}/dashboards/influxdb", "*.json")
config_json = file("${path.module}/dashboards/influxdb/${each.key}")
folder = grafana_folder.InfluxDB.id
}
resource "grafana_dashboard" "aws" {
provider = grafana.cloud
for_each = fileset("${path.module}/dashboards/aws", "*.json")
config_json = file("${path.module}/dashboards/aws/${each.key}")
folder = grafana_folder.AWS.id
}
```
## GitHub workflow for managing dashboards using Terraform
This GitHub workflow consists of the following steps:
- Using the [actions/checkout@v3](https://github.com/actions/checkout) action, The GitHub repository is checked out so that the GitHub workflow can access it.
- The Terraform CLI is installed on the GitHub runner using the [hashicorp/setup-terraform@v1](https://github.com/hashicorp/setup-terraform) action.
- `terraform init` is run as a bash command in the GitHub runner to initialize a working directory containing Terraform configuration files.
- `terraform fmt -check` is run as a bash command in the GitHub runner to check if the Terraform configuration files are properly formatted. If the Terraform configuration files are not properly formatted, the workflow will fail at this step.
- `terraform plan` is run as a bash command in the GitHub runner to preview the changes that Terraform will make.
- Using [mshick/add-pr-comment@v1](https://github.com/mshick/add-pr-comment) action, the preview from Terraform plan is posted as a comment on the pull request. This helps in reviewing the changes that Terraform will make before the pull request is merged.
- `terraform appy -auto-approve` is run as a bash command in the GitHub runner to apply the Terraform configuration files. `-auto-approve` flag is added to the command to skip interactive approval of plan before applying and make the workflow automated.
This step is run only when changes are committed to `main` branch. When a pull request is merged, the merge action creates a commit to the `main` branch which triggers the `terraform apply -auto-approve` step to execute.
1. In your GitHub repository, create a folder named `.github` in the root directory .
1. In the `.github` folder create a sub-folder named `workflows`.
1. To add the GitHub workflow to your GitHub repository, create a file named `terraform.yml` in the `workflows` directory and add the following code block:
````yaml
name: Terraform
on:
push:
branches:
- 'main'
pull_request:
jobs:
terraform:
runs-on: ubuntu-latest
steps:
# Checkout the repository to the GitHub Actions runner
- name: Checkout
uses: actions/checkout@v3
# Install the latest version of Terraform CLI
- name: Setup Terraform
uses: hashicorp/setup-terraform@v1
# Initialize a new or existing Terraform working directory by creating initial files, loading any remote state, downloading modules, etc.
- name: Terraform Init
run: terraform init
# Checks that all Terraform configuration files adhere to a canonical format
- name: Terraform Format
run: terraform fmt -check
# Previews the changes that Terraform will make
- name: Plan Terraform
id: plan
continue-on-error: true
run: terraform plan -input=false -no-color
# Post the preview (terraform plan) from the previous step as a GitHub pull request comment
- name: Post Plan to GitHub PR
if: github.ref != 'refs/heads/main'
uses: mshick/add-pr-comment@v1
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
repo-token-user-login: 'github-actions[bot]'
message: |
Applying:
```
${{ steps.plan.outputs.stdout }}
```
# Applies the terraform configuration files when the branch is `main`
- name: Apply Terraform
if: github.ref == 'refs/heads/main'
id: apply
continue-on-error: true
run: |
terraform apply -auto-approve
````
1. Commit the changes made to the `terraform.yml` in the previous step to the `main` branch in your GitHub repository. Once the changes are committed, The GitHub workflow you created should start to run automatically as the workflow we defined in the previous step runs when a pull request is created or when changes are committed to `main` branch.
## Managing the Terraform state
If you are not using a [Terraform backend](https://www.terraform.io/language/settings/backends/configuration) to store the `.tfstate` file, add the following code block to the end of the GitHub workflow file to make sure the Terraform state file is stored in Git.
```yaml
- name: commit the terraform state
if: github.ref == 'refs/heads/main'
uses: stefanzweifel/git-auto-commit-action@v4
with:
commit_message: Updating Terraform state
file_pattern: terraform.tfstate
```
When you run `terraform apply`,Terraform automatically manages and updates the `terraform.tfstate` file to store state about your infrastructure and configuration.
This step uses the [stefanzweifel/git-auto-commit-action@v4](https://github.com/stefanzweifel/git-auto-commit-action) action to auto-commit the `terraform.tfstate` file for changes made by the running the `terraform apply` step.
{{< admonition type="note" >}}
The Terraform state file (terraform.tfstate) should not be stored in Git to avoid leakage of sensitive data. Instead, store Terraform state file using a remote backend like AWS S3 with proper RBAC. For more information, see [Terraform state](https://www.terraform.io/language/state).
{{< /admonition >}}
## Validation
Once the GitHub workflow run is successful, you should be able to verify the following:
- `ElasticSearch`, `InfluxDB` and `AWS` folders are created in the Grafana instance.
![Folders in Dashboards](/media/docs/grafana-cloud/screenshot-folders-github-action-tf.png)
- Dashboard represented as JSON source code from `elasticsearch` folder in GitHub are added under the `ElasticSearch` folder in the Grafana instance.
![ElasticSearch Folder](/media/docs/grafana-cloud/screenshot-elastic-folder-github-action-tf.png)
- Dashboard source code from the `influxdb` folder in GitHub is added under the `InfluxDB` folder in the Grafana instance.
![InfluxDB Folder](/media/docs/grafana-cloud/screenshot-influxdb-folder-github-action-tf.png)
- Dashboards from `aws` folder in GitHub are added under the `AWS` folder in the Grafana instance.
![AWS EC2 Folder](/media/docs/grafana-cloud/screenshots-aws-folder-github-action-tf.png)
## Conclusion
In this guide, you created a GitHub workflow using Terraform to manage dashboard source code. Using this workflow, the dashboards in the Grafana instance will always be synchronized with the JSON source code files for dashboards in GitHub.
To learn more about managing Grafana Cloud using Terraform, see [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
docs/sources/as-code/infrastructure-as-code/terraform/terraform-cloud-provider-o11y.md
+115
View File
@@ -0,0 +1,115 @@
---
description: Learn how to manage Grafana Cloud Provider Observability resources in Grafana Cloud using Terraform
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
- Cloud Provider Observability
title: Manage Cloud Provider Observability in Grafana Cloud using Terraform
weight: 210
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-cloud-provider-o11y/
---
# Manage Cloud Provider Observability in Grafana Cloud using Terraform
Manage Cloud Provider Observability, including Amazon CloudWatch and Microsoft Azure resources, in Grafana Cloud using Terraform.
For more information on Cloud Provider Observability, refer to the [Cloud Provider Observability](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/) documentation.
## Before you begin
Before you begin, you should have the following available:
- A Grafana Cloud account
- For more information on setting up a Grafana Cloud account, refer to [Get started](/docs/grafana-cloud/get-started/).
- Terraform installed on your machine
- For more information on how to install Terraform, refer to the [Terraform install documentation](https://developer.hashicorp.com/terraform/install).
- Administrator permissions in your Grafana instance
- For more information on assigning Grafana RBAC roles, refer to [Assign RBAC roles](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/assign-rbac-roles/).
{{< admonition type="note" >}}
Save all of the following Terraform configuration files in the same directory.
{{< /admonition >}}
## Configure authentication for the Grafana Provider
The Grafana Provider is a logical abstraction of an upstream API that you can use to interact with Grafana Cloud resources.
You must configure it with the following information:
- A Grafana Cloud access policy token that includes the permissions the provider needs to access the Grafana Cloud Provider API.
- A regional cloud provider API endpoint to establish which Grafana Cloud stack you are accessing.
To configure authentication for the Grafana Provider:
1. Create a Grafana Cloud access policy and token.
- To create an access policy for your organization, refer to the [Create an access policy for a stack steps](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/create-access-policies/#create-an-access-policy-for-a-stack) and use the following scopes listed for the supported Amazon CloudWatch or Microsoft Azure resources:
- Amazon CloudWatch
- Metrics scrape or resource metadata scrape
- `integration-management:read`
- `integration-management:write`
- `stacks:read`
- Metric streams
- `metrics:write`
- ALB access logs, logs with Lambda, or logs with Amazon Data Firehose
- `logs:write`
- Microsoft Azure
- Serverless metrics
- `integration-management:read`
- `integration-management:write`
- `stacks:read`
- Logs with Azure functions
- `logs:write`
1. Obtain the regional Cloud Provider API endpoint.
- To obtain the regional Cloud provider API endpoint, use your access policy token and the following command to return a list of all of the Grafana stacks you own, along with their respective Cloud Provider API hostnames:
```bash
curl -sH "Authorization: Bearer <Access Token from previous step>" "https://grafana.com/api/instances" | \
jq '[.items[]|{stackName: .slug, clusterName:.clusterSlug, cloudProviderAPIURL: "https://cloud-provider-api-\(.clusterSlug).grafana.net"}]'
```
1. Create a file named `cloud-provider.tf` and add the following code block:
```tf
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
}
}
}
provider "grafana" {
cloud_api_url = "<CLOUD_PROVIDER_API_URL>"
cloud_access_policy_token = "<CLOUD_ACCESS_POLICY_TOKEN>"
}
```
1. Create a `variables.tf` file and paste the `<CLOUD_ACCESS_POLICY_TOKEN>` and `<CLOUD_PROVIDER_API_URL` variables with your values.
1. Run the following Terraform command:
```tf
terraform apply -var-file="variables.tf"
```
## Configure your resources
To find instructions for configuring specific Amazon CloudWatch and Microsoft Azure resources in Cloud Provider Observability using Terraform, refer to the following documents:
- Amazon CloudWatch
- [Metrics scrape](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/cloudwatch-metrics/config-cw-metric-scrape/): Pull CloudWatch metrics from multiple regions for your AWS account, without needing to install Grafana Alloy.
- [Metric streams](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/cloudwatch-metrics/config-cw-metric-streams/#configure-metric-streams-with-terraform): Push metrics with CloudWatch metric streams using Amazon Data Firehose, providing real-time insights and scalability while simplifying configuration and reducing cost and manual effort.
- [ALB access logs](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/logs/cloudwatch-logs/config-alb-access-logs-lambda/#configure-with-terraform): Send application load balancer access logs from AWS to Grafana Cloud using a Lambda function.
- [Logs with Lambda](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/logs/cloudwatch-logs/config-cw-logs-lambda/#configure-with-terraform): Send logs to Grafana Cloud from multiple AWS services using a lambda-promtail function.
- [Logs with Amazon Data Firehose](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/aws/logs/firehose-logs/config-firehose-logs/#configure-with-terraform): Send logs from AWS to Grafana Cloud with Amazon Data Firehose and minimal infrastructure.
- Microsoft Azure
- [Serverless metrics](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/azure/collect-azure-serverless/config-azure-metrics-serverless/): Monitor your Azure resources without the need to configure or deploy a collector by using Cloud Provider Observability.
- [Logs with Azure functions](/docs/grafana-cloud/monitor-infrastructure/monitor-cloud-provider/azure/config-azure-logs-azure-function/): Send Azure event logs to a Loki endpoint using an Azure function that subscribes to an Azure event hub.
## Grafana cloud provider resources
You can define the following Cloud Provider Observability resources and data sources using Terraform:
| Resource name | Description |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grafana_cloud_provider_aws_account` | Represents an AWS IAM role that authorizes Grafana Cloud to pull Amazon CloudWatch metrics for a set of regions. Usually, there's one of these resources per configured AWS account. For a full reference of this resource, refer to [the Terraform Grafana Provider reference documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_provider_aws_account). |
| `grafana_cloud_provider_aws_cloudwatch_scrape_job` | Represents a Grafana AWS scrape job. This configures Grafana to fetch a list of metrics/statistics for one or many AWS services, and for a given `grafana_cloud_provider_aws_account`. For a full reference of this resource, refer to [the Terraform Grafana Provider reference documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_provider_aws_cloudwatch_scrape_job) |
| `grafana_cloud_provider_aws_resource_metadata_scrape_job` | Represents a Grafana AWS Resource Metadata scrape job. This resource configures Grafana to fetch resource metadata for one or multiple AWS services, for a given `grafana_cloud_provider_aws_account`. For a full reference of this resource, refer to [the Terraform Grafana Provider reference documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_provider_aws_resource_metadata_scrape_job) |
| `grafana_cloud_provider_azure_credential` | A resource representing an Azure Service Principal credential used by Grafana Cloud to pull Azure Monitor metrics from one or more subscriptions. For a full reference of this resource, refer to [the Terraform Grafana Provider resource documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_provider_azure_credential). |
docs/sources/as-code/infrastructure-as-code/terraform/terraform-cloud-stack.md
+231
View File
@@ -0,0 +1,231 @@
---
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
title: Creating and managing a Grafana Cloud stack using Terraform
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-cloud-stack/
---
# Creating and managing a Grafana Cloud stack using Terraform
Learn how to add a data source, a dashboard, and a folder to a Grafana Cloud stack using Terraform.
## Prerequisites
Before you begin, you should have the following available:
- A Grafana Cloud account, as shown in [Get started](/docs/grafana-cloud/get-started/)
- [Terraform](https://www.terraform.io/downloads) installed on your machine
{{< admonition type="note" >}}
All of the following Terraform configuration files should be saved in the same directory.
{{< /admonition >}}
## Create a Cloud stack
1. Create a Terraform configuration file.
This Terraform configuration will create a Grafana Cloud stack and a second token needed for your Grafana instance.
Create a file named `cloud-stack.tf` and add the following:
```terraform
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
version = ">= 2.9.0"
}
}
}
// Step 1: Create a stack
provider "grafana" {
alias = "cloud"
cloud_access_policy_token = "<cloud-access-token>"
}
resource "grafana_cloud_stack" "my_stack" {
provider = grafana.cloud
name = "<stack-name>"
slug = "<stack-name>"
region_slug = "<region>" # Example "us","eu" etc
delete_protection = true
}
// Step 2: Create a service account and key for the stack
resource "grafana_cloud_stack_service_account" "cloud_sa" {
provider = grafana.cloud
stack_slug = grafana_cloud_stack.my_stack.slug
name = "<service-account-name>"
role = "Admin"
is_disabled = false
}
resource "grafana_cloud_stack_service_account_token" "cloud_sa" {
provider = grafana.cloud
stack_slug = grafana_cloud_stack.my_stack.slug
name = "terraform serviceaccount key"
service_account_id = grafana_cloud_stack_service_account.cloud_sa.id
}
// Step 3: Create resources within the stack
provider "grafana" {
alias = "my_stack"
url = grafana_cloud_stack.my_stack.url
auth = grafana_cloud_stack_service_account_token.cloud_sa.key
}
resource "grafana_folder" "my_folder" {
provider = grafana.my_stack
title = "Test Folder"
}
```
1. Replace the following field values:
- `<cloud-access-token>` with your Grafana Cloud Access Policy Token.
To create a new one, refer [Grafana Cloud Access Policies](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/access-policies/)
Add all stacks to the realms list.
The scopes needed for the example are:
- dashboards:read
- orgs:read
- stack-dashboards:read
- stacks:read
- dashboards:write
- orgs:write
- stack-dashboards:write
- stacks:write
- stack-service-accounts:write
- dashboards:delete
- stack-dashboards:delete
- stacks:delete
- `<stack-name>` with the name of your stack.
- `<region>` with the region in which you want to create the stack. For example `us`, `eu`.
- `<service-account-name>` with a name for the serviceaccount that will be created to use for operations within the stack/instance.
The first provider block, `grafana.cloud`, uses the Cloud Access Policy Token from the Cloud Portal and is referenced as a parameter when creating the Cloud stack and the token in the Grafana instance to provide the necessary authentication.
The second provider block, `grafana.my_stack`, is referenced as a parameter when creating resources inside the Grafana instance.
## Add a data source
This guide uses the InfluxDB data source. The required arguments for [grafana_data_source (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source) vary depending on the type of data source you select.
1. Create a file named `datasource.tf` and add the following:
```terraform
resource "grafana_data_source" "<data-source-name>" {
provider = grafana.my_stack
type = "influxdb"
name = "<data-source-name>"
url = "<data-source-url>"
username = "<username>"
password = "<password>"
database_name = "<db-name>"
}
```
1. Replace the following field values:
- `<data-source-name>` with the name of the data source to be added in Grafana.
- `<data-source-url>` with URL of your data source.
- `<username>` with the username for authenticating with your data source.
- `<password>` with password for authenticating with your data source.
- `<db-name>` with name of your database.
## Add a folder
This Terraform configuration creates a folder in your Grafana instance using [grafana_folder (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/folder).
1. Create a file named `folder.tf` and add the following:
```terraform
resource "grafana_folder" "<folder-name>" {
provider = grafana.my_stack
title = "<folder-name>"
}
```
1. Replace the following field value:
- `<folder-name>` with a name for the folder.
## Add a dashboard to the folder
This Terraform configuration creates a dashboard inside the folder created above in your Grafana instance using [grafana_dashboard (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/dashboard).
1. Create a file named `dashboard.tf` and add the following:
```terraform
# Using a JSON file
resource "grafana_dashboard" "dashboard" {
provider = grafana.my_stack
config_json = file("<file-name>.json")
folder = grafana_folder.<folder-name>.id
}
```
1. Replace the following field value:
- `<file-name>` with the name of the JSON file that has the source code for the dashboard.
The dashboard is represented by its JSON source code and referenced in the `config_json` parameter.
## Apply the Terraform configuration
In a terminal, run the following commands from the directory where all of the configuration files are located.
1. Initialize a working directory containing Terraform configuration files.
```shell
terraform init
```
1. Preview the changes that Terraform will make.
```shell
terraform plan
```
1. Apply the configuration files.
```shell
terraform apply
```
## Validation
Once you apply the changes in the Terraform configurations, you should be able to verify the following:
- The new Grafana stack is created and visible in the Cloud Portal
![Cloud Portal](/static/img/docs/grafana-cloud/terraform/cloud_portal_tf.png)
- A service account key token is added in your Grafana instance. In the following image, the service account key token named "terraform serviceaccount key" was added by the [grafana_cloud_stack_service_account_token (Resource)](#create-a-cloud-stack).
![API Key](/media/docs/grafana-cloud/screenshot-api_key_tf.png)
- A new data source (InfluxDB in this example) is visible in the grafana instance.
![InfluxDB data source](/media/docs/grafana-cloud/screenshot-influxdb_datasource_tf.png)
- A new folder in Grafana. In the following image, a folder named "Demos" was added by the [grafana_folder (Resource)](./#add-a-folder).
![Folder](/media/docs/grafana-cloud/screenshot-folder_tf.png)
- A new dashboard in the Grafana instance. In the following image a dashboard named "InfluxDB Cloud Demos" was created inside the "Demos" folder.
![InfluxDB dashboard](/static/img/docs/grafana-cloud/terraform/influxdb_dashboard_tf.png)
## Conclusion
In this guide, you created a Grafana Cloud stack along with a data source, folder, and dashboard imported from a JSON file using Terraform.
To learn more about managing Grafana Cloud using Terraform, see [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
docs/sources/as-code/infrastructure-as-code/terraform/terraform-fleet-management.md
+384
View File
@@ -0,0 +1,384 @@
---
description: Learn how to create Grafana Fleet Management collectors and pipelines in Grafana Cloud using Terraform
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
- Fleet Management
- Alloy
labels:
products:
- cloud
title: Manage Fleet Management in Grafana Cloud using Terraform
weight: 200
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-fleet-management/
---
# Manage Fleet Management in Grafana Cloud using Terraform
Learn how to create [Grafana Fleet Management](https://grafana.com/docs/grafana-cloud/send-data/fleet-management/) collectors and pipelines in Grafana Cloud using Terraform.
This guide shows you how to create an access policy and a token for Fleet Management and [Grafana Alloy](https://grafana.com/docs/alloy/latest/), a collector with remote attributes, and a pipeline for profiling Alloy.
## Before you begin
Before you begin, you should have the following available:
- A Grafana Cloud account, as shown in [Get started](https://grafana.com/docs/grafana-cloud/get-started/)
- [Terraform](https://www.terraform.io/downloads) installed on your machine
- [Alloy](https://grafana.com/docs/alloy/latest/set-up/install/) installed on your machine
- Administrator permissions in your Grafana instance
{{< admonition type="note" >}}
All of the following Terraform configuration files should be saved in the same directory.
{{< /admonition >}}
## Configure a provider for Grafana Cloud
This Terraform configuration configures the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when interacting with the Cloud API.
The [`grafana_cloud_stack` (Data Source)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/data-sources/cloud_stack) is used to retrieve the user ID and URL details of your instance.
1. Create a Grafana Cloud access policy and token.
To create a new one, refer to [Grafana Cloud Access Policies](https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/).
Add your stack to the realms list.
The scopes needed for the examples in this guide are:
- `accesspolicies:read`
- `accesspolicies:write`
- `accesspolicies:delete`
- `stacks:read`
1. Create a file named `cloud-provider.tf` and add the following code block:
```terraform
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
version = ">= 3.19.0"
}
}
}
provider "grafana" {
alias = "cloud"
cloud_access_policy_token = "<CLOUD_ACCESS_POLICY_TOKEN>"
}
data "grafana_cloud_stack" "stack" {
provider = grafana.cloud
slug = "<STACK_SLUG>"
}
```
1. Replace the following field values:
- `<CLOUD_ACCESS_POLICY_TOKEN>` with the access policy token you created in the first step
- `<STACK_SLUG>` with your stack slug, which is the subdomain where your Grafana Cloud instance is available: `https://<STACK_SLUG>.grafana.net`
## Create an access policy and token for Fleet Management
This Terraform configuration creates the following:
- An access policy named `fleet-management-policy` with `fleet-management:read` and `fleet-management:write` scopes, using [`grafana_cloud_access_policy` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy)
- A token named `fleet-management-token`, using [`grafana_cloud_access_policy_token` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy_token)
1. Create a file named `fm-access-policy.tf` and add the following code block:
```terraform
resource "grafana_cloud_access_policy" "fm_policy" {
provider = grafana.cloud
name = "fleet-management-policy"
region = data.grafana_cloud_stack.stack.region_slug
scopes = [
"fleet-management:read",
"fleet-management:write"
]
realm {
type = "stack"
identifier = data.grafana_cloud_stack.stack.id
}
}
resource "grafana_cloud_access_policy_token" "fm_token" {
provider = grafana.cloud
name = "fleet-management-token"
region = grafana_cloud_access_policy.fm_policy.region
access_policy_id = grafana_cloud_access_policy.fm_policy.policy_id
}
```
## Configure a provider for Fleet Management
This Terraform configuration configures the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when interacting with the Fleet Management API.
1. Create a file named `fm-provider.tf` and add the following code block:
```terraform
locals {
fm_id = data.grafana_cloud_stack.stack.fleet_management_user_id
fm_token = grafana_cloud_access_policy_token.fm_token.token
fm_url = data.grafana_cloud_stack.stack.fleet_management_url
}
provider "grafana" {
alias = "fm"
fleet_management_auth = "${local.fm_id}:${local.fm_token}"
fleet_management_url = local.fm_url
}
```
## Create a Fleet Management collector
This Terraform configuration creates a collector with a remote attribute, using [`grafana_fleet_management_collector` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/fleet_management_collector).
This configuration only preregisters the collector.
You must complete the [Run Alloy](#run-alloy) step for the collector to register with Fleet Management and be assigned remote attributes.
1. Create a file named `fm-collector.tf` and add the following code block:
```terraform
resource "grafana_fleet_management_collector" "fm_collector" {
provider = grafana.fm
id = "prod_collector"
remote_attributes = {
"env" = "PROD"
}
enabled = true
}
```
## Create a Fleet Management pipeline
This Terraform configuration creates a pipeline for Alloy profiling with a matcher for the collector declared in the previous step, using [`grafana_fleet_management_pipeline` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/fleet_management_pipeline).
The pipeline writes the profiles to [Grafana Cloud Profiles](https://grafana.com/docs/grafana-cloud/monitor-applications/profiles/).
1. Create a file named `profiling.alloy.tftpl` and add the following content:
```alloy
// This pipeline scrapes pprof Go profiles from Alloy and sends them to Pyroscope.
//
// It requires the following environment variables to be set where Alloy is running:
// Required:
// * GCLOUD_RW_API_KEY: The Grafana Cloud API key with write access to Pyroscope.
// Optional:
// * ALLOY_ADDRESS: The address Alloy listens on. Defaults to 127.0.0.1:12345.
pyroscope.scrape "alloy" {
targets = [
{
"__address__" = coalesce(
sys.env("ALLOY_ADDRESS"),
"127.0.0.1:12345",
),
"service_name" = "alloy",
},
]
forward_to = [pyroscope.write.grafana_cloud.receiver]
profiling_config {
profile.process_cpu {
enabled = true
}
profile.memory {
enabled = true
}
profile.mutex {
enabled = true
}
profile.block {
enabled = true
}
profile.goroutine {
enabled = true
}
}
}
pyroscope.write "grafana_cloud" {
endpoint {
url = "${profiles_url}"
basic_auth {
username = "${profiles_id}"
password = sys.env("GCLOUD_RW_API_KEY")
}
}
}
```
1. Create a file named `fm-pipeline.tf` and add the following code block:
```terraform
locals {
profiles_id = data.grafana_cloud_stack.stack.profiles_user_id
profiles_url = data.grafana_cloud_stack.stack.profiles_url
}
resource "grafana_fleet_management_pipeline" "pipeline" {
provider = grafana.fm
name = "profiling"
contents = templatefile(
"profiling.alloy.tftpl",
{
profiles_id = local.profiles_id,
profiles_url = local.profiles_url,
},
)
matchers = [
"env=\"PROD\""
]
enabled = true
}
```
## Create an access policy and token for Alloy
This Terraform configuration creates the following:
- An access policy named `alloy-policy` with `set:alloy-data-write` scope, using [`grafana_cloud_access_policy` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy)
- A token named `alloy-token`, using [`grafana_cloud_access_policy_token` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy_token)
1. Create a file named `alloy-access-policy.tf` and add the following code block:
```terraform
resource "grafana_cloud_access_policy" "alloy_policy" {
provider = grafana.cloud
name = "alloy-policy"
region = data.grafana_cloud_stack.stack.region_slug
scopes = [
"set:alloy-data-write"
]
realm {
type = "stack"
identifier = data.grafana_cloud_stack.stack.id
}
}
resource "grafana_cloud_access_policy_token" "alloy_token" {
provider = grafana.cloud
name = "alloy-token"
region = grafana_cloud_access_policy.alloy_policy.region
access_policy_id = grafana_cloud_access_policy.alloy_policy.policy_id
}
output "alloy_token" {
value = grafana_cloud_access_policy_token.alloy_token.token
sensitive = true
}
```
## Create a configuration file for Alloy
This Terraform configuration creates an Alloy configuration file with the [`remotecfg` block](https://grafana.com/docs/grafana-cloud/send-data/alloy/reference/config-blocks/remotecfg/) for Fleet Management, using [`local_file` (Resource)](https://registry.terraform.io/providers/hashicorp/local/latest/docs/resources/file).
1. Create a file named `config.alloy.tftpl` and add the following content:
```alloy
remotecfg {
id = "${collector_id}"
url = "${fm_url}"
poll_frequency = "60s"
basic_auth {
username = "${fm_id}"
password = sys.env("GCLOUD_RW_API_KEY")
}
}
```
1. Create a file named `alloy-config.tf` and add the following code block:
```terraform
resource "local_file" "alloy_config" {
filename = "<ALLOY_CONFIG_PATH>"
content = templatefile(
"config.alloy.tftpl",
{
collector_id = "prod_collector",
fm_id = local.fm_id,
fm_url = local.fm_url,
},
)
directory_permission = "0644"
file_permission = "0644"
}
```
1. Replace the following field values:
- `<ALLOY_CONFIG_PATH>` with the path the Alloy configuration file should be written to, for example `config.alloy`
## Apply the Terraform configuration
In a terminal, run the following commands from the directory where all of the configuration files are located.
1. Initialize a working directory containing Terraform configuration files:
```shell
terraform init
```
1. Preview the Terraform changes:
```shell
terraform plan
```
1. Apply the configuration:
```shell
terraform apply
```
## Run Alloy
To learn how to start or restart Alloy, refer to [Run Grafana Alloy](https://grafana.com/docs/alloy/latest/set-up/run/).
{{< admonition type="note" >}}
The variable `GCLOUD_RW_API_KEY` must be set in the environment where Alloy is running for the remote configuration in this example to work.
{{< /admonition >}}
1. Run the following command to view the Alloy token:
```shell
terraform output -raw alloy_token
```
1. Set the environment variable `GCLOUD_RW_API_KEY` to the value from the first step.
1. Run Alloy.
## Validation
After you apply the changes in the Terraform configurations and run Alloy, you should be able to verify the following:
- A collector is added to the Fleet Management **Inventory tab**:
{{< figure alt="The Inventory screen in the Fleet Management interface in Grafana Cloud which shows that a new collector called `prod_collector` is registered with attribute `env=PROD`, has a healthy status, and was last modified a few seconds ago." src="/media/docs/fleet-management/screenshot-fleet-management-terraform-validate-collector.png" >}}
- A pipeline is added to the Fleet Management **Remote configuration tab**:
{{< figure alt="The Remote configuration screen in the Fleet Management interface in Grafana Cloud which shows that a new configuration pipeline called `profiling` is active and was last modified a few seconds ago." src="/media/docs/fleet-management/screenshot-fleet-management-terraform-validate-pipeline.png" >}}
- Alloy profiles are being exported to Grafana Cloud Profiles:
{{< figure alt="A dashboard in Grafana Cloud which shows Alloy profiling data, including graphs for CPU and memory." src="/media/docs/fleet-management/screenshot-fleet-management-terraform-validate-profiles.png" >}}
## Conclusion
In this guide, you created an access policy and a token for Fleet Management and Alloy, a collector with remote attributes, and a pipeline for profiling Alloy, all using Terraform.
To learn more about managing Grafana Cloud using Terraform, refer to [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
docs/sources/as-code/infrastructure-as-code/terraform/terraform-frontend-observability.md
+105
View File
@@ -0,0 +1,105 @@
---
description: Learn how to manage Grafana Frontend Observability resources in Grafana Cloud using Terraform
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
- Frontend Observability
title: Manage Frontend Observability in Grafana Cloud with Terraform
weight: 200
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-frontend-observability/
---
# Manage Frontend Observability in Grafana Cloud with Terraform
Learn how to use Terraform to manage [Grafana Frontend Observability](https://grafana.com/docs/grafana-cloud/frontend-observability/) resources, such as your applications.
This guide shows you how to create an access policy and a token for Frontend Observability so that you can connect to the Frontend Observability API.
## Before you begin
Before you begin, you should have the following available:
- A Grafana Cloud account, as shown in [Get started](https://grafana.com/docs/grafana-cloud/get-started/)
- [Terraform](https://www.terraform.io/downloads) installed on your machine
- Administrator permissions in your Grafana instance
{{< admonition type="note" >}}
All of the following Terraform configuration files should be saved in the same directory.
{{< /admonition >}}
## Configure a provider for Grafana Cloud
This Terraform configuration configures the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when interacting with the Cloud API.
The [`grafana_cloud_stack` (Data Source)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/data-sources/cloud_stack) is used to retrieve the details of your instance.
1. Create a Grafana Cloud access policy and token.
To create a new one, refer to [Grafana Cloud Access Policies](https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/).
Add your stack to the realms list.
The scopes needed for the examples in this guide are:
- `accesspolicies:read`
- `accesspolicies:write`
- `accesspolicies:delete`
- `dashboards:read`
- `dashboards:write`
- `dashboards:delete`
- `orgs:read`
- `orgs:write`
- `stacks:read`
- `stacks:write`
- `stacks:delete`
- `stack-dashboards:read`
- `stack-dashboards:write`
- `stack-dashboards:delete`
- `stack-service-accounts:write`
1. Create a file named `cloud-provider.tf` and add the following code block:
```terraform
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
}
}
}
provider "grafana" {
alias = "cloud"
cloud_access_policy_token = "<CLOUD_ACCESS_POLICY_TOKEN>"
}
data "grafana_cloud_stack" "stack" {
provider = grafana.cloud
slug = "<STACK_SLUG>"
}
```
1. Replace the following field values:
- `<CLOUD_ACCESS_POLICY_TOKEN>` with the access policy token you created in the first step
- `<STACK_SLUG>` with your stack slug, which is the subdomain where your Grafana Cloud instance is available: `https://<STACK_SLUG>.grafana.net`
## Create an access policy and token for Frontend Observability
You must create a Terraform configuration with the following:
- An access policy with `frontend-observability:read`, `frontend-observability:write`, and `frontend-observability:delete` scopes, using [`grafana_cloud_access_policy` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy)
- A token named `frontend_o11y_api_access_token`, using [`grafana_cloud_access_policy_token` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_access_policy_token)
## Configure the provider to use the Frontend Observability API
After you have created the token, you can configure the provider as follows:
```terraform
provider "grafana" {
frontend_o11y_api_access_token = "<access token from previous step>"
}
```
## Conclusion
In this guide, you created an access policy and a token for Frontend Observability using Terraform.
To learn more about managing Grafana Cloud using Terraform, refer to [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/_index.md
+73
View File
@@ -0,0 +1,73 @@
---
cards:
items:
- description: Learn how to set up Terraform provider and configure your environment for managing Knowledge Graph resources.
height: 24
href: ./getting-started/
title: Get started with Terraform
- description: Configure notification alerts to manage how alerts are processed and routed in your Knowledge Graph.
height: 24
href: ./notification-alerts/
title: Notification alerts
- description: Define suppression rules to temporarily disable specific alerts during maintenance windows or testing.
height: 24
href: ./suppressed-assertions/
title: Suppressed assertions
- description: Create custom entity models and define how entities are discovered based on Prometheus queries.
height: 24
href: ./custom-model-rules/
title: Custom model rules
- description: Configure log data correlation with entities using data source mappings and filtering options.
height: 24
href: ./log-configurations/
title: Log configurations
- description: Set custom thresholds for request, resource, and health assertions to monitor your services.
height: 24
href: ./thresholds/
title: Thresholds
- description: Configure knowledge graph SLOs with entity-centric monitoring and RCA workbench integration for root cause analysis.
height: 24
href: ./knowledge-graph-slo/
title: Knowledge graph SLOs
title_class: pt-0 lh-1
description: Manage Grafana Cloud Knowledge Graph using Terraform
hero:
description: Use Terraform to manage Grafana Cloud Knowledge Graph resources as code. Configure notification alerts, suppressed assertions, custom model rules, log configurations, and threshold configurations using infrastructure as code best practices.
level: 1
title: Manage Knowledge Graph using Terraform
menuTitle: Manage Knowledge Graph in Grafana Cloud using Terraform
title: Manage Knowledge Graph in Grafana Cloud using Terraform
weight: 130
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
- Knowledge Graph
- Alert Configuration
- Suppressed Assertions
- Custom Model Rules
- Log Configuration
- Threshold Configuration
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/
---
{{< docs/hero-simple key="hero" >}}
---
## Overview
Terraform enables you to manage [Grafana Cloud Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) resources using infrastructure as code. With Terraform, you can define, version control, and deploy Knowledge Graph configurations including alert rules, suppression policies, entity models, log correlations, and thresholds.
## Explore
{{< card-grid key="cards" type="simple" >}}
---
## Related resources
- [Grafana Terraform Provider Documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs)
- [Knowledge Graph Documentation](/docs/grafana-cloud/knowledge-graph/)
- [Terraform Best Practices](https://www.terraform.io/docs/cloud/guides/recommended-practices/index.html)
docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/custom-model-rules.md
+431
View File
@@ -0,0 +1,431 @@
---
description: Define custom entity models for Knowledge Graph using Terraform
menuTitle: Custom model rules
title: Create custom model rules using Terraform
weight: 400
keywords:
- Terraform
- Knowledge Graph
- Custom Model Rules
- Entity Models
- Prometheus
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/custom-model-rules/
---
# Create custom model rules using Terraform
Custom model rules in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) allow you to define how entities are discovered and modeled based on Prometheus queries. These rules enable you to create custom entity types, define their relationships, and specify how they should be enriched with additional data.
For information about managing entities and relations in the Knowledge Graph UI, refer to [Manage entities and relations](/docs/grafana-cloud/knowledge-graph/configure/manage-entities-relations/).
## Basic custom model rules
Create a file named `custom-model-rules.tf` and add the following:
```terraform
# Basic custom model rule for services
resource "grafana_asserts_custom_model_rules" "basic_service" {
provider = grafana.asserts
name = "basic-service-model"
rules {
entity {
type = "Service"
name = "service"
defined_by {
query = "up{job!=''}"
label_values = {
service = "job"
}
literals = {
_source = "up_query"
}
}
}
}
}
```
## Advanced service model with scope and lookup
Define service entities with environment scoping and relationship mappings:
```terraform
# Advanced service model with environment scoping
resource "grafana_asserts_custom_model_rules" "advanced_service" {
provider = grafana.asserts
name = "advanced-service-model"
rules {
entity {
type = "Service"
name = "workload | service | job"
scope = {
namespace = "namespace"
env = "asserts_env"
site = "asserts_site"
}
lookup = {
workload = "workload | deployment | statefulset | daemonset | replicaset"
service = "service"
job = "job"
proxy_job = "job"
}
defined_by {
query = "up{job!='', asserts_env!=''}"
label_values = {
service = "service"
job = "job"
workload = "workload"
namespace = "namespace"
}
literals = {
_source = "up_with_workload"
}
}
defined_by {
query = "up{job='maintenance'}"
disabled = true
}
}
}
}
```
## Multi-entity model configuration
Define multiple entity types in a single configuration:
```terraform
# Multiple entity types in a single model
resource "grafana_asserts_custom_model_rules" "multi_entity" {
provider = grafana.asserts
name = "kubernetes-entities"
rules {
# Service entity
entity {
type = "Service"
name = "service"
scope = {
namespace = "namespace"
cluster = "cluster"
}
defined_by {
query = "up{service!=''}"
label_values = {
service = "service"
namespace = "namespace"
cluster = "cluster"
}
}
}
# Pod entity
entity {
type = "Pod"
name = "Pod"
scope = {
namespace = "namespace"
cluster = "cluster"
}
lookup = {
service = "service"
workload = "workload"
}
defined_by {
query = "kube_pod_info{pod!=''}"
label_values = {
Pod = "pod"
namespace = "namespace"
cluster = "cluster"
service = "service"
}
literals = {
_entity_type = "Pod"
}
}
}
# Namespace entity
entity {
type = "Namespace"
name = "namespace"
scope = {
cluster = "cluster"
}
defined_by {
query = "kube_namespace_status_phase{namespace!=''}"
label_values = {
namespace = "namespace"
cluster = "cluster"
}
}
}
}
}
```
## Complex entity with enrichment
Create service entities with multiple data sources and enrichment:
```terraform
# Service entity with enrichment from multiple sources
resource "grafana_asserts_custom_model_rules" "enriched_service" {
provider = grafana.asserts
name = "enriched-service-model"
rules {
entity {
type = "Service"
name = "service"
enriched_by = [
"prometheus_metrics",
"kubernetes_metadata",
"application_logs"
]
scope = {
environment = "asserts_env"
region = "asserts_site"
team = "team"
}
lookup = {
deployment = "workload"
Pod = "pod"
container = "container"
}
# Primary definition from service up metrics
defined_by {
query = "up{service!='', asserts_env!=''}"
label_values = {
service = "service"
environment = "asserts_env"
region = "asserts_site"
team = "team"
}
literals = {
_primary_source = "service_up"
}
}
# Secondary definition from application metrics
defined_by {
query = "http_requests_total{service!=''}"
label_values = {
service = "service"
environment = "environment"
version = "version"
}
literals = {
_secondary_source = "http_metrics"
}
}
# Disabled definition for testing
defined_by {
query = "test_metric{service!=''}"
disabled = true
}
}
}
}
```
## Database and infrastructure entities
Define database and infrastructure entity models:
```terraform
# Database and infrastructure entity models
resource "grafana_asserts_custom_model_rules" "infrastructure" {
provider = grafana.asserts
name = "infrastructure-entities"
rules {
# Database entity
entity {
type = "Database"
name = "database_instance"
scope = {
environment = "env"
region = "region"
}
lookup = {
host = "instance"
port = "port"
db_name = "database"
}
defined_by {
query = "mysql_up{instance!=''}"
label_values = {
database_instance = "instance"
database = "database"
env = "environment"
region = "region"
}
literals = {
_db_type = "mysql"
}
metric_value = "1"
}
defined_by {
query = "postgres_up{instance!=''}"
label_values = {
database_instance = "instance"
database = "datname"
env = "environment"
}
literals = {
_db_type = "postgresql"
}
}
}
# Load balancer entity
entity {
type = "LoadBalancer"
name = "lb_instance"
scope = {
environment = "env"
}
defined_by {
query = "haproxy_up{proxy!=''}"
label_values = {
lb_instance = "instance"
proxy = "proxy"
env = "environment"
}
literals = {
_lb_type = "haproxy"
}
}
}
}
}
```
## Resource reference
### `grafana_asserts_custom_model_rules`
Manage Knowledge Graph custom model rules through the Grafana API. This resource allows you to define custom entity models based on Prometheus queries with advanced mapping and enrichment capabilities.
#### Arguments
| Name | Type | Required | Description |
| ------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `name` | `string` | Yes | The name of the custom model rules. This field is immutable and forces recreation if changed. |
| `rules` | `list(object)` | Yes | The rules configuration containing entity definitions. Refer to [rules block](#rules-block) for details. |
#### Rules block
Each `rules` block supports the following:
| Name | Type | Required | Description |
| -------- | -------------- | -------- | ------------------------------------------------------------------------------- |
| `entity` | `list(object)` | Yes | List of entity definitions. Refer to [entity block](#entity-block) for details. |
#### Entity block
Each `entity` block supports the following:
| Name | Type | Required | Description |
| ------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `type` | `string` | Yes | The type of the entity (for example, Service, Pod, Namespace). |
| `name` | `string` | Yes | The name pattern for the entity. Can include pipe-separated alternatives. |
| `defined_by` | `list(object)` | Yes | List of queries that define this entity. Refer to [`defined_by` block](#defined_by-block) for details. |
| `disabled` | `bool` | No | Whether this entity is disabled. Defaults to `false`. |
| `enriched_by` | `list(string)` | No | List of enrichment sources for the entity. |
| `lookup` | `map(string)` | No | Lookup mappings for the entity to relate different label names. |
| `scope` | `map(string)` | No | Scope labels that define the boundaries of this entity type. |
#### `defined_by` block
Each `defined_by` block supports the following:
| Name | Type | Required | Description |
| -------------- | ------------- | -------- | ------------------------------------------------------------------------- |
| `query` | `string` | Yes | The Prometheus query that defines this entity. |
| `disabled` | `bool` | No | Whether this query is disabled. Defaults to `false`. |
| `label_values` | `map(string)` | No | Label value mappings for extracting entity attributes from query results. |
| `literals` | `map(string)` | No | Literal value mappings for adding static attributes to entities. |
| `metric_value` | `string` | No | Metric value to use from the query result. |
{{< admonition type="note" >}}
When `disabled = true` is set for a `defined_by` query, only the `query` field is used for matching. All other fields in the block are ignored.
{{< /admonition >}}
## Best practices
### Entity models
- Design your entity models to reflect your actual infrastructure and application architecture
- Use descriptive names for custom model rules that indicate their purpose and scope
- Start with basic entity definitions and gradually add complexity as needed
- Define clear entity scopes using the `scope` parameter to organize entities by environment, region, or team
### Query design and performance
- Write efficient Prometheus queries that don't overload your monitoring system
- Test your Prometheus queries independently before using them in model rules
- Use specific label filters to reduce the scope of your queries where possible
- Consider the cardinality implications of your entity definitions
- Use the `disabled` flag to temporarily disable problematic queries during debugging
### Relationships and enrichment
- Use `lookup` mappings to establish relationships between different entity types
- Leverage `enriched_by` to specify additional data sources for entity enrichment
- Map Prometheus labels to entity attributes using clear and descriptive names
- Use meaningful `literals` to add static metadata that helps with entity identification
### Label and attribute management
- Establish consistent labeling conventions across your infrastructure
- Use `label_values` to extract dynamic attributes from your metrics
- Document the meaning and expected values of custom literals
- Ensure label names match across different entity definitions for proper relationship discovery
## Validation
After applying the Terraform configuration, verify that:
- Custom model rules are applied in your Knowledge Graph instance
- Entities are being discovered according to your defined queries
- Entity relationships and enrichment are working as expected
- Entity graphs display the correct entity types and connections
- Queries perform well without causing excessive load
## Related documentation
- [Manage entities and relations in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/manage-entities-relations/)
- [Get started with Terraform for Knowledge Graph](../getting-started/)
- [Knowledge graph basics](/docs/grafana-cloud/knowledge-graph/knowledge-graph-basics/)
docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/getting-started.md
+140
View File
@@ -0,0 +1,140 @@
---
description: Learn how to configure Terraform to manage Knowledge Graph resources
menuTitle: Get started
title: Get started with Terraform for Knowledge Graph
weight: 100
keywords:
- Terraform
- Knowledge Graph
- Provider Setup
- Getting Started
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/getting-started/
---
# Get started with Terraform for Knowledge Graph
Learn how to configure Terraform to manage [Grafana Cloud Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) resources. This guide walks you through setting up the Grafana Terraform provider and preparing your environment.
## Before you begin
Before you begin, ensure you have the following:
- A Grafana Cloud account, as shown in [Get started](/docs/grafana-cloud/get-started/)
- [Terraform](https://www.terraform.io/downloads) installed on your machine
- Administrator permissions in your Grafana instance
- [Knowledge Graph enabled](/docs/grafana-cloud/knowledge-graph/get-started/) in your Grafana Cloud stack
{{< admonition type="note" >}}
All Terraform configuration files should be saved in the same directory.
{{< /admonition >}}
## Configure the Grafana provider
This Terraform configuration sets up the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when managing knowledge graph resources.
You can reuse a similar setup to the one described in [Creating and managing a Grafana Cloud stack using Terraform](/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/terraform-cloud-stack/) to set up a service account and a token.
### Steps
1. Create a Service account and token in Grafana.
To create a new one, refer to [Service account tokens](/docs/grafana/latest/administration/service-accounts/#service-account-tokens).
1. Create a file named `main.tf` and add the following:
```terraform
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
version = ">= 2.9.0"
}
}
}
provider "grafana" {
alias = "asserts"
url = "<Stack-URL>"
auth = "<Service-account-token>"
stack_id = "<Stack-ID>"
}
```
1. Replace the following field values:
- `<Stack-URL>` with the URL of your Grafana stack (for example, `https://my-stack.grafana.net/`)
- `<Service-account-token>` with the service account token that you created
- `<Stack-ID>` with your Grafana Cloud stack ID
{{< admonition type="note" >}}
The `stack_id` parameter is required for Knowledge Graph resources to identify the stack where the resources belong.
{{< /admonition >}}
## Apply Terraform configurations
After creating your Terraform configuration files, apply them using the following commands:
1. Initialize a working directory containing Terraform configuration files:
```shell
terraform init
```
1. Preview the changes that Terraform makes:
```shell
terraform plan
```
1. Apply the configuration files:
```shell
terraform apply
```
## Verify your setup
After applying the configuration, verify your setup by checking that:
- Terraform can authenticate with your Grafana Cloud stack
- The provider is properly configured with the correct stack ID
- No errors appear in the Terraform output
## Best practices
When managing Knowledge Graph resources with Terraform, consider the following best practices:
### Name conventions
- Use descriptive names that clearly indicate the purpose of each resource
- Follow a consistent naming pattern across your organization
- Include environment or team identifiers in names when appropriate
### Version control
- Store your Terraform configurations in version control (Git)
- Use separate directories or workspaces for different environments
- Document changes in commit messages
### State management
- Use remote state backends for team collaboration
- Enable state locking to prevent concurrent modifications
- Regularly back up your Terraform state files
### Security
- Never commit service account tokens or sensitive data to version control
- Use environment variables or secret management tools for credentials
- Rotate service account tokens regularly
## Next steps
Now that you have configured the Terraform provider, you can start managing knowledge graph resources:
- [Configure notification alerts](../notification-alerts/)
- [Define suppressed assertions](../suppressed-assertions/)
- [Create custom model rules](../custom-model-rules/)
- [Set up log configurations](../log-configurations/)
- [Configure thresholds](../thresholds/)
- [Configure knowledge graph SLOs](../knowledge-graph-slo/)
docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/knowledge-graph-slo.md
+696
View File
@@ -0,0 +1,696 @@
---
description: Learn how to configure knowledge graph SLOs in Grafana using Terraform for entity-centric monitoring and root cause analysis
menuTitle: Knowledge graph SLOs
title: Configure knowledge graph SLOs using Terraform
weight: 650
keywords:
- Terraform
- Knowledge graph
- SLO
- Service Level Objectives
- RCA workbench
---
# Configure knowledge graph SLOs using Terraform
Service level objectives (SLOs) in the [knowledge graph](/docs/grafana-cloud/knowledge-graph/) provide entity-centric service level monitoring with integrated root cause analysis capabilities. By using the `grafana_slo_provenance` label with the value `asserts`, you can create SLOs that display the "asserts" badge in the UI and enable the **Open RCA workbench** button for seamless troubleshooting.
For details about creating and managing SLOs in the knowledge graph UI, refer to [Create and manage the knowledge graph SLOs](/docs/grafana-cloud/knowledge-graph/configure/manage-slos/).
## Overview
Knowledge graph SLOs extend standard Grafana SLOs with entity-centric monitoring and root cause analysis features:
- **Entity-centric monitoring:** SLOs are tied to specific services, applications, or infrastructure entities tracked by the knowledge graph
- **RCA workbench integration:** The **Open RCA workbench** button enables deep-linking to pre-filtered troubleshooting views
- **Knowledge graph provenance badge:** SLOs display an "asserts" badge instead of "provisioned" in the UI
- **Search expressions:** Define custom search expressions to filter entities in RCA workbench when troubleshooting an SLO breach
## Before you begin
To create a knowledge graph SLO using Terraform, you need to:
- Configure the knowledge graph and have metrics flowing into Grafana Cloud
- [Set up Terraform for the knowledge Graph](../getting-started/)
- Possess knowledge of and have experience with defining SLOs, SLIs, SLAs, and error budgets
- Have an understanding of PromQL
## Create a basic knowledge graph SLO
Create a file named `kg-slo.tf` and add the following:
```terraform
# Basic knowledge graph SLO with entity-centric monitoring
resource "grafana_slo" "kg_example" {
name = "API Service Availability"
description = "SLO managed by knowledge graph for entity-centric monitoring and RCA"
query {
freeform {
query = "sum(rate(http_requests_total{code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total[$__rate_interval]))"
}
type = "freeform"
}
objectives {
value = 0.995
window = "30d"
}
destination_datasource {
uid = "grafanacloud-prom"
}
# Knowledge graph integration labels
# The grafana_slo_provenance label triggers knowledge graph-specific behavior:
# - Displays "asserts" badge instead of "provisioned"
# - Shows "Open RCA workbench" button in the SLO UI
# - Enables correlation with knowledge graph entity-centric monitoring
label {
key = "grafana_slo_provenance"
value = "asserts"
}
label {
key = "service_name"
value = "api-service"
}
# Search expression for RCA workbench
# This enables the "Open RCA workbench" button to deep-link with pre-filtered context
search_expression = "service=api-service"
alerting {
fastburn {
annotation {
key = "name"
value = "SLO Burn Rate Very High"
}
annotation {
key = "description"
value = "Error budget is burning too fast"
}
}
slowburn {
annotation {
key = "name"
value = "SLO Burn Rate High"
}
annotation {
key = "description"
value = "Error budget is burning too fast"
}
}
}
}
```
## Configure an SLO with multiple entity labels
Configure SLOs with multiple entity labels for fine-grained filtering in RCA workbench:
```terraform
# Knowledge graph SLO with comprehensive entity labels
resource "grafana_slo" "payment_service" {
name = "Payment Service Latency SLO"
description = "Latency SLO for payment processing with team and environment context"
query {
freeform {
query = "histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket{service=\"payment\"}[$__rate_interval])) by (le)) < 0.5"
}
type = "freeform"
}
objectives {
value = 0.99
window = "7d"
}
destination_datasource {
uid = "grafanacloud-prom"
}
# Knowledge graph provenance - required for RCA workbench integration
label {
key = "grafana_slo_provenance"
value = "asserts"
}
# Service identification
label {
key = "service_name"
value = "payment-service"
}
# Team ownership
label {
key = "team_name"
value = "payments-team"
}
# Environment
label {
key = "environment"
value = "production"
}
# Business unit
label {
key = "business_unit"
value = "fintech"
}
# Search expression with multiple filters
search_expression = "service=payment-service AND environment=production"
alerting {
fastburn {
annotation {
key = "name"
value = "Payment Latency Critical"
}
annotation {
key = "description"
value = "Payment service P99 latency exceeding SLO - immediate attention required"
}
annotation {
key = "runbook_url"
value = "https://docs.example.com/runbooks/payment-latency"
}
}
slowburn {
annotation {
key = "name"
value = "Payment Latency Warning"
}
annotation {
key = "description"
value = "Payment service experiencing elevated latency"
}
}
}
}
```
## Configure a Kubernetes service SLO
Configure knowledge graph SLOs for Kubernetes services with Pod and namespace context:
```terraform
# Knowledge graph SLO for Kubernetes service
resource "grafana_slo" "k8s_frontend" {
name = "Frontend Service Availability"
description = "Availability SLO for frontend service in Kubernetes"
query {
freeform {
query = "sum(rate(http_requests_total{namespace=\"frontend\",code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total{namespace=\"frontend\"}[$__rate_interval]))"
}
type = "freeform"
}
objectives {
value = 0.999
window = "30d"
}
destination_datasource {
uid = "grafanacloud-prom"
}
label {
key = "grafana_slo_provenance"
value = "asserts"
}
label {
key = "service_name"
value = "frontend"
}
label {
key = "namespace"
value = "frontend"
}
label {
key = "cluster"
value = "prod-us-west-2"
}
# Search expression targeting Kubernetes entities
search_expression = "namespace=frontend AND cluster=prod-us-west-2"
alerting {
fastburn {
annotation {
key = "name"
value = "Frontend Service Critical"
}
annotation {
key = "description"
value = "Frontend service availability below SLO"
}
annotation {
key = "severity"
value = "critical"
}
}
slowburn {
annotation {
key = "name"
value = "Frontend Service Degraded"
}
annotation {
key = "description"
value = "Frontend service showing signs of degradation"
}
annotation {
key = "severity"
value = "warning"
}
}
}
}
```
## Configure an API endpoint-specific SLO
Configure knowledge graph SLOs for specific API endpoints with request context:
```terraform
# Knowledge graph SLO for critical API endpoint
resource "grafana_slo" "checkout_api" {
name = "Checkout API Availability"
description = "Availability SLO for /api/checkout endpoint"
query {
freeform {
query = "sum(rate(http_requests_total{path=\"/api/checkout\",code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total{path=\"/api/checkout\"}[$__rate_interval]))"
}
type = "freeform"
}
objectives {
value = 0.9999
window = "30d"
}
destination_datasource {
uid = "grafanacloud-prom"
}
label {
key = "grafana_slo_provenance"
value = "asserts"
}
label {
key = "service_name"
value = "checkout-service"
}
label {
key = "endpoint"
value = "/api/checkout"
}
label {
key = "criticality"
value = "high"
}
# Search expression with endpoint context
search_expression = "service=checkout-service AND path=/api/checkout"
alerting {
fastburn {
annotation {
key = "name"
value = "Checkout API Critical Failure"
}
annotation {
key = "description"
value = "Checkout API experiencing high error rates - revenue impact"
}
annotation {
key = "severity"
value = "critical"
}
annotation {
key = "alert_priority"
value = "P0"
}
}
slowburn {
annotation {
key = "name"
value = "Checkout API Degradation"
}
annotation {
key = "description"
value = "Checkout API showing elevated error rates"
}
annotation {
key = "severity"
value = "warning"
}
}
}
}
```
## Configure a multi-environment SLO
Manage knowledge graph SLOs across multiple environments using Terraform workspaces or modules:
```terraform
# Variable for environment-specific configuration
variable "environment" {
description = "Environment name"
type = string
}
variable "slo_target" {
description = "SLO target percentage"
type = number
}
# Environment-aware knowledge graph SLO
resource "grafana_slo" "api_service" {
name = "${var.environment} - API Service Availability"
description = "API service availability SLO for ${var.environment} environment"
query {
freeform {
query = "sum(rate(http_requests_total{environment=\"${var.environment}\",code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total{environment=\"${var.environment}\"}[$__rate_interval]))"
}
type = "freeform"
}
objectives {
value = var.slo_target
window = "30d"
}
destination_datasource {
uid = "grafanacloud-prom"
}
label {
key = "grafana_slo_provenance"
value = "asserts"
}
label {
key = "service_name"
value = "api-service"
}
label {
key = "environment"
value = var.environment
}
search_expression = "service=api-service AND environment=${var.environment}"
alerting {
fastburn {
annotation {
key = "name"
value = "${var.environment} API Critical"
}
annotation {
key = "description"
value = "API service in ${var.environment} experiencing critical errors"
}
}
slowburn {
annotation {
key = "name"
value = "${var.environment} API Warning"
}
annotation {
key = "description"
value = "API service in ${var.environment} showing elevated errors"
}
}
}
}
```
## Resource reference
### `grafana_slo` with knowledge graph provenance
When creating knowledge graph-managed SLOs, the `grafana_slo` resource requires the `grafana_slo_provenance` label set to `asserts` to enable RCA workbench integration.
#### Required knowledge graph configuration
| Name | Type | Required | Description |
| ------------------------------ | -------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `grafana_slo_provenance` label | `string` | Yes | Must be set to `asserts` to enable knowledge graph-specific features and RCA workbench integration |
| `search_expression` | `string` | Recommended | Search expression for filtering entities in RCA workbench |
#### Key arguments for knowledge graph SLOs
| Name | Type | Required | Description |
| ------------------------ | -------------- | -------- | ----------------------------------------------------------------- |
| `name` | `string` | Yes | The name of the SLO |
| `description` | `string` | No | Description of the SLO purpose and scope |
| `query` | `object` | Yes | Query configuration defining how SLO is calculated |
| `objectives` | `object` | Yes | Target objectives including value and time window |
| `destination_datasource` | `object` | Yes | Destination data source for SLO metrics |
| `label` | `list(object)` | Yes | Labels for the SLO, must include `grafana_slo_provenance=asserts` |
| `search_expression` | `string` | No | Search expression for RCA workbench filtering |
| `alerting` | `object` | No | Alerting configuration for fast burn and slow burn alerts |
#### Query block
The `query` block supports the following:
| Name | Type | Required | Description |
| ---------- | -------- | -------- | --------------------------------------------------------- |
| `type` | `string` | Yes | Query type, typically `freeform` for knowledge graph SLOs |
| `freeform` | `object` | Yes | Freeform query configuration |
The `freeform` block supports:
| Name | Type | Required | Description |
| ------- | -------- | -------- | -------------------------------- |
| `query` | `string` | Yes | PromQL query for SLO calculation |
#### Objectives block
The `objectives` block supports the following:
| Name | Type | Required | Description |
| -------- | -------- | -------- | --------------------------------------------------- |
| `value` | `number` | Yes | Target SLO value (for example, 0.995 for 99.5%) |
| `window` | `string` | Yes | Time window for SLO evaluation (for example, "30d") |
#### Label block
Each `label` block supports the following:
| Name | Type | Required | Description |
| ------- | -------- | -------- | ----------- |
| `key` | `string` | Yes | Label key |
| `value` | `string` | Yes | Label value |
**Required label for knowledge graph SLOs:**
- `grafana_slo_provenance` = `asserts` (enables knowledge graph features)
**Recommended labels for entity tracking:**
- `service_name` - Name of the service
- `team_name` - Team responsible for the service
- `environment` - Environment (prod, staging, development)
- `namespace` - Kubernetes namespace
- `cluster` - Kubernetes cluster name
<!-- vale Grafana.Gerunds = NO -->
#### Alerting block
The `alerting` block supports the following:
| Name | Type | Required | Description |
| ---------- | -------- | -------- | ---------------------------------- |
| `fastburn` | `object` | No | Fast burn rate alert configuration |
| `slowburn` | `object` | No | Slow burn rate alert configuration |
Each alert block (`fastburn`, `slowburn`) supports:
| Name | Type | Required | Description |
| ------------ | -------------- | -------- | ------------------------------- |
| `annotation` | `list(object)` | No | Annotations to add to the alert |
Each `annotation` block supports:
| Name | Type | Required | Description |
| ------- | -------- | -------- | ---------------- |
| `key` | `string` | Yes | Annotation key |
| `value` | `string` | Yes | Annotation value |
Common annotation keys:
- `name` - Alert name
- `description` - Alert description
- `severity` - Alert severity level
- `runbook_url` - Link to runbook documentation
<!-- vale Grafana.Gerunds = YES -->
#### Example
```terraform
resource "grafana_slo" "kg_example" {
name = "My Service SLO"
description = "SLO with knowledge graph RCA integration"
query {
freeform {
query = "sum(rate(http_requests_total{code!~\"5..\"}[$__rate_interval])) / sum(rate(http_requests_total[$__rate_interval]))"
}
type = "freeform"
}
objectives {
value = 0.995
window = "30d"
}
destination_datasource {
uid = "grafanacloud-prom"
}
label {
key = "grafana_slo_provenance"
value = "asserts"
}
label {
key = "service_name"
value = "my-service"
}
search_expression = "service=my-service"
alerting {
fastburn {
annotation {
key = "name"
value = "SLO Fast Burn"
}
}
slowburn {
annotation {
key = "name"
value = "SLO Slow Burn"
}
}
}
}
```
## Best practices
Follow these best practices when setting knowledge graph SLOs.
### Use the knowledge graph provenance label
- Always include the `grafana_slo_provenance` label with value `asserts` for knowledge graph-managed SLOs
- This label enables the "asserts" badge in the UI instead of "provisioned"
- It also enables the **Open RCA workbench** button for troubleshooting SLO breaches
### Define search expressions
- Define meaningful search expressions that filter relevant entities in RCA workbench
- The search expression defines which entities populate RCA workbench when you troubleshoot an SLO breach
- Use entity attributes like service name, environment, namespace, and cluster
- Combine multiple filters with `AND` operators for precise filtering
- Test search expressions in RCA workbench before codifying them in Terraform
### Add entity labels
- Add descriptive labels to track service ownership, environment, and criticality
- Use consistent label naming conventions across all SLOs
- Include team names to enable quick identification of ownership
- Tag critical business services with appropriate labels
### Set SLO targets
- Set realistic SLO targets based on service requirements and capabilities
- Use higher targets (0.999+) for critical user-facing services
- Consider different targets for different environments (production vs staging)
- Review and adjust targets based on actual service performance
### Add alert annotations
- Add comprehensive descriptions to help on-call engineers understand the alert
- Include runbook URLs in annotations for quick access to troubleshooting guides
- Set appropriate severity levels (critical, warning) based on business impact
- Customize alert names to clearly identify the affected service and issue
### Configure queries
- Use PromQL queries that accurately represent service health
- Exclude expected error codes, such as 404, from error calculations when appropriate
- Leverage rate intervals with `$__rate_interval` for dynamic time range support
- Test queries in Grafana before adding them to Terraform configurations
### Set compliance windows
- Use 30-day windows for production SLOs to align with monthly reporting
- Consider shorter windows (7d) for development or testing environments
- Ensure compliance windows align with business requirements and error budget policies
## Verify the configuration
After applying the Terraform configuration, verify that:
- SLOs are created in your Grafana Cloud stack
- SLOs appear in **Observability > SLO** with the "asserts" badge
- The **Open RCA workbench** button is visible when you expand **Objective** for an SLO
- You can select a time range in the **Error Budget Burndown** panel and click **Open in RCA workbench**
- Search expressions correctly filter entities in RCA workbench
- Fast burn and slow burn alerts are configured with appropriate thresholds
- Labels are correctly applied and visible in the SLO details
## Troubleshooting
Follow these troubleshooting steps if you experience issues setting knowledge graph SLOs.
### SLO shows "provisioned" instead of "asserts" badge
Ensure the `grafana_slo_provenance` label is set to `asserts`:
```terraform
label {
key = "grafana_slo_provenance"
value = "asserts"
}
```
### Open RCA workbench button not appearing
- Verify the `search_expression` field is populated
- The **Open RCA workbench** button appears after you have added a search expression in the **RCA workbench Context** section
- Ensure the search expression uses valid entity attributes
- Check that the knowledge graph is properly configured and receiving data
### Alerts not triggering
- Verify the PromQL query returns valid results in Grafana
- Check that the destination data source is correctly configured
- Ensure alerting blocks are properly defined with annotations
## Related documentation
- [Create and manage knowledge graph SLOs](/docs/grafana-cloud/knowledge-graph/configure/manage-slos/)
- [Troubleshoot an SLO breach with the knowledge graph](/docs/grafana-cloud/knowledge-graph/troubleshoot-infra-apps/slos/)
- [Get started with Terraform for the knowledge graph](../getting-started/)
- [Introduction to Grafana SLO](/docs/grafana-cloud/alerting-and-irm/slo/introduction/)
- [Configure notifications in the knowledge graph](/docs/grafana-cloud/knowledge-graph/configure/notifications/)
docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/log-configurations.md
+290
View File
@@ -0,0 +1,290 @@
---
description: Configure log correlation for Knowledge Graph using Terraform
menuTitle: Log configurations
title: Configure log correlation using Terraform
weight: 500
keywords:
- Terraform
- Knowledge Graph
- Log Configuration
- Log Correlation
- Loki
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/log-configurations/
---
# Configure log correlation using Terraform
Log configurations in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) allow you to define how log data is queried and correlated with entities. You can specify data sources, entity matching rules, label mappings, and filtering options for spans and traces.
For information about configuring log correlation in the Knowledge Graph UI, refer to [Configure logs correlation](/docs/grafana-cloud/knowledge-graph/configure/logs-correlation/).
## Basic log configuration
Create a file named `log-configs.tf` and add the following:
```terraform
# Basic log configuration for services
resource "grafana_asserts_log_config" "production" {
provider = grafana.asserts
name = "production"
priority = 1000
default_config = false
data_source_uid = "grafanacloud-logs"
error_label = "error"
match {
property = "asserts_entity_type"
op = "EQUALS"
values = ["Service"]
}
match {
property = "environment"
op = "EQUALS"
values = ["production", "staging"]
}
entity_property_to_log_label_mapping = {
"otel_namespace" = "service_namespace"
"otel_service" = "service_name"
"environment" = "env"
"site" = "region"
}
filter_by_span_id = true
filter_by_trace_id = true
}
```
## Log configuration with multiple match rules
Configure log correlation with multiple entity matching criteria:
```terraform
# Development environment log configuration
resource "grafana_asserts_log_config" "development" {
provider = grafana.asserts
name = "development"
priority = 2000
default_config = true
data_source_uid = "elasticsearch-dev"
error_label = "error"
match {
property = "asserts_entity_type"
op = "EQUALS"
values = ["Service"]
}
match {
property = "environment"
op = "EQUALS"
values = ["development", "testing"]
}
match {
property = "site"
op = "EQUALS"
values = ["us-east-1"]
}
match {
property = "service"
op = "EQUALS"
values = ["api"]
}
entity_property_to_log_label_mapping = {
"otel_namespace" = "service_namespace"
"otel_service" = "service_name"
"environment" = "env"
"site" = "region"
"service" = "app"
}
filter_by_span_id = true
filter_by_trace_id = true
}
```
## Minimal log configuration
Create a minimal configuration for all entities:
```terraform
# Minimal configuration for all entities
resource "grafana_asserts_log_config" "minimal" {
provider = grafana.asserts
name = "minimal"
priority = 3000
default_config = false
data_source_uid = "loki-minimal"
match {
property = "asserts_entity_type"
op = "IS_NOT_NULL"
values = []
}
}
```
## Advanced log configuration with complex match rules
Configure logs with multiple operations and advanced match rules:
```terraform
# Advanced configuration with multiple operations
resource "grafana_asserts_log_config" "advanced" {
provider = grafana.asserts
name = "advanced"
priority = 1500
default_config = false
data_source_uid = "loki-advanced"
error_label = "level"
match {
property = "service_type"
op = "CONTAINS"
values = ["web", "api"]
}
match {
property = "environment"
op = "NOT_EQUALS"
values = ["test"]
}
match {
property = "team"
op = "IS_NOT_NULL"
values = []
}
entity_property_to_log_label_mapping = {
"service_type" = "type"
"team" = "owner"
"environment" = "env"
"version" = "app_version"
}
filter_by_span_id = true
filter_by_trace_id = false
}
```
## Resource reference
### `grafana_asserts_log_config`
Manage Knowledge Graph log configurations through the Grafana API.
#### Arguments
| Name | Type | Required | Description |
| -------------------------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------- |
| `name` | `string` | Yes | The name of the log configuration. This field is immutable and forces recreation if changed. |
| `priority` | `number` | Yes | Priority of the log configuration. Higher priority configurations are evaluated first. |
| `default_config` | `bool` | Yes | Whether this is the default configuration. Default configurations cannot be deleted. |
| `data_source_uid` | `string` | Yes | DataSource UID to be queried (for example, a Loki instance). |
| `match` | `list(object)` | No | List of match rules for entity properties. Refer to [match block](#match-block) for details. |
| `error_label` | `string` | No | Label name used to identify error logs. |
| `entity_property_to_log_label_mapping` | `map(string)` | No | Mapping of entity properties to log labels for correlation. |
| `filter_by_span_id` | `bool` | No | Whether to filter logs by span ID for distributed tracing correlation. |
| `filter_by_trace_id` | `bool` | No | Whether to filter logs by trace ID for distributed tracing correlation. |
#### Match block
Each `match` block supports the following:
| Name | Type | Required | Description |
| ---------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `property` | `string` | Yes | Entity property to match against. |
| `op` | `string` | Yes | Operation to use for matching. One of: `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `DOES_NOT_CONTAIN`, `IS_NULL`, `IS_NOT_NULL`. |
| `values` | `list(string)` | Yes | Values to match against. Can be empty for `IS_NULL` and `IS_NOT_NULL` operations. |
#### Example
```terraform
resource "grafana_asserts_log_config" "example" {
provider = grafana.asserts
name = "example-logs"
priority = 1000
default_config = false
data_source_uid = "loki-prod"
error_label = "level"
match {
property = "asserts_entity_type"
op = "EQUALS"
values = ["Service", "Pod"]
}
entity_property_to_log_label_mapping = {
"service" = "app"
"namespace" = "k8s_namespace"
"environment" = "env"
}
filter_by_span_id = true
filter_by_trace_id = true
}
```
## Best practices
### Priority management
- Assign lower priority numbers to more specific configurations
- Higher priority configurations are evaluated first
- Use consistent priority ranges for different configuration types
- Document the reasoning behind priority assignments
### Data source configuration
- Ensure the data source UID matches your actual Loki or log aggregation system
- Test data source connectivity before applying configurations
- Use descriptive names for log configurations to indicate their purpose
- Consider using separate data sources for different environments
### Label map strategy
- Map entity properties consistently across all log configurations
- Use meaningful log label names that match your logging standards
- Document the mapping relationships in configuration comments
- Verify that mapped labels exist in your log data
### Match rules design
- Start with broad match rules and refine based on needs
- Use specific property names that exist in your entity model
- Test match rules with sample data before deploying
- Combine multiple match rules for precise entity targeting
### Distributed trace integration
- Enable `filter_by_span_id` and `filter_by_trace_id` when using OpenTelemetry
- Ensure your logs contain the appropriate trace and span ID labels
- Use consistent label names for trace IDs across your logging infrastructure
- Test trace correlation to verify it works as expected
## Validation
After applying the Terraform configuration, verify that:
- Log configurations are created in your Knowledge Graph instance
- Configurations appear in the Knowledge Graph UI under **Observability > Configuration > Logs**
- Log correlation works when drilling down from entities
- Label mappings correctly translate entity properties to log labels
- Match rules properly filter entities
- Trace and span ID filtering works for distributed tracing
## Related documentation
- [Configure logs correlation in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/logs-correlation/)
- [Get started with Terraform for Knowledge Graph](../getting-started/)
- [Loki documentation](/docs/loki/latest/)
docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/notification-alerts.md
+224
View File
@@ -0,0 +1,224 @@
---
description: Configure notification alerts for Knowledge Graph using Terraform
menuTitle: Notification alerts
title: Configure notification alerts using Terraform
weight: 200
keywords:
- Terraform
- Knowledge Graph
- Notification Alerts
- Alert Configuration
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/notification-alerts/
---
# Configure notification alerts using Terraform
Notification alerts configurations in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) allow you to manage how alerts are processed and routed. You can specify match labels to filter alerts, add custom labels, set duration requirements, and control silencing.
For information about configuring notification alerts in the Knowledge Graph UI, refer to [Configure notifications](/docs/grafana-cloud/knowledge-graph/configure/notifications/).
## Basic notification alerts configuration
Create a file named `alert-configs.tf` and add the following:
```terraform
# Basic alert configuration with silencing
resource "grafana_asserts_notification_alerts_config" "prometheus_remote_storage_failures" {
provider = grafana.asserts
name = "PrometheusRemoteStorageFailures"
match_labels = {
alertname = "PrometheusRemoteStorageFailures"
alertgroup = "prometheus.alerts"
asserts_env = "prod"
}
silenced = true
}
# High severity alert with specific job and context matching
resource "grafana_asserts_notification_alerts_config" "error_buildup_notify" {
provider = grafana.asserts
name = "ErrorBuildupNotify"
match_labels = {
alertname = "ErrorBuildup"
job = "acai"
asserts_request_type = "inbound"
asserts_request_context = "/auth"
}
silenced = false
}
```
## Notification alerts with additional labels and duration
Configure alerts with custom labels and timing requirements:
```terraform
# Alert with additional labels and custom duration
resource "grafana_asserts_notification_alerts_config" "payment_test_alert" {
provider = grafana.asserts
name = "PaymentTestAlert"
match_labels = {
alertname = "PaymentTestAlert"
additional_labels = "asserts_severity=~\"critical\""
alertgroup = "alex-k8s-integration-test.alerts"
}
alert_labels = {
testing = "onetwothree"
}
duration = "5m"
silenced = false
}
```
## Latency and performance notification alerts
Monitor and alert on latency and performance issues:
```terraform
# Latency alert for shipping service
resource "grafana_asserts_notification_alerts_config" "high_shipping_latency" {
provider = grafana.asserts
name = "high shipping latency"
match_labels = {
alertname = "LatencyP99ErrorBuildup"
job = "shipping"
asserts_request_type = "inbound"
}
silenced = false
}
# CPU throttling alert with warning severity
resource "grafana_asserts_notification_alerts_config" "cpu_throttling_sustained" {
provider = grafana.asserts
name = "CPUThrottlingSustained"
match_labels = {
alertname = "CPUThrottlingSustained"
additional_labels = "asserts_severity=~\"warning\""
}
silenced = true
}
```
## Infrastructure and service notification alerts
Configure alerts for infrastructure components and services:
```terraform
# Ingress error rate alert
resource "grafana_asserts_notification_alerts_config" "ingress_error" {
provider = grafana.asserts
name = "ingress error"
match_labels = {
alertname = "ErrorRatioBreach"
job = "ingress-nginx-controller-metrics"
asserts_request_type = "inbound"
}
silenced = false
}
# MySQL Galera cluster alert
resource "grafana_asserts_notification_alerts_config" "mysql_galera_not_ready" {
provider = grafana.asserts
name = "MySQLGaleraNotReady"
match_labels = {
alertname = "MySQLGaleraNotReady"
}
silenced = false
}
```
## Resource reference
### `grafana_asserts_notification_alerts_config`
Manage Knowledge Graph notification alerts configurations through the Grafana API.
#### Arguments
| Name | Type | Required | Description |
| -------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` | Yes | The name of the notification alerts configuration. This field is immutable and forces recreation if changed. |
| `match_labels` | `map(string)` | No | Labels to match for this notification alerts configuration. Used to filter which alerts this configuration applies to. |
| `alert_labels` | `map(string)` | No | Labels to add to alerts generated by this notification alerts configuration. |
| `duration` | `string` | No | Duration for which the condition must be true before firing (for example, '5m', '30s'). Maps to 'for' in Knowledge Graph API. |
| `silenced` | `bool` | No | Whether this notification alerts configuration is silenced. Defaults to `false`. |
#### Example
```terraform
resource "grafana_asserts_notification_alerts_config" "example" {
provider = grafana.asserts
name = "ExampleAlert"
match_labels = {
alertname = "HighCPUUsage"
job = "monitoring"
}
alert_labels = {
severity = "warning"
team = "platform"
}
duration = "5m"
silenced = false
}
```
## Best practices
### Label management
- Use specific and meaningful labels in `match_labels` to ensure precise alert filtering
- Leverage existing label conventions from your monitoring setup
- Consider using `asserts_env` and `asserts_site` labels for multi-environment setups
### Silence strategy
- Use the `silenced` parameter for temporary suppression rather than deleting notification alerts configurations
- Document the reason for silencing in your Terraform configuration comments
- Regularly review silenced configurations to ensure they're still needed
### Duration configuration
- Set appropriate duration values based on your alerting requirements
- Consider the nature of the monitored condition when choosing duration
- Use consistent duration formats across similar alert types
## Validation
After applying the Terraform configuration, verify that:
- Notification alerts configurations are created in your Knowledge Graph instance
- Configurations appear in the Knowledge Graph UI under **Observability > Rules > Notify**
- Match labels correctly filter the intended alerts
- Custom labels are properly applied to generated alerts
## Related documentation
- [Configure notifications in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/notifications/)
- [Get started with Terraform for Knowledge Graph](../getting-started/)
- [Configure alerts in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/alerts/)
docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/suppressed-assertions.md
+308
View File
@@ -0,0 +1,308 @@
---
description: Configure suppressed assertions for Knowledge Graph using Terraform
menuTitle: Suppressed assertions
title: Configure suppressed assertions using Terraform
weight: 300
keywords:
- Terraform
- Knowledge Graph
- Suppressed Assertions
- Alert Suppression
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/suppressed-assertions/
---
# Configure suppressed assertions using Terraform
Suppressed assertions configurations allow you to disable specific alerts or assertions based on label matching in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/). This is useful for maintenance windows, test environments, or when you want to temporarily suppress certain types of alerts.
For information about suppressing insights in the Knowledge Graph UI, refer to [Suppress insights](/docs/grafana-cloud/knowledge-graph/troubleshoot-infra-apps/suppress-insights/).
## Basic suppressed assertions configuration
Create a file named `suppressed-assertions.tf` and add the following:
```terraform
# Basic suppressed alert configuration for maintenance
resource "grafana_asserts_suppressed_assertions_config" "maintenance_window" {
provider = grafana.asserts
name = "MaintenanceWindow"
match_labels = {
service = "api-service"
maintenance = "true"
}
}
# Suppress specific alertname during deployment
resource "grafana_asserts_suppressed_assertions_config" "deployment_suppression" {
provider = grafana.asserts
name = "DeploymentSuppression"
match_labels = {
alertname = "HighLatency"
job = "web-service"
env = "staging"
}
}
# Suppress alerts for specific test environment
resource "grafana_asserts_suppressed_assertions_config" "test_environment_suppression" {
provider = grafana.asserts
name = "TestEnvironmentSuppression"
match_labels = {
alertgroup = "test.alerts"
environment = "test"
}
}
```
## Service-specific suppression configurations
Suppress alerts for specific services during maintenance or operational activities:
```terraform
# Suppress alerts for specific services during maintenance
resource "grafana_asserts_suppressed_assertions_config" "api_service_maintenance" {
provider = grafana.asserts
name = "APIServiceMaintenance"
match_labels = {
service = "api-gateway"
job = "api-gateway"
maintenance = "scheduled"
}
}
# Suppress database alerts during backup operations
resource "grafana_asserts_suppressed_assertions_config" "database_backup" {
provider = grafana.asserts
name = "DatabaseBackupSuppression"
match_labels = {
service = "postgresql"
job = "postgres-exporter"
backup_mode = "active"
}
}
# Suppress monitoring system alerts during updates
resource "grafana_asserts_suppressed_assertions_config" "monitoring_update" {
provider = grafana.asserts
name = "MonitoringSystemUpdate"
match_labels = {
service = "prometheus"
job = "prometheus"
update = "in_progress"
}
}
```
## Environment and team-based suppression
Create suppression rules based on environment or team:
```terraform
# Suppress all alerts for development environment
resource "grafana_asserts_suppressed_assertions_config" "dev_environment" {
provider = grafana.asserts
name = "DevelopmentEnvironmentSuppression"
match_labels = {
environment = "development"
team = "platform"
}
}
# Suppress alerts for specific team during their maintenance window
resource "grafana_asserts_suppressed_assertions_config" "team_maintenance" {
provider = grafana.asserts
name = "TeamMaintenanceWindow"
match_labels = {
team = "backend"
maintenance = "team_scheduled"
timezone = "UTC"
}
}
# Suppress alerts for staging environment during testing
resource "grafana_asserts_suppressed_assertions_config" "staging_testing" {
provider = grafana.asserts
name = "StagingTestingSuppression"
match_labels = {
environment = "staging"
testing = "automated"
job = "integration-tests"
}
}
```
## Alert type and severity-based suppression
Suppress alerts based on their type or severity:
```terraform
# Suppress low severity alerts during business hours
resource "grafana_asserts_suppressed_assertions_config" "low_severity_business_hours" {
provider = grafana.asserts
name = "LowSeverityBusinessHours"
match_labels = {
severity = "warning"
timezone = "business_hours"
}
}
# Suppress specific alert types during known issues
resource "grafana_asserts_suppressed_assertions_config" "known_issue_suppression" {
provider = grafana.asserts
name = "KnownIssueSuppression"
match_labels = {
alertname = "HighMemoryUsage"
service = "legacy-service"
issue_id = "LEG-123"
}
}
# Suppress infrastructure alerts during planned maintenance
resource "grafana_asserts_suppressed_assertions_config" "infrastructure_maintenance" {
provider = grafana.asserts
name = "InfrastructureMaintenance"
match_labels = {
alertgroup = "infrastructure.alerts"
maintenance_type = "planned"
affected_services = "all"
}
}
```
## Complex multi-label suppression
Define complex suppression rules with multiple labels:
```terraform
# Complex suppression for multi-service deployments
resource "grafana_asserts_suppressed_assertions_config" "multi_service_deployment" {
provider = grafana.asserts
name = "MultiServiceDeploymentSuppression"
match_labels = {
deployment_id = "deploy-2024-01-15"
services = "api,worker,frontend"
environment = "production"
deployment_type = "blue_green"
}
}
# Suppress alerts for specific cluster during maintenance
resource "grafana_asserts_suppressed_assertions_config" "cluster_maintenance" {
provider = grafana.asserts
name = "ClusterMaintenanceSuppression"
match_labels = {
cluster = "production-cluster-1"
maintenance = "cluster_upgrade"
affected_nodes = "all"
estimated_duration = "2h"
}
}
# Suppress alerts for specific region during network issues
resource "grafana_asserts_suppressed_assertions_config" "regional_network_issue" {
provider = grafana.asserts
name = "RegionalNetworkIssueSuppression"
match_labels = {
region = "us-west-2"
issue_type = "network"
affected_services = "external_dependencies"
incident_id = "NET-456"
}
}
```
## Resource reference
### `grafana_asserts_suppressed_assertions_config`
Manage Knowledge Graph suppressed assertions configurations through the Grafana API.
#### Arguments
| Name | Type | Required | Description |
| -------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `name` | `string` | Yes | The name of the suppressed assertions configuration. This field is immutable and forces recreation if changed. |
| `match_labels` | `map(string)` | No | Labels to match for this suppressed assertions configuration. Used to determine which alerts should be suppressed. |
#### Example
```terraform
resource "grafana_asserts_suppressed_assertions_config" "example" {
provider = grafana.asserts
name = "ExampleSuppression"
match_labels = {
alertname = "TestAlert"
env = "development"
}
}
```
## Best practices
### Suppression strategy
- Use suppression rules for temporary situations rather than permanent solutions
- Document the reason for suppression in your Terraform configuration comments
- Set expiration dates or reminders to review suppression rules
- Prefer fixing alert thresholds over suppressing recurring false positives
### Label match rules
- Be specific with match labels to avoid suppressing unintended alerts
- Test suppression rules in non-production environments first
- Use descriptive names that indicate the purpose and scope of the suppression
- Include relevant context in labels (for example, incident IDs, maintenance windows)
### Lifecycle management
- Regularly review active suppression rules to ensure they're still needed
- Remove or update suppression rules after maintenance windows or deployments
- Use version control to track when suppression rules were added and why
- Consider using time-based automation to enable or disable suppression rules
## Validation
After applying the Terraform configuration, verify that:
- Suppressed assertions configurations are active in your Knowledge Graph instance
- Configurations appear in the Knowledge Graph UI under **Observability > Rules > Suppress**
- Matching alerts are properly suppressed
- Suppression rules don't affect unintended alerts
## Related documentation
- [Suppress insights in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/troubleshoot-infra-apps/suppress-insights/)
- [Get started with Terraform for Knowledge Graph](../getting-started/)
- [Configure notifications](/docs/grafana-cloud/knowledge-graph/configure/notifications/)
docs/sources/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/thresholds.md
+355
View File
@@ -0,0 +1,355 @@
---
description: Configure thresholds for Knowledge Graph using Terraform
menuTitle: Thresholds
title: Configure thresholds using Terraform
weight: 600
keywords:
- Terraform
- Knowledge Graph
- Thresholds
- Request Thresholds
- Resource Thresholds
- Health Thresholds
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/thresholds/
---
# Configure thresholds using Terraform
Threshold configurations in [Knowledge Graph](/docs/grafana-cloud/knowledge-graph/) allow you to define custom thresholds for request, resource, and health assertions. These configurations help you set specific limits and conditions for monitoring your services and infrastructure.
For information about managing thresholds in the Knowledge Graph UI, refer to [Manage thresholds](/docs/grafana-cloud/knowledge-graph/configure/manage-thresholds/).
## Basic threshold configuration
Create a file named `thresholds.tf` and add the following:
```terraform
# Basic threshold configuration with all three types
resource "grafana_asserts_thresholds" "basic" {
provider = grafana.asserts
request_thresholds = [{
entity_name = "payment-service"
assertion_name = "ErrorRatioBreach"
request_type = "inbound"
request_context = "/charge"
value = 0.01
}]
resource_thresholds = [{
assertion_name = "Saturation"
resource_type = "container"
container_name = "worker"
source = "metrics"
severity = "warning"
value = 75
}]
health_thresholds = [{
assertion_name = "ServiceDown"
expression = "up < 1"
entity_type = "Service"
}]
}
```
## Request threshold configurations
Configure thresholds for different service request types and contexts:
```terraform
# Multiple request thresholds for different services
resource "grafana_asserts_thresholds" "request_thresholds" {
provider = grafana.asserts
request_thresholds = [
{
entity_name = "api-service"
assertion_name = "ErrorRatioBreach"
request_type = "inbound"
request_context = "/api/v1/users"
value = 0.02
},
{
entity_name = "api-service"
assertion_name = "LatencyP99ErrorBuildup"
request_type = "inbound"
request_context = "/api/v1/orders"
value = 500
},
{
entity_name = "payment-gateway"
assertion_name = "RequestRateAnomaly"
request_type = "outbound"
request_context = "/payment/process"
value = 1000
}
]
}
```
## Resource threshold configurations
Define resource thresholds for different severity levels:
```terraform
# Resource thresholds for different severity levels
resource "grafana_asserts_thresholds" "resource_thresholds" {
provider = grafana.asserts
resource_thresholds = [
{
assertion_name = "Saturation"
resource_type = "container"
container_name = "web-server"
source = "metrics"
severity = "warning"
value = 75
},
{
assertion_name = "Saturation"
resource_type = "container"
container_name = "web-server"
source = "metrics"
severity = "critical"
value = 90
},
{
assertion_name = "ResourceRateBreach"
resource_type = "Pod"
container_name = "database"
source = "logs"
severity = "warning"
value = 80
}
]
}
```
## Health threshold configurations
Configure health checks with Prometheus expressions:
```terraform
# Health thresholds with Prometheus expressions
resource "grafana_asserts_thresholds" "health_thresholds" {
provider = grafana.asserts
health_thresholds = [
{
assertion_name = "ServiceDown"
expression = "up{job=\"api-service\"} < 1"
entity_type = "Service"
},
{
assertion_name = "HighMemoryUsage"
expression = "memory_usage_percent > 85"
entity_type = "Service"
},
{
assertion_name = "DatabaseConnectivity"
expression = "db_connection_pool_active / db_connection_pool_max > 0.9"
entity_type = "Service"
}
]
}
```
## Comprehensive threshold configuration
Define comprehensive thresholds for production environments:
```terraform
# Production environment with comprehensive thresholds
resource "grafana_asserts_thresholds" "production" {
provider = grafana.asserts
request_thresholds = [
{
entity_name = "frontend"
assertion_name = "ErrorRatioBreach"
request_type = "inbound"
request_context = "/"
value = 0.005
},
{
entity_name = "backend-api"
assertion_name = "LatencyP99ErrorBuildup"
request_type = "inbound"
request_context = "/api"
value = 200
}
]
resource_thresholds = [
{
assertion_name = "Saturation"
resource_type = "container"
container_name = "frontend"
source = "metrics"
severity = "warning"
value = 70
},
{
assertion_name = "Saturation"
resource_type = "container"
container_name = "backend-api"
source = "metrics"
severity = "critical"
value = 85
}
]
health_thresholds = [
{
assertion_name = "ServiceDown"
expression = "up < 1"
entity_type = "Service"
},
{
assertion_name = "NodeDown"
expression = "up{job=\"node-exporter\"} < 1"
entity_type = "Service"
}
]
}
```
## Resource reference
### `grafana_asserts_thresholds`
Manage Knowledge Graph threshold configurations through the Grafana API. This resource allows you to define custom thresholds for request, resource, and health assertions.
#### Arguments
| Name | Type | Required | Description |
| --------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `request_thresholds` | `list(object)` | No | List of request threshold configurations. Refer to [request thresholds block](#request-thresholds-block) for details. |
| `resource_thresholds` | `list(object)` | No | List of resource threshold configurations. Refer to [resource thresholds block](#resource-thresholds-block) for details. |
| `health_thresholds` | `list(object)` | No | List of health threshold configurations. Refer to [health thresholds block](#health-thresholds-block) for details. |
#### Request thresholds block
Each `request_thresholds` block supports the following:
| Name | Type | Required | Description |
| ----------------- | -------- | -------- | ------------------------------------------------------ |
| `entity_name` | `string` | Yes | The name of the entity to apply the threshold to. |
| `assertion_name` | `string` | Yes | The name of the assertion to configure. |
| `request_type` | `string` | Yes | The type of request (inbound, outbound). |
| `request_context` | `string` | Yes | The request context or path to apply the threshold to. |
| `value` | `number` | Yes | The threshold value. |
#### Resource thresholds block
Each `resource_thresholds` block supports the following:
| Name | Type | Required | Description |
| ---------------- | -------- | -------- | ---------------------------------------------------- |
| `assertion_name` | `string` | Yes | The name of the assertion to configure. |
| `resource_type` | `string` | Yes | The type of resource (container, Pod, node). |
| `container_name` | `string` | Yes | The name of the container to apply the threshold to. |
| `source` | `string` | Yes | The source of the metrics (metrics, logs). |
| `severity` | `string` | Yes | The severity level (warning, critical). |
| `value` | `number` | Yes | The threshold value. |
#### Health thresholds block
Each `health_thresholds` block supports the following:
| Name | Type | Required | Description |
| ---------------- | -------- | -------- | ------------------------------------------------------------------------------------ |
| `assertion_name` | `string` | Yes | The name of the assertion to configure. |
| `expression` | `string` | Yes | The Prometheus expression for the health check. |
| `entity_type` | `string` | Yes | Entity type for the health threshold (for example, Service, Pod, Namespace, Volume). |
| `alert_category` | `string` | No | Optional alert category label for the health threshold. |
#### Example
```terraform
resource "grafana_asserts_thresholds" "example" {
provider = grafana.asserts
request_thresholds = [{
entity_name = "api-service"
assertion_name = "ErrorRatioBreach"
request_type = "inbound"
request_context = "/api/v1/users"
value = 0.02
}]
resource_thresholds = [{
assertion_name = "Saturation"
resource_type = "container"
container_name = "web-server"
source = "metrics"
severity = "warning"
value = 75
}]
health_thresholds = [{
assertion_name = "ServiceDown"
expression = "up{job=\"api-service\"} < 1"
entity_type = "Service"
}]
}
```
## Best practices
### Threshold configuration management
- Set appropriate threshold values based on your service level objectives (SLOs)
- Use different severity levels (warning, critical) to create escalation paths
- Test threshold configurations in non-production environments first
- Monitor threshold effectiveness and adjust values based on actual performance data
### Request threshold best practices
- Configure request thresholds for critical user-facing endpoints
- Set different thresholds for different request types (inbound vs outbound)
- Consider request context when setting thresholds for specific API paths
- Use error ratio thresholds to catch service degradation early
- Review historical performance data to set realistic threshold values
### Resource threshold best practices
- Set resource thresholds based on your infrastructure capacity
- Use container-specific thresholds for microservices architectures
- Configure both warning and critical thresholds for gradual escalation
- Monitor resource utilization patterns to set realistic threshold values
- Consider seasonal or periodic patterns in resource usage
### Health threshold best practices
- Use Prometheus expressions that accurately reflect service health
- Test health check expressions independently before applying them
- Set up health thresholds for critical dependencies and external services
- Use composite expressions for complex health checks
- Ensure expressions perform efficiently without causing excessive load
### Value selection guidelines
- Start conservative and adjust based on real-world performance
- Use percentages (0-1 range) for ratio-based metrics
- Use milliseconds for latency thresholds
- Document the reasoning behind specific threshold values
- Review and update thresholds regularly based on system evolution
## Validation
After applying the Terraform configuration, verify that:
- Threshold configurations are applied in your Knowledge Graph instance
- Configurations appear in the Knowledge Graph UI under **Observability > Rules > Threshold**
- Request thresholds correctly identify breaches for specified services
- Resource thresholds trigger at appropriate severity levels
- Health thresholds accurately reflect service status
- Threshold values align with your SLO commitments
## Related documentation
- [Manage thresholds in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/manage-thresholds/)
- [Get started with Terraform for Knowledge Graph](../getting-started/)
- [Configure alerts in Knowledge Graph](/docs/grafana-cloud/knowledge-graph/configure/alerts/)
docs/sources/as-code/infrastructure-as-code/terraform/terraform-oncall.md
+357
View File
@@ -0,0 +1,357 @@
---
description: Learn how to create Grafana IRM integrations, escalation policies, and on-call schedules in Grafana Cloud using Terraform
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
- Grafana Cloud IRM
- OnCall
title: Manage Grafana IRM in Grafana Cloud using Terraform
weight: 120
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-oncall/
---
# Manage Grafana IRM in Grafana Cloud using Terraform
Learn how to use Terraform to manage [Grafana IRM](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/) resources.
This guide shows you how to connect an integration, configure escalation policies, and add on-call schedules using Terraform.
To illustrate the use of IRM across multiple teams, this guide features examples with two teams: `Devs` and `SREs`.
Additionally, it includes the necessary steps to configure Slack for IRM.
{{< admonition type="note" >}}
Grafana IRM supports Terraform-based configuration for a limited set of resources, primarily those related to OnCall functionality.
These resources use the `grafana_oncall_` naming convention in Terraform. Additional IRM components are not yet configurable via Terraform.
{{< /admonition >}}
## Before you begin
Before you begin, you should have the following:
- A Grafana Cloud account, as shown in [Get started](https://grafana.com/docs/grafana-cloud/get-started/)
- [Terraform](https://www.terraform.io/downloads) installed on your machine
- Administrator permissions in your Grafana instance
- (Optional) Administrator permissions in your Slack workspace, if you plan to integrate Slack with Grafana IRM
{{< admonition type="note" >}}
All of the following Terraform configuration files should be saved in the same directory.
{{< /admonition >}}
## Connect Slack to Grafana IRM
Before including Slack settings in your Terraform setup, you must first configure the Slack integration with Grafana IRM.
To connect your Slack workspace to Grafana IRM, refer to the [Slack integration for Grafana IRM](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/configure/integrations/irm-slack/) documentation.
## Configure the Grafana provider
This Terraform configuration sets up the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide necessary authentication when managing resources for Grafana IRM.
You can reuse a similar setup to the one described in [Creating and managing a Grafana Cloud stack using Terraform](../terraform-cloud-stack/) to set up a service account and a token.
1. Create a Service account and token in Grafana. To create a new one, refer to [Service account tokens](https://grafana.com/docs/grafana/latest/administration/service-accounts/#service-account-tokens).
1. Create a file named `main.tf` and add the following:
```terraform
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
version = ">= 3.15.3"
}
}
}
provider "grafana" {
alias = "oncall"
url = "<Stack-URL>"
auth = "<Service-account-token>"
oncall_url = "<OnCall-URL>"
}
```
1. Replace the following field values:
- `<Stack-URL>` with the URL of your Grafana stack
- `<Service-account-token>` with the service account token that you created
- `<OnCall-URL>` with the API URL found on the **Admin & API** tab of the IRM **Settings** page
{{< admonition type="note" >}}
If the service account has the right permissions, this provider setup also allows you to manage other Grafana resources.
{{< /admonition >}}
### Authentication via OnCall API tokens (deprecated)
OnCall API tokens are being deprecated.
While existing tokens will continue to work, we recommend using
[Grafana Cloud service account tokens](https://grafana.com/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/service-accounts/) for all new API authentication.
{{< collapse title="Authentication via OnCall API tokens" >}}
To use an existing OnCall API token:
1. Log into your Grafana Cloud instance
1. Select **Alerts & IRM** > **IRM**
1. Click **Settings**, and then select **Admin & API**
1. Locate the **Grafana IRM API** section
1. View, copy or revoke existing **OnCall API tokens**
1. Create a file named `main.tf` and add the following:
```terraform
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
version = ">= 2.9.0"
}
}
}
provider "grafana" {
alias = "oncall"
oncall_access_token = "<OnCall-API-Token>"
oncall_url = "<OnCall-URL>"
}
```
1. Replace the following field values:
- `<OnCall-API-Token>` with your existing OnCall API Token
- `<OnCall-URL>` with the API URL found on the **Admin & API** tab of the IRM **Settings** page
{{< /collapse >}}
## Add on-call schedules
This Terraform configuration sets up two on-call schedules, `SREs` and `Devs`, using the [`grafana_oncall_schedule` resource](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_schedule) to define the schedules within Grafana IRM.
Additionally, this configuration includes Slack channels to receive notifications for the on-call schedules of each team.
To learn more about managing on-call schedules, refer to the [On-call schedules documentation](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/manage/on-call-schedules/).
1. Create two new calendars in your calendar service, one for `Devs` and one for `SREs`
1. Locate and save the secret iCal URLs.
For example, in a Google calendar, these URLs can be found in **Settings > Settings for my calendars > Integrate calendar**
1. Create a file named `schedule.tf` and add the following:
```terraform
# Name of the Slack channel to notify about on-call schedules for Devs
data "grafana_oncall_slack_channel" "Devs" {
provider = grafana.oncall
name = "<Devs-channel-name>"
}
# Name of the Slack channel to notify about on-call schedules for SREs
data "grafana_oncall_slack_channel" "SREs" {
provider = grafana.oncall
name = "<SREs-channel-name>"
}
resource "grafana_oncall_schedule" "schedule_Devs" {
provider = grafana.oncall
name = "Devs"
type = "ical"
ical_url_primary = "<secret-iCal-URL-for-devs-calendar>"
slack {
channel_id = data.grafana_oncall_slack_channel.Devs.slack_id
}
}
resource "grafana_oncall_schedule" "schedule_SREs" {
provider = grafana.oncall
name = "SREs"
type = "ical"
ical_url_primary = "<secret-iCal-URL-for-SREs-calendar>"
slack {
channel_id = data.grafana_oncall_slack_channel.SREs.slack_id
}
}
```
1. Replace the following field values:
- `<Devs-channel-name>` with name of the Slack channel to notify about on-call schedules for `Devs`
- `<SREs-channel-name>` with name of the Slack channel to notify about on-call schedules for `SREs`
- `<secret-iCal-URL-for-devs-calendar>` with the secret iCal URL created in the first step for `Devs` Calendar
- `<secret-iCal-URL-for-SREs-calendar>` with the secret iCal URL created in the first step for `SREs` Calendar
## Add escalation chains
This Terraform configuration creates two escalation chains named `SREs` and `Devs` in Grafana IRM using the [`grafana_oncall_escalation_chain` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_escalation_chain).
The configuration also adds the following three steps to each escalation chain using the [`grafana_oncall_escalation` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_escalation):
- Notify users from on-call schedule
- Wait for 5 minutes
- Notify default Slack channel
1. Create a file named `escalation-devs.tf` and add the following:
```terraform
resource "grafana_oncall_escalation_chain" "Devs" {
provider = grafana.oncall
name = "Devs"
}
// Notify users from on-call schedule
resource "grafana_oncall_escalation" "notify_schedule_step_Devs" {
provider = grafana.oncall
escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
type = "notify_on_call_from_schedule"
notify_on_call_from_schedule = grafana_oncall_schedule.schedule_Devs.id
position = 0
}
// Wait step for 5 Minutes
resource "grafana_oncall_escalation" "wait_step_Devs" {
provider = grafana.oncall
escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
type = "wait"
duration = 300
position = 1
}
// Notify default Slack channel step
resource "grafana_oncall_escalation" "notify_step_Devs" {
provider = grafana.oncall
escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
type = "notify_whole_channel"
important = true
position = 2
}
```
2. Create a file named `escalation-sre.tf` and add the following:
```terraform
resource "grafana_oncall_escalation_chain" "SREs" {
provider = grafana.oncall
name = "SREs"
}
// Notify users from on-call schedule
resource "grafana_oncall_escalation" "notify_schedule_step_SREs" {
provider = grafana.oncall
escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
type = "notify_on_call_from_schedule"
notify_on_call_from_schedule = grafana_oncall_schedule.schedule_SREs.id
position = 0
}
// Wait step for 5 Minutes
resource "grafana_oncall_escalation" "wait_step_SREs" {
provider = grafana.oncall
escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
type = "wait"
duration = 300
position = 1
}
// Notify default Slack channel step
resource "grafana_oncall_escalation" "notify_step_SREs" {
provider = grafana.oncall
escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
type = "notify_whole_channel"
important = true
position = 2
}
```
## Connect an integration to Grafana IRM
This Terraform configuration connects Alertmanager to Grafana IRM using the [`grafana_oncall_integration` (Resource)](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/oncall_integration).
It also adds the `Devs` escalation chain as the default route for alerts.
1. Create a file named `integrations.tf` and add the following:
```terraform
resource "grafana_oncall_integration" "AlertManager" {
provider = grafana.oncall
name = "AlertManager"
type = "alertmanager"
default_route {
escalation_chain_id = grafana_oncall_escalation_chain.Devs.id
}
}
```
1. To configure Alertmanager, refer to [Alertmanager integration for Grafana OnCall](https://grafana.com/docs/grafana-cloud/alerting-and-irm/oncall/integrations/alertmanager/)
## Set up a route to configure escalation behavior for alert group notifications
This Terraform configuration sets up a route to the Alertmanager integration using the `grafana_oncall_route` (Resource).
This route ensures that notifications for alerts with `\"namespace\" *: *\"ops-.*\"` in the payload are escalated to the `SREs` escalation chain.
Create a file named `routes.tf` and add the following:
```terraform
resource "grafana_oncall_route" "route_SREs" {
provider = grafana.oncall
integration_id = grafana_oncall_integration.AlertManager.id
escalation_chain_id = grafana_oncall_escalation_chain.SREs.id
routing_regex = "\"namespace\" *: *\"ops-.*\""
position = 0
}
```
## Apply the Terraform configuration
In a terminal, run the following commands from the directory where all of the configuration files are located.
1. Initialize a working directory containing Terraform configuration files.
```shell
terraform init
```
1. Preview the changes that Terraform will make.
```shell
terraform plan
```
1. Apply the configuration files.
```shell
terraform apply
```
## Validation
After you apply the changes in the Terraform configurations, you can verify the following:
- Two new Schedules named `Devs` and `SREs` are created in Grafana IRM:
![`Devs` and `SREs` OnCall schedules](/media/docs/grafana-cloud/alerting-and-irm/screenshot-oncall-schedules-tf.png)
- New Escalation chain named `SREs` is created in Grafana IRM:
![`SREs` escalation chain](/media/docs/grafana-cloud/alerting-and-irm/screenshot-oncall-escalation-sre-tf.png)
- New Escalation chain named `Devs` is created in Grafana IRM:
![`Devs` escalation chain](/media/docs/grafana-cloud/alerting-and-irm/screenshot-oncall-escalation-devs-tf.png)
- The Alertmanager integration is added and configured with escalation policies:
![Alertmanager integration for SREs escalation](/media/docs/grafana-cloud/alerting-and-irm/screenshot-oncall-alertmanager-tf.png)
## Conclusion
In this guide, you learned how to use Terraform to manage Grafana IRM by connecting an integration, configuring escalation policies, and setting up on-call schedules.
To learn more about managing Grafana Cloud using Terraform, refer to [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs).
docs/sources/as-code/infrastructure-as-code/terraform/terraform-plugins.md
+81
View File
@@ -0,0 +1,81 @@
---
description: Learn how to install plugins in Grafana Cloud using Terraform
keywords:
- Infrastructure as Code
- Quickstart
- Grafana Cloud
- Terraform
- Plugins
title: Install plugins in Grafana Cloud using Terraform
weight: 300
canonical: https://grafana.com/docs/grafana/latest/as-code/infrastructure-as-code/terraform/terraform-plugins/
---
# Install plugins in Grafana Cloud using Terraform
This guide shows you how to install plugins in Grafana Cloud using Terraform. For more information about Grafana plugins see [Find and use Grafana plugins](/docs/grafana-cloud/introduction/find-and-use-plugins/).
## Before you begin
Before you begin, you should have the following available:
- A Grafana Cloud account; for more information on setting up a Grafana Cloud account, refer to [Get started](https://grafana.com/docs/grafana-cloud/get-started/).
- Terraform installed on your machine; for more information on how to install Terraform, refer to the [Terraform install documentation](https://developer.hashicorp.com/terraform/install).
- Administrator permissions in your Grafana instance; for more information on assigning Grafana RBAC roles, refer to [Assign RBAC roles](/docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/assign-rbac-roles/).
{{< admonition type="note" >}}
All of the following Terraform configuration files should be saved in the same directory.
{{< /admonition >}}
## Configure the Grafana provider
Use this Terraform configuration to set up the [Grafana provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs) to provide the authentication required to manage plugin resources.
1. Create a service account and token in Grafana. For more information on creating a service account and token, refer to [Service account tokens](https://grafana.com/docs/grafana/latest/administration/service-accounts/#service-account-tokens). You can also refer to [Creating and managing a Grafana Cloud stack using Terraform](../terraform-cloud-stack/) to set up a service account and a token.
1. Make sure that the token has the following permissions:
- `stack-plugins:read`
- `stack-plugins:write`
- `stack-plugins:delete`
Next, create a file named `main.tf` and add the following:
```terraform
terraform {
required_providers {
grafana = {
source = "grafana/grafana"
version = ">= 4.5.3"
}
}
}
provider "grafana" {
cloud_api_url = "<Stack-URL>"
cloud_access_policy_token = "<Service-account-token>"
}
```
Replace the following field values:
- `Stack-URL` with the URL of your Grafana stack, for example `https://my-stack.grafana.net/`
- `Service-account-token` with the service account token that you created
## Create new plugin resource
Create a file named `plugins.tf` and add the following:
```terraform
resource "grafana_cloud_plugin_installation" "grafana-clock-panel" {
stack_slug = "<Your-Stack-Slug>"
slug = "grafana-clock-panel"
version = "latest"
}
```
## Conclusion
In this guide, you learned how to install a plugin in Grafana Cloud using Terraform.
To learn more about plugin installation, refer to [Grafana provider's documentation](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/cloud_plugin_installation).
docs/sources/as-code/observability-as-code/_index.md
+116
View File
@@ -0,0 +1,116 @@
---
description: Overview of Observability as Code including description, key features, and explanation of benefits.
keywords:
- observability
- configuration
- as code
- dashboards
- git integration
- git sync
- github
labels:
products:
- enterprise
- oss
- cloud
title: Observability as Code
weight: 100
cards:
items:
- title: Get started
height: 24
href: ./get-started/
description: Learn about how you can use Observability as Code.
- title: Grafana CLI
height: 24
href: ./grafana-cli/
description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances. You can authenticate, manage multiple environments, and perform administrative tasks through Grafana’s REST API, all from the terminal.
- title: JSON schema v2
height: 24
href: ./schema-v2/
description: Grafana dashboards are represented as JSON objects that store metadata, panels, variables, and settings. Observability as Code works with all versions of the JSON model, and it's fully compatible with version 2.
- title: Foundation SDK
height: 24
href: ./foundation-sdk/
description: The Grafana Foundation SDK is a set of tools, types, and libraries that let you define Grafana dashboards and resources using strongly typed code.
- title: Git Sync (private preview)
height: 24
href: ./provision-resources/intro-git-sync/
description: Git Sync is an experimental feature that lets you store your dashboard files in a GitHub repository and synchronize those changes with your Grafana instance.
- title: File provisioning (private preview)
height: 24
href: ./provision-resources/
description: File provisioning in Grafana lets you include resources, including folders and dashboard JSON files, that are stored in a local file system.
title_class: pt-0 lh-1
hero:
title: Observability as Code
description: Using Observability as Code, you can version, automate, and scale Grafana configurations, including dashboards and observability workflows.
height: 110
level: 1
width: 110
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/
aliases:
- ../observability-as-code/ # /docs/grafana/next/observability-as-code/
---
{{< docs/hero-simple key="hero" >}}
---
## Overview
Observability as Code lets you apply code management best practices to your observability resources.
By representing Grafana resources as code, you can integrate them into existing infrastructure-as-code workflows and apply standard development practices.
Observability as Code provides more control over configuration. Instead of manually configuring dashboards or settings through the Grafana UI, you can:
- Write configurations in code: Define dashboards in JSON or other supported formats.
- Sync your Grafana setup to GitHub: Track changes, collaborate, and roll back updates using Git and GitHub, or other remote sources.
- Automate with CI/CD: Integrate Grafana directly into your development and deployment pipelines.
- Standardize workflows: Ensure consistency across your teams by using repeatable, codified processes for managing Grafana resources.
## Explore
{{< card-grid key="cards" type="simple" >}}
<!-- Hiding this part of the doc because the rest of the docs aren't released yet
## Key features
At this time, Observability as Code lets you configure dashboards in static files rather than using the UI.
The number of resources covered by this approach will expand over time.
### App Platform: A unified foundation
The [App Platform](https://github.com/grafana/grafana-app-sdk) is the backbone of Observability as Code. It provides consistent APIs for managing Grafana resources like dashboards, data sources, and service-level objectives (SLOs). With the App Platform, you gain:
- A stable and predictable API for integrating Grafana into your systems.
- Support for cloud-native workflows, making it easier to build and scale observability solutions.
- The ability to manage Grafana resources programmatically.
- Backwards compatibility with earlier versions of Grafana APIs, so older applications still work.
### Git integration
Version control is at the heart of Observability as Code. By integrating Grafana with Git, you can:
- Store your dashboards in a Git repository.
- Automatically deploy changes through CI/CD pipelines.
- Track who made changes, when they were made, and why.
### Enhanced dashboard management
Dashboards are central to Grafana’s value, and Observability as Code introduces improvements to make them easier to work with:
- **Ready for Schema v2:** An experimental dashboard schema that simplifies dashboards definition, separating properties for better clarity and making configurations more intuitive.
- **New layout options:** Flexible layouts, including a new responsive grid layout that allow for more dynamic and responsive panel layouts.
- **Improved metadata management:** Add descriptions, tags, and other metadata to better organize and understand your dashboards.
### Tooling and integrations
Observability as Code comes with tools to make your workflows seamless:
- Examples and best practices for integrating Grafana with tools like Terraform, Kubernetes, and GitHub Actions.
- The Foundation SDK provides a set of libraries for getting started quickly configuring and manipulating Grafana resources.
- A command line tool for configuring your dashboards programmatically.
- Documentation, videos, and SDKs to help you get started quickly.
-->
docs/sources/as-code/observability-as-code/foundation-sdk/_index.md
+306
View File
@@ -0,0 +1,306 @@
---
description: Learn about the Foundation SDK, a set of tools, types, and libraries for defining Grafana dashboards and resources.
keywords:
- as code
- as-code
- Foundation SDK
labels:
products:
- enterprise
- oss
title: Foundation SDK
weight: 250
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/
aliases:
- ../../observability-as-code/foundation-sdk/ # /docs/grafana/next/observability-as-code/foundation-sdk/
---
# Get started with the Grafana Foundation SDK
The [Grafana Foundation SDK](https://github.com/grafana/grafana-foundation-sdk) is a set of tools, types, and libraries that let you define Grafana dashboards and resources using strongly typed code. By writing your dashboards as code, you can:
- **Leverage strong typing:** Catch errors at compile time, ensuring more reliable configurations.
- **Enhance version control:** Track changes seamlessly using standard version control systems like Git.
- **Automate deployments:** Integrate dashboard provisioning into your CI/CD pipelines for consistent and repeatable setups.
The SDK supports multiple programming languages, including Go, TypeScript, Python, PHP, and Java, so you can choose the one that best fits your development environment.
{{< youtube id="_OKQoABmg0Q" >}}
## Before you begin
Ensure you have the following prerequisites:
- **Programming environment:** Set up for your chosen language. For example: Go, Node.js for TypeScript, or Python 3.x for Python.
- **Grafana instance:** A running Grafana instance compatible with the SDK version you’re using (refer to the [compatibility matrix](https://github.com/grafana/grafana-foundation-sdk#navigating-the-sdk)).
- **Package manager:** Appropriate for your language, for example, `npm` or `yarn` for TypeScript or `pip` for Python.
To get started, clone the [intro-to-foundation-sdk repository](https://github.com/grafana/intro-to-foundation-sdk) to access examples and a `docker-compose` stack.
## Install the Grafana Foundation SDK
Select the `go` or `typescript` tab to view instructions to install the SDK.
For other languages, refer to the Grafana Foundation SDK documentation for installation instructions.
{{< code >}}
```go
go get github.com/grafana/grafana-foundation-sdk/go@next+cog-v0.0.x
```
```typescript
npm install @grafana/grafana-foundation-sdk
```
{{< /code >}}
## Grafana Foundation SDK Overview
Here's a quick overview of how the Grafana Foundation SDK works:
- **Builder pattern:** The SDK uses a chainable builder pattern to let you define dashboards fluently. You start with a `DashboardBuilder`, then add panels, queries, and other components step by step.
- **Strong typing:** Everything in the SDK is strongly typed. This gives you autocompletion in your IDE, catches mistakes early, and helps ensure you're always using valid configuration values.
- **Structured options:** When a configuration get complex (like data reduction or display settings), the SDK uses typed option builders to keep things readable and predictable.
You'll see these concepts in action in the next example. These concepts are explained in more detail afterwards.
## Create a dashboard
The following example demonstrates how you can create a simple dashboard:
{{< code >}}
```go
package main
// Import the appropriate Grafana Foundation SDK packages
import (
"encoding/json"
"log"
"github.com/grafana/grafana-foundation-sdk/go/cog"
"github.com/grafana/grafana-foundation-sdk/go/common"
"github.com/grafana/grafana-foundation-sdk/go/dashboard"
"github.com/grafana/grafana-foundation-sdk/go/stat"
"github.com/grafana/grafana-foundation-sdk/go/testdata"
"github.com/grafana/grafana-foundation-sdk/go/timeseries"
)
func main() {
// Define a data source reference for our testdata data source
testdataRef := dashboard.DataSourceRef{
Type: cog.ToPtr("grafana-testdata-datasource"),
Uid: cog.ToPtr("testdata"),
}
// Define our dashboard as strongly typed code
builder := dashboard.NewDashboardBuilder("My Dashboard").
WithPanel(
stat.NewPanelBuilder().
Title("Version").
Datasource(testdataRef).
ReduceOptions(common.NewReduceDataOptionsBuilder().
Calcs([]string{"lastNotNull"}).
Fields("/.*/")).
WithTarget(
testdata.NewDataqueryBuilder().
ScenarioId("csv_content").
CsvContent("version\nv1.2.3"),
),
).
WithPanel(
timeseries.NewPanelBuilder().
Title("Random Time Series").
Datasource(testdataRef).
WithTarget(
testdata.NewDataqueryBuilder().
ScenarioId("random_walk"),
),
)
// Build the dashboard - errors in configuration will be thrown here
dashboard, err := builder.Build()
if err != nil {
log.Fatalf("failed to build dashboard: %v", err)
}
// Output the generated dashboard as JSON
dashboardJson, err := json.MarshalIndent(dashboard, "", " ")
if err != nil {
log.Fatalf("failed to marshal dashboard: %v", err)
}
log.Printf("Dashboard JSON:\n%s", dashboardJson)
}
```
```typescript
// Import the appropriate Grafana Foundation SDK packages
import * as common from '@grafana/grafana-foundation-sdk/common';
import * as dashboard from '@grafana/grafana-foundation-sdk/dashboard';
import * as stat from '@grafana/grafana-foundation-sdk/stat';
import * as testdata from '@grafana/grafana-foundation-sdk/testdata';
import * as timeseries from '@grafana/grafana-foundation-sdk/timeseries';
// Define a data source reference for our testdata data source
const testDataRef: dashboard.DataSourceRef = {
type: 'grafana-testdata-datasource',
uid: 'testdata',
};
// Define our dashboard as strongly typed code
const builder = new dashboard.DashboardBuilder('My Dashboard')
.withPanel(
new stat.PanelBuilder()
.title('Version')
.reduceOptions(new common.ReduceDataOptionsBuilder().calcs(['lastNotNull']).fields('/.*/'))
.datasource(testdataRef)
.withTarget(new testdata.DataqueryBuilder().scenarioId('csv_content').csvContent('version\nv1.2.3'))
)
.withPanel(
new timeseries.PanelBuilder()
.title('Random Time Series')
.datasource(testdataRef)
.withTarget(new testdata.DataqueryBuilder().scenarioId('random_walk'))
);
// Build the dashboard - errors in configuration will be thrown here
const dashboard = builder.build();
// Output the generated dashboard as JSON
console.log(JSON.stringify(dashboard, null, 2));
```
{{< /code >}}
This code defines a dashboard titled “My Dashboard” with a two panels:
- a simple stat panel displaying a version number, and
- a time series panel displaying randomized data from the `testdata` data source `random_walk` scenario.
## Export and use the JSON
After you've defined your dashboard as code, build the final dashboard representation using the dashboard builder (typically using the `build()` function depending on language choice) and output the result as a JSON.
With the JSON payload, you can:
- **Manually import:** Paste into Grafana’s dashboard import feature.
- **Automate:** Use [Grafana's API](/docs/grafana/<GRAFANA_VERSION>/developer-resources/api-reference/http-api/) or the [Grafana CLI](../grafana-cli/) to programmatically upload the dashboard JSON.
## Concepts
Now that you've seen how to define a basic dashboard using code, let's take a moment to explain how it all works behind the scenes. The Grafana Foundation SDK is built around a few core concepts that make your dashboards structured, reusable, and strongly typed.
### Builders
The SDK follows a builder pattern, which lets you compose dashboards step-by-step using chained method calls.
Almost every piece of the dashboard, including dashboards, panels, rows, queries, and variables, has its own `Builder` class.
Here are a few you've already seen:
- `DashboardBuilder` - Starts the dashboard definition and sets global configuration settings like title, UID, refresh interval, time range, etc.
- `PanelBuilder` - Creates individual visualizations like time series panels, stat panels, or log panels.
- `DataqueryBuilder` - Defines how a panel fetches data, for example, from Prometheus or the `testdata` plugin.
Builders are chainable, so you can fluently compose dashboards in a readable, structured way:
{{< code >}}
```go
stat.NewPanelBuilder().
Title("Version").
Datasource(testdataRef).
ReduceOptions(common.NewReduceDataOptionsBuilder().
Calcs([]string{"lastNotNull"}).
Fields("/.*/")).
WithTarget(
testdata.NewDataqueryBuilder().
ScenarioId("csv_content").
CsvContent("version\nv1.2.3"),
)
```
```typescript
new stat.PanelBuilder()
.title('Version')
.reduceOptions(new common.ReduceDataOptionsBuilder().calcs(['lastNotNull']).fields('/.*/'))
.datasource(testdataRef)
.withTarget(new testdata.DataqueryBuilder().scenarioId('csv_content').csvContent('version\nv1.2.3'));
```
{{< /code >}}
### Types
The Grafana Foundation SDK uses strong types under the hood to help catch mistakes before you deploy a broken dashboard.
For example:
- When setting a unit, you'll get autocomplete suggestions for valid Grafana units like `"percent"` or `"bps"`.
- When defining a time range, you'll be guided to provide the correct structure, like `from` and `to` values.
- When referencing data sources, you'll use a structured `DataSourceRef` object with defined `type` and `uid` fields.
This helps you:
- Avoid typos or unsupported configuration values
- Get full autocomplete and inline documentation in your IDE
- Write dashboards that are less error-prone and easier to maintain
Strong typing also makes it easier to build reusable patterns and components with confidence, especially in large codebases or teams.
### Options
Most builder methods accept simple values like strings or numbers, but others expect more structured option objects. These are used for things like:
- `ReduceDataOptions` - How to reduce time series data into single values (e.g. last, avg).
- `VizLegendOptions` - Configure how the legend of a panel is displayed.
- `CanvasElementOptions` - Define how the the various components of a Canvas panel should be displayed.
Example using options:
{{< code >}}
```go
stat.NewPanelBuilder().
ReduceOptions(common.NewReduceDataOptionsBuilder().
Calcs([]string{"lastNotNull"}).
Fields("/.*/"))
)
```
```typescript
new stat.PanelBuilder().reduceOptions(new common.ReduceDataOptionsBuilder().calcs(['lastNotNull']).fields('/.*/'));
```
{{< /code >}}
By using option builders, you don't need to manually construct deeply nested configuration objects. Instead, the SDK gives you a typed and guided API that mirrors a dashboards internal structure, making it easier to configure complex options without guesswork or referring back to the JSON schema.
## Explore a real-world example
If you want to explore further and see a more real-world example of using the Grafana Foundation SDK, watch the following walkthrough:
{{< youtube id="ZjWdGVsrCiQ" >}}
In this video, we generate a dashboard from code and deploy it using the Grafana API, covering patterns and practices you'd use in production environments. It also includes a working example of a web service that emits metrics and logs, and shows how to deploy a dashboard alongside it using Docker Compose.
You can find the full source code for this example in the [intro-to-foundation-sdk repository](https://github.com/grafana/intro-to-foundation-sdk/tree/main/generate-and-deploy-example).
## Summary
The Grafana Foundation SDK is designed to make dashboard creation:
- **Composable** through the use of chainable builders
- **Safe** with strong typing and clear APIs
- **Configurable** using structured options for fine control
As you build more advanced dashboards, you’ll work with additional builders and types to support richer functionality.
The SDK supports not just panels and queries, but also variables, thresholds, field overrides, transformations, and more.
Refer to [the full API reference](https://grafana.github.io/grafana-foundation-sdk/) to explore what's possible.
## Next steps
Now that you understand the basics of using the Grafana Foundation SDK, here are some next steps:
- **Explore more features:** Check out the [full API reference](https://grafana.github.io/grafana-foundation-sdk/) to learn about advanced dashboard configurations.
- **Version control your dashboards:** Store your dashboard code in a Git repository to track changes over time.
- **Automate dashboard provisioning with CI/CD:** [Integrate the SDK into your CI/CD pipeline](./dashboard-automation) to deploy dashboards automatically.
docs/sources/as-code/observability-as-code/foundation-sdk/dashboard-automation.md
+260
View File
@@ -0,0 +1,260 @@
---
description: Learn how to automatically generate and deploy Grafana dashboards as code with GitHub Actions.
keywords:
- foundation SDK
- dashboard provisioning
- CI/CD
- GitHub Actions
labels:
products:
- cloud
- enterprise
- oss
title: Automate dashboard provisioning with CI/CD
weight: 200
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/foundation-sdk/dashboard-automation/
aliases:
- ../../../observability-as-code/foundation-sdk/dashboard-automation/ # /docs/grafana/next/observability-as-code/foundation-sdk/dashboard-automation/
---
# Automate dashboard provisioning with CI/CD
## Introduction
Managing Grafana dashboards manually can be inefficient and error-prone. As you saw in the Getting Started guide, we can define dashboards using strongly typed code with the Grafana Foundation SDK. We can then commit them to version controls, and automatically deploy them using GitHub Actions.
This guide walks through:
- Generating a Grafana dashboard as code
- Formatting it for Kubernetes-style deployment
- Using GitHub Actions to deploy the dashboard
- Checking if the dashboard exists and updating it if needed
By the end, every change to your dashboard code will be automatically created or updated in your Grafana instance without manual intervention.
{{< youtube id="cFnO8kVOaAI" >}}
You can find the full example source code in the [intro-to-foundation-sdk repository](https://github.com/grafana/intro-to-foundation-sdk/tree/main/github-actions-example).
## 1. Generating the dashboard JSON
Before deploying a dashboard, we need to define it in code using the Grafana Foundation SDK. We ran through an example of this in the Getting Started guide, however, in order to comply with the Kubernetes resource compatible API that Grafana exposes, we’ll make some changes to the code to output the dashboard JSON in the appropriate format.
{{< code >}}
```go
package main
import (
"encoding/json"
"log"
"os"
"github.com/grafana/grafana-foundation-sdk/go/cog"
"github.com/grafana/grafana-foundation-sdk/go/common"
"github.com/grafana/grafana-foundation-sdk/go/dashboard"
)
type DashboardWrapper struct {
APIVersion string `json:"apiVersion"`
Kind string `json:"kind"`
Metadata Metadata `json:"metadata"`
Spec dashboard.Dashboard `json:"spec"`
}
type Metadata struct {
Name string `json:"name"`
}
func main() {
builder := dashboard.NewDashboardBuilder("My Dashboard").
Uid("my-dashboard").
Tags([]string{"generated", "foundation-sdk", "go"}).
Refresh("5m").
Time("now-1h", "now").
Timezone(common.TimeZoneBrowser).
WithRow(dashboard.NewRowBuilder("Overview"))
dashboard, err := builder.Build()
if err != nil {
log.Fatalf("failed to build dashboard: %v", err)
}
dashboardWrapper := DashboardWrapper{
APIVersion: "dashboard.grafana.app/v1beta1",
Kind: "Dashboard",
Metadata: Metadata{
Name: *dashboard.Uid,
},
Spec: dashboard,
}
dashboardJson, err := json.MarshalIndent(dashboardWrapper, "", " ")
if err != nil {
log.Fatalf("failed to marshal dashboard: %v", err)
}
err = os.WriteFile("dashboard.json", dashboardJson, 0644)
if err != nil {
log.Fatalf("failed to write dashboard to file: %v", err)
}
log.Printf("Dashboard JSON:\n%s", dashboardJson)
}
```
```typescript
import { DashboardBuilder, RowBuilder } from '@grafana/grafana-foundation-sdk/dashboard';
import * as fs from 'fs';
// Generate the dashboard JSON
const dashboard = new DashboardBuilder('My Dashboard')
.uid('my-dashboard')
.tags(['generated', 'foundation-sdk', 'typescript'])
.refresh('5m')
.time({ from: 'now-1h', to: 'now' })
.timezone('browser')
.withRow(new RowBuilder('Overview'))
.build();
// Convert to Kubernetes-style format
const dashboardWrapper = {
apiVersion: "dashboard.grafana.app/v1beta1",
kind: "Dashboard",
metadata: {
name: dashboard.uid!
},
spec: dashboard
};
// Save the formatted JSON to a file
const dashboardJSON = JSON.stringify(dashboardWrapper, null, 2);
fs.writeFileSync('dashboard.json', dashboardJSON, 'utf8');
console.log(`Dashboard JSON:\n${}`);
```
{{< /code >}}
This script:
- Generates a Grafana dashboard JSON file
- Wraps it in a Kubernetes-style API format (`apiVersion`, `kind`, `metadata`, `spec`)
- Saves it as `dashboard.json` for deployment
## 2. Automating deployment with GitHub Actions
Next, we’ll set up GitHub Actions to:
Extract the dashboard name from `dashboard.json`
Check if the dashboard already exists within our Grafana instance
Update it if it does, create it if it doesn’t
{{< admonition type="note" >}}
The following GitHub Action configuration assumes you are using a Go-based dashboard generator. If you are using one of the other languages that the Foundation SDK supports, please modify the **Generate Dashboard JSON** step accordingly.
{{< /admonition >}}
`.github/workflows/deploy-dashboard.yml`
```yaml
name: Deploy Grafana Dashboard
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version: 1.24.6
- name: Verify Go version
run: go version
- name: Download and Extract grafanactl
run: |
curl -L -o grafanactl-x86_64.tar.gz "https://github.com/grafana/grafanactl/releases/download/${{ vars.GRAFANACTL_VERSION }}/grafanactl_Linux_x86_64.tar.gz"
tar -xzf grafanactl-x86_64.tar.gz
chmod +x grafanactl
sudo mv grafanactl /usr/local/bin/grafanactl
- name: Generate Dashboard JSON
working-directory: ./github-actions-example
run: go run main.go
- name: Deploy Dashboard with grafanactl
env:
GRAFANA_SERVER: ${{ vars.GRAFANA_SERVER }}
GRAFANA_STACK_ID: ${{ vars.GRAFANA_STACK_ID }}
GRAFANA_TOKEN: ${{ secrets.GRAFANA_TOKEN }}
run: |
if [ -f dashboard.json ]; then
echo "dashboard.json exists, deploying dashboard."
grafanactl resources push dashboards --path ./dashboard.json
else
echo "dashboard.json does not exist."
exit 1
fi
working-directory: ./github-actions-example
```
## 3. Explaining this GitHub Action
This GitHub Action automates the deployment of a Grafana dashboard using the Foundation SDK and the `grafanactl` CLI tool.
### 1. Checkout and set up Go
The first few steps:
- Check out the repository to access the project code.
- Install Go 1.24.6 using the `actions/setup-go` action.
- Verify Go is properly installed.
### 2. Download and install `grafanactl`
This step downloads the `grafanactl` CLI from GitHub using a version defined in `vars.GRAFANACTL_VERSION`. It unpacks the tarball, makes it executable, and moves it to a location in the system `PATH`.
### 3. Generate the dashboard JSON
Runs the dashboard generator (`main.go`) from the `./github-actions-example` directory. This should produce a `dashboard.json` file that contains the Grafana dashboard definition.
### 4. Deploy the dashboard with `grafanactl`
If `dashboard.json` exists, it is deployed to your Grafana instance using:
```bash
grafanactl resources push dashboards --path ./dashboard.json
```
This command authenticates against Grafana using the following environment variables:
- `GRAFANA_SERVER`: Your Grafana instance URL
- `GRAFANA_STACK_ID`: Your Grafana stack ID
- `GRAFANA_TOKEN`: A Grafana service account token with sufficient permissions
### GitHub variables and secrets used
These are configured in your repository under **Settings → Security → Secrets and variables → Actions**:
- `vars.GRAFANACTL_VERSION`: Version of `grafanactl` to install
- `vars.GRAFANA_SERVER`: The URL of your Grafana instance
- `vars.GRAFANA_STACK_ID`: The stack ID in Grafana
- `secrets.GRAFANA_TOKEN`: Grafana API token
This action ensures that every push to `main` will regenerate and deploy your latest dashboard definition to Grafana.
### Why automate this?
Automating Grafana dashboard deployment eliminates the need for manual dashboard creation and updates, ensuring that dashboards remain consistent across environments. By defending dashboards as code and managing them through CI/CD such as GitHub Actions, we gain full version control, making it easy to track changes over time and roll back if needed. This also prevents duplication, as the workflow intelligently checks whether a dashboard exists before deciding to create or update it. With this fully automated CI/CD pipeline, developers can focus on improving their dashboards rather than manually uploading JSON files to Grafana.
### Conclusion
By integrating the Grafana Foundation SDK with GitHub Actions, we have successfully automated the entire lifecycle of Grafana dashboards. This setup allows us to define dashboards programmatically, convert them into a Kubernetes-compatible format, and deploy them automatically. With each push to the repository, the workflow ensures that dashboards are either created or updated as needed. This not only improves the efficiency but also guarantees that all deployed dashboards are always in sync with the latest code changes, reducing manual effort and potential errors.
docs/sources/as-code/observability-as-code/get-started.md
+88
View File
@@ -0,0 +1,88 @@
---
description: Get started with Observability as Code by exploring the documentation, libraries, and tools available for as-code practices.
keywords:
- configuration
- as code
- as-code
- dashboards
- Git Sync
- Git
labels:
products:
- enterprise
- oss
title: Get started with Observability as Code
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/get-started/
aliases:
- ../../observability-as-code/get-started/ # /docs/grafana/next/observability-as-code/get-started/
---
# Get started with Observability as Code
Grafana provides a suite of tools for **Observability as Code** to help you manage your Grafana resources programmatically and at scale. This approach lets you define dashboards, data sources, and other configurations in code, enabling version control, automated testing, and reliable deployments through CI/CD pipelines.
Historically, managing Grafana as code involved various community and Grafana Labs tools, but lacked a single, cohesive story. Grafana 12 introduces foundational improvements, including new versioned APIs and official tooling, to provide a clearer path forward.
## Grafana CLI (`grafanactl`)
Use the official command-line tool, `grafanactl`, to interact with your Grafana instances and manage resources via the new APIs.
- It's the recommended tool for automation and direct API interaction, suitable for CI/CD pipelines and local development or free-form tasks. It supports pulling/pushing configurations from remote instances, validating configurations, and more.
- `grafanactl` works across all environments for Grafana OSS, Enterprise, and Cloud.
Refer to the [Grafana CLI (`grafanactl`)](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/grafana-cli) documentation for more information.
## Git Sync
For an integrated, UI-driven Git workflow focused on dashboards, explore Git Sync.
- Connect folders or entire Grafana instances directly to a GitHub repository to synchronize dashboard definitions, enabling version control, branching, and pull requests directly from Grafana.
- Git Sync offers a simple, out-of-the-box approach for managing dashboards as code.
{{< admonition type="note" >}}
Git Sync is available in **private preview** for Grafana Cloud, and it's an **experimental feature** in Grafana 12, available in Grafana OSS and Enterprise [nightly releases](https://grafana.com/grafana/download/nightly).
{{< /admonition >}}
Refer to the [Git Sync documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync/) to learn more.
## Direct API usage
For maximum flexibility, advanced use cases, or building custom tooling, you can interact directly with the underlying versioned APIs.
- This approach requires handling HTTP requests and responses but provides complete control over resource management.
- `grafanactl`, Git Sync, and the Foundation SDK are all built on top of these APIs.
- To understand Dashboard Schemas accepted by the APIs, refer to the [JSON models documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/).
Refer to the [Grafana APIs](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/developers/http_api/apis/) documentation for more information.
## Foundation SDK
To programmatically define your Grafana resources (like dashboards or alerts) using familiar programming languages, use Foundation SDK.
- Define resources using strongly typed builders in languages like Go, TypeScript, Python, Java, and PHP.
- Avoid crafting complex JSON manually and integrate resource generation into your existing development workflows.
- Catch errors at compile time and easily integrate resource generation into your CI/CD pipelines.
- Use in conjunction with `grafanactl` to push your programmatically generated resources.
Refer to the [Foundation SDK](../foundation-sdk) documentation for more information.
## Additional Observability as Code tools
If you're already using established Infrastructure as Code or other configuration management tools, Grafana offers integrations to manage resources within your existing workflows.
- [Terraform](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/)
- Use the Grafana Terraform provider to manage dashboards, alerts, and more.
- Understand how to define and deploy resources using HCL/JSON configurations.
- [Ansible](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/ansible/)
- Learn to use the Grafana Ansible collection to manage Grafana Cloud resources, including folders and cloud stacks.
- Write playbooks to automate resource provisioning through the Grafana API.
- [Grafana Operator](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/grafana-operator/)
- Utilize Kubernetes-native management with the Grafana Operator.
- Manage dashboards, folders, and data sources via Kubernetes Custom Resources.
- Integrate with GitOps workflows for seamless version control and deployment.
- [Crossplane](https://github.com/grafana/crossplane-provider-grafana) lets you manage Grafana resources using Kubernetes manifests with the Grafana Crossplane provider.
- [Grafonnet](https://github.com/grafana/grafonnet) is a Jsonnet library for generating Grafana dashboard JSON definitions programmatically.
- [Grizzly](https://grafana.com/docs/grafana-cloud/as-code/infrastructure-as-code/grizzly/dashboards-folders-datasources/) is a deprecated command-line tool that simplifies managing Grafana resources using Kubernetes-inspired YAML syntax.
docs/sources/as-code/observability-as-code/grafana-cli/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
description: Overview of Grafana CLI, a command line tool for managing Grafana resources as code.
keywords:
- observability
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
labels:
products:
- cloud
- enterprise
- oss
cards:
items:
- description: Learn how to install Grafana CLI
height: 24
href: ./install-grafana-cli/
title: Install Grafana CLI
- description: Set up Grafana CLI
height: 24
href: ./set-up-grafana-cli/
title: Set up your Grafana CLI
- description: Learn how to manage resources with Grafana CLI
height: 24
href: ./grafanacli-workflows
title: Manage resources with Grafana CLI
title_class: pt-0 lh-1
hero:
description: Grafana CLI (`grafanactl`) is a command-line tool designed to simplify interaction with Grafana instances. It enables users to authenticate, manage multiple environments, and perform administrative tasks through Grafana’s REST API, all from the terminal. Whether you're automating workflows in CI/CD pipelines or switching between staging and production environments, Grafana CLI provides a flexible and scriptable way to manage your Grafana setup efficiently.
height: 110
level: 1
title: Grafana CLI
width: 110
title: Introduction to Grafana CLI
menuTitle: Grafana CLI
weight: 130
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/
aliases:
- ../../observability-as-code/grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/
---
{{< docs/hero-simple key="hero" >}}
## Explore
{{< card-grid key="cards" type="simple" >}}
docs/sources/as-code/observability-as-code/grafana-cli/grafanacli-workflows.md
+224
View File
@@ -0,0 +1,224 @@
---
description: Learn more about the supported workflows and use cases for Grafana CLI
keywords:
- workflows
- Grafana CLI
- CLI
- command line
- grafanactl
labels:
products:
- cloud
- enterprise
- oss
title: Manage resources with Grafana CLI
weight: 300
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/grafanacli-workflows/
aliases:
- ../../../observability-as-code/grafana-cli/grafanacli-workflows/ # /docs/grafana/next/observability-as-code/grafana-cli/grafanacli-workflows/
---
# Manage resources with Grafana CLI
{{< admonition type="note" >}}
`grafanactl` is under active development. Command-line flags and subcommands described here may change. This document outlines the target workflows the tool is expected to support. You can find a full list of supported commands [in this page](https://grafana.github.io/grafanactl/reference/cli/grafanactl/).
{{< /admonition >}}
## Migrate resources between environments
Using the `config` and `resources` options, you can migrate Grafana resources from one environment to another, for example, from a development to production environment.
The `config` option lets you define the configuration context.
Using `resources` with `pull`, `push`, and `serve` lets you pull a defined resource from one instance, and push that resource to another instance. `Serve` allows you to preview changes locally before pushing.
Use these steps to migrate resources between environments:
{{< admonition type="note" >}}
Currently, the `serve` command only works with dashboards.
{{< /admonition >}}
Use these steps to migrate resources between environments:
{{< admonition type="note" >}}
Resources are pulled and pushed from the `./resources` directory by default.
This can be configured with the `-p, --path` flags to specify custom paths on disk.
{{< /admonition >}}
1. Make changes to dashboards and other resources using the Grafana UI in your **development instance**.
1. Pull those resources from the development environment to your local machine:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "dev"
grafanactl resources pull --path ./resources/ -o yaml # or json
```
1. (Optional) Preview the resources locally before pushing:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "prod"
grafanactl resources serve ./resources/
```
1. Switch to the **production instance** and push the resources:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "prod"
grafanactl resources push -p ./resources/
```
## Back up Grafana resources
This workflow helps you back up all Grafana resources from one instance and later restore them. This is useful to replicate a configuration or perform disaster recovery.
1. Use `grafanactl` to pull all resources from your target environment:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "prod"
grafanactl resources pull --path ./resources/ -o yaml # or json
```
1. Save the exported resources to version control or cloud storage.
## Restore Grafana resources
1. (Optional) Preview the backup locally:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "prod"
grafanactl resources serve ./resources/
```
1. To restore the resources later or restore them on another instance, push the saved resources:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "prod"
grafanactl resources push -p ./resources/
```
## Manage dashboards as code
With this workflow, you can define and manage dashboards as code, saving them to a version control system like Git. This is useful for teams that want to maintain a history of changes, collaborate on dashboard design, and ensure consistency across environments.
1. Use a dashboard generation script (for example, with the [Foundation SDK](https://github.com/grafana/grafana-foundation-sdk)). You can find an example implementation in the Grafana as code [hands-on lab repository](https://github.com/grafana/dashboards-as-code-workshop/tree/main/part-one-golang-starter).
1. Serve and preview the output of the dashboard generator locally:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "dev"
grafanactl resources serve --script 'go run scripts/generate-dashboard.go' --watch './scripts'
```
1. When the output looks correct, generate dashboard manifest files:
```bash
go run scripts/generate-dashboard.go --generate-resource-manifests --output './resources'
```
1. Push the generated resources to your Grafana instance:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "dev"
grafanactl resources push -p ./resources/
```
## Explore and modify resources from the terminal
This section describes how to use the Grafana CLI to interact with Grafana resources directly from your terminal. These commands allow you to browse, inspect, update, and delete resources without using the Grafana UI. This approach is useful for advanced users who want to manage resources more efficiently or integrate Grafana operations into automated workflows.
### Find and delete dashboards using invalid data sources
Use this workflow to identify dashboards that reference incorrect or outdated data sources, and remove them if necessary.
1. Set the context to the appropriate environment:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "prod"
```
1. Find dashboards using specific data sources:
```bash
grafanactl resources get dashboards -ojson | jq '.items | map({ uid: .metadata.name, datasources: .spec.panels | map(.datasource.uid) })'
[
{
"uid": "important-production-dashboard",
"datasources": [
"mimir-prod"
]
},
{
"uid": "test-dashboard-from-dev",
"datasources": [
"mimir-prod",
"mimir-dev"
]
},
{
"uid": "test-dashboard-from-stg",
"datasources": [
"mimir-prod",
"mimir-stg",
"mimir-dev"
]
}
]
```
This command lists dashboard UIDs along with the data source UIDs used in their panels. You can then identify the dashboards that are using invalid or unexpected data sources.
1. Delete the identified dashboards directly:
```bash
grafanactl resources delete dashboards/test-dashboard-from-stg,test-dashboard-from-dev
✔ 2 resources deleted, 0 errors
```
### Find and deprecate dashboards using the old API version
Use this workflow to locate dashboards using a deprecated API version and mark them accordingly.
1. Set the context to the appropriate environment:
```bash
grafanactl config use-context YOUR_CONTEXT # for example "prod"
```
1. List all available resources types and versions:
```bash
grafanactl resources list
```
This command returns a list of resources, including their versions, types, and quantities:
```bash
GROUP VERSION KIND
folder.grafana.app v1 folder
dashboard.grafana.app v1 dashboard
dashboard.grafana.app v1 librarypanel
dashboard.grafana.app v2 dashboard
dashboard.grafana.app v2 librarypanel
playlist.grafana.app v1 playlist
```
1. Find dashboards that are still using a deprecated API version:
```bash
grafanactl resources get dashboards.v1.dashboard.grafana.app
```
This command returns a table displaying the resource type, resource name, and associated namespace:
```bash
KIND NAME NAMESPACE
dashboards really-old-dashboard default
```
1. Edit each of these dashboards to add a `deprecated` tag:
```bash
grafanactl resources edit dashboards.v1.dashboard.grafana.app/really-old-dashboard -p '{"spec":{"tags":["deprecated"]}}'
```
{{< admonition type="tip" >}}
You can get help by using the `grafanactl --help` command.
{{< /admonition >}}
docs/sources/as-code/observability-as-code/grafana-cli/install-grafana-cli.md
+49
View File
@@ -0,0 +1,49 @@
---
description: Installation guide for Grafana CLI, a command line tool for managing Grafana Observability as Code
keywords:
- configuration
- Grafana CLI
- CLI
- command line
- grafanactl
- installation
labels:
products:
- cloud
- enterprise
- oss
title: Install Grafana CLI
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/install-grafana-cli/
aliases:
- ../../../observability-as-code/grafana-cli/install-grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/install-grafana-cli/
---
# Install Grafana CLI
You can install the project using one of the following supported methods:
## 1. Download a pre-built binary
Download the latest binary for your platform from the [Releases page](https://github.com/grafana/grafanactl/releases).
Prebuilt binaries are available for a variety of operating systems and architectures. Visit the latest release page, and scroll down to the Assets section.
To install the binary, follow the instructions below:
1. Download the archive for the desired operating system and architecture
1. Extract the archive
1. Move the executable to the desired directory
1. Ensure this directory is included in the PATH environment variable
1. Verify that you have execute permission on the file
## 2. Build from source
To build `grafanactl` from source you must:
- Have `git` installed
- Have `go` v1.24 (or greater) installed
```bash
go install github.com/grafana/grafanactl/cmd/grafanactl@latest
```
docs/sources/as-code/observability-as-code/grafana-cli/set-up-grafana-cli.md
+122
View File
@@ -0,0 +1,122 @@
---
description: Configuration guide for Grafana CLI, a command line tool for managing Grafana resources as code.
keywords:
- configuration
- Grafana CLI
- CLI
- command line
- grafanactl
labels:
products:
- cloud
- enterprise
- oss
title: Set up Grafana CLI
weight: 200
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/grafana-cli/set-up-grafana-cli/
aliases:
- ../../../observability-as-code/grafana-cli/set-up-grafana-cli/ # /docs/grafana/next/observability-as-code/grafana-cli/set-up-grafana-cli/
---
# Set up Grafana CLI
You can configure Grafana CLI in two ways: using environment variables or through a configuration file.
- **Environment variables** are ideal for CI environments and support a single context. A full list of supported environment variables is available in the [reference documentation](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#environment-variables-reference).
- **Configuration files** can manage multiple contexts, making it easier to switch between different Grafana instances.
{{< admonition type="note" >}}
Configuration items may change depending on your set-up. For example, use `org-id` for Grafana on-prem, but use `stack-id` for Grafana Cloud.
{{< /admonition >}}
## Configure Grafana CLI with environment variables
Grafana CLI communicates with Grafana via its REST API, which requires authentication credentials.
At a minimum, set the URL of your Grafana instance and the organization ID:
```bash
GRAFANA_SERVER='http://localhost:3000' GRAFANA_ORG_ID='1' grafanactl config check
```
Depending on your authentication method, you may also need to set:
- A [token](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_token) for a [Grafana service account](https://grafana.com/docs/grafana/latest/administration/service-accounts/) (recommended)
- A [username](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_user) and [password](https://github.com/grafana/grafanactl/blob/main/docs/reference/environment-variables/index.md#grafana_password) for basic authentication
To persist your configuration, consider [creating a context](#use-configuration-contexts).
### Use configuration contexts
Contexts allow you to easily switch between multiple Grafana instances.
By default, the CLI uses a context named `default`. To configure it use:
```bash
grafanactl config set contexts.default.grafana.server http://localhost:3000
grafanactl config set contexts.default.grafana.org-id 1
# Authenticate with a service account token
grafanactl config set contexts.default.grafana.token service-account-token
# Or use basic authentication
grafanactl config set contexts.default.grafana.user admin
grafanactl config set contexts.default.grafana.password admin
```
You can define additional contexts in the same way:
```bash
grafanactl config set contexts.staging.grafana.server https://staging.grafana.example
grafanactl config set contexts.staging.grafana.org-id 1
```
{{< admonition type="note" >}}
In these examples, `default` and `staging` are the names of the contexts.
{{< /admonition >}}
## Configure Grafana CLI with configuration files
Grafana CLI stores its configuration in a YAML file. The CLI determines the configuration file location in the following order:
1. If the `--config` flag is provided, the specified file is used.
2. If `$XDG_CONFIG_HOME` is set:
`$XDG_CONFIG_HOME/grafanactl/config.yaml`
3. If `$HOME` is set:
`$HOME/.config/grafanactl/config.yaml`
4. If `$XDG_CONFIG_DIRS` is set:
`$XDG_CONFIG_DIRS/grafanactl/config.yaml`
{{< admonition type="note" >}}
Use `grafanactl config check` to display the configuration file currently in use.
{{< /admonition >}}
## Useful commands
Check the current configuration:
```bash
grafanactl config check
```
{{< admonition type="note" >}}
This command is useful to troubleshoot your configuration.
{{< /admonition >}}
List all available contexts:
```bash
grafanactl config list-contexts
```
Switch to a specific context:
```bash
grafanactl config use-context staging
```
View the full configuration:
```bash
grafanactl config view
```
docs/sources/as-code/observability-as-code/provision-resources/_index.md
+67
View File
@@ -0,0 +1,67 @@
---
description: Learn about how to provision resources using Git Sync and local file provisioning administration.
keywords:
- observability
- configuration
- as code
- git integration
- git sync
- github
labels:
products:
- enterprise
- oss
title: Provision resources and sync dashboards
menuTitle: Provision resources
weight: 300
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/
aliases:
- ../../observability-as-code/provision-resources/ # /docs/grafana/next/observability-as-code/provision-resources/
---
# Provision resources and sync dashboards
{{< admonition type="caution" >}}
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud. Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided. You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
Git Sync and local file provisioning are [experimental features](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.
{{< /admonition >}}
Provisioning allows you to configure how to store your dashboard JSON and other files in GitHub repositories using either Git Sync or a local path.
Of the two options, **Git Sync** is the favorited method for provisioning your dashboards. You can synchronize any new dashboards and changes to existing dashboards from the UI to your configured GitHub repository. If you push a change in the repository, those changes are mirrored in your Grafana instance. Refer to [Git Sync workflow](#git-sync-workflow) for more information.
Alternatively, **local file provisioning** allows you to include in your Grafana instance resources (such as folders and dashboard JSON files) that are stored in a local file system. Refer to [Local file workflow](#local-file-workflow) for more information.
## Provisioned folders and connections
The dashboards saved in your GitHub repository or local folder appear in Grafana in the 'provisioned' folder. The dashboards and folders saved to the local path are referred to as 'provisioned' resources and are labeled as such in the Grafana UI. You can update any provisioned dashboard that is either stored within a GitHub repository (Git Sync workflow) or in a local file (local file workflow).
You can set a single folder, or multiple folders to a different repository, with up to 10 connections. Alternatively, your entire Grafana instance can be the provisioned folder.
## Git Sync workflow
In the Git Sync workflow:
- When you provision resources with Git Sync you can modify them from within the Grafana UI or within the GitHub repository. Changes made in either the repository or the Grafana UI are bidirectional.
- Any changes made in the provisioned files stored in the GitHub repository are reflected in the Grafana database. By default, Grafana polls GitHub every 60 seconds. The Grafana UI reads from the database and updates the UI to reflect these changes.
For example, if you update a dashboard within the Grafana UI and click **Save** to preserve the changes, you'll be notified that the dashboard is provisioned in a GitHub repository. Next you'll be prompted to choose how to preserve the changes: either directly to a branch, or pushed to a new branch using a pull request in GitHub.
For more information, see [Introduction to Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync) and [Set up Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/git-sync-setup).
## Local file workflow
In the local file workflow:
- All provisioned resources are changed in the local files.
- Any changes made in the provisioned files are reflected in the Grafana database. The Grafana UI reads the database and updates the UI to reflect these changes.
- You can't use the Grafana UI to edit or delete provisioned resources.
Learn more in [Set up file provisioning](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/).
## Explore provisioning
{{< section withDescriptions="true" depth="5" >}}
docs/sources/as-code/observability-as-code/provision-resources/file-path-setup.md
+170
View File
@@ -0,0 +1,170 @@
---
description: Instructions for setting up file provisioning with a local path.
keywords:
- as code
- as-code
- file provisioning
- local path
labels:
products:
- enterprise
- oss
title: Set up file provisioning
weight: 200
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/file-path-setup/
aliases:
- ../../../observability-as-code/provision-resources/file-path-setup/ # /docs/grafana/next/observability-as-code/provision-resources/file-path-setup/
---
# Set up file provisioning
{{< admonition type="caution" >}}
Local file provisioning is an [experimental feature](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions, but it's **not available in Grafana Cloud**. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.
{{< /admonition >}}
Use local file provisioning to include in your Grafana instance resources (such as folders and dashboard JSON files) that are stored in a local file system.
This page explains how to set up local file provisioning.
The local path mount is referred to as a repository.
Using the local path lets you also use it with a tool like `fuse`, allowing you to mount S3 buckets as local paths. You can also use tools like `restic` to automatically back up your dashboards to your preferred backup storage solution.
To set up file sync with local with local files, you need to:
1. Enable feature toggles and paths in Grafana configuration file (first time set up).
1. Set the local path.
1. Choose what content to sync with Grafana.
## New file provisioning capabilities
Local file provisioning using **Administration** > **Provisioning** will eventually replace the traditional methods Grafana has used for referencing local file systems for dashboard files.
{{< admonition type="note" >}}
For production systems, use the `folderFromFilesStructure` capability instead of **Administration** > **Provisioning** to include dashboards from a local file system in your Grafana instance. Refer to [Provision Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information.
{{< /admonition >}}
### Limitations
- A provisioned dashboard can't be deleted from within Grafana UI. The dashboard has to be deleted at the local file system and those changes synced to Grafana.
- Changes from the local file system are one way: you can't save changes from the Grafana UI to GitHub.
## Before you begin
{{< admonition type="note" >}}
Enable the `provisioning` and `kubernetesDashboards` feature toggles in Grafana to use this feature.
{{< /admonition >}}
To set up file provisioning, you need:
- Administration rights in your Grafana organization.
- A local directory where your dashboards will be stored.
- If you want to use a GitHub repository, refer to [Set up Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/).
- To update the `permitted_provisioning_paths` section of `custom.ini`.
- To enable the required feature toggles in your Grafana instance.
## Enable required feature toggles and configure permitted paths
To activate local file provisioning in Grafana, you need to enable the `provisioning` and `kubernetesDashboards` feature toggles.
For additional information about feature toggles, refer to [Configure feature toggles](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/feature-toggles).
The local setting must be a relative path and its relative path must be configured in the `permitted_provisioned_paths` configuration option.
The configuration option is relative to your working directory, i.e. where you are running Grafana from; this is usually `/usr/share/grafana` or similar.
Local file paths can point to any directory that is permitted by the configuration.
The default paths is `devenv/dev-dashboards` and `conf/provisioning` in your `grafana` installation directory.
The path must behave as a standard file directory on the system of choice.
Any subdirectories are automatically included.
The values that you enter for the `permitted_provisioning_paths` become the base paths for those entered when you enter a local path in the **Connect to local storage** wizard.
1. Open your Grafana configuration file, either `grafana.ini` or `custom.ini`. For file location based on operating system, refer to [Configuration file location](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/feature-toggles/#experimental-feature-toggles).
1. Locate or add a `[feature_toggles]` section. Add these values:
```ini
[feature_toggles]
provisioning = true
kubernetesDashboards = true ; use k8s from browser
```
1. Locate or add a `[paths]` section. To add more than one location, use the pipe character (`|`) to separate the paths. The list should not include empty paths or trailing pipes. Add these values:
```ini
[paths]
; This is devenv/dev-dashboards and conf/provisioning by default.
permitted_provisioning_paths = grafana/ | /etc/grafana/provisioning/
```
1. Save the changes to the file and start Grafana.
## Set up file-based provisioning
To use file-based provisioning, you need the file path to the `grafana` folder where your dashboards are stored in the repository.
To start setting up file-based provisioning:
1. Log in to your Grafana server with an account that has the Grafana Admin flag set.
1. Select **Administration** in the left-side menu and then **Provisioning**.
1. Select [Configure file provisioning](#set-up-file-based-provisioning).
### Connect to local storage
The local path can point to any directory that is permitted by the configuration.
Refer to [Enabled required feature toggles and paths](#enable-required-feature-toggles-and-configure-permitted-paths) for information.
The starting path is always your working `grafana` directory.
The prefix that must be entered is determined by the locations configured in `permitted_provisioning_paths`.
The default paths are `devenv/dev-dashboards` and `conf/provisioning` in your `grafana` installation directory.
The value you enter in the Grafana UI must _begin_ with any of the configured values. For example, `conf/provisioning/test` is valid, but `conf/test` is not.
1. Enter the **Local path**, for example `grafana/`. This must begin with any of the configured `permitted_provisioned_paths`.
1. Select **Choose what to synchronize**.
The set up process verifies the path and provides an error message if a problem occurs.
### Choose what to synchronize
#### Synchronization limitations
Full instance sync is not available in Grafana Cloud.
In Grafana OSS/Enterprise:
- If you try to perform a full instance sync with resources that contain alerts or panels, the connection will be blocked.
- You won't be able to create new alerts or library panels after setup is completed.
- If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the provisioned repository and connect again with folder sync.
#### Set up synchronization
Choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections).
- Choose **Sync all resources with external storage** if you want to sync and manage your entire Grafana instance through external storage. With this option, all of your dashboards are synced to that one repository. You can only have one provisioned connection with this selection, and you won't have the option of setting up additional repositories to connect to.
- Choose **Sync external storage to new Grafana folder** to sync external resources into a new folder without affecting the rest of your instance. You can repeat this process for up to 10 connections.
Next, enter a **Display name** for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI.
Click **Synchronize** to continue.
### Synchronize with external storage
After this one time step, all future updates are automatically saved to the local file path and provisioned back to the instance.
During the initial synchronization, your dashboards will be temporarily unavailable. No data or configurations will be lost.
How long the process takes depends upon the number of resources involved.
Select **Begin synchronization** to start the process.
### Choose additional settings
If you wish, you can make any files synchronized as as **Read only** so no changes can be made to the resources through Grafana.
Any resources made outside of Grafana and saved to the local repository will be reflected in Grafana.
Select **Finish**.
## Verify your dashboards in Grafana
To verify that your dashboards are available at the location that you specified, click **Dashboards**. The name of the dashboard is listed in the **Name** column.
docs/sources/as-code/observability-as-code/provision-resources/git-sync-setup.md
+227
View File
@@ -0,0 +1,227 @@
---
description: Instructions for setting up Git Sync, so you can provision GitHub repositories for use with Grafana.
keywords:
- set up
- git integration
- git sync
- github
labels:
products:
- enterprise
- oss
title: Set up Git Sync
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/git-sync-setup/
aliases:
- ../../../observability-as-code/provision-resources/git-sync-setup/ # /docs/grafana/next/observability-as-code/provision-resources/git-sync-setup/
---
# Set up Git Sync
{{< admonition type="caution" >}}
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud, and is an [experimental feature](https://grafana.com/docs/release-life-cycle/) in Grafana v12 for open source and Enterprise editions.
Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.
You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
{{< /admonition >}}
Git Sync lets you manage Grafana dashboards as code by storing dashboard JSON files and folders in a remote GitHub repository.
To set up Git Sync and synchronize with a GitHub repository follow these steps:
1. [Enable feature toggles in Grafana](#enable-required-feature-toggles) (first time set up).
1. [Create a GitHub access token](#create-a-github-access-token).
1. [Configure a connection to your GitHub repository](#set-up-the-connection-to-github).
1. [Choose what content to sync with Grafana](#choose-what-to-synchronize).
Optionally, you can [extend Git Sync](#configure-webhooks-and-image-rendering) by enabling pull request notifications and image previews of dashboard changes.
| Capability | Benefit | Requires |
| ----------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------- |
| Adds a table summarizing changes to your pull request | Provides a convenient way to save changes back to GitHub. | Webhooks configured |
| Add a dashboard preview image to a PR | View a snapshot of dashboard changes to a pull request without opening Grafana. | Image renderer and webhooks configured |
{{< admonition type="note" >}}
Alternatively, you can configure a local file system instead of using GitHub. Refer to [Set up file provisioning](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/) for more information.
{{< /admonition >}}
## Performance impacts of enabling Git Sync
Git Sync is an experimental feature and is under continuous development. Reporting any issues you encounter can help us improve Git Sync.
When Git Sync is enabled, the database load might increase, especially for instances with a lot of folders and nested folders. Evaluate the performance impact, if any, in a non-production environment.
## Before you begin
{{< admonition type="caution" >}}
Refer to [Known limitations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#known-limitations/) before using Git Sync.
{{< /admonition >}}
### Requirements
To set up Git Sync, you need:
- Administration rights in your Grafana organization.
- Enable the required feature toggles in your Grafana instance. Refer to [Enable required feature toggles](#enable-required-feature-toggles) for instructions.
- A GitHub repository to store your dashboards in.
- If you want to use a local file path, refer to [the local file path guide](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/).
- A GitHub access token. The Grafana UI will prompt you during setup.
- Optional: A public Grafana instance.
- Optional: The [Image Renderer service](https://github.com/grafana/grafana-image-renderer) to save image previews with your PRs.
## Enable required feature toggles
To activate Git Sync in Grafana, you need to enable the `provisioning` and `kubernetesDashboards` feature toggles.
For additional information about feature toggles, refer to [Configure feature toggles](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/feature-toggles).
To enable the required feature toggles, add them to your Grafana configuration file:
1. Open your Grafana configuration file, either `grafana.ini` or `custom.ini`. For file location based on operating system, refer to [Configuration file location](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/feature-toggles/#experimental-feature-toggles).
1. Locate or add a `[feature_toggles]` section. Add these values:
```ini
[feature_toggles]
provisioning = true
kubernetesDashboards = true ; use k8s from browser
```
1. Save the changes to the file and restart Grafana.
## Create a GitHub access token
Whenever you connect to a GitHub repository, you need to create a GitHub access token with specific repository permissions.
This token needs to be added to your Git Sync configuration to enable read and write permissions between Grafana and GitHub repository.
1. Create a new token using [Create new fine-grained personal access token](https://github.com/settings/personal-access-tokens/new). Refer to [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for instructions.
1. Under **Permissions**, expand **Repository permissions**.
1. Set these permissions for Git Sync:
- **Contents**: Read and write permission
- **Metadata**: Read-only permission
- **Pull requests**: Read and write permission
- **Webhooks**: Read and write permission
1. Select any additional options and then press **Generate token**.
1. Verify the options and select **Generate token**.
1. Copy the access token. Leave the browser window available with the token until you've completed configuration.
GitHub Apps are not currently supported.
## Set up the connection to GitHub
Use **Provisioning** to guide you through setting up Git Sync to use a GitHub repository.
1. Log in to your Grafana server with an account that has the Grafana Admin flag set.
1. Select **Administration** in the left-side menu and then **Provisioning**.
1. Select **Configure Git Sync**.
### Connect to external storage
To connect your GitHub repository, follow these steps:
1. Paste your GitHub personal access token into **Enter your access token**. Refer to [Create a GitHub access token](#create-a-github-access-token) for instructions.
1. Paste the **Repository URL** for your GitHub repository into the text box.
1. Enter a branch to use. The default value is `main`.
1. Add a **Path** to a subdirectory where your dashboards are stored. The default value is `grafana/`. If your dashboards are stored in the root of your repository, then remove the directory name.
1. Select **Choose what to synchronize** to have the connection to your repository verified and continue setup.
### Choose what to synchronize
In this step you can decide which elements to synchronize. Keep in mind the available options depend on the status of your Grafana instance.
- If the instance contains resources in an incompatible data format, you'll have to migrate all the data using instance sync. Folder sync won't be supported.
- If there is already another connection using folder sync, instance sync won't be offered.
#### Synchronization limitations
Git Sync only supports dashboards and folders. Alerts, panels, and other resources are not supported yet.
{{< admonition type="caution" >}}
Refer to [Known limitations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#known-limitations/) before using Git Sync. Refer to [Supported resources](/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#supported-resources) for details about which resources you can sync.
{{< /admonition >}}
Full instance sync is not available in Grafana Cloud.
In Grafana OSS/Enterprise:
- If you try to perform a full instance sync with resources that contain alerts or panels, Git Sync will block the connection.
- You won't be able to create new alerts or library panels after the setup is completed.
- If you opted for full instance sync and want to use alerts and library panels, you'll have to delete the synced repository and connect again with folder sync.
#### Set up synchronization
To set up synchronization, choose to either sync your entire organization resources with external storage, or to sync certain resources to a new Grafana folder (with up to 10 connections).
- Choose **Sync all resources with external storage** if you want to sync and manage your entire Grafana instance through external storage. With this option, all of your dashboards are synced to that one repository. You can only have one provisioned connection with this selection, and you won't have the option of setting up additional repositories to connect to.
- Choose **Sync external storage to new Grafana folder** to sync external resources into a new folder without affecting the rest of your instance. You can repeat this process for up to 10 connections.
Next, enter a **Display name** for the repository connection. Resources stored in this connection appear under the chosen display name in the Grafana UI. Click **Synchronize** to continue.
### Choose additional settings
Finally, you can set up how often your configured storage is polled for updates.
1. For **Update instance interval (seconds)**, enter how often you want the instance to pull updates from GitHub. The default value is 60 seconds.
1. Optional: Select **Read only** to ensure resources can't be modified in Grafana.
1. Optional: If you have the Grafana Image Renderer plugin configured, you can **Enable dashboards previews in pull requests**. If image rendering is not available, then you can't select this option. For more information, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer).
1. Select **Finish** to proceed.
## Verify your dashboards in Grafana
To verify that your dashboards are available at the location that you specified, click **Dashboards**. The name of the dashboard is listed in the **Name** column.
Now that your dashboards have been synced from a repository, you can customize the name, change the branch, and create a pull request (PR) for it. Refer to [Manage provisioned repositories with Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/use-git-sync/) for more information.
## Configure webhooks and image rendering
You can extend Git Sync by getting instant updates and pull requests using webhooks and add dashboard previews in pull requests.
### Set up webhooks for realtime notification and pull request integration
When connecting to a GitHub repository, Git Sync uses webhooks to enable real-time updates from GitHub public repositories or enable pull request integrations. Without webhooks, the polling interval is set in the final configuration screen, and the default is 60 seconds. If you use local storage, then Git Sync only provides periodic pulling.
You can set up webhooks with whichever service or tooling you prefer. You can use Cloudflare Tunnels with a Cloudflare-managed domain, port-forwarding and DNS options, or a tool such as `ngrok`.
To set up webhooks you need to expose your Grafana instance to the public Internet. You can do this via port forwarding and DNS, a tool such as `ngrok`, or any other method you prefer. The permissions set in your GitHub access token provide the authorization for this communication.
After you have the public URL, you can add it to your Grafana configuration file:
```yaml
[server]
root_url = https://PUBLIC_DOMAIN.HERE
```
To check the configured webhooks, go to **Administration** > **Provisioning** and click the **View** link for your GitHub repository.
#### Expose necessary paths only
If your security setup does not permit publicly exposing the Grafana instance, you can either choose to `allowlist` the GitHub IP addresses, or expose only the necessary paths.
The necessary paths required to be exposed are, in RegExp:
- `/apis/provisioning\.grafana\.app/v0(alpha1)?/namespaces/[^/]+/repositories/[^/]+/(webhook|render/.*)$`
<!-- TODO: Path for the blob storage for image rendering? @ryantxu would know this best. -->
### Set up image rendering for dashboard previews
Set up image rendering to add visual previews of dashboard updates directly in pull requests. Image rendering also requires webhooks.
To enable this capability, install the Grafana Image Renderer in your Grafana instance. For more information and installation instructions, refer to the [Image Renderer service](https://github.com/grafana/grafana-image-renderer).
## Modify configurations after set up is complete
To update your repository configuration after you've completed set up:
1. Log in to your Grafana server with an account that has the Grafana Admin flag set.
1. Select **Administration** in the left-side menu and then **Provisioning**.
1. Select **Settings** for the repository you wish to modify.
1. Use the **Configure repository** screen to update any of the settings.
1. Select **Save** to preserve the updates.
docs/sources/as-code/observability-as-code/provision-resources/intro-git-sync.md
+167
View File
@@ -0,0 +1,167 @@
---
description: Learn about Git Sync, the Grafana feature for storing and managing dashboards within GitHub repositories.
keywords:
- dashboards
- git integration
- git sync
- github
labels:
products:
- enterprise
- oss
- cloud
refs:
roles-and-permissions:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/account-management/authentication-and-permissions/cloud-roles/
title: Git Sync
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/intro-git-sync/
aliases:
- ../../../observability-as-code/provision-resources/intro-git-sync/ # /docs/grafana/next/observability-as-code/provision-resources/intro-git-sync/
---
# Introduction to Git Sync
{{< admonition type="caution" >}}
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud, and is an [experimental feature](https://grafana.com/docs/release-life-cycle/) in Grafana v12 for open source and Enterprise editions.
Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.
You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
{{< /admonition >}}
Git Sync in Grafana lets you manage your dashboards as code as JSON files stored in GitHub. You and your team can version control, collaborate, and automate deployments efficiently.
Using Git Sync, you can:
- Manage dashboard configuration outside of Grafana instances using Git
- Introduce a review process for creating and modifying dashboards
- Replicate dashboards across multiple instances
## How it works
{{< admonition type="caution" >}}
Git Sync only works with specific folders for the moment. Full-instance sync is not currently supported.
{{< /admonition >}}
Git Sync is bidirectional and works both with changes done directly in GitHub as well as in the Grafana UI.
### Provisioning folder
Git Sync creates a folder for all the synchronized resources to live under. You can continue to have unprovisioned resources outside that folder.
### Make changes in Grafana
Whenever you modify a dashboard directly from the UI, Grafana can commit changes to Git upon saving. You can configure settings to either enforce PR approvals before merging in your repository, or allow direct commits.
Grafana periodically polls GitHub at a regular internal to synchronize any changes. The default polling interval is 60 seconds, and you can change this setting in the Grafana UI.
- If you enable the [webhooks feature](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/git-sync-setup/#configure-webhooks-and-image-rendering), repository notifications appear almost immediately.
- Without webhooks, Grafana polls for changes at the specified interval.
### Make changes in your GitHub repositories
With Git Sync, you can make changes to the files in the provisioned folder in GitHub and see them in Grafana. Automated workflows ensure those changes are automatically represented in the Grafana database by updating Git. The Grafana UI reads the database and updates the UI to reflect these changes.
## Known limitations
{{< admonition type="caution" >}}
Refer to [Requirements](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/git-sync-setup#requirements/) to learn what you need to use Git Sync.
{{< /admonition >}}
**Git Sync is under development and the following limitations apply.**
**Synced resources**
- You can only sync dashboards and folders. Refer to [Supported resources](#supported-resources) for more information.
- If you're using Git Sync in Grafana OSS and Grafana Enterprise, some resources might be in an incompatible data format and won't be synced.
- Full-instance sync is not available in Grafana Cloud and has limitations in Grafana OSS and Grafana Enterprise. Refer to [Choose what to synchronize](../git-sync-setup/#choose-what-to-synchronize) for more details.
- When migrating to full instance sync, during the synchronization process your resources will be temporarily unavailable. No one will be able to create, edit, or delete resources during this process.
- If you want to manage existing resources with Git Sync, you need to save them as JSON files and commit them to the synced repository. Open a PR to import, copy, move, or save a dashboard.
- Restoring resources from the UI is currently not possible. As an alternative, you can restore dashboards directly in your GitHub repository by raising a PR, and they will be updated in Grafana.
**Authentication**
- You can only authenticate in GitHub using your Personal Access Token token.
**Permission management**
- You cannot modify the permissions of a provisioned folder after you've synced it.
- Default permissions are: Admin = Admin, Editor = Editor, and Viewer = Viewer. Refer to [Roles and permissions](ref:roles-and-permissions) for more information.
**Compatibility**
- Support for native Git, Git app, and other providers, such as GitLab or Bitbucket, is on the roadmap.
## Supported resources
Git Sync only supports dashboards and folders. Alerts, panels, and other resources are not supported yet.
If you're using Git Sync in Grafana OSS or Grafana Enterprise, some supported resources might be in an incompatible data format. If this happens, syncing will be blocked. Compatibility issues will be fixed with an upcoming migration tool.
### Resource states
A resource can be:
| Is the resource? | **Compatible** | **Incompatible** |
| ---------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Supported** | The resource can be managed with Git Sync. | The resource is supported but has compatibility issues. It **cannot** be managed with Git Sync. |
| **Unsupported** | The resource is **not** supported and **cannot** be managed with Git Sync. | Not applicable. |
### Git Sync instance states
An instance can be in one of the following Git Sync states:
- **Unprovisioned**: None of the instance's resources are being managed by Git Sync.
- **Partially provisioned**: Some of the resources are controlled by Git Sync.
- **Fully provisioned**: All supported resource types are managed by Git Sync. Note that unsupported resources are not managed.
## Common use cases
You can use Git Sync in the following scenarios.
### Version control and auditing
Organizations can maintain a structured, version-controlled history of Grafana dashboards. The version control lets you revert to previous versions when necessary, compare modifications across commits, and ensure transparency in dashboard management.
Additionally, having a detailed history of changes enhances compliance efforts, as teams can generate audit logs that document who made changes, when they were made, and why.
### Automated deployment and CI/CD integration
Teams can streamline their workflow by integrating dashboard updates into their CI/CD pipelines. By pushing changes to GitHub, automated processes can trigger validation checks, test dashboard configurations, and deploy updates programmatically using the `grafanactl` CLI and Foundation SDK.
This reduces the risk of human errors, ensures consistency across environments, and enables a faster, more reliable release cycle for dashboards used in production monitoring and analytics.
### Collaborative dashboard development
With Git Sync, multiple users can work on dashboards simultaneously without overwriting each other’s modifications.
By leveraging pull requests and branch-based workflows, teams can submit changes for review before merging them into the main branch. This process not only improves quality control but also ensures that dashboards adhere to best practices and organizational standards.
Additionally, GitHub’s built-in discussion and review tools facilitate effective collaboration, making it easier to address feedback before changes go live.
### Multi-environment synchronization
Enterprises managing multiple Grafana instances, such as development, staging, and production environments, can seamlessly sync dashboards across these instances. This ensures consistency in visualization and monitoring configurations, reducing discrepancies that might arise from manually managing dashboards in different environments.
By using Git Sync, teams can automate deployments across environments, eliminating repetitive setup tasks and maintaining a standardized monitoring infrastructure across the organization.
### Disaster recovery and backup
By continuously syncing dashboards to GitHub, organizations can create an always-updated backup, ensuring dashboards are never lost due to accidental deletion or system failures.
If an issue arises, such as a corrupted dashboard, unintended modification, or a system crash, teams can quickly restore the latest functional version from the Git repository. This not only minimizes downtime but also adds a layer of resilience to Grafana monitoring setups, ensuring critical dashboards remain available when needed.
## Provision dashboards as code
Because dashboards are defined in JSON files, you can enable as-code workflows where the JSON file is an output from Go, TypeScript, or another coding language in the format of a dashboard schema.
To learn more about creating dashboards in a coding language to provision them for Git Sync, refer to the [Foundation SDK](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/foundation-sdk) documentation.
docs/sources/as-code/observability-as-code/provision-resources/provisioned-dashboards.md
+138
View File
@@ -0,0 +1,138 @@
---
description: Update, save, and modify provisioned resources in Grafana using Git Sync.
keywords:
- dashboards
- provisioned files
- git sync
- github
labels:
products:
- enterprise
- oss
title: Work with provisioned dashboards
weight: 300
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/provisioned-dashboards/
aliases:
- ../../../observability-as-code/provision-resources/provisioned-dashboards/ # /docs/grafana/next/observability-as-code/provision-resources/provisioned-dashboards/
---
# Work with provisioned dashboards
{{< admonition type="caution" >}}
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud. Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided. You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
Git Sync and local file provisioning are [experimental features](https://grafana.com/docs/release-life-cycle/) introduced in Grafana v12 for open source and Enterprise editions. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided.
{{< /admonition >}}
Using Provisioning, you can choose to store your dashboard JSON files in either GitHub repositories using Git Sync or a local file path.
For more information, refer to the [Dashboards](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/) documentation.
## Provisioning methods
Dashboards and folders synchronized using Git Sync or a local file path are referred to as "provisioned" resources.
### Git Sync provisioning
Of the two experimental options, **Git Sync** is the recommended method for provisioning your dashboards.
You can synchronize any new dashboards and changes to existing dashboards to your configured GitHub repository.
If you push a change in the repository, those changes are mirrored in your Grafana instance.
For more information on configuring Git Sync, refer to [Introduction to Git Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync/).
### Local path provisioning
Local path provisioning makes files from a specified path available within Grafana, and any changes made in the configured local path are updated in Grafana. Note that these provisioned resources can only be modified in the local files and not within Grafana.
Refer to [Set up file provisioning](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup) to learn more about the version of local file provisioning in Grafana 12.
{{< admonition type="note" >}}
The experimental local path provisioning using **Administration** > **Provisioning** will replace the file provisioning methods Grafana uses for referencing local file.
For production systems, use the established methods for provisioning file systems in Grafana.
Refer to [Provision Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/provisioning/#provision-folders-structure-from-filesystem-to-grafana) for more information.
{{< /admonition >}}
## Manage dashboards provisioned with Git Sync
Using Git Sync, you can manage your dashboards in the UI and synchronize them with a GitHub repository.
Git Sync changes the behavior in Grafana for dashboards that are saved in Git Sync:
- Dashboards saved in your repository or local folder configured with Git Sync appear in a provisioned folder in Grafana.
- Any dashboard folders saved with Git Sync have a **Provisioned** label in the UI.
- Any changes to a provisioned resources have to be saved to the repository by opening a pull request or committing directly to the `main` branch.
You can set a single folder, or multiple folders to a different repository, with up to 10 connections.
### Git workflow with dashboards
By default, Git version control uses a branch-based workflow for changes. This means that you can:
- Commit changes to an existing branch (such as `main`) or save them to a new branch in your GitHub repository.
- Use pull requests to review changes to dashboards.
- Preview the changes before merging.
To learn more about Git, refer to [Getting Started - About Version Control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) of the [Pro Git book](https://git-scm.com/book/en/v2) in the official Git documentation.
### Add and save a new dashboard
When you create a new dashboard in a provisioned folder associated with a GitHub repository, you follow the same process you use for any new dashboard.
Refer to [Create a dashboard](http://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/) for more information.
After you create the dashboard, the steps are similar to [Save dashboard changes to GitHub](#save-dashboard-changes-to-github).
1. Select **Save** to preserve the new dashboard.
1. Enter a title for the dashboard and a description.
1. Select the provisioned folder from the **Folder** drop-down list.
1. In **Path**, provide the path for your repository, ending in a JSON or YAML file.
1. For **Workflow**, select **Push to main** to make a Git commit directly to the repository or **Push to a new branch** to create a pull request.
- **Branch**: Specify the branch name in GitHub (for example, main). This option only appears if you select **Push to a new branch**.
1. Select **Save**.
### Save dashboard changes to GitHub
When you edit a provisioned resource, you are prompted to save or discard those changes.
Saving changes requires opening a pull request in your GitHub repository.
1. Select **Edit** to update a provisioned dashboard. Make your desired changes.
1. Click **Save dashboard**.
1. On the **Provisioned dashboard** panel, choose the options you want to use:
- **Update default refresh value**: Check this box to make the current refresh the new default.
- **Update default variable values**: Check this box to make the current values the new default.
- **Path**: Provide the path for your repository, ending in a JSON or YAML file.
- **Workflow:** Select **Push to main** to make a Git commit directly to the repository or **Push to a new branch** to create a pull request.
- **Branch**: Specify the branch name in GitHub (for example, main). This option only appears if you select **Push to a new branch**.
- **Comment**: Add a comment describing your changes.
1. Optional: Select the **Changes** tab to view the differences between the updates you made and the original resource.
1. Select **Save**.
1. If you chose **Push to a new branch**, select **Open a pull request in GitHub** to open a new PR to your repository. GitHub opens with your dashboard’s code as the contents of the PR.
1. Follow your usual GitHub workflow to save and merge the PR to your repository.
### Remove dashboards
You can remove a provisioned dashboard by deleting the dashboard from the repository. The Grafana UI updates when the changes from the GitHub repository sync.
To restore a deleted dashboard, raise a PR directly in your GitHub repository. Restoring resources from the UI is currently not possible.
### Tips
- Use GitHub pull requests for changes to maintain review processes.
- Provide clear commit messages describing your changes.
- Regularly sync your repository to keep Grafana up to date.
- Review the **Events** tab to monitor sync status.
## Manage dashboards provisioned with file provisioning
To update any resources in the local path, you need to edit the files directly and then save them locally.
These changes are synchronized to Grafana. However, you can't create, edit, or delete these resources using the Grafana UI.
Refer to [Set up file provisioning](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/file-path-setup/) for configuration instructions.
docs/sources/as-code/observability-as-code/provision-resources/use-git-sync.md
+94
View File
@@ -0,0 +1,94 @@
---
description: Instructions for working with Git Sync to perform common tasks, such as saving dashboards to GitHub and synchronizing changes with Grafana.
keywords:
- as code
- as-code
- dashboards
- git integration
- git sync
- github
labels:
products:
- enterprise
- oss
title: Manage provisioned repositories with Git Sync
menuTitle: Manage repositories with Git Sync
weight: 400
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/provision-resources/use-git-sync/
aliases:
- ../../../observability-as-code/provision-resources/use-git-sync/ # /docs/grafana/next/observability-as-code/provision-resources/use-git-sync/
---
# Manage provisioned repositories with Git Sync
{{< admonition type="caution" >}}
Git Sync is available in [private preview](https://grafana.com/docs/release-life-cycle/) for Grafana Cloud, and is an [experimental feature](https://grafana.com/docs/release-life-cycle/) in Grafana v12 for open source and Enterprise editions.
Support and documentation is available but might be limited to enablement, configuration, and some troubleshooting. No SLAs are provided.
You can sign up to the private preview using the [Git Sync early access form](https://forms.gle/WKkR3EVMcbqsNnkD9).
{{< /admonition >}}
After you have set up Git Sync, you can synchronize any changes you make in your existing provisioned folders in the UI with your configured GitHub repository. Similarly, if you push a change into your repository, those changes are mirrored in your Grafana instance.
## View current status of synchronization
When you synchronize a repository, Git Sync also creates a dashboard that provides a summary of resources, health, pull status, webhook, sync jobs, resources, and files.
Use the **View** section in **Provisioning** to see detailed information about the current status of your sync, understand the health of your repository's connection with Grafana, and [troubleshoot](#troubleshoot-synchronization) possible issues:
1. Log in to your Grafana server with an account that has the Grafana Admin or Editor flag set.
1. Select **Administration** in the left-side menu and then **Provisioning**.
1. Locate the repository you are interested in.
1. If you see a green `Up-to-date` label next to the repository name, then everything is syncing as expected.
1. Select **View** to access detailed dashboards and reports about the synchronization history of your repository.
## Synchronize changes
Synchronizing resources from provisioned repositories into your Grafana instance pulls the resources into the selected folder. Existing dashboards with the same `uid` are overwritten.
To sync changes from your Grafana dashboards with your Git repository:
1. From the left menu, select **Administration** > **Provisioning**.
1. Select **Pull** under the repository you want to sync.
1. Wait for the synchronization process to complete.
## Remove a repository
To delete a repository, follow these steps.
1. Log in to your Grafana server with an account that has the Grafana Admin or Editor flag set.
1. Select **Administration** in the left-side menu and then **Provisioning**.
1. Locate the repository you are interested in.
1. Select the trashcan icon in the right side to delete the chosen entry.
1. Select **Delete** to confirm.
Refer to [Work with provisioned dashboards](../provisioned-dashboards) for information on removing provisioned files.
## Troubleshoot synchronization
{{< admonition type="caution" >}}
Before you proceed to troubleshoot, understand the [known limitations](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/provision-resources/intro-git-sync#known-limitations/).
{{< /admonition >}}
Monitor the **View** status page for synchronization issues and status updates. Common events include:
- Sync started
- Sync completed
- Sync failed (with error details)
- Sync issues
### Dashboard sync errors
- If dashboards are not syncing, check if the repository URL is correct and accessible from the Grafana instance.
- Ensure that the configured repository branch exists and is correctly referenced.
- Check for conflicts in the repository that may prevent syncing.
### Dashboard import errors
- Validate the JSON format of the dashboard files before importing.
- If the import fails, check Grafana logs for error messages and troubleshoot accordingly.
docs/sources/as-code/observability-as-code/schema-v2/_index.md
+243
View File
@@ -0,0 +1,243 @@
---
description: A reference for the JSON dashboard schemas used with Observability as Code, including the experimental V2 schema.
keywords:
- configuration
- as code
- dashboards
- git integration
- git sync
- github
labels:
products:
- cloud
- enterprise
- oss
title: JSON schema v2
weight: 200
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/
aliases:
- ../../observability-as-code/schema-v2/ # /docs/grafana/next/observability-as-code/schema-v2/
---
# Dashboard JSON schema v2
{{< admonition type="caution" >}}
Dashboard JSON schema v2 is an [experimental](https://grafana.com/docs/release-life-cycle/) feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. To get early access to this feature, request it through [this form](https://docs.google.com/forms/d/e/1FAIpQLSd73nQzuhzcHJOrLFK4ef_uMxHAQiPQh1-rsQUT2MRqbeMLpg/viewform?usp=dialog).
**Do not enable this feature in production environments as it may result in the irreversible loss of data.**
{{< /admonition >}}
Grafana dashboards are represented as JSON objects that store metadata, panels, variables, and settings.
Observability as Code works with all versions of the JSON model, and it's fully compatible with version 2.
## Before you begin
Schema v2 is automatically enabled with the Dynamic Dashboards feature toggle.
To get early access to this feature, request it through [this form](https://docs.google.com/forms/d/e/1FAIpQLSd73nQzuhzcHJOrLFK4ef_uMxHAQiPQh1-rsQUT2MRqbeMLpg/viewform?usp=dialog).
It also requires the new dashboards API feature toggle, `kubernetesDashboards`, to be enabled as well.
For more information on how dashboards behave depending on your feature flag configuration, refer to [Notes and limitations](#notes-and-limitations).
## Accessing the JSON Model
To view the JSON representation of a dashboard:
1. Toggle on the edit mode switch in the top-right corner of the dashboard.
1. Click the gear icon in the top navigation bar to go to **Settings**.
1. Select the **JSON Model** tab.
1. Copy or edit the JSON structure as needed.
## JSON fields
```json
{
"annotations": [],
"cursorSync": "Off",
"editable": true,
"elements": {},
"layout": {
"kind": GridLayout, // Can also be AutoGridLayout, RowsLayout, or TabsLayout
"spec": {
"items": []
}
},
"links": [],
"liveNow": false,
"preload": false,
"tags": [], // Tags associated with the dashboard.
"timeSettings": {
"autoRefresh": "",
"autoRefreshIntervals": [
"5s",
"10s",
"30s",
"1m",
"5m",
"15m",
"30m",
"1h",
"2h",
"1d"
],
"fiscalYearStartMonth": 0,
"from": "now-6h",
"hideTimepicker": false,
"timezone": "browser",
"to": "now"
},
"title": "",
"variables": []
},
```
The dashboard JSON sample shown uses the default `GridLayoutKind`.
The JSON in a new dashboard for the other three layout options, `AutoGridLayout`, `RowsLayout`, and `TabsLayout`, are as follows:
**`AutoGridLayout`**
```json
"layout": {
"kind": "AutoGridLayout",
"spec": {
"columnWidthMode": "standard",
"items": [],
"fillScreen": false,
"maxColumnCount": 3,
"rowHeightMode": "standard"
}
},
```
**`RowsLayout`**
```json
"layout": {
"kind": "RowsLayout",
"spec": {
"rows": []
},
```
**`TabsLayout`**
```json
"layout": {
"kind": "TabsLayout",
"spec": {
"tabs": []
},
```
### `DashboardSpec`
The following table explains the usage of the dashboard JSON fields.
The table includes default and other fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ------------ | ------------------------------------------------------------------------- |
| annotations | Contains the list of annotations that are associated with the dashboard. |
| cursorSync | Dashboard cursor sync behavior.<ul><li>`Off` - No shared crosshair or tooltip (default)</li><li>`Crosshair` - Shared crosshair</li><li>`Tooltip` - Shared crosshair and shared tooltip</li></ul> |
| editable | bool. Whether or not a dashboard is editable. |
| elements | Contains the list of elements included in the dashboard. Supported dashboard elements are: PanelKind and LibraryPanelKind. |
| layout | The dashboard layout. Supported layouts are:<ul><li>GridLayoutKind</li><li>AutoGridLayoutKind</li><li>RowsLayoutKind</li><li>TabsLayoutKind</li></ul> |
| links | Links with references to other dashboards or external websites. |
| liveNow | bool. When set to `true`, the dashboard redraws panels at an interval matching the pixel width. This keeps data "moving left" regardless of the query refresh rate. This setting helps avoid dashboards presenting stale live data. |
| preload | bool. When set to `true`, the dashboard loads all panels when the dashboard is loaded. |
| tags | Contains the list of tags associated with dashboard. |
| timeSettings | All time settings for the dashboard. |
| title | Title of the dashboard. |
| variables | Contains the list of configured template variables. |
<!-- prettier-ignore-end -->
### `annotations`
The configuration for the list of annotations that are associated with the dashboard.
For the JSON and field usage notes, refer to the [annotations schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/annotations-schema/).
### `elements`
Dashboards can contain the following elements:
- [PanelKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/panel-schema/)
- [LibraryPanelKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/librarypanel-schema/)
### `layout`
Dashboards can have four layout options:
- [GridLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/#gridlayoutkind)
- [AutoGridLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/#autogridlayoutkind)
- [RowsLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/#rowslayoutkind)
- [TabsLayoutKind](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/#tabslayoutkind)
For the JSON and field usage notes about each of these, refer to the [layout schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/layout-schema/).
### `links`
The configuration for links with references to other dashboards or external websites.
For the JSON and field usage notes, refer to the [links schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/links-schema/).
### `tags`
The tags associated with the dashboard:
` [...string]`
### `timesettings`
The `TimeSettingsSpec` defines the default time configuration for the time picker and the refresh picker for the specific dashboard.
For the JSON and field usage notes about the `TimeSettingsSpec`, refer to the [timesettings schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/timesettings-schema/).
### `variables`
The `variables` schema defines which variables are used in the dashboard.
There are eight variables types:
- QueryVariableKind
- TextVariableKind
- ConstantVariableKind
- DatasourceVariableKind
- IntervalVariableKind
- CustomVariableKind
- GroupByVariableKind
- AdhocVariableKind
For the JSON and field usage notes about the `variables` spec, refer to the [variables schema documentation](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/variables-schema/).
## Notes and limitations
### Existing dashboards
With schema v2 enabled, you can still open and view your pre-existing dashboards.
Upon saving, they’ll be updated to the new schema where you can take advantage of the new features and functionalities.
### Dashboard behavior with disabled feature flags
If you disable the Dynamic dashboards or `kubernetesDashboards` feature flags, you should be aware of how dashboards will behave.
#### Disable Dynamic dashboards
If the Dynamic dashboards feature toggle is disabled, depending on how the dashboard was built, it will behave differently:
- Dashboards built on the new schema through the UI - View only
- Dashboards built on Schema v1 - View and edit
- Dashboards built on the new schema by way of Terraform or the CLI - View and edit
- Provisioned dashboards built on the new schema - View and edit, but the edit experience will be the old experience
#### Disable Dynamic dashboards and `kubernetesDashboards`
You’ll be unable to view or edit dashboards created or updated in the new schema.
### Import and export
From the UI, dashboards created on schema v2 can be exported and imported like other dashboards.
When you export them to use in another instance, references of data sources are not persisted but data source types are.
You’ll have the option to select the data source of your choice in the import UI.
docs/sources/as-code/observability-as-code/schema-v2/annotations-schema.md
+86
View File
@@ -0,0 +1,86 @@
---
description: A reference for the JSON annotations schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- annotations
labels:
products:
- cloud
- enterprise
- oss
menuTitle: annotations schema
title: annotations
weight: 100
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/annotations-schema/
aliases:
- ../../../observability-as-code/schema-v2/annotations-schema/ # /docs/grafana/next/observability-as-code/schema-v2/annotations-schema/
---
# `annotations`
The configuration for the list of annotations that are associated with the dashboard.
```json
"annotations": [
{
"kind": "AnnotationQuery",
"spec": {
"builtIn": false,
"datasource": {
"type": "",
"uid": ""
},
"enable": false,
"hide": false,
"iconColor": "",
"name": ""
}
}
],
```
`AnnotationsQueryKind` consists of:
- kind: "AnnotationQuery"
- spec: [AnnotationQuerySpec](#annotationqueryspec)
## `AnnotationQuerySpec`
| Name | Type/Definition |
| ---------- | ----------------------------------------------------------------- |
| datasource | [`DataSourceRef`](#datasourceref) |
| query | [`DataQueryKind`](#dataquerykind) |
| enable | bool |
| hide | bool |
| iconColor | string |
| name | string |
| builtIn | bool. Default is `false`. |
| filter | [`AnnotationPanelFilter`](#annotationpanelfilter) |
| options | `[string]`: A catch-all field for datasource-specific properties. |
### `DataSourceRef`
| Name | Usage |
| ----- | ---------------------------------- |
| type? | string. The plugin type-id. |
| uid? | The specific data source instance. |
### `DataQueryKind`
| Name | Type |
| ---- | ------ |
| kind | string |
| spec | string |
### `AnnotationPanelFilter`
| Name | Type/Definition |
| -------- | ------------------------------------------------------------------------------ |
| exclude? | bool. Should the specified panels be included or excluded. Default is `false`. |
| ids | `[...uint8]`. Panel IDs that should be included or excluded. |
docs/sources/as-code/observability-as-code/schema-v2/layout-schema.md
+339
View File
@@ -0,0 +1,339 @@
---
description: A reference for the JSON layout schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- layout
labels:
products:
- cloud
- enterprise
- oss
menuTitle: layout schema
title: layout
weight: 400
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/layout-schema/
aliases:
- ../../../observability-as-code/schema-v2/layout-schema/ # /docs/grafana/next/observability-as-code/schema-v2/layout-schema/
---
# `layout`
There are four layout options offering two types of panel control:
**Panel layout options**
These options control the size and position of panels:
- [GridLayoutKind](#gridlayoutkind) - Corresponds to the **Custom** option in the UI. You define panel size and panel positions using x- and y- settings.
- [AutoGridLayoutKind](#autogridlayoutkind) - Corresponds to the **Auto grid** option in the UI. Panel size and position are automatically set based on column and row parameters.
**Panel grouping options**
These options control the grouping of panels:
- [RowsLayoutKind](#rowslayoutkind) - Groups panels into rows.
- [TabsLayoutKind](#tabslayoutkind) - Groups panels into tabs.
## `GridLayoutKind`
The grid layout allows you to manually size and position grid items by setting the height, width, x, and y of each item.
This layout corresponds to the **Custom** option in the UI.
Following is the JSON for a default grid layout, a grid layout item, and a grid layout row:
```json
"kind": "GridLayout",
"spec": {
"items": [
{
"kind": "GridLayoutItem",
"spec": {
"element": {...},
"height": 0,
"width": 0,
"x": 0,
"y": 0
}
},
{
"kind": "GridLayoutRow",
"spec": {
"collapsed": false,
"elements": [],
"title": "",
"y": 0
}
},
]
}
```
`GridLayoutKind` consists of:
- kind: "GridLayout"
- spec: GridLayoutSpec
- items: GridLayoutItemKind` or GridLayoutRowKind`
- GridLayoutItemKind
- kind: "GridLayoutItem"
- spec: [GridLayoutItemSpec](#gridlayoutitemspec)
- GridLayoutRowKind
- kind: "GridLayoutRow"
- spec: [GridLayoutRowSpec](#gridlayoutrowspec)
### `GridLayoutItemSpec`
The following table explains the usage of the grid layout item JSON fields:
| Name | Usage |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| x | integer. Position of the item x-axis. |
| y | integer. Position of the item y-axis. |
| width | Width of the item in pixels. |
| height | Height of the item in pixels. |
| element | `ElementReference`. Reference to a [`PanelKind`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. |
| repeat? | [RepeatOptions](#repeatoptions). Configured repeat options, if any |
#### `RepeatOptions`
The following table explains the usage of the repeat option JSON fields:
| Name | Usage |
| ---------- | ---------------------------------------------------- |
| mode | `RepeatMode` - "variable" |
| value | string |
| direction? | Options are `h` for horizontal and `v` for vertical. |
| maxPerRow? | integer |
### `GridLayoutRowSpec`
The following table explains the usage of the grid layout row JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| y | integer. Position of the row y-axis |
| collapsed | bool. Whether or not the row is collapsed |
| title | Row title |
| elements | [`[...GridLayoutItemKind]`](#gridlayoutitemspec). Grid items in the row will have their y value be relative to the row's y value. This means a panel positioned at `y: 0` in a row with `y: 10` will be positioned at `y: 11` (row header has a height of 1) in the dashboard. |
| repeat? | [RowRepeatOptions](#rowrepeatoptions) Configured row repeat options, if any</p> |
<!-- prettier-ignore-end -->
#### `RowRepeatOptions`
| Name | Usage |
| ----- | ------------------------- |
| mode | `RepeatMode` - "variable" |
| value | string |
## `AutoGridLayoutKind`
With an auto grid, Grafana sizes and positions your panels for the best fit based on the column and row constraints that you set.
This layout corresponds to the **Auto grid** option in the UI.
Following is the JSON for a default auto grid layout and a grid layout item:
<!-- prettier-ignore-end -->
```json
"kind": "AutoGridLayout",
"spec": {
"columnWidthMode": "standard",
"fillScreen": false,
"items": [
{
"kind": "AutoGridLayoutItem",
"spec": {
"element": {...},
}
}
],
"maxColumnCount": 3,
"rowHeightMode": "standard"
}
```
`AutoGridLayoutKind` consists of:
- kind: "AutoGridLayout"
- spec: [AutoGridLayoutSpec](#autogridlayoutspec)
### `AutoGridLayoutSpec`
The following table explains the usage of the auto grid layout JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| maxColumnCount? | number. Default is `3`. |
| columnWidthMode | Options are: `narrow`, `standard`, `wide`, and `custom`. Default is `standard`. |
| columnWidth? | number |
| rowHeightMode | Options are: `short`, `standard`, `tall`, and `custom`. Default is `standard`. |
| rowHeight? | number |
| fillScreen? | bool. Default is `false`. |
| items | `AutoGridLayoutItemKind`. Consists of:<ul><li>kind: "AutoGridLayoutItem"</li><li>spec: [AutoGridLayoutItemSpec](#autogridlayoutitemspec)</li></ul> |
<!-- prettier-ignore-end -->
#### `AutoGridLayoutItemSpec`
The following table explains the usage of the auto grid layout item JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| element | `ElementReference`. Reference to a [`PanelKind`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/observability-as-code/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. |
| repeat? | [AutoGridRepeatOptions](#autogridrepeatoptions). Configured repeat options, if any. |
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
<!-- prettier-ignore-end -->
##### `AutoGridRepeatOptions`
The following table explains the usage of the auto grid repeat option JSON fields:
| Name | Usage |
| ----- | ------------------------- |
| mode | `RepeatMode` - "variable" |
| value | String |
##### `ConditionalRenderingGroupSpec`
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| visibility | Options are `show` and `hide` |
| condition | Options are `and` and `or` |
| items | Options are:<ul><li>ConditionalRenderingVariableKind<ul><li>kind: "ConditionalRenderingVariable"</li><li>spec: [ConditionalRenderingVariableSpec](#conditionalrenderingvariablespec)</li></ul></li><li>ConditionalRenderingDataKind<ul><li>kind: "ConditionalRenderingData"</li><li>spec: [ConditionalRenderingDataSpec](#conditionalrenderingdataspec)</li></ul></li><li>ConditionalRenderingTimeRangeSizeKind<ul><li>kind: "ConditionalRenderingTimeRangeSize"</li><li>spec: [ConditionalRenderingTimeRangeSizeSpec](#conditionalrenderingtimerangesizespec)</li></ul></li></ul> |
<!-- prettier-ignore-end -->
###### `ConditionalRenderingVariableSpec`
| Name | Usage |
| -------- | ------------------------------------ |
| variable | string |
| operator | Options are `equals` and `notEquals` |
| value | string |
###### `ConditionalRenderingDataSpec`
| Name | Type |
| ----- | ---- |
| value | bool |
###### `ConditionalRenderingTimeRangeSizeSpec`
| Name | Type |
| ----- | ------ |
| value | string |
## `RowsLayoutKind`
The `RowsLayoutKind` is one of two options that you can use to group panels.
You can nest any other kind of layout inside a layout row.
Rows can also be nested in auto grids or tabs.
Following is the JSON for a default rows layout row:
```json
"kind": "RowsLayout",
"spec": {
"rows": [
{
"kind": "RowsLayoutRow",
"spec": {
"layout": {
"kind": "GridLayout", // Can also be AutoGridLayout or TabsLayout
"spec": {...}
},
"title": ""
}
}
]
}
```
`RowsLayoutKind` consists of:
- kind: RowsLayout
- spec: RowsLayoutSpec
- rows: RowsLayoutRowKind
- kind: RowsLayoutRow
- spec: [RowsLayoutRowSpec](#rowslayoutrowspec)
### `RowsLayoutRowSpec`
The following table explains the usage of the rows layout row JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| title? | Title of the row. |
| collapse | bool. Whether or not the row is collapsed. |
| hideHeader? | bool. Whether the row header is hidden or shown. |
| fullScreen? | bool. Whether or not the row takes up the full screen. |
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing rows, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
| repeat? | [RowRepeatOptions](#rowrepeatoptions). Configured repeat options, if any. |
| layout | Supported layouts are:<ul><li>[GridLayoutKind](#gridlayoutkind)</li><li>[RowsLayoutKind](#rowslayoutkind)</li><li>[AutoGridLayoutKind](#autogridlayoutkind)</li><li>[TabsLayoutKind](#tabslayoutkind)</li></ul> |
<!-- prettier-ignore-end -->
## `TabsLayoutKind`
The `TabsLayoutKind` is one of two options that you can use to group panels.
You can nest any other kind of layout inside a tab.
Tabs can also be nested in auto grids or rows.
Following is the JSON for a default tabs layout tab and a tab:
```json
"kind": "TabsLayout",
"spec": {
"tabs": [
{
"kind": "TabsLayoutTab",
"spec": {
"layout": {
"kind": "GridLayout", // Can also be AutoGridLayout or RowsLayout
"spec": {...}
},
"title": "New tab"
}
}
]
}
```
`TabsLayoutKind` consists of:
- kind: TabsLayout
- spec: TabsLayoutSpec
- tabs: TabsLayoutTabKind
- kind: TabsLayoutTab
- spec: [TabsLayoutTabSpec](#tabslayouttabspec)
### `TabsLayoutTabSpec`
The following table explains the usage of the tabs layout tab JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| title? | The title of the tab. |
| layout | Supported layouts are:<ul><li>[GridLayoutKind](#gridlayoutkind)</li><li>[RowsLayoutKind](#rowslayoutkind)</li><li>[AutoGridLayoutKind](#autogridlayoutkind)</li><li>[TabsLayoutKind](#tabslayoutkind)</li></ul> |
| conditionalRendering? | `ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of:<ul><li>kind: "ConditionalRenderingGroup"</li><li>spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)</li></ul> |
<!-- prettier-ignore-end -->
docs/sources/as-code/observability-as-code/schema-v2/librarypanel-schema.md
+68
View File
@@ -0,0 +1,68 @@
---
description: A reference for the JSON library panel schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- library panel
labels:
products:
- cloud
- enterprise
- oss
menuTitle: LibraryPanelKind schema
title: LibraryPanelKind
weight: 300
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/librarypanel-schema/
aliases:
- ../../../observability-as-code/schema-v2/librarypanel-schema/ # /docs/grafana/next/observability-as-code/schema-v2/librarypanel-schema/
---
# `LibraryPanelKind`
A library panel is a reusable panel that you can use in any dashboard.
When you make a change to a library panel, that change propagates to all instances of where the panel is used.
Library panels streamline reuse of panels across multiple dashboards.
Following is the default library panel element JSON:
```json
"kind": "LibraryPanel",
"spec": {
"id": 0,
"libraryPanel": {
name: "",
uid: "",
}
"title": ""
}
```
The `LibraryPanelKind` consists of:
- kind: "LibraryPanel"
- spec: [LibraryPanelKindSpec](#librarypanelkindspec)
- libraryPanel: [LibraryPanelRef](#librarypanelref)
## `LibraryPanelKindSpec`
The following table explains the usage of the library panel element JSON fields:
| Name | Usage |
| ------------ | ------------------------------------------------ |
| id | Panel ID for the library panel in the dashboard. |
| libraryPanel | [`LibraryPanelRef`](#librarypanelref) |
| title | Title for the library panel in the dashboard. |
### `LibraryPanelRef`
The following table explains the usage of the library panel reference JSON fields:
| Name | Usage |
| ---- | ------------------ |
| name | Library panel name |
| uid | Library panel uid |
docs/sources/as-code/observability-as-code/schema-v2/links-schema.md
+66
View File
@@ -0,0 +1,66 @@
---
description: A reference for the JSON links schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- links
labels:
products:
- cloud
- enterprise
- oss
menuTitle: links schema
title: links
weight: 500
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/links-schema/
aliases:
- ../../../observability-as-code/schema-v2/links-schema/ # /docs/grafana/next/observability-as-code/schema-v2/links-schema/
---
# `links`
The `links` schema is the configuration for links with references to other dashboards or external websites.
Following are the default JSON fields:
```json
"links": [
{
"asDropdown": false,
"icon": "",
"includeVars": false,
"keepTime": false,
"tags": [],
"targetBlank": false,
"title": "",
"tooltip": "",
"type": "link",
},
],
```
## `DashboardLink`
The following table explains the usage of the dashboard link JSON fields.
The table includes default and other fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ----------- | --------------------------------------- |
| title | string. Title to display with the link. |
| type | `DashboardLinkType`. Link type. Accepted values are:<ul><li>dashboards - To refer to another dashboard</li><li>link - To refer to an external resource</li></ul> |
| icon | string. Icon name to be displayed with the link. |
| tooltip | string. Tooltip to display when the user hovers their mouse over it. |
| url? | string. Link URL. Only required/valid if the type is link. |
| tags | string. List of tags to limit the linked dashboards. If empty, all dashboards will be displayed. Only valid if the type is dashboards. |
| asDropdown | bool. If true, all dashboards links will be displayed in a dropdown. If false, all dashboards links will be displayed side by side. Only valid if the type is dashboards. Default is `false`. |
| targetBlank | bool. If true, the link will be opened in a new tab. Default is `false`. |
| includeVars | bool. If true, includes current template variables values in the link as query params. Default is `false`. |
| keepTime | bool. If true, includes current time range in the link as query params. Default is `false`. |
<!-- prettier-ignore-end -->
docs/sources/as-code/observability-as-code/schema-v2/panel-schema.md
+305
View File
@@ -0,0 +1,305 @@
---
description: A reference for the JSON panel schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- panels
labels:
products:
- cloud
- enterprise
- oss
menuTitle: PanelKind schema
title: PanelKind
weight: 200
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/panel-schema/
aliases:
- ../../../observability-as-code/schema-v2/panel-schema/ # /docs/grafana/next/observability-as-code/schema-v2/panel-schema/
---
# `PanelKind`
The panel element contains all the information about the panel including the visualization type, panel and visualization configuration, queries, and transformations.
There's a panel element for each panel contained in the dashboard.
Following is the default panel element JSON:
```json
"kind": "Panel",
"spec": {
"data": {
"kind": "QueryGroup",
"spec": {...},
"description": "",
"id": 0,
"links": [],
"title": "",
"vizConfig": {
"kind": "",
"spec": {...},
}
}
```
The `PanelKind` consists of:
- kind: "Panel"
- spec: [PanelSpec](#panelspec)
## `PanelSpec`
The following table explains the usage of the panel element JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ------------ | --------------------------------------------------------------------- |
| data | `QueryGroupKind`, which includes queries and transformations. Consists of:<ul><li>kind: "QueryGroup"</li><li>spec: [QueryGroupSpec](#querygroupspec)</li></ul> |
| description | The panel description. |
| id | The panel ID. |
| links | Links with references to other dashboards or external websites. |
| title | The panel title. |
| vizConfig | `VizConfigKind`. Includes visualization type, field configuration options, and all other visualization options. Consists of:<ul><li>kind: string. Plugin ID.</li><li>spec: [VizConfigSpec](#vizconfigspec)</li></ul> |
| transparent? | bool. Controls whether or not the panel background is transparent. |
<!-- prettier-ignore-end -->
### `QueryGroupSpec`
<!-- prettier-ignore-start -->
| Name | Usage |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| queries | `PanelQueryKind`. Consists of:<ul><li>kind: PanelQuery</li><li>spec: [PanelQuerySpec](#panelqueryspec)</li></ul> |
| transformations | `TransformationKind`. Consists of:<ul><li>kind: string. The transformation ID.</li><li>spec: [DataTransformerConfig](#datatransformerconfig)</li></ul> |
| queryOptions | [`QueryOptionsSpec`](#queryoptionsspec) |
<!-- prettier-ignore-end -->
#### `PanelQuerySpec`
| Name | Usage |
| ----------- | --------------------------------- |
| query | [`DataQueryKind`](#dataquerykind) |
| datasource? | [`DataSourceRef`](#datasourceref) |
##### `DataQueryKind`
| Name | Type |
| ---- | ------ |
| kind | string |
| spec | string |
##### `DataSourceRef`
| Name | Usage |
| ----- | ---------------------------------- |
| type? | string. The plugin type-id. |
| uid? | The specific data source instance. |
#### `DataTransformerConfig`
Transformations allow you to manipulate data returned by a query before the system applies a visualization.
Using transformations you can: rename fields, join time series data, perform mathematical operations across queries, or use the output of one transformation as the input to another transformation.
<!-- prettier-ignore-start -->
| Name | Usage |
| --------- | ------------------------------------------- |
| id | string. Unique identifier of transformer. |
| disabled? | bool. Disabled transformations are skipped. |
| filter? | [`MatcherConfig`](#matcherconfig). Optional frame matcher. When missing it will be applied to all results. |
| topic? | `DataTopic`. Where to pull `DataFrames` from as input to transformation. Options are: `series`, `annotations`, and `alertStates`. |
| options | Options to be passed to the transformer. Valid options depend on the transformer id. |
<!-- prettier-ignore-end -->
##### `MatcherConfig`
Matcher is a predicate configuration.
Based on the configuration a set of field or values, it's filtered to apply an override or transformation.
It comes with in id (to resolve implementation from registry) and a configuration that’s specific to a particular matcher type.
| Name | Usage |
| -------- | -------------------------------------------------------------------------------------- |
| id | string. The matcher id. This is used to find the matcher implementation from registry. |
| options? | The matcher options. This is specific to the matcher implementation. |
#### `QueryOptionsSpec`
| Name | Type |
| ----------------- | ------- |
| timeFrom? | string |
| maxDataPoints? | integer |
| timeShift? | string |
| queryCachingTTL? | integer |
| interval? | string |
| cacheTimeout? | string |
| hideTimeOverride? | bool |
### `VizConfigSpec`
| Name | Type/Definition |
| ------------- | --------------------------------------- |
| pluginVersion | string |
| options | string |
| fieldConfig | [FieldConfigSource](#fieldconfigsource) |
#### `FieldConfigSource`
The data model used in Grafana, namely the _data frame_, is a columnar-oriented table structure that unifies both time series and table query results.
Each column within this structure is called a field.
A field can represent a single time series or table column.
Field options allow you to change how the data is displayed in your visualizations.
<!-- prettier-ignore-start -->
| Name | Type/Definition |
| ---------- | ------------------------------------- |
| defaults | [`FieldConfig`](#fieldconfig). Defaults are the options applied to all fields. |
| overrides | The options applied to specific fields overriding the defaults. |
| matcher | [`MatcherConfig`](#matcherconfig). Optional frame matcher. When missing it will be applied to all results. |
| properties | `DynamicConfigValue`. Consists of:<ul><li>`id` - string</li><li>value?</li></ul> |
<!-- prettier-ignore-end -->
##### `FieldConfig`
<!-- prettier-ignore-start -->
| Name | Type/Definition |
| ------------------ | --------------------------------------- |
| displayName? | string. The display value for this field. This supports template variables where empty is auto. |
| displayNameFromDS? | string. This can be used by data sources that return an explicit naming structure for values and labels. When this property is configured, this value is used rather than the default naming strategy. |
| description? | string. Human readable field metadata. |
| path? | string. An explicit path to the field in the data source. When the frame meta includes a path, this will default to `${frame.meta.path}/${field.name}`. When defined, this value can be used as an identifier within the data source scope, and may be used to update the results. |
| writeable? | bool. True if the data source can write a value to the path. Auth/authz are supported separately. |
| filterable? | bool. True if the data source field supports ad-hoc filters. |
| unit? | string. Unit a field should use. The unit you select is applied to all fields except time. You can use the unit's ID available in Grafana or a custom unit. [Available units in Grafana](https://github.com/grafana/grafana/blob/main/packages/grafana-data/src/valueFormats/categories.ts). As custom units, you can use the following formats:<ul><li>`suffix:<suffix>` for custom unit that should go after value.</li><li>`prefix:<prefix>` for custom unit that should go before value.</li><li> `time:<format>` for custom date time formats type for example</li><li>`time:YYYY-MM-DD`</li><li>`si:<base scale><unit characters>` for custom SI units. For example: `si: mF`. You can specify both a unit and the source data scale, so if your source data is represented as milli (thousands of) something, prefix the unit with that SI scale character.</li><li>`count:<unit>` for a custom count unit.</li><li>`currency:<unit>` for custom a currency unit.</li></ul> |
| decimals? | number. Specify the number of decimals Grafana includes in the rendered value. If you leave this field blank, Grafana automatically truncates the number of decimals based on the value. For example 1.1234 will display as 1.12 and 100.456 will display as 100. To display all decimals, set the unit to `string`. |
| min? | number. The minimum value used in percentage threshold calculations. Leave empty for auto calculation based on all series and fields. |
| max? | number. The maximum value used in percentage threshold calculations. Leave empty for auto calculation based on all series and fields. |
| mappings? | `[...ValueMapping]`. Convert input values into a display string. Options are: [`ValueMap`](#valuemap), [`RangeMap`](#rangemap), [`RegexMap`](#rangemap), [`SpecialValueMap`](#specialvaluemap). |
| thresholds? | `ThresholdsConfig`. Map numeric values to states. Consists of:<ul><li>`mode` - `ThresholdsMode`. Options are: `absolute` and `percentage`.</li><li>`steps` - `[...Threshold]`</li></ul> |
| color? | [`FieldColor`](#fieldcolor). Panel color configuration. |
| links? | `[...]`. The behavior when clicking a result. |
| noValue? | string. Alternative to an empty string. |
| custom? | `{...}`. Specified by the `FieldConfig` field in panel plugin schemas. |
<!-- prettier-ignore-end -->
###### `ValueMap`
Maps text values to a color or different display text and color.
For example, you can configure a value mapping so that all instances of the value 10 appear as Perfection! rather than the number.
<!-- prettier-ignore-start -->
| Name | Usage |
| ------- | -------- |
| type | `MappingType` & "value". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
| options | string. [`ValueMappingResult`](#valuemappingresult). Map with `<value_to_match>`: `ValueMappingResult`. For example: `{ "10": { text: "Perfection!", color: "green" } }`. |
<!-- prettier-ignore-end -->
###### `RangeMap`
Maps numerical ranges to a display text and color.
For example, if a value is within a certain range, you can configure a range value mapping to display Low or High rather than the number.
<!-- prettier-ignore-start -->
| Name | Usage |
| ------- | ---------------------------------------------------------------------------------------------------- |
| type | `MappingType` & "range". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
| options | Range to match against and the result to apply when the value is within the range. Spec:<ul><li>`from` - `float64` or `null`. Min value of the range. It can be null which means `-Infinity`.</li><li>`to` - `float64` or `null`. Max value of the range. It can be null which means `+Infinity`.</li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
<!-- prettier-ignore-end -->
###### `RegexMap`
Maps regular expressions to replacement text and a color.
For example, if a value is `www.example.com`, you can configure a regex value mapping so that Grafana displays www and truncates the domain.
<!-- prettier-ignore-start -->
| Name | Usage |
| ------- | --------------------------------------------------------------------------------------------- |
| type | `MappingType` & "regex". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
| options | Regular expression to match against and the result to apply when the value matches the regex. Spec:<ul><li>`pattern` - string. Regular expression to match against.</li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
<!-- prettier-ignore-end -->
###### `SpecialValueMap`
Maps special values like Null, NaN (not a number), and boolean values like true and false to a display text and color.
See `SpecialValueMatch` in the following table to see the list of special values.
For example, you can configure a special value mapping so that null values appear as N/A.
<!-- prettier-ignore-start -->
| Name | Usage |
| ------- | ----------------------------------------------------------------------------------------------- |
| type | `MappingType` & "special". `MappingType` options are: `value`, `range`, `regex`, and `special`. |
| options | Spec:<ul><li>`match` - `SpecialValueMatch`. Special value to match against. Types are:<ul><li>true</li><li>false</li><li>null</li><li>nan</li><li>empty</li></ul> </li><li>`result` - [`ValueMappingResult`](#valuemappingresult) |
<!-- prettier-ignore-end -->
###### `ValueMappingResult`
Result used as replacement with text and color when the value matches.
| Name | Usage |
| ----- | ----------------------------------------------------------------------------- |
| text | string. Text to display when the value matches. |
| color | string. Color to use when the value matches. |
| icon | string. Icon to display when the value matches. Only specific visualizations. |
| index | int32. Position in the mapping array. Only used internally. |
###### `FieldColor`
Map a field to a color.
<!-- prettier-ignore-start -->
| Name | Usage |
| ----------- | -------------------------------------------------------------------- |
| mode | [`FieldColorModeId`](#fieldcolormodeid). The main color scheme mode. |
| FixedColor? | string. The fixed color value for fixed or shades color modes. |
| seriesBy? | `FieldColorSeriesByMode`. Some visualizations need to know how to assign a series color from by value color schemes. Defines how to assign a series color from "by value" color schemes. For example for an aggregated data points like a timeseries, the color can be assigned by the min, max or last value. Options are: `min`, `max`, and `last`. |
<!-- prettier-ignore-end -->
###### `FieldColorModeId`
Color mode for a field.
You can specify a single color, or select a continuous (gradient) color schemes, based on a value.
Continuous color interpolates a color using the percentage of a value relative to min and max.
Accepted values are:
<!-- prettier-ignore-start -->
| Name | Description |
| --- | ---- |
| thresholds | From thresholds. Informs Grafana to take the color from the matching threshold. |
| palette-classic | Classic palette. Grafana will assign color by looking up a color in a palette by series index. Useful for graphs and pie charts and other categorical data visualizations. |
| palette-classic-by-name | Classic palette (by name). Grafana will assign color by looking up a color in a palette by series name. Useful for Graphs and pie charts and other categorical data visualizations |
| continuous-GrYlRd | Continuous Green-Yellow-Red palette mode |
| continuous-RdYlGr | Continuous Red-Yellow-Green palette mode |
| continuous-BlYlRd | Continuous Blue-Yellow-Red palette mode |
| continuous-YlRd | Continuous Yellow-Red palette mode |
| continuous-BlPu | Continuous Blue-Purple palette mode |
| continuous-YlBl | Continuous Yellow-Blue palette mode |
| continuous-blues | Continuous Blue palette mode |
| continuous-reds | Continuous Red palette mode |
| continuous-greens | Continuous Green palette mode |
| continuous-purples | Continuous Purple palette mode |
| shades | Shades of a single color. Specify a single color, useful in an override rule. |
| fixed | Fixed color mode. Specify a single color, useful in an override rule. |
<!-- prettier-ignore-end -->
docs/sources/as-code/observability-as-code/schema-v2/timesettings-schema.md
+87
View File
@@ -0,0 +1,87 @@
---
description: A reference for the JSON timesettings schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- time settings
labels:
products:
- cloud
- enterprise
- oss
menuTitle: timesettings schema
title: timesettings
weight: 600
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/timesettings-schema/
aliases:
- ../../../observability-as-code/schema-v2/timesettings-schema/ # /docs/grafana/next/observability-as-code/schema-v2/timesettings-schema/
---
# `timeSettings`
The `TimeSettingsSpec` defines the default time configuration for the time picker and the refresh picker for the specific dashboard.
Following is the JSON for default time settings:
```json
"timeSettings": {
"autoRefresh": "",
"autoRefreshIntervals": [
"5s",
"10s",
"30s",
"1m",
"5m",
"15m",
"30m",
"1h",
"2h",
"1d"
],
"fiscalYearStartMonth": 0,
"from": "now-6h",
"hideTimepicker": false,
"timezone": "browser",
"to": "now"
},
```
`timeSettings` consists of:
- [TimeSettingsSpec](#timesettingsspec)
## `TimeSettingsSpec`
The following table explains the usage of the time settings JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ---- | ----- |
| timezone? | string. Timezone of dashboard. Accepted values are IANA TZDB zone ID, `browser`, or `utc`. Default is `browser`. |
| from | string. Start time range for dashboard. Accepted values are relative time strings like `now-6h` or absolute time strings like `2020-07-10T08:00:00.000Z`. Default is `now-6h`. |
| to | string. End time range for dashboard. Accepted values are relative time strings like `now-6h` or absolute time strings like `2020-07-10T08:00:00.000Z`. Default is `now`. |
| autoRefresh | string. Refresh rate of dashboard. Represented by interval string. For example: `5s`, `1m`, `1h`, `1d`. No default. In schema v1: `refresh`. |
| autoRefreshIntervals | string. Interval options available in the refresh picker drop-down menu. The default array is `["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"]`. |
|quickRanges? | Selectable options available in the time picker drop-down menu. Has no effect on provisioned dashboard. Defined in the [`TimeRangeOption`](#timerangeoption) spec. In schema v1: `timepicker.quick_ranges`, not exposed in the UI. |
| hideTimepicker | bool. Whether or not the time picker is visible. Default is `false`. In schema v1: `timepicker.hidden`. |
| weekStart? | Day when the week starts. Expressed by the name of the day in lowercase. For example: `monday`. Options are `saturday`, `monday`, and `sunday`. |
| fiscalYearStartMonth | The month that the fiscal year starts on. `0` = January, `11` = December |
| nowDelay? | string. Override the "now" time by entering a time delay. Use this option to accommodate known delays in data aggregation to avoid null values. In schema v1: `timepicker.nowDelay`. |
<!-- prettier-ignore-end -->
### `TimeRangeOption`
The following table explains the usage of the time range option JSON fields:
| Name | Usage |
| ------- | ---------------------------------- |
| display | string. Default is `Last 6 hours`. |
| from | string. Default is `now-6h`. |
| to | string. Default is `now`. |
docs/sources/as-code/observability-as-code/schema-v2/variables-schema.md
+501
View File
@@ -0,0 +1,501 @@
---
description: A reference for the JSON variables schema used with Observability as Code.
keywords:
- configuration
- as code
- as-code
- dashboards
- git integration
- git sync
- github
- variables
labels:
products:
- cloud
- enterprise
- oss
menuTitle: variables schema
title: variables
weight: 700
canonical: https://grafana.com/docs/grafana/latest/as-code/observability-as-code/schema-v2/variables-schema/
aliases:
- ../../../observability-as-code/schema-v2/variables-schema/ # /docs/grafana/next/observability-as-code/schema-v2/variables-schema/
---
# `variables`
The available variable types described in the following sections:
- [QueryVariableKind](#queryvariablekind)
- [TextVariableKind](#textvariablekind)
- [ConstantVariableKind](#constantvariablekind)
- [DatasourceVariableKind](#datasourcevariablekind)
- [IntervalVariableKind](#intervalvariablekind)
- [CustomVariableKind](#customvariablekind)
- [SwitchVariableKind](#switchvariablekind)
- [GroupByVariableKind](#groupbyvariablekind)
- [AdhocVariableKind](#adhocvariablekind)
## `QueryVariableKind`
Following is the JSON for a default query variable:
```json
"variables": [
{
"kind": "QueryVariable",
"spec": {
"current": {
"text": "",
"value": ""
},
"hide": "dontHide",
"includeAll": false,
"multi": false,
"name": "",
"options": [],
"query": defaultDataQueryKind(),
"refresh": "never",
"regex": "",
"skipUrlSync": false,
"sort": "disabled"
}
}
]
```
`QueryVariableKind` consists of:
- kind: "QueryVariable"
- spec: [QueryVariableSpec](#queryvariablespec)
### `QueryVariableSpec`
The following table explains the usage of the query variable JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| ------------ | ---------------------------------------------- |
| name | string. Name of the variable. |
| current | "Text" and a "value" or [`VariableOption`](#variableoption) |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
| datasource? | [`DataSourceRef`](#datasourceref) |
| query | `DataQueryKind`. Consists of:<ul><li>kind: string</li><li>spec: string</li></ul> |
| regex | string |
| sort | `VariableSort`. Options are:<ul><li>disabled</li><li>alphabeticalAsc</li><li>alphabeticalDesc</li><li>numericalAsc</li><li>numericalDesc</li><li>alphabeticalCaseInsensitiveAsc</li><li>alphabeticalCaseInsensitiveDesc</li><li>naturalAsc</li><li>naturalDesc</li></ul> |
| definition? | string |
| options | [`VariableOption`](#variableoption) |
| multi | bool. Default is `false`. |
| includeAll | bool. Default is `false`. |
| allValue? | string |
| placeholder? | string |
<!-- prettier-ignore-end -->
#### `VariableOption`
| Name | Usage |
| -------- | -------------------------------------------- |
| selected | bool. Whether or not the option is selected. |
| text | string. Text to be displayed for the option. |
| value | string. Value of the option. |
#### `DataSourceRef`
| Name | Usage |
| ----- | ---------------------------------- |
| type? | string. The plugin type-id. |
| uid? | The specific data source instance. |
## `TextVariableKind`
Following is the JSON for a default text variable:
```json
"variables": [
{
"kind": "TextVariable",
"spec": {
"current": {
"text": "",
"value": ""
},
"hide": "dontHide",
"name": "",
"query": "",
"skipUrlSync": false
}
}
]
```
`TextVariableKind` consists of:
- kind: TextVariableKind
- spec: [TextVariableSpec](#textvariablespec)
### `TextVariableSpec`
The following table explains the usage of the query variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| current | "Text" and a "value" or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| query | string |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
## `ConstantVariableKind`
Following is the JSON for a default constant variable:
```json
"variables": [
{
"kind": "ConstantVariable",
"spec": {
"current": {
"text": "",
"value": ""
},
"hide": "hideVariable",
"name": "",
"query": "",
"skipUrlSync": true
}
}
]
```
`ConstantVariableKind` consists of:
- kind: "ConstantVariable"
- spec: [ConstantVariableSpec](#constantvariablespec)
### `ConstantVariableSpec`
The following table explains the usage of the constant variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| query | string |
| current | "Text" and a "value" or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
## `DatasourceVariableKind`
Following is the JSON for a default data source variable:
```json
"variables": [
{
"kind": "DatasourceVariable",
"spec": {
"current": {
"text": "",
"value": ""
},
"hide": "dontHide",
"includeAll": false,
"multi": false,
"name": "",
"options": [],
"pluginId": "",
"refresh": "never",
"regex": "",
"skipUrlSync": false
}
}
]
```
`DatasourceVariableKind` consists of:
- kind: "DatasourceVariable"
- spec: [DatasourceVariableSpec](#datasourcevariablespec)
### `DatasourceVariableSpec`
The following table explains the usage of the data source variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| pluginId | string |
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
| regex | string |
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| multi | bool. Default is `false`. |
| includeAll | bool. Default is `false`. |
| allValue? | string |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
## `IntervalVariableKind`
Following is the JSON for a default interval variable:
```json
"variables": [
{
"kind": "IntervalVariable",
"spec": {
"auto": false,
"auto_count": 0,
"auto_min": "",
"current": {
"text": "",
"value": ""
},
"hide": "dontHide",
"name": "",
"options": [],
"query": "",
"refresh": "never",
"skipUrlSync": false
}
}
]
```
`IntervalVariableKind` consists of:
- kind: "IntervalVariable"
- spec: [IntervalVariableSpec](#intervalvariablespec)
### `IntervalVariableSpec`
The following table explains the usage of the interval variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| query | string |
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| auto | bool. Default is `false`. |
| auto_count | integer. Default is `0`. |
| refresh | `VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false` |
| description? | string |
## `CustomVariableKind`
Following is the JSON for a default custom variable:
```json
"variables": [
{
"kind": "CustomVariable",
"spec": {
"current": defaultVariableOption(),
"hide": "dontHide",
"includeAll": false,
"multi": false,
"name": "",
"options": [],
"query": "",
"skipUrlSync": false
}
}
]
```
`CustomVariableKind` consists of:
- kind: "CustomVariable"
- spec: [CustomVariableSpec](#customvariablespec)
### `CustomVariableSpec`
The following table explains the usage of the custom variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| query | string |
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| multi | bool. Default is `false`. |
| includeAll | bool. Default is `false`. |
| allValue? | string |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
## `SwitchVariableKind`
Following is the JSON for a default switch variable:
```json
"variables": [
{
"kind": "SwitchVariable",
"spec": {
"current": "false",
"enabledValue": "true",
"disabledValue": "false",
"hide": "dontHide",
"name": "",
"skipUrlSync": false
}
}
]
```
`SwitchVariableKind` consists of:
- kind: "SwitchVariable"
- spec: [SwitchVariableSpec](#switchvariablespec)
### `SwitchVariableSpec`
The following table explains the usage of the switch variable JSON fields:
<!-- prettier-ignore-start -->
| Name | Usage |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| current | string. Current value of the switch variable (either `enabledValue` or `disabledValue`). |
| enabledValue | string. Value when the switch is in the enabled state. |
| disabledValue | string. Value when the switch is in the disabled state. |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
<!-- prettier-ignore-end -->
## `GroupByVariableKind`
Following is the JSON for a default group by variable:
```json
"variables": [
{
"kind": "GroupByVariable",
"spec": {
"current": {
"text": [
""
],
"value": [
""
]
},
"datasource": {},
"hide": "dontHide",
"multi": false,
"name": "",
"options": [],
"skipUrlSync": false
}
}
]
```
`GroupByVariableKind` consists of:
- kind: "GroupByVariable"
- spec: [GroupByVariableSpec](#groupbyvariablespec)
### `GroupByVariableSpec`
The following table explains the usage of the group by variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable |
| datasource? | `DataSourceRef`. Refer to the [`DataSourceRef` definition](#datasourceref) under `QueryVariableKind`. |
| current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. |
| multi | bool. Default is `false`. |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string. |
## `AdhocVariableKind`
Following is the JSON for a default ad hoc variable:
```json
"variables": [
{
"kind": "AdhocVariable",
"spec": {
"baseFilters": [],
"defaultKeys": [],
"filters": [],
"hide": "dontHide",
"name": "",
"skipUrlSync": false
}
}
]
```
`AdhocVariableKind` consists of:
- kind: "AdhocVariable"
- spec: [AdhocVariableSpec](#adhocvariablespec)
### `AdhocVariableSpec`
The following table explains the usage of the ad hoc variable JSON fields:
| Name | Usage |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string. Name of the variable. |
| datasource? | `DataSourceRef`. Consists of:<ul><li>type? - string. The plugin type-id.</li><li>uid? - string. The specific data source instance.</li></ul> |
| baseFilters | [AdHocFilterWithLabels](#adhocfilterswithlabels) |
| filters | [AdHocFilterWithLabels](#adhocfilterswithlabels) |
| defaultKeys | [MetricFindValue](#metricfindvalue) |
| label? | string |
| hide | `VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. |
| skipUrlSync | bool. Default is `false`. |
| description? | string |
#### `AdHocFiltersWithLabels`
The following table explains the usage of the ad hoc variable with labels JSON fields:
| Name | Type |
| ------------ | ------------- |
| key | string |
| operator | string |
| value | string |
| values? | `[...string]` |
| keyLabel | string |
| valueLabels? | `[...string]` |
| forceEdit? | bool |
#### `MetricFindValue`
The following table explains the usage of the metric find value JSON fields:
| Name | Type |
| ----------- | ---------------- |
| text | string |
| value? | string or number |
| group? | string |
| expandable? | bool |