feat: add promtail role (#197)

Co-authored-by: Ishan Jain <[email protected]>

.github/workflows/promtail-molecule.yml

@@ -0,0 +1,44 @@
+---
+name: Promtail Molecule
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+defaults:
+  run:
+    working-directory: roles/promtail
+
+jobs:
+  molecule:
+    name: Molecule
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        distro:
+          - rockylinux9
+          - ubuntu2204
+          - debian12
+
+    steps:
+      - name: Check out the codebase.
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install test dependencies.
+        run: pip3 install ansible molecule molecule-plugins[docker] docker
+
+      - name: Run Molecule tests.
+        run: molecule test
+        env:
+          PY_COLORS: '1'
+          ANSIBLE_FORCE_COLOR: '1'
+          MOLECULE_DISTRO: ${{ matrix.distro }}

CODEOWNERS

@@ -5,3 +5,4 @@
 /roles/opentelemetry_collector @ishanjainn
 /roles/loki                    @voidquark @ishanjainn
 /roles/mimir                   @GVengelen @gardar @ishanjainn
+/roles/promtail                @voidquark @ishanjainn

README.md

@@ -6,7 +6,7 @@
 [![GitHub Last Commit](https://img.shields.io/github/last-commit/grafana/grafana-ansible-collection)](https://github.com/grafana/grafana-ansible-collection/tags)
 [![GitHub Contributors](https://img.shields.io/github/contributors/grafana/grafana-ansible-collection)](https://github.com/grafana/grafana-ansible-collection/tags)
 
-This collection (`grafana.grafana`) contains modules and roles to assist in automating the management of resources in **Grafana**, **Grafana Agent**, **OpenTelemetry Collector**, and **Loki** with Ansible.
+This collection (`grafana.grafana`) contains modules and roles to assist in automating the management of resources in **Grafana**, **Grafana Agent**, **OpenTelemetry Collector**, **Loki**, **Mimir**, and **Promtail** with Ansible.
 
 -   [Ansible collection Documentation](https://docs.ansible.com/ansible/latest/collections/grafana/grafana/)
 -   [Grafana](https://grafana.com)
@@ -43,12 +43,14 @@ collections:
 
 ## Roles included in the collection
 
-This collection includes the following roles to help set up and manage Grafana, Grafana Agent, OpenTelemetry Collector, and Loki:
+This collection includes the following roles to help set up and manage Grafana, Grafana Agent, OpenTelemetry Collector, Loki, Mimir and Promtail:
 
 - **Grafana**: Installs and configures Grafana on your target hosts.
 - **Grafana Agent**: Deploys and configures Grafana Agent, allowing for efficient metrics, logs, and trace data shipping to Grafana Cloud or other endpoints.
 - **OpenTelemetry Collector**: Sets up and configures the OpenTelemetry Collector, enabling advanced observability features through data collection and transmission.
 - **Loki**: Deploy and manage Loki, the log aggregation system.
+- **Mimir**: Deploy and manage Mimir, the scalable long-term storage for Prometheus.
+- **Promtail**: Deploy and manage Promtail, the agent which ships the contents of local logs to a private Grafana Loki.
 
 ## Using this collection
 

examples/promtail-multiple-logs.yml

@@ -0,0 +1,24 @@
+---
+- name: Deploy Promtail to ship logs to the local Loki instance
+  hosts: all
+  become: true
+  roles:
+    - role: grafana.grafana.promtail
+  vars:
+    promtail_clients:
+      - url: http://localhost:3100/loki/api/v1/push
+    promtail_scrape_configs:
+      - job_name: system
+        static_configs:
+          - targets:
+              - localhost
+            labels:
+              job: messages
+              instance: "{{ ansible_fqdn }}"
+              __path__: /var/log/messages
+          - targets:
+              - localhost
+            labels:
+              job: nginx
+              instance: "{{ ansible_fqdn }}"
+              __path__: /var/log/nginx/*.log

roles/promtail/README.md

@@ -0,0 +1,164 @@
+# Ansible role - Promtail
+
+[![License](https://img.shields.io/github/license/grafana/grafana-ansible-collection)](LICENSE)
+
+The Ansible Promtail Role allows you to effortlessly deploy and manage Promtail, agent which ships contents of local logs to private Loki.
+This role is tailored for operating systems such as **RedHat**, **Rocky Linux**, **AlmaLinux**, **Ubuntu**, and **Debian**.
+
+**🔑 Key Features**
+- **⚡ Root-less/Root runtime**: By default, Promtail operates in root-less mode, utilizing ACL (Access Control List) to securely access logs without requiring root permissions. You have the option to configure root mode if necessary.
+- **🧹 Effortless Uninstall**: Easily remove Promtail from your system using the "promtail_uninstall" tag.
+
+📢 **[Check the blog post](https://voidquark.com/blog/rootless-promtail-with-ansible/)** 📝 **Learn more about root-less mode.**
+
+## Table of Content
+
+- [Requirements](#requirements)
+- [Role Variables](#role-variables)
+- [Playbook](#playbook)
+
+## Requirements
+
+- Ansible 2.10+
+
+## Role Variables
+
+```yaml
+promtail_version: "latest"
+```
+The version of Promtail to download and deploy. Supported standard version "3.0.0" format or "latest".
+
+```yaml
+promtail_http_listen_port: 9080
+```
+The TCP port on which Promtail listens. By default, it listens on port `9080`.
+
+```yaml
+promtail_http_listen_address: "0.0.0.0"
+```
+The address on which Promtail listens for HTTP requests. By default, it listens on all interfaces.
+
+```yaml
+promtail_expose_port: false
+```
+By default, this is set to `false`. It supports only simple `firewalld` configurations. If set to `true`, a firewalld rule is added to expose the TCP `promtail_http_listen_port`. If set to `false`, configuration is skipped. If the `firewalld.service` is not active, all firewalld tasks are skipped.
+
+```yaml
+promtail_positions_path: "/var/lib/promtail"
+```
+Promtail path for position file. File indicating how far it has read into a file. It is needed for when Promtail is restarted to allow it to continue from where it left off.
+
+```yaml
+promtail_runtime_mode: "acl"
+```
+By default, Promtail runs in root-less mode. It supports two modes:
+- `acl`: Root-less mode, utilizing ACL permission model to read target log files.
+- `root`: Root mode, where Promtail runs as root and ACL configuration is skipped.
+
+```yaml
+promtail_user_append_groups:
+  - "systemd-journal"
+```
+Appends the promtail user to specific groups in root-less mode. By default, it appends the user to the `systemd-journal` group, granting permission to read system journal logs.
+
+```yaml
+promtail_download_url_rpm: "https://github.com/grafana/loki/releases/download/v{{ promtail_version }}/promtail-{{ promtail_version }}.{{ __promtail_arch }}.rpm"
+```
+The default download URL for the Promtail rpm package from GitHub.
+
+```yaml
+promtail_download_url_deb: "https://github.com/grafana/loki/releases/download/v{{ promtail_version }}/promtail_{{ promtail_version }}_{{ __promtail_arch }}.deb"
+```
+The default download URL for the Promtail deb package from GitHub.
+
+```yaml
+promtail_server:
+  http_listen_port: "{{ promtail_http_listen_port }}"
+  http_listen_address: "{{ promtail_http_listen_address }}"
+```
+The `server` block configures Promtail behavior as an HTTP server. [All possible values for `server`](https://grafana.com/docs/loki/latest/clients/promtail/configuration/#server)
+
+```yaml
+promtail_positions:
+  filename: "{{ promtail_positions_path }}/positions.yaml"
+```
+The `positions` block configures where Promtail will save a file indicating how far it has read into a file. It is needed for when Promtail is restarted to allow it to continue from where it left off. [All possible values for `positions`](https://grafana.com/docs/loki/latest/clients/promtail/configuration/#positions)
+
+```yaml
+promtail_clients:
+  - url: http://localhost:3100/loki/api/v1/push
+```
+The `clients` block configures how Promtail connects to instances of Loki. [All possible values for `clients`](https://grafana.com/docs/loki/latest/clients/promtail/configuration/#clients). ⚠️ This configuration is mandatory. By default, it's empty, and the example above serves as a simple illustration for inspiration.
+
+```yaml
+promtail_scrape_configs:
+  - job_name: system
+    static_configs:
+      - targets:
+          - localhost
+        labels:
+          job: messages
+          instance: "{{ ansible_fqdn }}"
+          __path__: /var/log/messages
+      - targets:
+          - localhost
+        labels:
+          job: nginx
+          instance: "{{ ansible_fqdn }}"
+          __path__: /var/log/nginx/*.log
+```
+The `scrape_configs` block configures how Promtail can scrape logs from a series of targets using a specified discovery method. [All possible values for `scrape_configs`](https://grafana.com/docs/loki/latest/clients/promtail/configuration/#scrape_configs). ⚠️ This configuration is mandatory. By default, it's empty, and the example above serves as a simple illustration for inspiration.
+
+| Variable Name | Description
+| ----------- | ----------- |
+| `promtail_limits_config` | The optional limits_config block configures global limits for this instance of Promtail. 📚 [documentation](https://grafana.com/docs/loki/latest/clients/promtail/configuration/#limits_config).
+| `promtail_target_config` | The target_config block controls the behavior of reading files from discovered targets. 📚 [documentation](https://grafana.com/docs/loki/latest/clients/promtail/configuration/#target_config).
+
+## Dependencies
+
+No Dependencies
+
+## Playbook
+
+```yaml
+- name: Manage promtail service
+  hosts: all
+  become: true
+  vars:
+    promtail_clients:
+      - url: http://localhost:3100/loki/api/v1/push
+    promtail_scrape_configs:
+      - job_name: system
+        static_configs:
+          - targets:
+              - localhost
+            labels:
+              job: messages
+              instance: "{{ ansible_fqdn }}"
+              __path__: /var/log/messages
+          - targets:
+              - localhost
+            labels:
+              job: nginx
+              instance: "{{ ansible_fqdn }}"
+              __path__: /var/log/nginx/*.log
+  roles:
+    - role: grafana.grafana.promtail
+```
+
+- Playbook execution example
+```shell
+# Deploy Promtail
+ansible-playbook function_promtail_play.yml
+
+# Uninstall Promtail
+ansible-playbook function_promtail_play.yml -t promtail_uninstall
+```
+
+## License
+
+See [LICENSE](https://github.com/grafana/grafana-ansible-collection/blob/main/LICENSE)
+
+## Author Information
+
+-   [VoidQuark](https://github.com/voidquark)

roles/promtail/defaults/main.yml

@@ -0,0 +1,47 @@
+---
+# defaults file for promtail
+promtail_version: "latest"
+promtail_http_listen_port: 9080
+promtail_http_listen_address: "0.0.0.0"
+promtail_expose_port: false
+promtail_positions_path: "/var/lib/promtail"
+promtail_runtime_mode: "acl"  # Supported "root" or "acl"
+
+promtail_user_append_groups:
+  - "systemd-journal"
+
+promtail_download_url_rpm: "https://github.com/grafana/loki/releases/download/v{{ promtail_version }}/promtail-{{ promtail_version }}.{{ __promtail_arch }}.rpm"
+promtail_download_url_deb: "https://github.com/grafana/loki/releases/download/v{{ promtail_version }}/promtail_{{ promtail_version }}_{{ __promtail_arch }}.deb"
+
+# default variables for /etc/promtail/config.yml
+promtail_server:
+  http_listen_port: "{{ promtail_http_listen_port }}"
+  http_listen_address: "{{ promtail_http_listen_address }}"
+
+promtail_positions:
+  filename: "{{ promtail_positions_path }}/positions.yaml"
+
+promtail_clients: []
+# promtail_clients:
+#   - url: http://localhost:3100/loki/api/v1/push
+
+promtail_scrape_configs: []
+# promtail_scrape_configs:
+#   - job_name: system
+#     static_configs:
+#       - targets:
+#           - localhost
+#         labels:
+#           job: messages
+#           instance: "{{ ansible_fqdn }}"
+#           __path__: /var/log/messages
+#       - targets:
+#           - localhost
+#         labels:
+#           job: nginx
+#           instance: "{{ ansible_fqdn }}"
+#           __path__: /var/log/nginx/*.log
+
+# not set by default
+# promtail_limits_config:
+# promtail_target_config:

roles/promtail/handlers/main.yml

@@ -0,0 +1,9 @@
+---
+# handlers file for promtail
+- name: Restart promtail
+  listen: "restart promtail"
+  ansible.builtin.systemd:
+    daemon_reload: true
+    name: promtail.service
+    state: restarted
+    enabled: true

roles/promtail/meta/main.yml

@@ -0,0 +1,28 @@
+---
+galaxy_info:
+  role_name: promtail
+  author: voidquark
+  description: Manage Grafana Promtail Application
+  license: "GPL-3.0-or-later"
+  min_ansible_version: "2.10"
+  platforms:
+    - name: EL
+      versions:
+        - "9"
+        - "8"
+    - name: Fedora
+      versions:
+        - all
+    - name: Debian
+      versions:
+        - all
+    - name: Ubuntu
+      versions:
+        - all
+  galaxy_tags:
+    - promtail
+    - grafana
+    - logging
+    - monitoring
+
+dependencies: []

roles/promtail/molecule/default/converge.yml

@@ -0,0 +1,15 @@
+---
+- name: Converge
+  hosts: all
+  vars:
+    promtail_scrape_configs:
+      - job_name: test
+        static_configs:
+          - targets:
+              - localhost
+            labels:
+              job: test
+              instance: "{{ ansible_fqdn }}"
+              __path__: /var/log/last*
+  roles:
+    - role: grafana.grafana.promtail

roles/promtail/molecule/default/molecule.yml

@@ -0,0 +1,20 @@
+---
+dependency:
+  name: galaxy
+  options:
+    ignore-errors: true
+driver:
+  name: docker
+platforms:
+  - name: instance
+    image: "geerlingguy/docker-${MOLECULE_DISTRO:-rockylinux8}-ansible:latest"
+    command: ${MOLECULE_DOCKER_COMMAND:-""}
+    volumes:
+      - /sys/fs/cgroup:/sys/fs/cgroup:rw
+    cgroupns_mode: host
+    privileged: true
+    pre_build_image: true
+provisioner:
+  name: ansible
+  playbooks:
+    converge: converge.yml