Skip to content

Blackbox Exporter Setup (Docker Compose)

Gitlab-Repository

Overview

Purpose:\ Blackbox Exporter performs active probing of external and internal services (HTTP/HTTPS, TCP, ICMP, DNS) and exposes the results as Prometheus metrics. It is mainly used for SLIs such as service availability, port reachability, and TLS certificate validity.

Scope (covered): - Deployment of prom/blackbox-exporter via Docker Compose - Configuration of blackbox.yml - Integration with Prometheus (scrape config + targets) - Validation, testing, and common issues

Out of scope (not covered): - Full Prometheus/Grafana/Alertmanager setup

Audience: DevOps engineers, OPS

Prerequisites

  • Docker + Docker Compose
  • Existing Docker network (e.g., monitoring) shared with Prometheus
  • Network/firewall access to the systems and ports you plan to probe
  • Required files:
    • ./provisioning/config/blackbox.yml
    • (Optional) ./provisioning/config/hosts for custom name resolution

./provisioning/config/hosts

192.168.134.80  qcans-qcint.quintessence.de
192.168.134.80 qcgit-qcint.quintessence.de
192.168.134.80  qcbas-qcint.quintessence.de
192.168.134.80  qcprx-qcint.quintessence.de
192.168.134.1  qcfwl-qcint.quintessence.de
192.168.134.80  qcprt-qcint.quintessence.de
192.168.134.80  qcmon-qcint.quintessence.de
192.168.134.80  qcmon-qcint.quintessence.de
192.168.134.80  qcnex-qcint.quintessence.de
192.168.134.80  qcjen-qcint.quintessence.de

Architecture Diagram

Configuration Details

Docker Compose Service

blackbox:
  image: prom/blackbox-exporter:latest
  container_name: blackbox
  ports:
    - 9115:9115
  command:
    - '--config.file=/etc/blackbox/blackbox.yml'
  volumes:
    - ./provisioning/config/hosts:/etc/hosts
    - ./provisioning/config/blackbox.yml:/etc/blackbox/blackbox.yml
  restart: always
  networks:
    - monitoring

Ports

  • 9115/tcp --- HTTP endpoint of Blackbox Exporter\
  • Prometheus must reach the container via blackbox:9115 inside the Docker network

Volumes

  • blackbox.yml → main probe configuration\
  • hosts → optional DNS override file

Step-by-Step Setup

  1. mkdir /home/prometheus-grafana (as root)
  2. cd /home/prometheus-grafana
  3. git clone https://qcgit-qcint.quintessence.de/net.quintessence.monitoring/prometheus-grafana.git
  4. docker compose up -d

Configure blackbox.yml

modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      method: GET
      valid_status_codes: [200, 301, 302]  # Разрешаем редиректы

  http_post_2xx:
    prober: http
    timeout: 5s
    http:
      method: POST
      valid_status_codes: [200]

  http_2xx_with_redirects:
    prober: http
    timeout: 5s
    http:
      method: GET
      follow_redirects: true
      valid_http_versions: [ "HTTP/1.1", "HTTP/2" ]
      valid_status_codes: [200, 301, 302, 401]

4. Add Blackbox job to Prometheus

scrape_configs:
  - job_name: 'blackbox-customers'
    scrape_interval: 60s
    scrape_timeout: 30s
    metrics_path: /probe
    params:
      module: [http_2xx_with_redirects]
    static_configs:
      - targets:
          - https://asghvtest-qcint.quintessence.de/asgard
          - https://dockerhvtest-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asghvdev-qcint.quintessence.de/asgard
          - https://dockerhvdev-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asgewtest-qcint.quintessence.de/asgard
          - https://dockerewtest-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asgewdev-qcint.quintessence.de/asgard
          - https://dockerewdev-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asga3dev-qcint.quintessence.de/asgard
          - https://dockera3dev-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asga3test-qcint.quintessence.de/asgard
          - https://dockera3test-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asglhtest-qcint.quintessence.de/asgard
          - https://dockerlhtest-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asgtotest-qcint.quintessence.de/asgard
          - https://dockertotest-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asgtodev-qcint.quintessence.de/asgard
          - https://dockertodev-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asgngtest-qcint.quintessence.de/asgard
          - https://dockerngtest-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asgdtftest-qcint.quintessence.de/asgard
          - https://dockerdtftest-qcint.quintessence.de/flightdeck/applicationInformation
          - https://asgdtfdev-qcint.quintessence.de/asgard
          - https://dockerdtfdev-qcint.quintessence.de/flightdeck/applicationInformation
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox:9115

Validation & Testing

ssh youruser:qcmon-qcint@qcbas-qcint.quintessence.de -p 2222
curl http://localhost:9115/metrics
curl "http://localhost:9115/probe?target=https://example.com&module=http_2xx"

Look for: - probe_success 1 - probe_duration_seconds

Troubleshooting

HTTPS probe fails - Check certificate chain\ - Try insecure module for testing

  • docker compose restart blackbox

Security Considerations

  • Restrict external access to port 9115\
  • Avoid privileged containers\
  • Be cautious with /etc/hosts overrides

Maintenance

cd /home/prometheus-grafana/
docker compose down blackbox
docker compose up -d blackbox
docker compose restart blackbox

Change Log

Version 1.0\ Date: 2026-01-27

Changelog

Date Author Message
2026-03-06 Daniel Germann QC-51493 change flightdeck urls
2026-02-25 aresnikowa Merge remote-tracking branch 'origin/master'