Configuration Guide

Brokkr uses a layered configuration system that allows settings to be defined through default values, configuration files, and environment variables. This guide provides a comprehensive reference for all configuration options and explains how to configure both the broker and agent components.

Configuration Sources

Configuration values are loaded from multiple sources, with later sources taking precedence over earlier ones:

1. Default values embedded in the application from default.toml
2. Configuration file (optional) specified at startup
3. Environment variables prefixed with BROKKR__

This layering enables a flexible deployment model where defaults work out of the box, configuration files provide environment-specific settings, and environment variables allow runtime overrides without modifying files.

Environment Variable Naming

All environment variables use the BROKKR__ prefix with double underscores (__) as separators for nested configuration. The naming convention converts configuration paths to uppercase with underscores.

For example, the configuration path broker.webhook_delivery_interval_seconds becomes the environment variable BROKKR__BROKER__WEBHOOK_DELIVERY_INTERVAL_SECONDS.

Database Configuration

The database configuration controls the connection to PostgreSQL.

The schema setting enables multi-tenant deployments where each tenant’s data is isolated in a separate PostgreSQL schema. When configured, all queries automatically set search_path to the specified schema.

# Standard single-tenant configuration
BROKKR__DATABASE__URL=postgres://user:password@db.example.com:5432/brokkr

# Multi-tenant configuration with schema isolation
BROKKR__DATABASE__URL=postgres://user:password@db.example.com:5432/brokkr
BROKKR__DATABASE__SCHEMA=tenant_acme

Logging Configuration

Logging settings control the verbosity and format of application logs.

The log level is hot-reloadable—changes take effect without restarting the application. Use json format in production environments for easier log aggregation and parsing.

# Production logging configuration
BROKKR__LOG__LEVEL=info
BROKKR__LOG__FORMAT=json

Broker Configuration

The broker configuration controls the central management service’s behavior.

Core Settings

Webhook Settings

Webhooks deliver event notifications to external systems. These settings control the delivery worker’s behavior.

The encryption key protects webhook URLs and authentication headers at rest. If not configured, the broker generates a random key at startup and logs a warning. This means encrypted data will become unreadable if the broker restarts. For production deployments, always configure an explicit encryption key.

# Production webhook configuration
BROKKR__BROKER__WEBHOOK_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
BROKKR__BROKER__WEBHOOK_DELIVERY_INTERVAL_SECONDS=5
BROKKR__BROKER__WEBHOOK_DELIVERY_BATCH_SIZE=100
BROKKR__BROKER__WEBHOOK_CLEANUP_RETENTION_DAYS=30

Diagnostic Settings

Diagnostics are temporary operations that agents execute for debugging purposes.

Audit Log Settings

Audit logs record all significant actions for security and compliance.

# Extended audit retention for compliance
BROKKR__BROKER__AUDIT_LOG_RETENTION_DAYS=365

Auth Cache Settings

The broker caches PAK authentication results in memory to reduce database queries per request. Each authenticated request would otherwise require 2-3 database lookups (admin, agent, generator tables). The cache is automatically invalidated when PAKs are rotated or entities are deleted.

# Increase cache TTL for high-throughput deployments
BROKKR__BROKER__AUTH_CACHE_TTL_SECONDS=120

# Disable auth caching entirely
BROKKR__BROKER__AUTH_CACHE_TTL_SECONDS=0

CORS Configuration

Cross-Origin Resource Sharing (CORS) settings control which origins can access the broker API.

CORS settings are hot-reloadable. In production, restrict allowed_origins to specific domains rather than using *.

Agent Configuration

The agent configuration controls the Kubernetes cluster agent’s behavior.

Required Settings

Polling Settings

Health and Monitoring

Kubernetes Settings

# Complete agent configuration
BROKKR__AGENT__BROKER_URL=https://broker.example.com:3000
BROKKR__AGENT__PAK=brokkr_BRabc123_xyzSecretTokenHere
BROKKR__AGENT__AGENT_NAME=production-east
BROKKR__AGENT__CLUSTER_NAME=prod-us-east-1
BROKKR__AGENT__POLLING_INTERVAL=10
BROKKR__AGENT__HEALTH_PORT=8080
BROKKR__AGENT__DEPLOYMENT_HEALTH_ENABLED=true
BROKKR__AGENT__DEPLOYMENT_HEALTH_INTERVAL=60

Telemetry Configuration

Telemetry settings control OpenTelemetry trace export for distributed tracing.

Base Settings

Component Overrides

The broker and agent can have independent telemetry configurations that override the base settings.

