This repo hosts the community.grafana Ansible Collection.
The collection includes a variety of Ansible content to help automate the management of resources in Grafana.
Click on the name of a plugin or module to view that content's documentation:
- Connection Plugins:
- Filter Plugins:
- Inventory Source:
- Callback Plugins:
- Lookup Plugins:
- Modules:
We aim at keeping the last 3 minor versions (at least) of Grafana tested.
This collection is currently testing the modules against Grafana versions 7.0.6, 7.1.3 and 8.1.2.
Before using the Grafana collection, you need to install it with the Ansible Galaxy CLI:
ansible-galaxy collection install community.grafana
You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml, using the format:
---
collections:
- name: community.grafana
version: 1.3.1You can either call modules by their Fully Qualified Collection Namespace (FQCN), like community.grafana.grafana_datasource, or you can call modules by their short name if you list the community.grafana collection in the playbook's collections, like so:
---
- hosts: localhost
gather_facts: false
connection: local
collections:
- community.grafana
tasks:
- name: Ensure Influxdb datasource exists.
grafana_datasource:
name: "datasource-influxdb"
grafana_url: "https://grafana.company.com"
grafana_user: "admin"
grafana_password: "xxxxxx"
org_id: "1"
ds_type: "influxdb"
ds_url: "https://influx.company.com:8086"
database: "telegraf"
time_interval: ">10s"
tls_ca_cert: "/etc/ssl/certs/ca.pem"For documentation on how to use individual modules and other content included in this collection, please see the links in the 'Included content' section earlier in this README.
In your playbooks, you can set module defaults for the community.grafana.grafana group to avoid repeating the same parameters (e.g., grafana_url, grafana_user, grafana_password) in your tasks:
- hosts: localhost
gather_facts: false
connection: local
collections:
- community.grafana
module_defaults:
group/community.grafana.grafana:
grafana_url: "https://grafana.company.com"
grafana_user: "admin"
grafana_password: "xxxxxx"
tasks:
- name: Ensure Influxdb datasource exists.
grafana_datasource:
name: "datasource-influxdb"
org_id: "1"
ds_type: "influxdb"
ds_url: "https://influx.company.com:8086"
database: "telegraf"
time_interval: ">10s"
tls_ca_cert: "/etc/ssl/certs/ca.pem"
- name: Create or update a Grafana user
grafana_user:
name: "Bruce Wayne"
email: "[email protected]"
login: "batman"
password: "robin"
is_admin: trueIf you want to develop new content for this collection or improve what's already here, the easiest way to work on the collection is to clone it into one of the configured COLLECTIONS_PATHS, and work on it there.
The tests directory contains configuration for running sanity and integration tests using ansible-test.
You can run the collection's test suites with the commands:
ansible-test sanity --docker -v --color
ansible-test units --docker -v --color
ansible-test integration --docker -v --color
The current process for publishing new versions of the Grafana Collection is manual, and requires a user who has access to the community.grafana namespace on Ansible Galaxy to publish the build artifact.
-
Ensure
CHANGELOG.mdcontains all the latest changes. -
Update
galaxy.ymland this README'srequirements.ymlexample with the newversionfor the collection. -
Tag the version in Git and push to GitHub.
-
Run the following commands to build and release the new version on Galaxy:
ansible-galaxy collection build ansible-galaxy collection publish ./community-grafana-$VERSION_HERE.tar.gz
After the version is published, verify it exists on the Grafana Collection Galaxy page.
- Every change that does not only affect docs or tests must have a changelog fragment.
- Exception: fixing/extending a feature that already has a changelog fragment and has not yet been released. Such PRs must always link to the original PR(s) they update.
- Use your common sense!
- (This might change later. The trivial category should then be used to document changes which are not important enough to end up in the text version of the changelog.)
- Fragments must not be added for new module PRs and new plugin PRs. The only exception are test and filter plugins: these are not automatically documented yet.
- The (x+1).0.0 changelog continues the x.0.0 changelog.
- A x.y.0 changelog with y > 0 is not part of a changelog of a later X.. (with X > x) or x,Y,* (with Y > y) release.
- A x.y.z changelog with z > 0 is not part of a changelog of a later (x+1).. or x.Y.z (with Y > y) release. Since everything adding to the minor/patch changelogs are backports, the same changelog fragments of these minor/patch releases will be in the next major release's changelog. (This is the same behavior as in ansible/ansible.)
- Changelogs do not contain previous major releases, and only use the ancestor feature (in changelogs/changelog.yaml) to point to the previous major release.
- Changelog fragments are removed after a release is made.
See antsibull-changelog documentation
For more information about Ansible's Grafana integration, join the #ansible-community channel on irc.libera.chat, and browse the resources in the Grafana Working Group Community wiki page.
GNU General Public License v3.0 or later
See LICENCE to see the full text.
Any contribution is welcome and we only ask contributors to:
- Provide at least integration tests for any contribution.
- Create an issue for any significant contribution that would change a large portion of the code base.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!