gitadmin/italiadatacenter
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
d190719c5e3168e51a4158d2d0adbe9c861b511b
italiadatacenter/add-on/blackbox-exporter.md
T
alessandro d190719c5e varie
2026-09-21 10:00:05 +02:00

12 KiB
Raw Blame History

BLACKBOX EXPORTER - GUIDA OPERATIVA KUBERNETES

Stack di partenza

Nel cluster e' gia' installato kube-prometheus-stack nel namespace monitoring:

helm list -A | grep prometheus

kube-prometheus-stack  monitoring  4  2026-08-08 23:55:14.193903052 +0000 UTC  deployed  kube-prometheus-stack-88.1.5

Obiettivo

Installare prometheus-blackbox-exporter per eseguire test HTTP/HTTPS su servizi Kubernetes interni, Ingress o URL esterni, esportando le metriche verso Prometheus tramite Prometheus Operator.

Metriche principali:

probe_success
probe_duration_seconds
probe_http_status_code
probe_http_ssl
probe_dns_lookup_time_seconds

Legenda

  • COMANDO: istruzione da eseguire nel terminale.
  • FILE: file da creare o aggiornare.
  • NOTA: informazione da verificare prima di procedere.
  • OUTPUT ATTESO: risultato indicativo del comando.

Prerequisiti

  • Accesso kubectl al cluster.
  • Helm installato.
  • Namespace monitoring presente o creabile.
  • kube-prometheus-stack installato con Prometheus Operator.
  • CRD Probe disponibile: probes.monitoring.coreos.com.
  1. VERIFICA PROMETHEUS E PROMETHEUS OPERATOR ============================================

COMANDO - verifica release Helm Prometheus

helm list -A | grep prometheus

COMANDO - verifica pod Prometheus

kubectl get pods -A | grep prometheus

COMANDO - verifica CRD Probe

kubectl get crd probes.monitoring.coreos.com

COMANDO - verifica label delle risorse Prometheus

kubectl get prometheus -A --show-labels

COMANDO - controlla selector della risorsa Prometheus

kubectl get prometheus -n monitoring -o yaml

NOTA - label dei manifest Dal comando kubectl get prometheus -A --show-labels risulta che Prometheus seleziona le risorse con la label release=kube-prometheus-stack. Negli esempi sotto viene quindi usata questa label:

release: kube-prometheus-stack

Se in futuro il tuo Prometheus usa un selector diverso, sostituisci questa label nei manifest Probe e PrometheusRule. Controlla soprattutto questi campi nella risorsa Prometheus:

spec:
  probeSelector:
  probeNamespaceSelector:
  ruleSelector:
  ruleNamespaceSelector:
  1. AGGIUNTA REPOSITORY HELM ===========================

COMANDO - aggiungi repository prometheus-community

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

COMANDO - aggiorna indice chart Helm

helm repo update
  1. CREA FILE VALUES HELM ========================

FILE - blackbox-values.yaml

Descrizione:

  • configura i moduli HTTP usati da blackbox-exporter;
  • espone blackbox-exporter come Service ClusterIP sulla porta 9115;
  • lascia disabilitato ServiceMonitor perche' lo scraping dei target viene configurato tramite Probe.

COMANDO - crea blackbox-values.yaml

cat > blackbox-values.yaml <<'EOF'
fullnameOverride: blackbox-exporter

config:
  modules:
    http_2xx:
      prober: http
      timeout: 10s
      http:
        method: GET
        preferred_ip_protocol: ip4
        valid_http_versions:
          - HTTP/1.1
          - HTTP/2.0
        valid_status_codes:
          - 200
          - 204
          - 301
          - 302

    http_post_2xx:
      prober: http
      timeout: 10s
      http:
        method: POST
        preferred_ip_protocol: ip4
        valid_status_codes:
          - 200
          - 201
          - 202
          - 204

    http_k8s_health:
      prober: http
      timeout: 10s
      http:
        method: GET
        preferred_ip_protocol: ip4
        fail_if_ssl: false
        fail_if_not_ssl: false
        valid_status_codes:
          - 200

service:
  type: ClusterIP
  port: 9115

serviceMonitor:
  enabled: false

resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    cpu: 200m
    memory: 256Mi
EOF
  1. INSTALLA BLACKBOX EXPORTER =============================

