From 394344bf1c53a8849c8b33379b0a7d7ac4f090c5 Mon Sep 17 00:00:00 2001 From: sudo-Tiz Date: Wed, 10 Jul 2024 13:20:59 +0200 Subject: [PATCH] upgrade cadvisor documentation --- docs/services/cadvisor.md | 117 ++++++++++++++++++++++++++++++ docs/supported-services.md | 1 + templates/group_vars_mash_servers | 34 ++++----- templates/setup.yml | 4 + 4 files changed, 136 insertions(+), 20 deletions(-) create mode 100644 docs/services/cadvisor.md diff --git a/docs/services/cadvisor.md b/docs/services/cadvisor.md new file mode 100644 index 00000000..a21b24b4 --- /dev/null +++ b/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: + + + +# 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). diff --git a/docs/supported-services.md b/docs/supported-services.md index f8150647..e5aa7581 100644 --- a/docs/supported-services.md +++ b/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) | diff --git a/templates/group_vars_mash_servers b/templates/group_vars_mash_servers index 2805d329..cca35e99 100644 --- a/templates/group_vars_mash_servers +++ b/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 }}" diff --git a/templates/setup.yml b/templates/setup.yml index 1d24d4c4..43deaaf0 100644 --- a/templates/setup.yml +++ b/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