Skip to content

TLS Setup

Requirements

TLS Without Mutual Authentication

Server-side TLS authenticates the proxy to the agent:

Component Required Files
Proxy certChainFilePath (server cert), privateKeyFilePath (server key)
Agent trustCertCollectionFilePath (CA cert)

TLS With Mutual Authentication

Both sides authenticate each other:

Component Required Files
Proxy certChainFilePath, privateKeyFilePath, trustCertCollectionFilePath
Agent certChainFilePath, privateKeyFilePath, trustCertCollectionFilePath

TLS provider

Since 4.1.0 the fat JARs and the Docker images use OpenSSL (BoringSSL) for TLS on Linux (x86_64, aarch_64), macOS (x86_64, aarch_64), and Windows (x86_64), and fall back to the JDK's TLS elsewhere. Certificates, keys, and the TLS options are used as before, but anything that differs between the two providers, such as the default cipher suites, now follows BoringSSL.

Configuration

# Proxy with TLS (no mutual authentication):
java -jar prometheus-proxy.jar \
  --cert /path/to/server.crt \
  --key /path/to/server.key

# Agent with TLS (no mutual authentication):
java -jar prometheus-agent.jar \
  --config myconfig.conf \
  --trust /path/to/ca.crt

# Proxy with mutual TLS:
java -jar prometheus-proxy.jar \
  --cert /path/to/server.crt \
  --key /path/to/server.key \
  --trust /path/to/ca.crt

# Agent with mutual TLS:
java -jar prometheus-agent.jar \
  --config myconfig.conf \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --trust /path/to/ca.crt

proxy {
  agent.port = 50440

  tls {
    certChainFilePath = "certs/server.pem"
    privateKeyFilePath = "certs/server.key"
  }
}

agent {
  proxy {
    hostname = "proxy-host.example.com"
    port = 50440
  }

  tls {
    trustCertCollectionFilePath = "certs/ca.pem"
  }
}

proxy {
  agent.port = 50440

  tls {
    certChainFilePath = "certs/server.pem"
    privateKeyFilePath = "certs/server.key"
    trustCertCollectionFilePath = "certs/ca.pem"
  }
}

agent {
  proxy {
    hostname = "proxy-host.example.com"
    port = 50440
  }

  tls {
    certChainFilePath = "certs/client.pem"
    privateKeyFilePath = "certs/client.key"
    trustCertCollectionFilePath = "certs/ca.pem"
  }
}

Using the Included Test Certificates

The repository includes test certificates for development:

# Proxy with TLS (no mutual auth) using included certs
java -jar prometheus-proxy.jar --config examples/tls-no-mutual-auth.conf

# Agent with TLS (no mutual auth) using included certs
java -jar prometheus-agent.jar --config examples/tls-no-mutual-auth.conf

For mutual auth:

java -jar prometheus-proxy.jar --config examples/tls-with-mutual-auth.conf
java -jar prometheus-agent.jar --config examples/tls-with-mutual-auth.conf

Test certificates only

The certificates in testing/certs/ are for development and testing only. Generate your own certificates for production deployments.

TLS with Docker

Mount certificate files into the container:

# Proxy with TLS (no mutual auth):
docker run --rm \
  -p 8080:8080 \
  -p 50440:50440 \
  -p 8082:8082 \
  -p 8092:8092 \
  --mount type=bind,source="$(pwd)"/certs,target=/app/certs \
  --mount type=bind,source="$(pwd)"/tls.conf,target=/app/tls.conf \
  --env PROXY_CONFIG=tls.conf \
  --env ADMIN_ENABLED=true \
  --env METRICS_ENABLED=true \
  pambrose/prometheus-proxy:4.4.0

# Agent with TLS (no mutual auth):
docker run --rm \
  -p 8083:8083 \
  -p 8093:8093 \
  --mount type=bind,source="$(pwd)"/certs,target=/app/certs \
  --mount type=bind,source="$(pwd)"/tls.conf,target=/app/tls.conf \
  --env AGENT_CONFIG=tls.conf \
  --env PROXY_HOSTNAME=proxy-host:50440 \
  pambrose/prometheus-agent:4.4.0

Override Authority

For testing scenarios where the server certificate's CN doesn't match the hostname:

agent.tls.overrideAuthority = "expected.hostname.com"

Or via CLI:

java -jar prometheus-agent.jar --override expected.hostname.com --config agent.conf

Example Config Files

The repository includes complete TLS configuration examples:

File Description
examples/tls-no-mutual-auth.conf Server-side TLS only
examples/tls-with-mutual-auth.conf Mutual TLS authentication

Setting Up TLS

For detailed instructions on creating TLS certificates for gRPC, see the gRPC TLS documentation.