COMANDO - installa o aggiorna blackbox-exporter

helm upgrade --install blackbox-exporter prometheus-community/prometheus-blackbox-exporter \
  --namespace monitoring \
  --create-namespace \
  -f blackbox-values.yaml

COMANDO - verifica pod blackbox-exporter

kubectl get pods -n monitoring | grep blackbox

COMANDO - verifica Service blackbox-exporter

kubectl get svc -n monitoring | grep blackbox

OUTPUT ATTESO

blackbox-exporter   ClusterIP   <cluster-ip>   <none>   9115/TCP
  1. CREA PROBE HTTP PER SERVIZI KUBERNETES INTERNI =================================================

FILE - blackbox-probes.yaml

Descrizione:

  • testa endpoint HTTP interni tramite DNS Kubernetes;
  • usa il modulo http_k8s_health definito in blackbox-values.yaml;
  • invia le metriche a Prometheus tramite la risorsa Probe del Prometheus Operator.

Da personalizzare:

  • my-service
  • my-namespace
  • porta del servizio
  • path HTTP, ad esempio /health, /ready o /
  • label release se diversa da prometheus

COMANDO - crea blackbox-probes.yaml

cat > blackbox-probes.yaml <<'EOF'
apiVersion: monitoring.coreos.com/v1
kind: Probe
metadata:
  name: http-services-probe
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  jobName: http-services-probe
  interval: 30s
  scrapeTimeout: 15s
  module: http_k8s_health
  prober:
    url: blackbox-exporter.monitoring.svc.cluster.local:9115
    scheme: http
    path: /probe
  targets:
    staticConfig:
      static:
        - http://frontend.idcidp-dev.svc.cluster.local
EOF

COMANDO - applica Probe servizi interni

kubectl apply -f blackbox-probes.yaml

COMANDO - verifica Probe

kubectl get probe -n monitoring
kubectl describe probe http-services-probe -n monitoring

NOTA - campi importanti della Probe

spec:
  module: http_k8s_health
  prober:
    url: blackbox-exporter.monitoring.svc.cluster.local:9115
  targets:
    staticConfig:
      static:
        - http://my-service.my-namespace.svc.cluster.local:8080/health
  1. CREA PROBE HTTP/HTTPS PER INGRESS O URL ESTERNI ==================================================

FILE - blackbox-ingress-probes.yaml

Descrizione:

  • testa URL esposti tramite Ingress, Gateway, reverse proxy o endpoint pubblici;
  • usa il modulo generico http_2xx.

COMANDO - crea blackbox-ingress-probes.yaml

cat > blackbox-ingress-probes.yaml <<'EOF'
apiVersion: monitoring.coreos.com/v1
kind: Probe
metadata:
  name: ingress-http-probe
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  jobName: ingress-http-probe
  interval: 30s
  scrapeTimeout: 15s
  module: http_2xx
  prober:
    url: blackbox-exporter.monitoring.svc.cluster.local:9115
    scheme: http
    path: /probe
  targets:
    staticConfig:
      static:
        - https://app.example.com/health
        - https://api.example.com/ready
EOF

COMANDO - applica Probe endpoint esterni

kubectl apply -f blackbox-ingress-probes.yaml
  1. VERIFICA METRICHE IN PROMETHEUS ==================================

COMANDO - apri Prometheus in locale con port-forward

kubectl port-forward -n monitoring svc/kube-prometheus-stack-prometheus 9090:9090

Poi apri nel browser:

http://localhost:9090

QUERY PROMQL - tutte le probe

probe_success

QUERY PROMQL - probe servizi interni

probe_success{job="http-services-probe"}

QUERY PROMQL - status code HTTP

probe_http_status_code{job="http-services-probe"}

QUERY PROMQL - durata probe

probe_duration_seconds{job="http-services-probe"}

QUERY PROMQL - target falliti

probe_success{job="http-services-probe"} == 0

Interpretazione:

  • probe_success = 1: test riuscito.
  • probe_success = 0: test fallito.
  • probe_http_status_code: status HTTP ricevuto.
  • probe_duration_seconds: durata della probe.
  1. CREA ALERT PROMETHEUSRULE ============================

FILE - blackbox-http-alerts.yaml

