Last updated: 2026-05-15

Prometheus TLS/SSL Configuration Guide

This guide provides recommended TLS/SSL settings for Prometheus to encrypt connections to the web UI, API, and scrape targets. Prometheus 2.24+ supports native TLS for its HTTP server and TLS-encrypted scraping.

Prerequisites

  • Prometheus 2.24 or later (for native TLS support)
  • SSL certificates (server certificate, private key, and CA certificate)

Certificate Setup

Place your certificates in a dedicated directory:

mkdir -p /etc/prometheus/ssl
chmod 750 /etc/prometheus/ssl
chown prometheus:prometheus /etc/prometheus/ssl

cp server.crt /etc/prometheus/ssl/server-cert.pem
cp server.key /etc/prometheus/ssl/server-key.pem
cp ca.crt /etc/prometheus/ssl/ca.pem

chmod 640 /etc/prometheus/ssl/*.pem
chown prometheus:prometheus /etc/prometheus/ssl/*.pem

Web Server TLS

Configure Prometheus to serve its web UI and API over HTTPS using a web configuration file.

Web Configuration File

Create /etc/prometheus/web-config.yml:

tls_server_config:
  cert_file: /etc/prometheus/ssl/server-cert.pem
  key_file: /etc/prometheus/ssl/server-key.pem
  min_version: TLS12
  max_version: TLS13
  cipher_suites:
    - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
    - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
  curve_preferences:
    - X25519
    - P256
    - P384

Note: The cipher_suites setting only applies to TLS 1.2. Go's TLS 1.3 implementation uses a fixed set of secure cipher suites.

Start Prometheus with TLS

prometheus --config.file=/etc/prometheus/prometheus.yml \
    --web.config.file=/etc/prometheus/web-config.yml

Client Certificate Authentication

To require clients to present a TLS certificate (mutual TLS):

tls_server_config:
  cert_file: /etc/prometheus/ssl/server-cert.pem
  key_file: /etc/prometheus/ssl/server-key.pem
  client_ca_file: /etc/prometheus/ssl/ca.pem
  client_auth_type: RequireAndVerifyClientCert
  min_version: TLS12
  max_version: TLS13
  cipher_suites:
    - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
    - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

Available client_auth_type values:

  • NoClientCert -- Do not request a client certificate (default)
  • RequestClientCert -- Request but do not require a client certificate
  • RequireAndVerifyClientCert -- Require and verify a client certificate

Scrape Target TLS

Configure Prometheus to scrape targets over HTTPS. Add TLS settings to your prometheus.yml scrape configuration.

Scraping HTTPS Targets

scrape_configs:
  - job_name: "node"
    scheme: https
    tls_config:
      ca_file: /etc/prometheus/ssl/ca.pem
      insecure_skip_verify: false
    static_configs:
      - targets:
          - "node1.example.com:9100"
          - "node2.example.com:9100"

Scraping with Mutual TLS

If the target requires client certificates:

scrape_configs:
  - job_name: "secure-app"
    scheme: https
    tls_config:
      ca_file: /etc/prometheus/ssl/ca.pem
      cert_file: /etc/prometheus/ssl/client-cert.pem
      key_file: /etc/prometheus/ssl/client-key.pem
      insecure_skip_verify: false
    static_configs:
      - targets:
          - "app.example.com:9090"

Configuration Explained

  • scheme: https -- Use HTTPS to connect to scrape targets.
  • ca_file -- CA certificate to verify the target's server certificate.
  • cert_file / key_file -- Client certificate and key for mutual TLS.
  • insecure_skip_verify -- Set to true to skip server certificate verification (not recommended for production).

See RFC 8446 ยง4.3.2 for the TLS Certificate Request specification, and Wikipedia: Mutual authentication for a general overview.

Basic Authentication

The web configuration file also supports HTTP basic authentication, which should always be used in conjunction with TLS:

tls_server_config:
  cert_file: /etc/prometheus/ssl/server-cert.pem
  key_file: /etc/prometheus/ssl/server-key.pem
  min_version: TLS12

basic_auth_users:
  admin: $2y$10$...  # bcrypt hash

Generate a bcrypt password hash:

htpasswd -nBC 10 admin

Complete Configuration

web-config.yml

tls_server_config:
  cert_file: /etc/prometheus/ssl/server-cert.pem
  key_file: /etc/prometheus/ssl/server-key.pem
  min_version: TLS12
  max_version: TLS13
  cipher_suites:
    - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
    - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
  curve_preferences:
    - X25519
    - P256
    - P384

prometheus.yml (TLS scrape excerpt)

scrape_configs:
  - job_name: "prometheus"
    scheme: https
    tls_config:
      ca_file: /etc/prometheus/ssl/ca.pem
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: "node"
    scheme: https
    tls_config:
      ca_file: /etc/prometheus/ssl/ca.pem
    static_configs:
      - targets:
          - "node1.example.com:9100"
          - "node2.example.com:9100"

Security Notes

Prometheus uses Go's crypto/tls package, which has a different vulnerability history than OpenSSL:

  • POODLE (CVE-2014-3566, 2014): SSL 3.0 has never been supported in Go's TLS implementation.
  • BEAST (CVE-2011-3389, 2011): Mitigated by recommending TLS 1.2 as the minimum; AEAD-only ciphers eliminate the CBC padding oracle.
  • CRIME (CVE-2012-4929, 2012): TLS compression is not supported in Go's crypto/tls.
  • Lucky13 (2013): AEAD-only cipher list eliminates CBC padding timing side-channels entirely.
  • FREAK (CVE-2015-0204, 2015): EXPORT-grade ciphers have never been supported in Go's crypto/tls.
  • LOGJAM (CVE-2015-4000, 2015): DHE key exchange is not offered by default in Go; only ECDHE is used.
  • Sweet32 (CVE-2016-2183, 2016): 3DES was removed from Go's default cipher list in Go 1.14 (February 2020) and is excluded from the recommended configuration.
  • ROBOT (CVE-2017-13099, 2017): Static RSA key exchange is not offered in Go's crypto/tls; only ECDHE is used.
  • Downgrade attacks: TLS_FALLBACK_SCSV is supported in Go's TLS implementation.

The following are not addressable through TLS configuration alone:

  • Heartbleed (CVE-2014-0160, 2014): Not applicable. Go's crypto/tls is an independent TLS implementation and was never affected by Heartbleed.
  • BREACH (CVE-2013-3587, 2013): Exploits HTTP-level response compression. Prometheus serves metrics and UI over HTTP; if HTTP compression is enabled, mitigate at the application layer. TLS configuration cannot prevent it.
  • DROWN (CVE-2016-0800, 2016): Not applicable. Go's crypto/tls does not support SSLv2.

Verification

Check that Prometheus is serving over HTTPS:

curl -v --cacert /etc/prometheus/ssl/ca.pem https://prometheus.example.com:9090/-/healthy

Test the TLS connection:

openssl s_client -connect prometheus.example.com:9090

Verify scrape targets are up in the Prometheus UI:

curl -s --cacert /etc/prometheus/ssl/ca.pem https://prometheus.example.com:9090/api/v1/targets | python3 -m json.tool

Check Prometheus logs for TLS errors:

journalctl -u prometheus | grep -i tls

Related Guides

Grafana

Open-source monitoring and dashboards.

Docker

Container runtime and platform.

Vault

HashiCorp secrets management platform.

View all Infrastructure guides →

Configured TLS? Now Monitor It.

Generator Labs alerts you before certificates expire, get revoked, or fail chain validation — across HTTPS, SMTPS, IMAPS, LDAPS, and more.

Certificate Monitoring →