Installs Grafana Cloud Agent on RedHat/CentOS or Debian/Ubuntu servers to collect observability data and sends it to Grafana Cloud. Available on Galaxy.
This role installs and configures the latest version of Grafana Cloud Agent from GitHub releases. It also creates a systemd service to manage the agent.
It optionally installs Promtail, which is an agent which ships the contents of local logs to Grafana Cloud (Loki).
WHY? => Monitoring your home lab devices in the cloud for free.
None. Other than an account on Grafana Cloud -> Create an account.
Available variables are listed below, along with default values (see defaults/main.yml). You can get the values for your environment from the Grafana Cloud Portal.
prometheus_user: <username>
Each service in Grafana Cloud has a unique service id or user. Once in the Grafana Cloud Portal click on Prometheus to get the value you need to provide for prometheus_user.
grafana_api_key: <key>
You can generate a new API Key in the API Keys section of the Grafana Cloud Portal. The role has to be MetricsPublisher.
agent_location: /usr/local/bin
Location where the Grafana Cloud Agent's binary will be installed. The default location (/usr/local/bin) is preferred in systems where SELinux is enabled.
config_location: /etc/grafana
Location where the Grafana Cloud Agent's config will be stored. The default location (/etc/grafana) is preferred in systems where SELinux is enabled.
By default, this role will ensure Grafana Cloud Agent is running and enabled at boot.
loki_user: <username>
Each service in Grafana Cloud has a unique service id or user. Once in the Grafana Cloud Portal click on Loki to get the value you need to provide for loki_user. If this value is present, this role will install the Promtail agent and create a Systemd service for it. It will scrape messages from /var/log and journald. For reference, see Journal Scraping.
install_unzip: true
Whether to install unzip, to extract files from agent's zip releases. By default is set to true.
grafana_location_prometheus: us-central1
grafana_location_promtail: us-central1
The closest Grafana region for promtail or prometheus. As displayed in @logs-prod-us-central1.grafana.net/api/prom/push for example. By default is us-central1
To override the agent configuration template, you can define your own template. By default it'll source it from the role file templates/agent-config.yaml.j2.
grafana_agent_config_template: agent-config.yaml.j2
The grafana agent systemd service template can be set using the following variable:
grafana_agent_systemd_template: grafana-agent.service.j2
To override the promtail configuration template, you can define your own template. By default it'll source it from the role file templates/promtail-config.yaml.j2.
grafana_promtail_config_template: promtail-config.yaml.j2
The promtail systemd service template can be set using the following variable:
grafana_promtail_systemd_template: promtail.service.j2
None. But, Grafana Agent's configuration file has had some breaking changes recently that might impact this role as we catch up with it (https://grafana.com/docs/agent/v0.26/upgrade-guide/#deprecation-on-yaml-fields-in-server-block-that-have-flags).
- hosts: server
roles:
- { role: nleiva.grafana_agent }
See an example playbook I run for my home-lab here.
The role is tested using Molecule. Dependencies for testing are podman and its plugin for Molecule.
Run molecule test in the repository root to test the role.
The default OS for tests is Debian. This can be changed using the ROLE_TEST_OS environment variable. The available options can be found here.
GPL-3.0 License
This role was created in 2021 by Nicolas Leiva.