Descrizione:

  • genera alert quando un target HTTP non risponde correttamente;
  • genera alert quando un target risponde troppo lentamente.

COMANDO - crea blackbox-http-alerts.yaml

cat > blackbox-http-alerts.yaml <<'EOF'
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: blackbox-http-alerts
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  groups:
    - name: blackbox-http
      rules:
        - alert: BlackboxHttpProbeFailed
          expr: probe_success == 0
          for: 2m
          labels:
            severity: warning
          annotations:
            summary: "HTTP probe fallita"
            description: "Il target {{ $labels.instance }} non risponde correttamente da almeno 2 minuti."

        - alert: BlackboxHttpSlowResponse
          expr: probe_duration_seconds > 2
          for: 5m
          labels:
            severity: warning
          annotations:
            summary: "HTTP probe lenta"
            description: "Il target {{ $labels.instance }} risponde in piu' di 2 secondi da almeno 5 minuti."
EOF

COMANDO - applica alert

kubectl apply -f blackbox-http-alerts.yaml

COMANDO - verifica PrometheusRule

kubectl get prometheusrule -n monitoring | grep blackbox
kubectl describe prometheusrule blackbox-http-alerts -n monitoring
  1. TEST MANUALE BLACKBOX EXPORTER =================================

COMANDO - port-forward blackbox-exporter

kubectl port-forward -n monitoring svc/blackbox-exporter 9115:9115

COMANDO - esegui probe manuale da un altro terminale

curl "http://localhost:9115/probe?target=http://my-service.my-namespace.svc.cluster.local:8080/health&module=http_k8s_health"

OUTPUT ATTESO - metriche indicative

probe_success 1
probe_http_status_code 200
  1. TROUBLESHOOTING ===================

CASO - Prometheus non vede la Probe

COMANDO

kubectl get probe -A
kubectl describe probe -n monitoring http-services-probe
kubectl get prometheus -n monitoring -o yaml

Controlla:

  • spec.probeSelector
  • spec.probeNamespaceSelector
  • metadata.labels della Probe

CASO - blackbox-exporter non parte

COMANDO

kubectl get pods -n monitoring | grep blackbox
kubectl logs -n monitoring deploy/blackbox-exporter

CASO - servizio target non raggiungibile

COMANDO

kubectl get svc -n my-namespace
kubectl get endpoints -n my-namespace my-service
kubectl describe svc -n my-namespace my-service

CASO - DNS Kubernetes non risolve

COMANDO

kubectl run dns-test --rm -it --image=busybox:1.36 --restart=Never -- nslookup my-service.my-namespace.svc.cluster.local

CASO - endpoint HTTPS fallisce per certificati, redirect o header

Azioni consigliate:

  • usare il modulo http_2xx per endpoint esterni generici;
  • verificare se l'endpoint richiede SNI, autenticazione, header custom o path diverso;
  • aggiungere un modulo dedicato in blackbox-values.yaml se serve una configurazione HTTP specifica.
  1. ORDINE DI ESECUZIONE CONSIGLIATO ====================================

COMANDO - sequenza completa

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm upgrade --install blackbox-exporter prometheus-community/prometheus-blackbox-exporter \
  --namespace monitoring \
  --create-namespace \
  -f blackbox-values.yaml

kubectl apply -f blackbox-probes.yaml
kubectl apply -f blackbox-ingress-probes.yaml
kubectl apply -f blackbox-http-alerts.yaml

FILE CONSIGLIATI DA VERSIONARE

blackbox-values.yaml
blackbox-probes.yaml
blackbox-ingress-probes.yaml
blackbox-http-alerts.yaml
  1. NOTE PER DEV, QA E PROD ===========================

Per separare gli ambienti e semplificare dashboard e alert, usa Probe distinte:

dev-http-services-probe
qa-http-services-probe
prod-http-services-probe

QUERY PROMQL - ambiente dev

probe_success{job="dev-http-services-probe"}

QUERY PROMQL - target prod falliti

probe_success{job="prod-http-services-probe"} == 0

Per endpoint critici in produzione, valuta:

  • interval piu' basso, ad esempio 15s o 30s;
  • durata for degli alert tra 1m e 5m in base alla criticita';
  • dashboard Grafana con stato, status code e latenza per target.
Reference in New Issue View Git Blame Copy Permalink