Configuration Management Guide

Complete guide to configuring KafkaGuard using configuration files, environment variables, and command-line flags.

Table of Contents

• Configuration Overview
• Configuration Precedence
• Configuration File Format
• All Configuration Options
• Environment Variables
• Configuration File Locations
• Sensitive Data Handling
• Configuration Examples
• Next Steps

---

Configuration Overview

KafkaGuard supports three configuration methods that can be used independently or combined:

1. Configuration File (.kafkaguard.yaml) - YAML file with all settings
2. Environment Variables (KAFKAGUARD_* prefix) - Shell environment variables
3. Command-Line Flags - Direct CLI arguments

When to Use Each Method

Method	Best For	Advantages	Disadvantages
Configuration File	Persistent settings, team sharing	Easy to version control, readable	May contain sensitive data if not careful
Environment Variables	Credentials, CI/CD, containerized environments	Secure (no file storage), easy to inject	Less readable, harder to document
Command-Line Flags	One-off scans, quick overrides	Explicit, temporary	Verbose, credentials visible in process list

Best Practice: Use configuration files for general settings, environment variables for credentials, and CLI flags for overrides.

---

Configuration Precedence

When the same option is specified in multiple places, KafkaGuard uses this precedence order:

1. Command-line flags (highest precedence)
   ↓
2. Environment variables
   ↓
3. Configuration file
   ↓
4. Default values (lowest precedence)

Precedence Example

Given these configurations:

# .kafkaguard.yaml
bootstrap: "kafka-config:9092"
policy: "policies/baseline-dev.yaml"
timeout: 300

# Environment variables
export KAFKAGUARD_BOOTSTRAP="kafka-env:9092"
export KAFKAGUARD_TIMEOUT=600

# Command line
kafkaguard scan --bootstrap kafka-cli:9092

Result:

• bootstrap: kafka-cli:9092 (from CLI flag - highest precedence)
• policy: policies/baseline-dev.yaml (from config file - no override)
• timeout: 600 (from environment variable - overrides config file)

---

Configuration File Format

KafkaGuard uses YAML format for configuration files (.kafkaguard.yaml).

Basic Configuration File Structure

# .kafkaguard.yaml - KafkaGuard Configuration File

# Kafka Connection Settings
bootstrap: "kafka1:9092,kafka2:9092,kafka3:9092"
timeout: 300

# Policy Settings
policy: "policies/enterprise-default.yaml"

# Report Settings
out: "./reports"
format: ["json", "html", "pdf"]
fail-on: "high"

# Logging
log-level: "info"

# Security Settings
security:
  protocol: "SASL_SSL"
  sasl:
    mechanism: "SCRAM-SHA-512"
    username: "admin"
    # Password should be set via environment variable for security
    # password: "${KAFKA_PASSWORD}"
  tls:
    ca-cert: "/etc/kafkaguard/certs/ca.pem"
    client-cert: "/etc/kafkaguard/certs/client.pem"
    client-key: "/etc/kafkaguard/certs/client-key.pem"
    skip-verify: false

# Performance Settings (optional)
scan:
  parallel: true
  max-collectors: 6

Environment Variable References in Config Files

You can reference environment variables in configuration files using ${VAR_NAME} syntax:

bootstrap: "${KAFKA_BROKER}"
security:
  sasl:
    username: "${KAFKA_USERNAME}"
    password: "${KAFKA_PASSWORD}"

This allows you to keep sensitive data out of configuration files while still using them.

---

All Configuration Options

Complete reference of all available configuration options:

Connection Options

Option	Type	Default	Description	CLI Flag	Env Var
bootstrap	string	(required)	Kafka bootstrap servers (comma-separated)	--bootstrap, -b	KAFKAGUARD_BOOTSTRAP
timeout	int	300	Scan timeout in seconds	--timeout	KAFKAGUARD_TIMEOUT

Policy Options

Option	Type	Default	Description	CLI Flag	Env Var
policy	string	policies/baseline-dev.yaml	Path to policy YAML file	--policy, -p	KAFKAGUARD_POLICY

Report Options

Option	Type	Default	Description	CLI Flag	Env Var
out	string	./reports	Output directory for reports	--out, -o	KAFKAGUARD_OUT
format	string[]	["json"]	Report formats (json, html, pdf, csv)	--format, -f	KAFKAGUARD_FORMAT
fail-on	string	high	Fail threshold severity (high, medium, low, none)	--fail-on	KAFKAGUARD_FAIL_ON

Security Options

Protocol Settings

Option	Type	Default	Description	CLI Flag	Env Var
security.protocol	string	auto-detect	Security protocol (PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL)	--security-protocol	KAFKAGUARD_SECURITY_PROTOCOL

SASL Settings

Option	Type	Default	Description	CLI Flag	Env Var
security.sasl.mechanism	string	-	SASL mechanism (PLAIN, SCRAM-SHA-256, SCRAM-SHA-512)	--sasl-mechanism	KAFKAGUARD_SASL_MECHANISM
security.sasl.username	string	-	SASL username	--sasl-username	KAFKAGUARD_SASL_USERNAME
security.sasl.password	string	-	SASL password (use env var recommended)	--sasl-password	KAFKAGUARD_SASL_PASSWORD