# Enable telemetry with different sampling for broker and agent
BROKKR__TELEMETRY__ENABLED=true
BROKKR__TELEMETRY__OTLP_ENDPOINT=http://otel-collector:4317
BROKKR__TELEMETRY__SERVICE_NAME=brokkr
BROKKR__TELEMETRY__SAMPLING_RATE=0.1
BROKKR__TELEMETRY__BROKER__SERVICE_NAME=brokkr-broker
BROKKR__TELEMETRY__BROKER__SAMPLING_RATE=0.5
BROKKR__TELEMETRY__AGENT__SERVICE_NAME=brokkr-agent
BROKKR__TELEMETRY__AGENT__SAMPLING_RATE=0.1

PAK Configuration

Prefixed API Key (PAK) settings control token generation characteristics.

These settings are typically left at their defaults. Changing them affects only newly generated PAKs—existing PAKs remain valid.

Configuration File Format

Configuration files use TOML format. All settings can be specified in a configuration file as an alternative to environment variables.

[database]
url = "postgres://user:password@localhost:5432/brokkr"
schema = "tenant_acme"

[log]
level = "info"
format = "json"

[broker]
webhook_encryption_key = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
webhook_delivery_interval_seconds = 5
webhook_delivery_batch_size = 50
webhook_cleanup_retention_days = 7
diagnostic_cleanup_interval_seconds = 900
diagnostic_max_age_hours = 1
audit_log_retention_days = 90
auth_cache_ttl_seconds = 60

[cors]
allowed_origins = ["https://admin.example.com"]
allowed_methods = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
allowed_headers = ["Content-Type", "Authorization"]
max_age_seconds = 3600

[agent]
broker_url = "https://broker.example.com:3000"
pak = "brokkr_BRabc123_xyzSecretTokenHere"
agent_name = "production-east"
cluster_name = "prod-us-east-1"
polling_interval = 10
max_retries = 60
health_port = 8080
deployment_health_enabled = true
deployment_health_interval = 60

[telemetry]
enabled = true
otlp_endpoint = "http://otel-collector:4317"
service_name = "brokkr"
sampling_rate = 0.1

[telemetry.broker]
service_name = "brokkr-broker"
sampling_rate = 0.5

[telemetry.agent]
service_name = "brokkr-agent"
sampling_rate = 0.1

[pak]
prefix = "brokkr"
short_token_prefix = "BR"
short_token_length = 8
long_token_length = 24

Hot-Reload Configuration

The broker supports dynamic configuration reloading for certain settings without requiring a restart.

Hot-Reloadable Settings

These settings can be changed at runtime:

• log.level - Log verbosity
• cors.allowed_origins - CORS origins
• cors.max_age_seconds - CORS preflight cache
• broker.diagnostic_cleanup_interval_seconds - Diagnostic cleanup interval
• broker.diagnostic_max_age_hours - Diagnostic retention
• broker.webhook_delivery_interval_seconds - Webhook delivery interval
• broker.webhook_delivery_batch_size - Webhook batch size
• broker.webhook_cleanup_retention_days - Webhook retention

Static Settings (Require Restart)

These settings require an application restart to change:

• database.url - Database connection
• database.schema - Database schema
• broker.webhook_encryption_key - Encryption key
• broker.pak_hash - Admin PAK hash
• broker.auth_cache_ttl_seconds - Auth cache TTL
• telemetry.* - All telemetry settings
• pak.* - All PAK generation settings

Triggering a Reload

Reload configuration via the admin API:

curl -X POST https://broker.example.com/api/v1/admin/config/reload \
  -H "Authorization: Bearer $ADMIN_PAK"

When a configuration file is specified via BROKKR_CONFIG_FILE, the broker automatically watches it for filesystem changes with a 5-second debounce period.

Troubleshooting

Common Configuration Issues

Database connection failures typically indicate incorrect credentials or network issues. Verify the database URL is correct, the database server is running, and network connectivity exists between the broker and database.

# Test database connectivity
psql "postgres://user:password@localhost:5432/brokkr" -c "SELECT 1"

Agent authentication failures usually result from an invalid PAK. Verify the PAK was copied correctly without extra whitespace and that the agent record hasn’t been deleted from the broker.

Kubernetes access issues in agents may indicate missing or invalid credentials. When running outside a cluster, ensure BROKKR__AGENT__KUBECONFIG_PATH points to a valid kubeconfig file. When running inside a cluster, verify the service account has appropriate RBAC permissions.

Debugging Configuration

Enable trace-level logging to see configuration loading details:

BROKKR__LOG__LEVEL=trace brokkr-broker

The broker logs configuration values at startup (with sensitive values redacted), making it easy to verify which settings were applied.

Getting Help

If you encounter configuration issues:

1. Check the logs for detailed error messages
2. Verify all required configuration values are set
3. Test connectivity to external dependencies (database, Kubernetes API)
4. Consult the GitHub Issues for known issues