upgrade cadvisor documentation

Author: sudo-Tiz

docs/services/cadvisor.md

@@ -0,0 +1,117 @@
+# cAdvisor
+
+This playbook can configure [cAdvisor](https://github.com/google/cadvisor)
+
+## Dependencies
+
+This service requires the following other services:
+
+-   (optionally) [Traefik](traefik.md) - a reverse-proxy server for exposing cadvisor publicly
+-   (optionally) [Prometheus](./prometheus.md) - a database for storing metrics
+-   (optionally) [Grafana](./grafana.md) - a web UI that can query the prometheus datasource (connection) and display the logs
+
+## Configuration
+
+To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:
+
+```yaml
+########################################################################
+#                                                                      #
+# cadvisor                                                             #
+#                                                                      #
+########################################################################
+
+cadvisor_enabled: true
+# You will have to mount specific folders depending on your need
+# cadvisor_container_extra_arguments:
+#   - "--mount type=bind,source=/,destination=/rootfs,readonly"
+#   - "--mount type=bind,source=/sys,destination=/sys,readonly"
+#   - "--mount type=bind,source=/var/lib/docker/,destination=/var/lib/docker,readonly"
+#   - "--mount type=bind,source=/dev/disk/,destination=/dev/disk,readonly"
+
+########################################################################
+#                                                                      #
+# /cadvisor                                                            #
+#                                                                      #
+########################################################################
+```
+
+See the full list of options in the [default/main.yml](default/main.yml) file
+
+cAdvisor can scrape metrics from system and containers. These metrics can be :
+
+-   Displayed on the cAdvisor Web UI
+-   Exposed to a metric-storage server like [Prometheus](./prometheus.md).
+
+## Exposing publicly the Web UI
+
+To expose cAdvisor to the web, you need to assign a hostname in `cadvisor_hostname` and optionally a path-prefix.
+
+```yaml
+# To expose the metrics publicly, enable and configure the lines below:
+cadvisor_hostname: mash.example.com
+cadvisor_path_prefix: /
+
+# To protect the metrics with HTTP Basic Auth, enable and configure the lines below.
+# See: https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
+cadvisor_container_labels_traefik_middleware_basic_auth_enabled: true
+cadvisor_container_labels_traefik_middleware_basic_auth_users: ""
+```
+
+### Exposing metrics publicly
+
+Unless you're scraping the cadvisor metrics from a local [Prometheus](prometheus.md) instance, as described in [Integrating with Prometheus](cadvisor.md#), you will probably wish to expose the metrics publicly so that a remote Prometheus instance can fetch them. When exposing publicly, it's natural to set up [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) **or anyone would be able to read your metrics**.
+
+```yaml
+cadvisor_container_labels_metrics_enabled: true
+
+# To expose the metrics publicly, enable and configure the lines below:
+<!-- cadvisor_hostname: mash.example.com -->
+<!-- cadvisor_path_prefix: /metrics/mash-cadvisor -->
+
+# To protect the metrics with HTTP Basic Auth, enable and configure the lines below.
+# See: https://doc.traefik.io/traefik/middlewares/http/basicauth/#users
+cadvisor_container_labels_metrics_middleware_basic_auth_enabled: true
+cadvisor_container_labels_metrics_middleware_basic_auth_users: ""
+```
+
+## Integrating with Prometheus
+
+cAdvisor can expose its metrics to [Prometheus](./prometheus.md).
+
+### Prerequesites
+
+The bare minimium is to ensure Prometheus can reach cadvisor.
+
+-   If cadvisor is on a different host than Prometheus, refer to section [Expose metrics publicly](cadvisor.md#)
+-   If cadvisor is on the same host than prometheus, refer to section [Ensure Prometheus is on the same container network as cadvisor.](cadvisor.md#)
+
+### Ensure Prometheus is on the same container network as cAdvisor.
+
+If you are using MASH playbook, cadvisor should already be connected to prometheus container network
+
+If cadvisor and prometheus do not share a network, you will have to
+
+-   Either connect Prometheus container network to cadvisor by editing `prometheus_container_additional_networks_auto`
+-   Either connect cadvisor container network to Prometheus by editing `cadvisor_container_additional_networks_custom`
+
+Exemple:
+
+```yaml
+prometheus_container_additional_networks:
+    - "{{ cadvisor_container_network }}"
+```
+
+### Write the scrape config for prometheus
+
+# Healthcheck
+
+```yaml
+cadvisor_environment_variables_extension: |
+
+# CADVISOR_HEALTHCHECK_URL=http://localhost:8080/cadvisor/healthz
+```
+
+## Usage
+
+After [installing](../installing.md), refer to the documentation of [cAdvisor](https://github.com/google/cadvisor).

docs/supported-services.md

@@ -11,6 +11,7 @@
 | [authentik](https://goauthentik.io/) | An open-source Identity Provider focused on flexibility and versatility. | [Link](services/authentik.md) |
 | [borgbackup](https://www.borgbackup.org/) (via [borgmatic](https://torsion.org/borgmatic/)) | A deduplicating backup program with optional compression and encryption| [Link](services/backup-borg.md) |
 | [Calibre-Web](https://github.com/janeczku/calibre-web) | Web app for browsing, reading and downloading eBooks stored in a [Calibre](https://calibre-ebook.com/) database | [Link](services/calibre-web.md) |
+| [cAdvisor](https://github.com/google/cadvisor) |  Analyzes resource usage and performance characteristics of running containers.  | [Link](services/cadvisor.md) |
 | [Changedetection.io](https://github.com/dgtlmoon/changedetection.io) | A simple website change detection and restock monitoring solution. | [Link](services/changedetection.md) |
 | [ClickHouse](https://clickhouse.com/) | An open-source column-oriented DBMS for online analytical processing (OLAP) that allows users to generate analytical reports using SQL queries in real-time. | [Link](services/clickhouse.md) |
 | [Collabora Online](https://www.collaboraoffice.com/) | Your Private Office Suite In The Cloud | [Link](services/collabora-online.md) |

templates/group_vars_mash_servers

@@ -1610,39 +1610,33 @@ wetty_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolve
 
 cadvisor_enabled: false
 
-cadvisor_identifier: "{{ mash_playbook_service_identifier_prefix }}prometheus-node-exporter"
-
-cadvisor_hostname: "{{ mash_playbook_metrics_exposure_hostname }}"
-cadvisor_path_prefix: "{{ mash_playbook_metrics_exposure_path_prefix }}/{{ cadvisor_identifier }}"
-
-cadvisor_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}prometheus-node-exporter"
+cadvisor_identifier: "{{ mash_playbook_service_identifier_prefix }}cadvisor"
 
 cadvisor_uid: "{{ mash_playbook_uid }}"
 cadvisor_gid: "{{ mash_playbook_gid }}"
 
-cadvisor_container_additional_networks: |
-  {{
-    ([mash_playbook_reverse_proxyable_services_additional_network] if mash_playbook_reverse_proxyable_services_additional_network else [])
-  }}
-
 # Only enable Traefik labels if a hostname is set (indicating that this will be exposed publicly)
 cadvisor_container_labels_traefik_enabled: "{{ mash_playbook_traefik_labels_enabled and cadvisor_hostname }}"
 cadvisor_container_labels_traefik_docker_network: "{{ mash_playbook_reverse_proxyable_services_additional_network }}"
 cadvisor_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}"
 cadvisor_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}"
 
+cadvisor_container_labels_metrics_enabled: "{{ prometheus_enabled | default(false) or mash_playbook_metrics_exposure_enabled }}"
+cadvisor_container_labels_metrics_hostname: "{{ mash_playbook_metrics_exposure_hostname }}"
+cadvisor_container_labels_metrics_path_prefix: "{{ mash_playbook_metrics_exposure_path_prefix }}/{{ cadvisor_identifier }}"
+cadvisor_container_labels_metrics_traefik_middleware_basic_auth_enabled: "{{ mash_playbook_metrics_exposure_http_basic_auth_enabled }}"
+cadvisor_container_labels_metrics_traefik_middleware_basic_auth_users: "{{ mash_playbook_metrics_exposure_http_basic_auth_users }}"
 cadvisor_container_labels_metrics_middleware_basic_auth_enabled: "{{ mash_playbook_metrics_exposure_http_basic_auth_enabled }}"
 cadvisor_container_labels_metrics_middleware_basic_auth_users: "{{ mash_playbook_metrics_exposure_http_basic_auth_users }}"
 
-cadvisor_container_extra_arguments_auto:
-  - "--mount type=bind,source=/,destination=/rootfs,readonly"
-  - "--mount type=bind,source=/var/run,destination=/var/run,readonly"
-  - "--mount type=bind,source=/sys,destination=/sys,readonly"
-  - "--mount type=bind,source=/var/lib/docker/,destination=/var/lib/docker,readonly"
-  - "--mount type=bind,source=/dev/disk/,destination=/dev/disk,readonly"
-  - "--mount type=bind,source=/dev/kmsg,target=/dev/kmsg"
-
-
+cadvisor_container_additional_networks_auto: |
+  {{
+    (
+      ([mash_playbook_reverse_proxyable_services_additional_network] if mash_playbook_reverse_proxyable_services_additional_network else [])
+      +
+      ([prometheus_container_network] if (prometheus_enabled | default(false) and prometheus_container_network | default('') != cadvisor_container_network) else [])
+    ) | unique
+  }}
 
 cadvisor_process_extra_arguments_auto:
   - "--url_base_prefix={{ cadvisor_container_labels_traefik_path_prefix }}"

templates/setup.yml

@@ -131,6 +131,10 @@
     - role: galaxy/calibre-web
     # /role-specific:calibre-web
 
+    # role-specific:cadvisor
+    - role: galaxy/cadvisor
+    # /role-specific:cadvisor
+
     # role-specific:clickhouse
     - role: galaxy/clickhouse
     # /role-specific:clickhouse