add Cadvisor

docs/services/cadvisor.md

@@ -0,0 +1,100 @@
+# 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 cAdvisor
+
+To expose cAdvisor WebUI and metrics 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 web ui and your 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: ""
+```
+
+## Integrating with Prometheus
+
+### Prerequesites
+
+The bare minimium is to ensure Prometheus can reach cadvisor.
+
+-   If cadvisor is on a different host than Prometheus, refer to section [Exposing publicly cAdvisor](cadvisor.md#Exposing-publicly-cAdvisor)
+-   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 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
+
+```yaml
+prometheus_config_scrape_configs_additional:
+    - job_name: cadvisor
+      scrape_interval: 5s
+      scrape_timeout: 5s
+      static_configs:
+          - targets:
+                - "{{ cadvisor_identifier }}:8080"
+```
+
+replace the target by your ip_adress:port if cAdvisor is on a different host than Prometheus
+
+## Usage
+
+After [installing](../installing.md), refer to the documentation of [cAdvisor](https://github.com/google/cadvisor).

docs/services/grafana.md

@@ -2,13 +2,11 @@
 
 [Grafana](https://grafana.com/) is an open and composable observability and data visualization platform, often used with [Prometheus](prometheus.md).
 
-
 ## Dependencies
 
 This service requires the following other services:
 
-- a [Traefik](traefik.md) reverse-proxy server
-
+-   a [Traefik](traefik.md) reverse-proxy server
 
 ## Configuration
 
@@ -28,8 +26,7 @@ grafana_path_prefix: /grafana
 
 grafana_default_admin_user: admin
 # Generating a strong password (e.g. `pwgen -s 64 1`) is recommended
-grafana_default_admin_password: ''
-
+grafana_default_admin_password: ""
 ########################################################################
 #                                                                      #
 # /grafana                                                             #
@@ -70,7 +67,7 @@ grafana_provisioning_datasources:
 
 # Prometheus runs in another container network, so we need to connect to it.
 grafana_container_additional_networks_custom:
-  - "{{ prometheus_container_network }}"
+    - "{{ prometheus_container_network }}"
 ```
 
 For connecting to a **remote** Prometheus instance, you may need to adjust this configuration.
@@ -81,22 +78,22 @@ If you're installing [Grafana Loki](grafana-loki.md) on the same server, you can
 
 ```yaml
 grafana_provisioning_datasources:
-  - name: Loki (your-tenant-id)
-    type: loki
-    access: proxy
-    url: "http://{{ loki_identifier }}:{{ loki_server_http_listen_port }}"
-    # Enable below and also (basicAuthPassword) if connecting to a remote instance that uses Basic Auth.
-    # basicAuth: true
-    # basicAuthUser: loki
-    jsonData:
-      httpHeaderName1: X-Scope-OrgID
-    secureJsonData:
-      httpHeaderValue1: "your-tenant-id"
-      # basicAuthPassword: ""
+    - name: Loki (your-tenant-id)
+      type: loki
+      access: proxy
+      url: "http://{{ loki_identifier }}:{{ loki_server_http_listen_port }}"
+      # Enable below and also (basicAuthPassword) if connecting to a remote instance that uses Basic Auth.
+      # basicAuth: true
+      # basicAuthUser: loki
+      jsonData:
+          httpHeaderName1: X-Scope-OrgID
+      secureJsonData:
+          httpHeaderValue1: "your-tenant-id"
+          # basicAuthPassword: ""
 
 # Loki runs in another container network, so we need to connect to it.
 grafana_container_additional_networks_custom:
-  - "{{ loki_container_network }}"
+    - "{{ loki_container_network }}"
 ```
 
 For connecting to a **remote** Loki instance, you may need to adjust this configuration.
