Authentication Modules

Authentication modules enable secure multi-target monitoring by pre-configuring credentials that can be referenced when probing different PostgreSQL instances.

Multi-target support is currently in BETA and may require changes in future releases. Feedback is welcome.

Overview

Auth modules solve the problem of managing credentials when monitoring multiple PostgreSQL instances. Instead of passing credentials in URLs (which can expose them in logs), you define them once in a configuration file and reference them by name.

Use Cases

SaaS-managed PostgreSQL: Monitor multiple managed database instances where sidecar deployment isn’t possible
Multi-tenant architectures: Single exporter monitoring databases across multiple tenants
Centralized monitoring: One exporter instance scraping multiple PostgreSQL servers

Configuration File

Auth modules are defined in the YAML configuration file specified by --config.file (default: postgres_exporter.yml).

Basic Structure

auth_modules:
  module_name:
    type: userpass
    userpass:
      username: <username>
      password: <password>
    options:
      key: value

Auth Module Schema

auth_modules

object

Map of authentication module definitions, keyed by module name

auth_modules.<module_name>

object

Individual auth module configuration

auth_modules.<module_name>.type

string

required

Authentication type. Currently only userpass is supported.

auth_modules.<module_name>.userpass

object

Username and password credentials (required when type is userpass)

auth_modules.<module_name>.userpass.username

string

required

Database username for authentication

auth_modules.<module_name>.userpass.password

string

required

Database password for authentication

auth_modules.<module_name>.options

object

Additional connection parameters to include in the DSN as key=value query parameters

Configuration Examples

Single Auth Module

postgres_exporter.yml

auth_modules:
  production:
    type: userpass
    userpass:
      username: postgres_exporter
      password: secure_prod_password
    options:
      sslmode: require
      connect_timeout: "10"

Multiple Environments

postgres_exporter.yml

auth_modules:
  prod_db:
    type: userpass
    userpass:
      username: prod_monitor
      password: prod_secret
    options:
      sslmode: verify-full
      sslrootcert: /etc/ssl/certs/prod-ca.crt
  
  staging_db:
    type: userpass
    userpass:
      username: staging_monitor
      password: staging_secret
    options:
      sslmode: require
  
  dev_db:
    type: userpass
    userpass:
      username: dev_monitor
      password: dev_secret
    options:
      sslmode: disable

With Custom Options

postgres_exporter.yml

auth_modules:
  analytics_db:
    type: userpass
    userpass:
      username: analytics_reader
      password: analytics_pass
    options:
      sslmode: require
      connect_timeout: "15"
      application_name: postgres_exporter_analytics
      statement_timeout: "30000"

Using Auth Modules

Auth modules are used with the /probe endpoint for multi-target monitoring.

Multi-Target Endpoint

The exporter provides a /probe endpoint that accepts target and auth_module parameters:

curl "http://localhost:9187/probe?target=postgres1.example.com:5432/mydb&auth_module=prod_db"

target

string

required

PostgreSQL instance to probe. Can be a hostname, hostname:port, or full DSN.

auth_module

string

required

Name of the auth module to use for credentials

How It Works

When you request /probe?target=dbhost:5432&auth_module=prod_db:

Parse Target

The exporter parses the target parameter into a DSN structure

Apply Auth Module

Credentials from the prod_db auth module are applied to the DSN

Merge Options

Connection options from the auth module are added as query parameters

Connect and Scrape

The exporter connects to PostgreSQL and returns metrics

Prometheus Configuration

Integrate multi-target monitoring with Prometheus using relabel configs:

scrape_configs:
  - job_name: 'postgres_multi_target'
    static_configs:
      - targets:
        - db1.example.com:5432
        - db2.example.com:5432
        - db3.example.com:5432
    metrics_path: /probe
    params:
      auth_module: [prod_db]
    relabel_configs:
      # Pass the target as a URL parameter
      - source_labels: [__address__]
        target_label: __param_target
      # Use the target as the instance label
      - source_labels: [__param_target]
        target_label: instance
      # Point to the exporter's actual address
      - target_label: __address__
        replacement: postgres-exporter.monitoring.svc:9187

Multiple Auth Modules

Monitor different groups of databases with different credentials:

scrape_configs:
  # Production databases
  - job_name: 'postgres_production'
    static_configs:
      - targets:
        - prod-db1.example.com:5432
        - prod-db2.example.com:5432
    metrics_path: /probe
    params:
      auth_module: [prod_db]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: postgres-exporter:9187
  
  # Staging databases
  - job_name: 'postgres_staging'
    static_configs:
      - targets:
        - staging-db1.example.com:5432
        - staging-db2.example.com:5432
    metrics_path: /probe
    params:
      auth_module: [staging_db]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: postgres-exporter:9187

Security Best Practices

