Merge pull request #8 from scalair/docs

add: documentation rework

README.md

@@ -2,42 +2,30 @@
 
 ![Apache 2.0 Licence](https://img.shields.io/hexpm/l/plug.svg) ![Ansible](https://img.shields.io/badge/ansible-2.10.x-green.svg)
 
-Ansible role that creates monitoring stack based on the well-known following products :
+**tethys** aims to **facilitate the integration of monitoring stack** using the well-known [Prometheus](https://prometheus.io/), [Grafana](https://grafana.com/) and [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/), in order to **monitor several products** (node, kubernetes, apache, elasticsearch, etc).
 
-- prometheus
-- grafana
-- alertmanager
+We also provide a **[collection of Prometheus exporters](docs/exporters/README.md)** that collects metrics for several products.
 
-The resulting Prometheus server is planned to **federate others Prometheuses servers**. [More information about Prometheus federation](https://prometheus.io/docs/prometheus/latest/federation/).
+Here is an overview :
 
-## Why tethys
+![overview](docs/medias/overview.svg)
 
-- simplify Prometheuses servers federation
-- add glue between Prometheus, Grafana and AlertManager in order to get a stack that just work from scratch
-- provides custom dashboards for well-known products, such as :
-  - node : monitor any VM/instances (cloud-based or on-prem)
-  - elasticsearch : monitor elasticsearch clusters
-  - kubernetes : monitor k8s clusters, and its workloads
-- simplify multi-tenant configuration
+## Why tethys
 
-## Prerequisites
+Because we are used to integrating monitoring stacks for our clients, we have concluded several things :
 
-### For federated Prometheuses servers
+- there are a ton of Prometheus exporters in the community, even for the same product. So, it is hard an boring to choose the good one. **We provide a list of Prometheus exporters for each product you want to monitor, that just works with our stack.**
+- there are a ton of Grafana dashboars in the community, even for the same product. It is hard an boring to choose the good one. **We provide Grafana dashboards for each product you want to monitor, that just works with our stack.**
+- glue between Prometheus exporters, Prometheus servers, Prometheus federation server, Grafana and Alertmanager is a complex task and requires a certain expertise to be maintained. **We've decided to add an abstraction layer to facilitate the integration and the glue.**
+- because we had a monitoring stack for each customer which operated independently, it was becoming complicated on a daily basis to consult and maintain the stack of each customer. **tethys provides a simplified customer-centric view, and simplify multi-tenant configuration of the stack.**
 
-Because metrics datas retrieved from federated prometheuses servers must have the expected structure for each product, we **highly recommand** to install the exporters from the following list :
+For all these reasons, we decided to create tethys.
 
-|Exporter|Platform|Provisioning Tool|Repo|Description|
-|-|-|-|-|-|
-|node-exporter|VM, instances, etc.|ansible|<https://galaxy.ansible.com/cloudalchemy/node-exporter>|Install node-exporter on classic instance or virtual machines|
-|node-exporter|Kubernetes|helm|<https://prometheus-community.github.io/helm-charts>|Install node-exporter as Kubernetes `DaemonSet` to monitor Kubernetes cluster nodes.|
-|kube-state-metrics|Kubernetes|helm|<https://prometheus-community.github.io/helm-charts>|Install state-metrics for Kubernetes cluster.|
-|cadvisor|Kubernetes|helm|<https://artifacthub.io/packages/helm/ckotzbauer/cadvisor>|Install cadvisor for in-depth metrics in Kubernetes workloads.|
-|elasticsearch-exporter|VM, instances, etc.|ansible|<https://galaxy.ansible.com/lyr/elasticsearch_exporter>|Install elasticsearch-exporter on classic instance or virtual machines|
-|elasticsearch-exporter|Kubernetes|helm|<https://artifacthub.io/packages/helm/prometheus-community/prometheus-elasticsearch-exporter>|Install elasticsearch-exporter within Kubernetes.|
-|apache-exporter|VM, instances, etc.|ansible|<https://galaxy.ansible.com/idealista/apache_exporter-role>|Install apache-exporter on classic instance or virtual machines.|
+## Prerequisites
 
+- ![ansible](https://img.shields.io/badge/ansible-2.10.x-green.svg)
 
-## Variables
+## Usage
 
 ### `clients`
 

docs/exporters/README.md

@@ -0,0 +1,10 @@
+# exporters collection
+
+**tethys** provides a collection of Prometheus exporters that can be installed and used regarding the products you want to monitor.
+
+Here are products we are currently supporting :
+
+- [node](node/README.md) : exporter for any *nix OS.
+- [kubernetes](kubernetes/README.md) : exporter for Kubernetes cluster.
+- [apache](kubernetes/README.md) : exporter for Apache web server.
+- [elasticsearch](elasticsearch/README.md) : exporter for Elasticsearch cluster.

docs/exporters/apache/README.md

@@ -0,0 +1,30 @@
+# apache exporter
+
+Prometheus exporter that exposes Apache mod_status statistics.
+
+The exporter is maintained by [Lusitaniae/apache_exporter project](https://github.com/Lusitaniae/apache_exporter).
+
+## Install on a standard instance
+
+For a standard instance, we use an ansible role maintained by [Xat59/ansible-role-apache_exporter](https://github.com/Xat59/ansible-role-apache_exporter/), to deploy the exporter into an instance.
+
+### Create the ansible playbook file
+
+Create a `apache-exporter.yml` file with the following content :
+
+```yaml
+- hosts: <host>
+  roles:
+    - role: xat59.apache_exporter
+      apache_exporter_option_scrape_uri: http://<server>/server-status?auto
+```
+
+> Replace _\<host\>_ with the host (or list of hosts) where to install the exporter.
+Plus, replace _\<server\>_ with the DNS or IP of the Apache you want to monitor.
+
+### Deploy it
+
+```bash
+ansible-galaxy install xat59.apache_exporter
+ansible-playbook -vv apache-exporter.yml
+```

docs/exporters/elasticsearch/README.md

@@ -0,0 +1,101 @@
+# node exporter
+
+Prometheus exporter for various metrics about ElasticSearch.
+
+The exporter is maintained by [justwatchcom/elasticsearch_exporter project](https://github.com/justwatchcom/elasticsearch_exporter).
+
+We provides two ways to install the elasticsearch exporter :
+
+- on a standard instance (on-prem, cloud, etc)
+- on Kubernetes cluster nodes
+
+## Install on a standard instance
+
+For a standard instance, we use an ansible role maintained by [Lyr/ansible-elasticsearch-exporter](https://github.com/Lyr/ansible-elasticsearch-exporter), to deploy the exporter into an instance.
+
+### Create the ansible playbook file
+
+Create a `elasticsearch-exporter.yml` file with the following content :
+
+```yaml
+- hosts: <host>
+  roles:
+    - role: lyr.elasticsearch_exporter
+      elasticsearch_exporter_es_uri: "<scheme>://<username>:<password>@<url>:<port>"
+      elasticsearch_exporter_es_all: true
+      elasticsearch_exporter_es_indices: true
+      elasticsearch_exporter_es_shards: true
+```
+
+Of course, the elasticsearch endpoint must be available from the exporter.
+
+> Replace _\<host\>_ with the host (or list of hosts) where to install the exporter.
+Plus, replace _\<scheme\>_, _\<username\>_, _\<password\>_, _\<url\>_ and _\<port\>_ with your elasticsearch cluster information.
+
+### Deploy it into the instance
+
+```bash
+ansible-galaxy install lyr.elasticsearch_exporter
+ansible-playbook -vv elasticsearch-exporter.yml
+```
+
+## Install on Kubernetes cluster nodes
+
+To install the exporter in a Kubernetes cluster, do the following.
+
+### Connect to your Kubernetes cluster
+
+First, connect to your Kubernetes cluster you want to deploy the exporter in.
+
+### Configure the exporter
+
+Create the `ekasticsearch-exporter.yml` file with the following content :
+
+```yaml
+es:
+  all: true
+  cluster_settings: true
+  indices: true
+  indices_settings: true
+  shards: true
+  snapshots: true
+  uri: <scheme>://<username>:<password>@<url>:<port>
+
+# If you are using prometheus-operator, add the following :
+service:
+  annotations: {}
+  httpPort: 9108
+  labels:
+    job: elasticsearch-exporter
+  metricsPort:
+    name: http
+  type: ClusterIP
+serviceMonitor:
+  enabled: true
+  interval: 60s
+  labels:
+    prometheus-scrape: "true"
+  metricRelabelings: []
+  relabelings:
+    - sourceLabels: [ "job" ]
+      regex: ^.*$
+      action: replace
+      replacement: elasticsearch-exporter
+      targetLabel: job
+  sampleLimit: 0
+  scheme: http
+  scrapeTimeout: 10s
+  targetLabels:
+    - job
+```
+
+> Replace _\<scheme\>_, _\<username\>_, _\<password\>_, _\<url\>_ and _\<port\>_ with your elasticsearch cluster information.
+Even if _\<scheme\>_ is _http_, it is mandatory to specify it.
+
+### Deploy it into your Kubernetes cluster
+
+```yaml
+helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
+helm repo update
+helm upgrade --install --create-namespace -f elasticsearch-exporter.yml -n monitoring elasticsearch-exporter prometheus-community/prometheus-elasticsearch-exporter --version 4.4.0
+```

docs/exporters/node/README.md

@@ -0,0 +1,37 @@
+# node exporter
+
+Prometheus exporter for hardware and OS metrics exposed by *nix kernels.
+
+The exporter is maintained by [prometheus/node_exporter project](https://github.com/prometheus/node_exporter).
+
+We provides two ways to install the node exporter :
+
+- on a standard instance (on-prem, cloud, etc)
+- on Kubernetes cluster nodes
+
+## Install on a standard instance
+
+For a standard instance, we use an ansible role maintained by [cloudalchemy/ansible-node-exporter](https://github.com/cloudalchemy/ansible-node-exporter), to deploy the exporter into an instance.
+
+### Create the ansible playbook file
+
+Create a `node-exporter.yml` file with the following content :
+
+```yaml
+- hosts: <host>
+  roles:
+    - role: cloudalchemy.node-exporter
+```
+
+> Replace _\<host\>_ with the host (or list of hosts) where to install the exporter.
+
+### Deploy it
+
+```bash
+ansible-galaxy install cloudalchemy.node-exporter
+ansible-playbook -vv node-exporter.yml
+```
+
+## Install on Kubernetes cluster nodes
+
+If you've already installed the [monitoring for Kubernetes](../kubernetes/README.md) in your Kubernetes cluster, so your nodes are probably already monitored.