@@ -111,10 +108,25 @@ The Prometheus Node Exporter role exposes a list of URLs containing dashboards (
 
 You can add this **additional** configuration to make the Grafana service pull these dashboards:
 
+```yaml
+grafana_dashboard_download_urls: |
+    {{
+      prometheus_node_exporter_dashboard_urls
+    }}
+```
+
+### Integrating with cAdvisor
+
+If you've installed [cAdvisor](cadvisor.md) on any host (target) scraped by Prometheus, you may wish to install a dashboard for cAdvisor.
+
+The cAdvisor role exposes a list of URLs containing dashboards (JSON files) in its `cadvisor_dashboard_urls` variable.
+
+You can add this **additional** configuration to make the Grafana service pull these dashboards:
+
 ```yaml
 grafana_dashboard_download_urls: |
   {{
-    prometheus_node_exporter_dashboard_urls
+    cadvisor_dashboard_urls
   }}
 ```
 
@@ -154,34 +166,33 @@ grafana_environment_variables_additional_variables: |
 
 Make sure the user you want to login as has an email address in authentik, otherwise there will be an error.
 
-
 #### Single-Sign-On / Authelia
 
 The configuration flow below assumes [Authelia](authelia.md) configured via the playbook, but you can run Authelia in another way too.
 
-- Come up with a client ID you'd like to use. Example: `grafana`
-- Generate a shared secret for the OpenID Connect application: `pwgen -s 64 1`. This is to be used in `GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET` below
-- Hash the shared secret for use in Authelia's configuration (`authelia_config_identity_providers_oidc_clients`): `php -r 'echo password_hash("PASSWORD_HERE",  PASSWORD_ARGON2ID);'`. Feel free to use another language (or tool) for creating a hash as well. A few different hash algorithms are supported besides Argon2id.
-- Define this `grafana` client in Authelia via `authelia_config_identity_providers_oidc_clients`. See [example configuration](authelia.md#protecting-a-service-with-openid-connect) on the Authelia documentation page.
+-   Come up with a client ID you'd like to use. Example: `grafana`
+-   Generate a shared secret for the OpenID Connect application: `pwgen -s 64 1`. This is to be used in `GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET` below
+-   Hash the shared secret for use in Authelia's configuration (`authelia_config_identity_providers_oidc_clients`): `php -r 'echo password_hash("PASSWORD_HERE",  PASSWORD_ARGON2ID);'`. Feel free to use another language (or tool) for creating a hash as well. A few different hash algorithms are supported besides Argon2id.
+-   Define this `grafana` client in Authelia via `authelia_config_identity_providers_oidc_clients`. See [example configuration](authelia.md#protecting-a-service-with-openid-connect) on the Authelia documentation page.
 
 ```yaml
 # To make Grafana honor the expiration time of JWT tokens, enable this experimental feature below.
 # grafana_feature_toggles_enable: accessTokenExpirationCheck
 
 grafana_environment_variables_additional_variables: |
-  GF_AUTH_GENERIC_OAUTH_ENABLED=true
-  GF_AUTH_GENERIC_OAUTH_NAME=Authelia
-  GF_AUTH_GENERIC_OAUTH_CLIENT_ID=grafana
-  GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=PLAIN_TEXT_SHARED_SECRET
-  GF_AUTH_GENERIC_OAUTH_SCOPES=openid profile email groups
-  GF_AUTH_GENERIC_OAUTH_EMPTY_SCOPES=false
-  GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://authelia.example.com/api/oidc/authorization
-  GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://authelia.example.com/api/oidc/token
-  GF_AUTH_GENERIC_OAUTH_API_URL=https://authelia.example.com/api/oidc/userinfo
-  GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH=preferred_username
-  GF_AUTH_GENERIC_OAUTH_GROUPS_ATTRIBUTE_PATH=groups
-  GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH=name
-  GF_AUTH_GENERIC_OAUTH_USE_PKCE=true
+    GF_AUTH_GENERIC_OAUTH_ENABLED=true
+    GF_AUTH_GENERIC_OAUTH_NAME=Authelia
+    GF_AUTH_GENERIC_OAUTH_CLIENT_ID=grafana
+    GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=PLAIN_TEXT_SHARED_SECRET
+    GF_AUTH_GENERIC_OAUTH_SCOPES=openid profile email groups
+    GF_AUTH_GENERIC_OAUTH_EMPTY_SCOPES=false
+    GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://authelia.example.com/api/oidc/authorization
+    GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://authelia.example.com/api/oidc/token
+    GF_AUTH_GENERIC_OAUTH_API_URL=https://authelia.example.com/api/oidc/userinfo
+    GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH=preferred_username
+    GF_AUTH_GENERIC_OAUTH_GROUPS_ATTRIBUTE_PATH=groups
+    GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH=name
+    GF_AUTH_GENERIC_OAUTH_USE_PKCE=true
 ```
 
 ## Usage
@@ -190,7 +201,6 @@ After installation, you should be able to access your new Grafana instance at th
 
 Going there, you'll be taken to the initial setup wizard, which will let you assign some paswords and other configuration.
 
-
 ## Recommended other services
 
 Grafana is just a visualization tool which requires pulling data from a metrics (time-series) database like.

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

@@ -186,6 +186,11 @@ mash_playbook_devture_systemd_service_manager_services_list_auto_itemized:
     {{ ({'name': (authelia_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'authelia']} if authelia_enabled else omit) }}
   # /role-specific:authelia
 
+  # role-specific:cadvisor
+  - |-
+    {{ ({'name': (cadvisor_identifier + '.service'), 'priority': 500, 'groups': ['mash', 'metrics', 'cadvisor']} if cadvisor_enabled else omit) }}
+  # /role-specific:cadvisor
+
   # role-specific:calibre-web
   - |-
     {{ ({'name': (calibre_web_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'calibre-web']} if calibre_web_enabled else omit) }}
@@ -1662,6 +1667,53 @@ wetty_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primar
 
 
 
+# role-specific:cadvisor
+########################################################################
+#                                                                      #
+# cadvisor                                                             #
+#                                                                      #
+########################################################################
+
+cadvisor_enabled: false
+
+cadvisor_identifier: "{{ mash_playbook_service_identifier_prefix }}cadvisor"
+
+cadvisor_uid: "{{ mash_playbook_uid }}"
+cadvisor_gid: "{{ mash_playbook_gid }}"
+
+cadvisor_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}cadvisor"
+
+# 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_additional_networks_auto: |
+  {{
+      ([prometheus_container_network] if (prometheus_enabled | default(false) and prometheus_container_network | default('') != cadvisor_container_network) else [])
+  }}
+
+cadvisor_process_extra_arguments_auto:
+  - "--url_base_prefix={{ cadvisor_path_prefix }}"
+
+########################################################################
+#                                                                      #
+# /cadvisor                                                            #
+#                                                                      #
+########################################################################
+# /role-specific:cadvisor
+
+
+
 # role-specific:calibre-web
 ########################################################################
 #                                                                      #

templates/requirements.yml

@@ -32,6 +32,10 @@
   version: v1.4.0-1.9.4-0
   name: backup_borg
   activation_prefix: backup_borg_
+- src: git+https://github.com/sudo-Tiz/ansible-role-cadvisor.git
+  version: main
+  name: cadvisor
+  activation_prefix: cadvisor_
 - src: git+https://github.com/lingawakad/ansible-role-calibre-web.git
   version: v0.6.24-0
   name: calibre-web

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