TLS Settings

Option	Type	Default	Description	CLI Flag	Env Var
security.tls.ca-cert	string	-	Path to CA certificate file	--tls-ca-cert	KAFKAGUARD_TLS_CA_CERT
security.tls.client-cert	string	-	Path to client certificate (mTLS)	--tls-client-cert	KAFKAGUARD_TLS_CLIENT_CERT
security.tls.client-key	string	-	Path to client private key (mTLS)	--tls-client-key	KAFKAGUARD_TLS_CLIENT_KEY
security.tls.skip-verify	bool	false	Skip TLS certificate verification (testing only)	--tls-insecure-skip-verify	KAFKAGUARD_TLS_INSECURE_SKIP_VERIFY

---

Environment Variables

All KafkaGuard configuration options can be set via environment variables using the KAFKAGUARD_ prefix.

Environment Variable Naming Convention

1. Prefix all variables with KAFKAGUARD_
2. Convert option names to UPPERCASE
3. Replace hyphens (-) with underscores (_)
4. For nested options, use underscores to separate levels

Complete Environment Variable Reference

Connection Variables

export KAFKAGUARD_BOOTSTRAP="kafka1:9092,kafka2:9092"
export KAFKAGUARD_TIMEOUT="600"

Security Variables

# Protocol
export KAFKAGUARD_SECURITY_PROTOCOL="SASL_SSL"

# SASL
export KAFKAGUARD_SASL_MECHANISM="SCRAM-SHA-512"
export KAFKAGUARD_SASL_USERNAME="admin"
export KAFKAGUARD_SASL_PASSWORD="secret"

# TLS
export KAFKAGUARD_TLS_CA_CERT="/etc/kafkaguard/certs/ca.pem"
export KAFKAGUARD_TLS_CLIENT_CERT="/etc/kafkaguard/certs/client.pem"
export KAFKAGUARD_TLS_CLIENT_KEY="/etc/kafkaguard/certs/client-key.pem"
export KAFKAGUARD_TLS_INSECURE_SKIP_VERIFY="false"

---

Sensitive Data Handling

Protect credentials and sensitive configuration data:

Best Practices

✅ DO: Use Environment Variables for Credentials

# .kafkaguard.yaml (safe - no credentials)
security:
  sasl:
    mechanism: "SCRAM-SHA-512"
    username: "${KAFKA_USERNAME}"  # Reference env var
    password: "${KAFKA_PASSWORD}"  # Reference env var

# Set credentials via environment
export KAFKA_USERNAME="admin"
export KAFKA_PASSWORD="secret"
kafkaguard scan

❌ DON'T: Store Credentials in Config Files

# .kafkaguard.yaml (UNSAFE - DO NOT DO THIS)
security:
  sasl:
    username: "admin"
    password: "secret"  # ❌ Credentials in plain text

---

Configuration Examples

Example 1: Development Environment

File: .kafkaguard.yaml

# Development cluster configuration
bootstrap: "localhost:9092"
policy: "policies/baseline-dev.yaml"
out: "./reports"
format: ["html", "json"]
log-level: "debug"
timeout: 300

# No security (PLAINTEXT)
security:
  protocol: "PLAINTEXT"

Usage:

kafkaguard scan  # Uses config file

Example 2: Production Environment

File: /etc/kafkaguard/config.yaml

# Production cluster configuration
bootstrap: "kafka1.prod.example.com:9095,kafka2.prod.example.com:9095,kafka3.prod.example.com:9095"
policy: "policies/enterprise-default.yaml"
out: "/var/reports/kafkaguard"
format: ["json", "html", "pdf"]
fail-on: "high"
log-level: "info"
timeout: 600

# Security settings (credentials via environment variables)
security:
  protocol: "SASL_SSL"
  sasl:
    mechanism: "SCRAM-SHA-512"
    username: "${KAFKA_USERNAME}"
    password: "${KAFKA_PASSWORD}"
  tls:
    ca-cert: "/etc/kafkaguard/certs/ca.pem"
    skip-verify: false

# Performance tuning for large cluster
scan:
  parallel: true
  max-collectors: 10

Usage:

# Set credentials via environment
export KAFKA_USERNAME="kafkaguard-prod"
export KAFKA_PASSWORD="$(vault kv get -field=password secret/kafka/prod)"

# Run scan
kafkaguard scan --config /etc/kafkaguard/config.yaml

---

Next Steps

• Scanning Guide - Learn how to scan Kafka clusters with your configuration
• Policy Tiers - Understand policy tiers and choose the right one
• Installation Guide - Return to installation if needed
• Advanced Usage - Learn about custom policies and automation

---

Need Help?

• Scanning Guide - Learn about scanning commands
• Policy Tiers - Understand policy configuration
• GitHub Issues - Report bugs or request features

Ready to Get Started?

Book a demo to see KafkaGuard in action and learn how it can help secure your Kafka clusters.

📅 Book a Demo