Appearance

Installation Guide ​

This guide provides comprehensive installation instructions for KafkaGuard on all supported platforms and deployment scenarios.

Table of Contents ​

Prerequisites ​

Before installing KafkaGuard, ensure you have:

  • Operating System: Linux (Ubuntu 20.04+, RHEL 7+, Debian 10+) or macOS 12+
  • Architecture: x86_64 (amd64) or ARM64 (arm64)
  • Network Access: Ability to download from GitHub Releases (for binary installation)
  • Disk Space: ~100MB for binary and temporary reports

For Docker Installation ​

  • Docker: Version 20.10+ with multi-architecture support
  • Network Access: Ability to pull from Docker Hub (docker.io)
  • Disk Space: ~60MB for Docker image

For Running Scans ​

  • Kafka Access: Network connectivity to Kafka brokers (default port 9092)
  • Credentials: SASL/SSL credentials if your cluster requires authentication
  • Permissions: Read-only access to Kafka cluster metadata (no write permissions needed)

Binary Installation ​

Binary installation is the fastest and easiest method. Pre-built binaries are available for Linux and macOS on both x86_64 and ARM64 architectures.

Linux (Ubuntu/Debian) ​

Method 1: Download and Install to /usr/local/bin (Recommended)

bash
# Download latest release (amd64)
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz
tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Or for ARM64
# curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_arm64.tar.gz
# tar -xzf kafkaguard_Linux_arm64.tar.gz

# Move to system path
sudo mv kafkaguard /usr/local/bin/
sudo chmod +x /usr/local/bin/kafkaguard

# Verify installation
kafkaguard version

Method 2: Download to Local Directory

bash
# Create local bin directory (if it doesn't exist)
mkdir -p ~/bin

# Download latest release
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz
tar -xzf kafkaguard_Linux_x86_64.tar.gz

# Move to local bin
mv kafkaguard ~/bin/
chmod +x ~/bin/kafkaguard

# Add to PATH (add this to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/bin:$PATH"

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

# Verify installation
kafkaguard version

macOS (Intel) ​

bash
# Download latest release (Intel x86_64)
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Darwin_x86_64.tar.gz
tar -xzf kafkaguard_Darwin_x86_64.tar.gz

# Move to system path
sudo mv kafkaguard /usr/local/bin/
sudo chmod +x /usr/local/bin/kafkaguard

# On first run, you may need to allow the binary in System Preferences → Security & Privacy
# Or remove the quarantine attribute:
xattr -d com.apple.quarantine /usr/local/bin/kafkaguard

# Verify installation
kafkaguard version

macOS (Apple Silicon) ​

bash
# Download latest release (ARM64)
curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Darwin_arm64.tar.gz
tar -xzf kafkaguard_Darwin_arm64.tar.gz

# Move to system path
sudo mv kafkaguard /usr/local/bin/
sudo chmod +x /usr/local/bin/kafkaguard

# Remove quarantine attribute (prevents "unidentified developer" warning)
xattr -d com.apple.quarantine /usr/local/bin/kafkaguard

# Verify installation
kafkaguard version

Docker Installation ​

Docker provides the easiest cross-platform installation with no dependencies.

Pull from Docker Hub ​

bash
# Pull latest image (multi-architecture)
docker pull aiopsone/kafkaguard:latest

# Verify installation
docker run --rm aiopsone/kafkaguard:latest version

Expected Output:

KafkaGuard v1.0.0
Commit: a1b2c3d
Built: 2025-11-15T12:00:00Z
Go: go1.22.0 linux/amd64

Run Basic Scan ​

bash
# Create directories for policies and reports
mkdir -p policies reports

# Copy policy files to policies directory
cp /path/to/policies/*.yaml policies/

# Run scan against Kafka cluster
docker run --rm \
  -v $(pwd)/policies:/policies:ro \
  -v $(pwd)/reports:/reports \
  aiopsone/kafkaguard:latest scan \
    --bootstrap kafka.example.com:9092 \
    --policy /policies/baseline-dev.yaml \
    --format html,json \
    --out /reports

Installation Verification ​

After installing KafkaGuard, verify the installation is working correctly.

Basic Verification ​

bash
# 1. Check version
kafkaguard version

# Expected output:
# KafkaGuard v1.0.0
# Commit: a1b2c3d
# Built: 2025-11-15T12:00:00Z
# Go: go1.22.0 linux/amd64

# 2. Check help
kafkaguard --help

# Expected output: List of available commands

# 3. List available controls
kafkaguard list-controls --policy policies/baseline-dev.yaml

# Expected output: List of 20 controls from baseline-dev policy

# 4. Validate a policy file
kafkaguard validate-policy --policy policies/baseline-dev.yaml

# Expected output: "✅ Policy validation successful"

Run Your First Scan in 5 Minutes ​

Ready to scan your Kafka cluster? Follow these quick steps:

Step 1: Verify Installation (30 seconds) ​

bash
kafkaguard version

Step 2: Run Your First Scan (1-2 minutes) ​

bash
# Scan using baseline-dev policy (development clusters)
kafkaguard scan \
  --bootstrap localhost:9092 \
  --policy policies/baseline-dev.yaml \
  --format html,json \
  --out ./reports

What This Does:

  • --bootstrap localhost:9092 - Connects to your Kafka broker
  • --policy policies/baseline-dev.yaml - Uses development policy (20 reliability/operational controls)
  • --format html,json - Generates both HTML and JSON reports
  • --out ./reports - Saves reports to ./reports directory

Expected Output:

🚀 KafkaGuard v1.0.0 - Starting scan...
✅ Connected to Kafka cluster (3 brokers detected)
🔍 Collecting broker configurations...
🔍 Collecting topic metadata...
📊 Evaluating 20 controls from baseline-dev policy...

Results:
  ✅ Passed: 16 controls
  ❌ Failed: 3 controls
  ⚠️  N/A: 1 control

Overall Score: 84%

📁 Reports generated:
  - ./reports/scan-20251114120530-abc123.html
  - ./reports/scan-20251114120530-abc123.json

✨ Scan completed in 9.8 seconds

Step 3: View Your Report (30 seconds) ​

Open HTML Report:

bash
# macOS
open ./reports/scan-*.html

# Linux
xdg-open ./reports/scan-*.html

Or view JSON report:

bash
cat ./reports/scan-*.json | jq '.summary'

Next Steps ​

Next Steps ​

After installing KafkaGuard:

  1. Run Your First Scan - Follow the Quick Start Guide to run your first scan
  2. Configure KafkaGuard - Review the Configuration Guide to set up authentication and settings
  3. Learn About Policies - Check out the Policy Tiers Guide to understand available policies
  4. Explore Advanced Usage - See the Advanced Usage Guide for custom policies and automation

Need Help?

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