gitadmin/italiadatacenter

Fork 0

Files

T

alessandro barucci 63649a642a varie

2026-09-20 19:26:05 +02:00

19 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.

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:

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

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

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

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://my-service.my-namespace.svc.cluster.local:8080/health
        - http://another-service.default.svc.cluster.local:80/
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

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

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.

CREA DASHBOARD GRAFANA PER LE PROBE ======================================

Obiettivo:

visualizzare lo stato delle probe HTTP;
vedere quali target sono UP o DOWN;
controllare status code e latenza per ogni endpoint;
filtrare la dashboard per job e target.

COMANDO - apri Grafana in locale con port-forward

kubectl port-forward -n monitoring svc/kube-prometheus-stack-grafana 3000:80

Poi apri nel browser:

http://localhost:3000

COMANDO - recupera password admin Grafana se non la conosci

kubectl get secret -n monitoring kube-prometheus-stack-grafana \
  -o jsonpath="{.data.admin-password}" | base64 -d

Credenziali predefinite tipiche:

utente: admin
password: valore recuperato dal secret

NOTA - datasource Prometheus Con kube-prometheus-stack il datasource Prometheus di solito e' gia' configurato in Grafana. Verifica da Grafana:

Connections -> Data sources -> Prometheus

CREAZIONE DASHBOARD DA INTERFACCIA

Vai su Dashboards -> New -> New dashboard.
Clicca Add visualization.
Seleziona il datasource Prometheus.
Crea i pannelli usando le query sotto.
Salva la dashboard con nome, ad esempio:

Blackbox HTTP Probes

VARIABILI CONSIGLIATE

Variabile job:

Name: job
Type: Query
Data source: Prometheus
Query: label_values(probe_success, job)
Multi-value: enabled
Include All option: enabled

Variabile instance:

Name: instance
Type: Query
Data source: Prometheus
Query: label_values(probe_success{job=~"$job"}, instance)
Multi-value: enabled
Include All option: enabled

PANNELLO - stato generale probe

Tipo pannello: Stat

Query:

min(probe_success{job=~"$job", instance=~"$instance"})

Configurazione consigliata:

Unit: none
Thresholds:
  0 = red
  1 = green
Value mappings:
  0 -> DOWN
  1 -> UP

PANNELLO - stato per target

Tipo pannello: State timeline oppure Table

Query:

probe_success{job=~"$job", instance=~"$instance"}

Configurazione consigliata:

Legend: {{ instance }}
Value mappings:
  0 -> DOWN
  1 -> UP

PANNELLO - target attualmente falliti

Tipo pannello: Table

Query:

probe_success{job=~"$job", instance=~"$instance"} == 0

Configurazione consigliata:

Legend: {{ instance }}
Mostra colonne: instance, job, value

PANNELLO - durata probe per target

Tipo pannello: Time series

Query:

probe_duration_seconds{job=~"$job", instance=~"$instance"}

Configurazione consigliata:

Unit: seconds
Legend: {{ instance }}
Thresholds:
  1 = yellow
  2 = red

PANNELLO - status code HTTP

Tipo pannello: Time series oppure Table

Query:

probe_http_status_code{job=~"$job", instance=~"$instance"}

Configurazione consigliata:

Unit: none
Legend: {{ instance }}

PANNELLO - percentuale disponibilita' per target

Tipo pannello: Bar gauge oppure Table

Query:

avg_over_time(probe_success{job=~"$job", instance=~"$instance"}[24h]) * 100

Configurazione consigliata:

Unit: percent
Min: 0
Max: 100
Legend: {{ instance }}
Thresholds:
  95 = yellow
  99 = green

PANNELLO - durata media nelle ultime 24 ore

Tipo pannello: Bar gauge oppure Table

Query:

avg_over_time(probe_duration_seconds{job=~"$job", instance=~"$instance"}[24h])

Configurazione consigliata:

Unit: seconds
Legend: {{ instance }}

QUERY RAPIDE SENZA VARIABILI

Se vuoi creare una dashboard solo per la Probe di esempio dei servizi interni:

probe_success{job="http-services-probe"}
probe_http_status_code{job="http-services-probe"}
probe_duration_seconds{job="http-services-probe"}
probe_success{job="http-services-probe"} == 0
avg_over_time(probe_success{job="http-services-probe"}[24h]) * 100

