.. SPDX-FileCopyrightText: 2023 Gerald Wiese
..
.. SPDX-License-Identifier: GPL-3.0-or-later

plg
===

This role installs a Prometheus-Loki-Grafana stack as monitoring server.

On the one hand those services are a common combination and on the other hand Incus which is often used for virtualization in this project provides easy integration with those.

The components roughly have the following objectives:

- **Prometheus**: Aggregate metrics (pull)
- **Loki**: Aggregate logs (push)
- **Grafana**: Visualize collected metrics & logs

The counterpart is Grafana Alloy as agent on the instances to monitor (see ``alloy`` role).

Check ``Examples -> Production -> Extended`` as an example usage.

It can be configured by the following options (`p`, `l` or `g` after `plg_` state if they are needed for Prometheus, Loki or Grafana):

- **Parameters**:

  - plg_p_incus_connection: URL for Incus connection, default works for Incus host containing this server as instance
  - plg_p_incus_servername: Hostname of Incus, has to match the real hostname (at the time of Incus installation when a certificate was created with the name)
  - plg_p_certs: Dictionary containing paths for certificates needed for the Incus connection, a path where to find them and a directory where to put them (see ``Examples -> Production -> Extended``)
  - plg_p_alloy_targets: List of dictionaries with an URL and a label for agents to pull metrics from
  - plg_g_smtp: Use SMTP if true (for email alerts)
  - plg_g_smtp_host: Connection information of SMTP host
  - plg_g_smtp_user: Email address used for sending
  - plg_g_stmp_pw: Email password, usually overtaken from vault_plg_g_stmp_pw to be encrypted

- **Variables**:

  - plg_p_user: OS user for Prometheus
  - plg_p_url: URL for downloading an archive
  - plg_p_checksum: Checksum of the archive
  - plg_p_parent_dir: Directory to put Prometheus inside
  - plg_p_base_dir: Prometheus base directory (by default inside parent directory)
  - plg_p_config_path: Path of main config file
  - plg_p_service_path: Path where to put the systemd service file
  - plg_l_apt: Dictionary for APT installation of Loki containing `key_url` for downloading a GPG key to `key_dest` and `repo` as APT repository sources entry.
  - plg_l_config_path: Main config path for Loki
  - plg_g_apt: Dictionary for APT installation of Grafana containing `key_url` for downloading a GPG key to `key_dest` and `repo` as APT repository sources entry (same as Loki currently).
  - plg_g_config_path: Main config path for Grafana
  - plg_file_mode: Default file mode.
  - plg_dir_mode: Default directory mode.
  - plg_ansible_comment: Put `plg_template_comment` on top of templates if true
  - plg_template_comment: Comment put on top of every template delivered by Ansible