Creating and managing 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.

Prerequisites

Before you begin, you should have the following available:

A Grafana Cloud account.
Ansible installed on your machine

Create a Cloud stack

Create a Grafana Cloud API key. You’ll need this for the Ansible playbook to be able to create a Grafana Cloud stack. See Create a Grafana Cloud API key.

Create an Ansible playbook file.

This Ansible playbook will create a Grafana Cloud stack by calling the Cloud stack API using the Ansible’s builtin uri module.

Create a file named cloud-stack.yml and add the following:

- name: Create Grafana Cloud stack
  connection: local
  hosts: localhost

  vars:
    cloud_api_key: "<cloud-API-Key>"
    stacks: [
      { name: "<stack-name>", region: "<region>" },
    ]
    org_name: "<org-name>"

  tasks:
    - name: List all existing stacks
      uri:
        url: "https://grafana.com/api/orgs/{{ org_name }}/instances"
        method: GET
        headers:
          Authorization: Bearer {{ cloud_api_key }}
      register: check_stacks

    - name: Extract existing Grafana Cloud stack names
      set_fact:
        existing_stack_names: "{{ existing_stack_names | default ([]) + [item.value] }}"
      with_items: "{{ lookup('ansible.builtin.dict', check_stacks.json) }}"
      when: "'items' in item.key"
      no_log: true

    - name: Create a list of Grafana Cloud existing stacks
      set_fact:
        existing_stacks: "{{ existing_stacks | default ([]) + [item.slug] }}"
      with_items: "{{ existing_stack_names }}"
      no_log: true

    - name: Create Grafana Cloud stack
      uri:
        url: https://grafana.com/api/instances
        method: POST
        body_format: json
        body:
          {
            name: "{{ item.name }}",
            slug: "{{ item.name }}",
            region: "{{ item.region | default('us') }}"
          }
        headers:
          Authorization: Bearer {{ cloud_api_key }}
      when: item.name is not in (existing_stacks | default ([]))
      loop: "{{ stacks }}"

Replace the following field values:
- <cloud-API-Key> with the API key you created in the Grafana Cloud portal.
- <stack-name> with the name of your stack.
- <region> with the region in which you want to create the stack. For example us, eu.
- <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.

Log into your Grafana Cloud instance.
Open settings(Gear icon) and select the API Keys option.
Click Add API Key.
In Key Name, enter a name for your API key.
In Role, select the Admin or Editor role to associate with this API key.
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.

Create a file named data-source.yml and add the following:

- 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_url: <grafana-url>
    api_key: <API-key>

  tasks:
    - name: List all existing data sources
      uri:
        url: "{{ grafana_url }}/api/datasources"
        method: GET
        headers:
          Authorization: Bearer {{ api_key }}
      register: check_data_sources
      no_log: True

    - name: Create list of existing data sources
      set_fact:
        existing_data_sources: "{{ existing_data_sources | default ([]) + [item.name] }}"
      loop: "{{ check_data_sources.json }}"
      no_log: True

    - name: Update data sources
      uri:
        url: "{{ grafana_url }}/api/datasources/uid/{{ item.uid }}"
        method: PUT
        body_format: json
        body: "{{ item }}"
        headers:
          Authorization: Bearer {{ api_key }}
      when:  item.name is in (existing_data_sources | default ([]))
      loop: "{{ data_sources }}"

    - name: Add data sources
      uri:
        url: "{{ grafana_url }}/api/datasources"
        method: POST
        body_format: json
        body: "{{ item }}"
        headers:
          Authorization: Bearer {{ api_key }}
      when:  item.name is not in (existing_data_sources | default ([]))
      loop: "{{ data_sources }}"

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.
- <grafana-url> with the URL of your Grafana instance. For example https://ishan-demo.grafana.net/.
- <API-key> with the API key created in the Grafana instance.

Add a folder

This Ansible playbook creates a folder in your Grafana instance by calling the Folder API using the Ansible’s builtin uri module.

Create a file named folder.yml and add the following:

- name: Add/Update Folders
  connection: local
  hosts: localhost

  vars:
    folders: [
      { title: "<folder-name>", uid: "<uid>", id: <id>, overwrite: true }
    ]

    grafana_url: <grafana-url>
    api_key: <API-key>

  tasks:
    - name: List all existing folders
      uri:
        url: "{{ grafana_url }}/api/folders"
        method: GET
        headers:
          Authorization: Bearer {{ api_key }}
      register: check_folders
      no_log: True

    - name: Create list of existing folders
      set_fact:
        existing_folders: "{{ existing_folders | default ([]) + [item.title] }}"
      loop: "{{ check_folders.json }}"
      no_log: True

    - name: Update folders
      uri:
        url: "{{ grafana_url }}/api/folders/{{ item.uid }}"
        method: PUT
        body_format: json
        body: "{{ item }}"
        headers:
          Authorization: Bearer {{ api_key }}
      register: update_folder
      when:  item.title in (existing_folders | default ([]))
      loop: "{{ folders }}"

    - name: Add folders
      uri:
        url: "{{ grafana_url }}/api/folders"
        method: POST
        body_format: json
        body: "{{ item }}"
        headers:
          Authorization: Bearer {{ api_key }}
      when:  item.title not in (existing_folders | default ([]))
      loop: "{{ folders }}"

Replace the following field values:
- <folder-name> with the name of the folder to be added in Grafana.
- <id> with the ID for your folder in Grafana.
- <uid> with the UID for your folder in Grafana.
- <grafana-url> with the URL of your Grafana instance. For example https://ishan-demo.grafana.net/.
- <API-key> with the API key created in the Grafana instance.

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 calling the Dashboard API using the Ansible’s builtin uri module.

Create a file named dashboard.yml and add the following:

- name: Add/Update Dashboards
  connection: local
  hosts: localhost

  vars:
    dashboards_path: <path-to-dashboard-files> # Example "./dashboards"
    grafana_url: <grafana-url>
    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: Add/Update dashboard
      uri:
        url: "{{ grafana_url }}/api/dashboards/db"
        method: POST
        body_format: json
        body: "{{ lookup('ansible.builtin.file','{{ item }}' ) }}"
        headers:
          Authorization: Bearer {{ api_key }}
      loop: "{{ dashboard_file_names }}"

Replace the following field values:
- <path-to-dashboard-files> with the path to the folder containing dashboard JSON source code files.
- <grafana-url> with the URL of your Grafana instance. For example https://ishan-demo.grafana.net/.
- <API-key> with the API key created in the Grafana instance.

Run the Ansible playbooks

In a terminal, run the following commands from the directory where all of the Ansible playbooks are located.

To create the Grafana Cloud stack.
```
ansible-playbook cloud-stack.yml
```
To add a data source to the Grafana stack.
```
ansible-playbook data-source.yml
```
To add a folder to the Grafana stack
```
ansible-playbook folder.yml
```
To add a dashboard to the folder in your Grafana stack.
```
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.
A new data source (InfluxDB in this example) is visible in the Grafana stack.
A new folder in Grafana. In the following image, a folder named Demos was added.
A new dashboard in the Grafana stack. In the following image a dashboard named InfluxDB Cloud Demos was created inside the “Demos” folder.