patrickjahns.promtail
Ansible Role: promtail
Description
This Ansible role helps you install and set up promtail. It works with both amd64 and arm systems. For recent updates, check the CHANGELOG or visit github releases.
Requirements
- You need Ansible version 2.7 or higher.
Role Variables
There are several adjustable options in the role. You can find all default settings in the defaults/main.yml file and in the table below.
| Name | Default Value | Description |
|---|---|---|
promtail_version |
"3.0.0" | The version of the promtail package. You can also use latest. |
promtail_custom_checksum |
"" | Checksum for custom-built promtail binaries. |
promtail_binary_local_dir |
"" | Use local packages instead of downloading from GitHub; specify the local zip file path. |
promtail_extra_args |
[] | Extra arguments for the promtail systemd service file. |
promtail_config_dir |
/etc/promtail | Directory for promtail configuration files. |
promtail_config_expand_env |
"false" | Activates environment variable use in the configuration. |
promtail_config_file_sd_dir |
"{{ promtail_config_dir }}/file_sd" | Default directory for file service discovery. |
promtail_config_file |
"{{ promtail_config_dir }}/promtail.yml" | The main configuration file for promtail. |
promtail_system_user |
promtail | The Linux user under which promtail will run. |
promtail_system_group |
"{{ promtail_system_user }}" | The group for the promtail user. |
promtail_user_additional_groups |
"adm" | Additional user groups for the promtail user, allowing it to access specific log files. |
promtail_config_clients |
see defaults/main.yml | Configuration for promtail clients. |
promtail_loki_server_url |
http://127.0.0.1:3100 | The URL where promtail will send its logs. |
promtail_config_server |
see defaults/main.yml | Configuration for the promtail server. |
promtail_positions_directory |
/var/lib/promtail |
Directory where promtail tracks log scraping positions. |
promtail_config_positions |
{"filename": "{{ promtail_positions_directory }}/positions.yml"} | Configuration for positions tracking. |
promtail_config_scrape_configs |
[] | Configuration for which logs to scrape. |
promtail_target_config |
{} | Configuration for targets. |
promtail_log_level |
"info" | The logging level: debug, info, warn, or error. |
promtail_config_include_default_file_sd_config |
"True" | If false, the default file service discovery is not included. |
promtail_apt_update_cache |
"True" | If false, the role won't update the APT cache. |
You can customize sections like promtail_config_clients or promtail_config_server following the official promtail configuration. The role converts Ansible variables into YAML configurations for LOKI.
Example Playbook
Here’s a simple playbook that assumes Loki is running at http://127.0.0.1:3100 and scrapes logs from /var/log:
---
- hosts: all
roles:
- role: patrickjahns.promtail
vars:
promtail_config_scrape_configs:
- job_name: system
static_configs:
- targets:
- localhost
labels:
job: varlogs
__path__: /var/log/*log
For a more detailed example that customizes server and client configurations, as well as scraping logs from /var/log:
---
- hosts: all
roles:
- role: patrickjahns.promtail
vars:
promtail_config_server:
http_listen_port: 9080
grpc_listen_port: 9081
promtail_config_clients:
- url: "http://prometheus.domain.tld:3100/loki/api/v1/push"
external_labels:
host: "{{ ansible_hostname }}"
promtail_config_positions:
filename: "{{ promtail_positions_directory }}/positions.yaml"
sync_period: "60s"
promtail_config_scrape_configs:
- job_name: system
static_configs:
- targets:
- localhost
labels:
job: varlogs
__path__: /var/log/*log
Local Testing
To test the role locally, use Docker and molecule (v3.x). First, install Docker if you haven’t already. For installing tox, run:
pip3 install tox
To test with all Ansible versions (this might take some time):
tox
To run a specific test scenario:
tox -e ansible29 -- molecule test -s default
Check the molecule docs for more details.
If you want to run tests on a remote Docker host, set the DOCKER_HOST variable before running the tests.
CI
This role uses GitHub Actions with ansible-later and molecule to test and validate it. Molecule tests run on various operating systems and Ansible versions to ensure compatibility.
License
This project is licensed under the MIT License. See LICENSE for details.
Maintainers and Contributors
Deploy (loki) promtail
ansible-galaxy install patrickjahns.promtail