cloudalchemy.prometheus

DEPRECATED

This role is no longer in use. Please use the prometheus-community/ansible collection instead.

Ansible Role: prometheus

Description

This role helps you set up the Prometheus monitoring system using Ansible.

Upgrade Notice

If you are upgrading from version 2.4.0 or lower to version 2.4.1 or higher, please turn off your Prometheus instance first. For more information, see the 2.4.1 release notes.

Requirements

Ansible version 2.7 or higher (it may work with older versions, but we can't guarantee that).
The jmespath library on the machine running Ansible. If using a Python virtual environment, install it via pip.
The gnu-tar package on a Mac (brew install gnu-tar).

Role Variables

All customizable variables are listed in the defaults/main.yml file and in the table below.

Name	Default Value	Description
`prometheus_version`	2.27.0	Version of the Prometheus package. Use "latest" for the most recent version. Only Prometheus 2.x is supported.
`prometheus_skip_install`	false	Set to true to skip the installation of Prometheus.
`prometheus_binary_local_dir`	""	Use local binaries instead of those from GitHub. Specify the directory where `prometheus` and `promtool` are stored.
`prometheus_config_dir`	/etc/prometheus	Directory for Prometheus configuration files.
`prometheus_db_dir`	/var/lib/prometheus	Directory for the Prometheus database.
`prometheus_read_only_dirs`	[]	Paths that Prometheus can read (helpful for SSL certificates outside the config directory).
`prometheus_web_listen_address`	"0.0.0.0:9090"	Address where Prometheus listens for requests.
`prometheus_web_config`	{}	Configuration for Prometheus web server (can be used for TLS and authentication).
`prometheus_web_external_url`	""	External URL for Prometheus, useful when behind a reverse proxy (e.g., `http://example.org/prometheus`).
`prometheus_storage_retention`	"30d"	Duration for retaining data.
`prometheus_storage_retention_size`	"0"	Data retention limit based on size.
`prometheus_config_flags_extra`	{}	Extra flags for the Prometheus startup.
`prometheus_alertmanager_config`	[]	Configuration for alert managers, listed in YAML format.
`prometheus_alert_relabel_configs`	[]	Rules for relabeling alerts, listed in YAML format.
`prometheus_global`	{ scrape_interval: 60s, scrape_timeout: 15s, evaluation_interval: 15s }	Global configuration settings for Prometheus.
`prometheus_remote_write`	[]	Remote write configuration.
`prometheus_remote_read`	[]	Remote read configuration.
`prometheus_external_labels`	environment: "{{ ansible_fqdn	default(ansible_host)
`prometheus_targets`	{}	Targets that Prometheus will scrape data from.
`prometheus_scrape_configs`	defaults/main.yml#L58	Configuration for scraping jobs.
`prometheus_config_file`	"prometheus.yml.j2"	Template for a custom Prometheus configuration file.
`prometheus_alert_rules`	defaults/main.yml#L81	List of alerting rules to apply.
`prometheus_alert_rules_files`	defaults/main.yml#L78	Folders to search for alerting rules files.
`prometheus_static_targets_files`	defaults/main.yml#L78	Folders to look for static target configuration files.

Explanation of Variables

prometheus_targets is a map used to create files in the directory "{{ prometheus_config_dir }}/file_sd". Each top-level key in this map becomes a filename with a ".yml" suffix. The contents of these files list scrape targets.

The configurations for what Prometheus scrapes are stored in prometheus_scrape_configs, using the options mentioned in the Prometheus documentation.

In contrast, prometheus_targets allows for using the Prometheus scrape type file_sd and defines the content of the files created. Each top-level key corresponds to a file that must have a matching scrape job in prometheus_scrape_configs.

You can customize prometheus_scrape_configs without using prometheus_targets, but if you specify prometheus_targets, there needs to be a corresponding entry in prometheus_scrape_configs. Failing to do so will cause an error.

Example

Here’s a sample configuration showcasing all features. By default, the prometheus_targets might look like this:

prometheus_targets:
  node:
    - targets:
      - localhost:9100
      labels:
        env: test

This configuration creates a node.yml file in the directory {{ prometheus_config_dir }}/file_sd containing the specified targets.

Next, you must reference this file in the scrape configuration, like so:

prometheus_scrape_configs:
  - job_name: "prometheus"
    metrics_path: "/metrics"
    static_configs:
      - targets:
          - "localhost:9090"
  - job_name: "example-node-file-servicediscovery"
    file_sd_configs:
      - files:
          - "{{ prometheus_config_dir }}/file_sd/node.yml"

Example Playbook

---
- hosts: all
  roles:
  - cloudalchemy.prometheus
  vars:
    prometheus_targets:
      node:
      - targets:
        - localhost:9100
        - demo.cloudalchemy.org:9100
        labels:
          env: demosite

Demo Site

The Prometheus organization has a demo site for a complete monitoring solution using Prometheus and Grafana. The repository with the code and running instances is available on GitHub.

Defining Alerting Rules

Alerting rules are set in the prometheus_alert_rules variable. The format is similar to what is mentioned in the Prometheus 2.0 documentation. All templates should be enclosed in {% raw %} and {% endraw %} tags. An example can be found in the defaults/main.yml file.

Local Testing

To test the role locally, use Docker and molecule (v2.x). You need Docker installed on your system. Check the "Get started" section for the appropriate Docker package. We use tox to make testing on multiple Ansible versions easier. To install tox, run:

pip3 install tox

To run tests on all Ansible versions (note: this may take a while):

tox

To execute a specific molecule command with a custom environment and the default test scenario:

tox -e py35-ansible28 -- molecule test -s default

For more information about molecule, refer to the docs.

If you want to run tests on a remote Docker host, set the DOCKER_HOST variable before running the tests.

CircleCI

Using molecule with CircleCI allows us to test how new pull requests behave across various Ansible versions and operating systems. It also helps create test scenarios for different role configurations, resulting in a large test matrix. Therefore, this testing may take longer than local testing, so please be patient.