Per la Probe di esempio degli Ingress o URL esterni:

probe_success{job="ingress-http-probe"}
probe_http_status_code{job="ingress-http-probe"}
probe_duration_seconds{job="ingress-http-probe"}
probe_success{job="ingress-http-probe"} == 0
avg_over_time(probe_success{job="ingress-http-probe"}[24h]) * 100

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

CONFIGURA ALERTMANAGER - INVIO EMAIL SU FAIL DI UN SERVIZIO ================================================================

Obiettivo:

inviare una email a un indirizzo specifico quando la probe di un servizio specifico (serviceX) fallisce (alert BlackboxHttpProbeFailed).

FILE - blackbox-email-alert.yaml

Descrizione:

crea un receiver email dedicato al servizio da monitorare;
instrada verso quel receiver solo gli alert che riguardano il target specifico, identificato tramite il label instance.

NOTA - credenziali SMTP Se il server SMTP richiede autenticazione, crea prima un Secret con la password:

COMANDO - crea secret con password SMTP

kubectl create secret generic alertmanager-smtp \
  -n monitoring --from-literal=password='<SMTP_PASSWORD>'

COMANDO - crea blackbox-email-alert.yaml

cat > blackbox-email-alert.yaml <<'EOF'
apiVersion: monitoring.coreos.com/v1alpha1
kind: AlertmanagerConfig
metadata:
  name: blackbox-email-routing
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  route:
    groupBy: ["alertname", "instance"]
    groupWait: 30s
    groupInterval: 5m
    repeatInterval: 1h
    receiver: "email-default"
    routes:
      - matchers:
          - name: alertname
            value: BlackboxHttpProbeFailed
            matchType: "="
          - name: instance
            value: "<SERVIZIO_X_URL_O_HOST>"
            matchType: "="
        receiver: "email-servizioX"

  receivers:
    - name: "email-default"
      emailConfigs: []

    - name: "email-servizioX"
      emailConfigs:
        - to: "<INDIRIZZO_X>"
          from: "<SMTP_FROM>"
          smarthost: "<SMTP_HOST>:<SMTP_PORT>"
          authUsername: "<SMTP_USER>"
          authPassword:
            name: alertmanager-smtp
            key: password
          requireTLS: true
          sendResolved: true
          headers:
            subject: "[ALERT] Servizio X non raggiungibile"
          html: |
            <p>Il servizio <b>{{ "{{" }} .CommonLabels.instance {{ "}}" }}</b> non risponde.</p>
            <p>{{ "{{" }} .CommonAnnotations.description {{ "}}" }}</p>
EOF

Da personalizzare:

<SERVIZIO_X_URL_O_HOST>: valore del label instance della probe da monitorare (es. http://my-service.my-namespace.svc.cluster.local:8080/health);
<INDIRIZZO_X>: indirizzo email destinatario;
<SMTP_HOST>, <SMTP_PORT>: server SMTP (es. smtp.gmail.com:587);
<SMTP_FROM>: mittente email;
<SMTP_USER>: utente SMTP, se richiesta autenticazione.

COMANDO - applica la configurazione

kubectl apply -f blackbox-email-alert.yaml

COMANDO - verifica AlertmanagerConfig

kubectl get alertmanagerconfig -n monitoring
kubectl describe alertmanagerconfig blackbox-email-routing -n monitoring

NOTA - matcher su instance vs job Se vuoi far scattare l'email per TUTTI i target di una Probe (job) invece che per un singolo servizio, sostituisci il matcher su instance con:

- name: job
  value: "http-services-probe"
  matchType: "="

COMANDO - verifica alert in Alertmanager

kubectl port-forward -n monitoring svc/kube-prometheus-stack-alertmanager 9093
# -> http://localhost:9093, controlla che l'alert BlackboxHttpProbeFailed
#    per il servizio X sia instradato sul receiver email-servizioX

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

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.

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

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.

19 KiB Raw Blame History

BLACKBOX EXPORTER - GUIDA OPERATIVA KUBERNETES

Stack di partenza

Obiettivo

Legenda

Prerequisiti

19 KiB

Raw Blame History