william-yeh.prometheus for Ansible Galaxy

Summary

Role name in Ansible Galaxy: william-yeh.prometheus

This Ansible role has the following features for Prometheus:

• Install specific versions of Prometheus server, Node exporter, Alertmanager.
• Handlers for restart/reload/stop events;
• Bare bone configuration (real configuration should be left to user's template files; see Usage section below).

To keep this role simple, this role only installs 3 components: Prometheus server, Node exporter, and Alertmanager. Use the following roles if you want to install other Prometheus exporters:

• Consul: william-yeh.consul_exporter
• Elasticsearch: william-yeh.es_cluster_exporter
• MongoDB: williamyeh.mongodb_exporter

Supports for Ubuntu 12.04 (Precise) and CentOS 6 have been ended since Nov 2018.

Role Variables

Mandatory variables

The components to be installed:

# Supported components:
#
#   [Server components]
#     - "prometheus"
#     - "alertmanager"
#
#   [Exporter components]
#     - "node_exporter"
#
prometheus_components

Optional variables: general settings

User-configurable defaults:

# user and group
prometheus_user:   prometheus
prometheus_group:  prometheus


# directory for executable files
prometheus_install_path:   /opt/prometheus

# directory for configuration files
prometheus_config_path:    /etc/prometheus

# directory for logs
prometheus_log_path:       /var/log/prometheus

# directory for PID files
prometheus_pid_path:       /var/run/prometheus



# directory for temporary files
prometheus_download_path:  /tmp


# version of helper utility "gosu"
gosu_version:  "1.11"

Optional variables: systemd or not

If the Linux distributions are equipped with systemd, this role will use this mechanism accordingly. You can disable this (i.e., use traditional SysV-style init script) by defining the following variable(s) to false:

prometheus_use_systemd

Optional variables: Prometheus server

User-configurable defaults:

# which version?
prometheus_version:  2.5.0



# directory for rule files
prometheus_rule_path:  {{ prometheus_config_path }}/rules

# directory for file_sd files
prometheus_file_sd_config_path:  {{ prometheus_config_path }}/tgroups

# directory for runtime database
prometheus_db_path:   /var/lib/prometheus

User-installable configuration file (see doc for details):

# main conf template relative to `playbook_dir`;
# to be installed to "{{ prometheus_config_path }}/prometheus.yml"
prometheus_conf_main

User-installable rule files (see doc for details):

# rule files to be installed to "{{ prometheus_rule_path }}" directory;
# dict fields:
#   - key: memo for this rule
#   - value:
#     - src:  file relative to `playbook_dir`
#     - dest: target file relative to `{{ prometheus_rule_path }}`
prometheus_rule_files

Alertmanager to be triggered:

prometheus_alertmanager_hostport

Additional command-line arguments, if any (use prometheus --help to see the full list of arguments):

prometheus_opts

Optional variables: Node exporter

User-configurable defaults:

# which version?
prometheus_node_exporter_version:  0.16.0

Additional command-line arguments, if any (use node_exporter --help to see the full list of arguments):

prometheus_node_exporter_opts

Optional variables: Alertmanager

User-configurable defaults:

# which version?
prometheus_alertmanager_version:  0.15.3

# directory for runtime database (currently for `silences.json`)
prometheus_alertmanager_db_path: /var/lib/alertmanager

User-installable alertmanager conf file (see doc for details):

# main conf template relative to `playbook_dir`;
# to be installed to "{{ prometheus_config_path }}/alertmanager.yml"
prometheus_alertmanager_conf

Additional command-line arguments, if any (use alertmanager --help to see the full list of arguments):

prometheus_alertmanager_opts

Optional: building from source tree

(Credit: Robbie Trencheny)

For aforementioned prometheus_components, you can optionally download/compile from the master branch of Prometheus repositories by setting the respective version to git.

It will install a temporary Golang compiler in the prometheus_workdir directory (defined in defaults/main.yml).

For example, get the latest code for all components by assigning all *_version variables to git:

prometheus_version: git
prometheus_node_exporter_version: git
prometheus_alertmanager_version: git

If you'd like to force rebuild each time, enable the following variable (default is false):

prometheus_rebuild: true

Handlers

Prometheus server:

• restart prometheus

• reload prometheus

• stop prometheus

Node exporter:

• restart node_exporter

• reload node_exporter (actually, the same as restart)

• stop node_exporter

Alertmanager:

• restart alertmanager

• reload alertmanager

• stop alertmanager

Usage

Step 1: add role

Add role name william-yeh.prometheus to your playbook file.

Step 2: add variables

Set vars in your playbook file, if necessary.

Simple example:

---
# file: simple-playbook.yml

- hosts: all
  become: True
  roles:
    - william-yeh.prometheus

  vars:
    prometheus_components: [ "prometheus", "alertmanager" ]

    prometheus_alertmanager_hostport: "localhost:9093"

Step 3: copy user's config files, if necessary

More practical example:

---
# file: complex-playbook.yml

- hosts: all
  become: True
  roles:
    - william-yeh.prometheus

  vars:
    prometheus_components:
      - prometheus
      - node_exporter
      - alertmanager

    prometheus_rule_files:
      this_is_rule_1_InstanceDown:
        src:  some/path/basic.rules
        dest: basic.rules

    prometheus_alertmanager_conf: some/path/alertmanager.yml.j2

Step 4: browse the default Prometheus pages

Open the page in your browser:

• Prometheus - http://HOST:9090 or http://HOST:9090/consoles/node.html

• Alertmanager - http://HOST:9093

Dependencies

None.

Contributors

• William Yeh
• Robbie Trencheny - contribute an early version of building binaries from Go source code.
• Travis Truman - contribute an early version of consul_exporter installer; now moved to William-Yeh.consul_exporter.
• Musee Ullah

License

MIT License. See the LICENSE file for details.