Last updated: 2026-02-13

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

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"

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