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

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:3.1.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:3.1.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.