ansible-ffibk/roles/service-prometheus/README.md

FFMWU prometheus
============


## Summary

Prometheus ansible role based on **[williamyeh.prometheus](https://galaxy.ansible.com/williamyeh/prometheus/)**

This Ansible role has the following features for [Prometheus](http://prometheus.io/):

 - Install specific versions of [Prometheus server](https://github.com/prometheus/prometheus), [Node exporter](https://github.com/prometheus/node_exporter), [Alertmanager](https://github.com/prometheus/alertmanager).
 - Handlers for restart/reload/stop events;
 - Bare bone configuration (*real* configuration should be left to user's template files; see **Usage** section below).

## Role Variables


### Mandatory variables

The components to be installed:

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



### Optional variables: general settings


User-configurable defaults:

```yaml
# 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 temporary files
prometheus_download_path:  /tmp

# version of helper utility "gosu"
gosu_version:  "1.10"
```

### Optional variables: Prometheus server

User-configurable defaults:

```yaml
# which version?
prometheus_version:  2.0.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](http://prometheus.io/docs/operating/configuration/) for details):


```yaml
# 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](http://prometheus.io/docs/alerting/rules/) for details):


```yaml
# 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
```


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

```yaml
prometheus_opts
```


### Optional variables: Node exporter


User-configurable defaults:

```yaml
# which version?
node_exporter_version:  0.15.1
```

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

```yaml
node_exporter_opts
```


### Optional variables: Alertmanager


User-configurable defaults:

```yaml
# which version?
alertmanager_version:  0.10.0

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

User-installable alertmanager conf file (see [doc](http://prometheus.io/docs/alerting/alertmanager/) for details):
See files directory alertmanager.yml


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

```yaml
prometheus_alertmanager_opts
```




## Handlers

Prometheus server:

- `reload prometheus`

Alertmanager:

- `reload alertmanager`


## Usage


### Step 1: add role

Add role name `service-prometheus` to your playbook file.


### Step 2: add variables

Set vars in your playbook file, if necessary.

Simple example:

```yaml
---
# file: simple-playbook.yml

- hosts: all
  become: True
  roles:
    - service-prometheus

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


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


More practical example:

```yaml
---
# file: complex-playbook.yml

- hosts: all
  become: True
  roles:
    - service-prometheus

  vars:
    prometheus_components:
      - prometheus
      - node_exporter
      - alertmanager

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


### 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`


## License

MIT License. See the [LICENSE file](LICENSE) for details.