The configuration file contains sensitive credentials. Protect it appropriately.

File Permissions

# Restrict read access to the config file
chmod 600 postgres_exporter.yml
chown postgres_exporter:postgres_exporter postgres_exporter.yml

Using Secrets Management

Integrate with secrets management systems:

Kubernetes
Docker

apiVersion: v1
kind: Secret
metadata:
  name: postgres-exporter-config
type: Opaque
stringData:
  postgres_exporter.yml: |
    auth_modules:
      prod_db:
        type: userpass
        userpass:
          username: monitor_user
          password: ${DB_PASSWORD}
        options:
          sslmode: require
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: postgres-exporter
        image: quay.io/prometheuscommunity/postgres-exporter
        args:
        - --config.file=/config/postgres_exporter.yml
        volumeMounts:
        - name: config
          mountPath: /config
          readOnly: true
      volumes:
      - name: config
        secret:
          secretName: postgres-exporter-config
          defaultMode: 0400

# Create config file
cat > /secure/location/config.yml <<EOF
auth_modules:
  prod_db:
    type: userpass
    userpass:
      username: monitor_user
      password: secure_password
    options:
      sslmode: require
EOF

chmod 600 /secure/location/config.yml

# Run with mounted config
docker run \
  -v /secure/location/config.yml:/config/postgres_exporter.yml:ro \
  -p 9187:9187 \
  quay.io/prometheuscommunity/postgres-exporter \
  --config.file=/config/postgres_exporter.yml

Avoid Logging Credentials

The exporter redacts passwords from logs. When you see:

level=info msg="Configured auth module" module=prod_db dsn="postgresql://user:******@dbhost:5432/mydb?sslmode=require"

This is expected and secure.

Reloading Configuration

Currently, the exporter requires a restart to reload the configuration file. Send a SIGTERM or SIGINT to gracefully stop the process:

# Find the process
pgrep postgres_exporter

# Send termination signal
kill -TERM <pid>

# Restart with new config
./postgres_exporter --config.file=postgres_exporter.yml

Future versions may support dynamic configuration reloading via signals or HTTP endpoints.

Troubleshooting

Config file not found

level=warn msg="Error loading config" err="error opening config file \"postgres_exporter.yml\": no such file or directory"

Solution: Specify the full path with --config.file=/path/to/config.yml

Invalid YAML syntax

level=error msg="Error loading config" err="error parsing config file: yaml: line 5: did not find expected key"

Solution: Validate YAML syntax. Check indentation (use spaces, not tabs) and ensure all keys are properly formatted.

Auth module not found

When using /probe?auth_module=nonexistent, you’ll receive an error response.Solution: Verify the module name matches exactly what’s defined in the config file (case-sensitive).

Connection fails with auth module

The module credentials may be incorrect or the user lacks necessary permissions.Solution: Test the credentials directly with psql:

psql "postgresql://username:password@target:5432/database?sslmode=require"

Limitations

Only the userpass authentication type is currently supported
Certificate-based authentication is not yet available via auth modules
Configuration changes require a process restart

Next Steps

Multi-Target Pattern

Learn more about the Prometheus multi-target exporter pattern

Environment Variables

Explore other configuration options

Get Started

Configuration

Deployment

Collectors

Advanced

Overview

Use Cases

Configuration File

Basic Structure

Auth Module Schema

Configuration Examples

Single Auth Module

Multiple Environments

With Custom Options

Using Auth Modules

Multi-Target Endpoint

How It Works

Prometheus Configuration

Multiple Auth Modules

Security Best Practices

File Permissions

Using Secrets Management

Avoid Logging Credentials

Reloading Configuration

Troubleshooting

Limitations

Next Steps

Multi-Target Pattern

Environment Variables

Build docs developers (and LLMs) love

Get Started

Configuration

Deployment

Collectors

Advanced

​Overview

​Use Cases

​Configuration File

​Basic Structure

​Auth Module Schema

​Configuration Examples

​Single Auth Module

​Multiple Environments

​With Custom Options

​Using Auth Modules

​Multi-Target Endpoint

​How It Works

​Prometheus Configuration

​Multiple Auth Modules

​Security Best Practices

​File Permissions

​Using Secrets Management

​Avoid Logging Credentials

​Reloading Configuration

​Troubleshooting

​Limitations

​Next Steps

Multi-Target Pattern

Environment Variables

Build docs developers (and LLMs) love

Overview

Use Cases

Configuration File

Basic Structure

Auth Module Schema

Configuration Examples

Single Auth Module

Multiple Environments

With Custom Options

Using Auth Modules

Multi-Target Endpoint

How It Works

Prometheus Configuration

Multiple Auth Modules

Security Best Practices

File Permissions

Using Secrets Management

Avoid Logging Credentials

Reloading Configuration

Troubleshooting

Limitations

Next Steps