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

Restructure As code and developer resources (#113845)

Browse Source
This commit is contained in:
Jack Baldry
2025-11-13 14:04:57 +00:00
committed by GitHub
parent 0d67fac87f
commit 7fe5772888
96 changed files with 8108 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
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).