DriftGuard

DriftGuard

Intelligent GitOps Configuration Drift Detection Engine

DriftGuard is an intelligent GitOps configuration drift detection platform that continuously monitors Kubernetes resources for configuration drift by comparing live cluster states against desired states stored in Git repositories. It features enhanced state tracking, automatic resolution detection, and comprehensive drift analysis.

🚀 Key Features

• Enhanced Drift Detection: Continuously monitors Kubernetes resources with intelligent drift classification
• Drift Resolution Detection: Automatically detects when drift is resolved and configuration matches Git again
• State Management: Tracks drift status (active/resolved/none) with timestamps and resolution messages
• Git Integration: Compares live state against Git-stored manifests with hash-based state tracking
• Intelligent Classification: Automatically classifies drift types (Scaling, VersionChange, ResourceChange, etc.)
• Severity Assessment: Assigns severity levels (low, medium, high) to detected drifts
• MongoDB Storage: Persistent storage of drift records with enhanced state tracking
• REST API: Comprehensive HTTP endpoints for querying drift records, status filtering, and statistics
• Metrics & Monitoring: Prometheus metrics and health checks
• Enhanced Logging: Detailed logging with emojis for drift detection and resolution events

---

Learn More About DriftGuard

Want to dive deeper into the configuration drift crisis and understand how DriftGuard solves real-world infrastructure challenges? Check out our comprehensive guide:

[Learn More About DriftGuard](ABOUT.md) - Discover the configuration drift crisis, understand GitOps vs InfraOps, explore real-world examples, and learn about DriftGuard's business value and architecture.

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Kubernetes    │    │   Git Repo      │    │   DriftGuard    │
│   API Server    │    │   (Desired      │    │   Backend       │
│   (Live State)  │◄──►│   State)        │◄──►│   (Controller)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   MongoDB       │    │   REST API      │
                       │   (Enhanced     │    │   (HTTP         │
                       │   Drift Records)│    │   Endpoints)    │
                       └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   Prometheus    │    │   Health        │
                       │   Metrics       │    │   Checks        │
                       └─────────────────┘    └─────────────────┘

📋 Prerequisites

• Go 1.21+
• MongoDB 4.4+
• Kubernetes cluster (local or remote)
• Git repository with Kubernetes manifests
• kubectl configured to access your cluster

🛠️ Installation & Setup

1. Clone the Repository

git clone 
cd DriftGuard

2. Start MongoDB

# Create data directory
mkdir -p ~/data/db

# Start MongoDB (macOS/Linux)
sudo mongod --dbpath=~/data/db

# Or using Docker
docker run -d -p 27017:27017 --name mongodb mongo:latest

3. Configure DriftGuard

Update the configuration file (backend/configs/config.yaml):

server:
  port: 8080
  read_timeout: 30s
  write_timeout: 30s
  idle_timeout: 60s

database:
  host: localhost
  port: 27017
  dbname: driftguard
  timeout: 10s

kubernetes:
  config_path: ""  # Leave empty for default kubeconfig
  context: ""
  namespaces: ["driftguard"]
  resources: ["deployments", "services", "configmaps", "secrets"]
  skip_system_namespaces: true

git:
  repository_url: "Add your Repo"
  default_branch: main
  clone_timeout: 5m
  pull_timeout: 2m

drift_detection:
  interval: 30s
  enable_periodic: true

4. Create Test Git Repository

# Create a dummy Git repository for testing
mkdir -p dummy-k8s-repo
cd dummy-k8s-repo
git init

# Create test Kubernetes manifests
cat > test-deployment.yaml 50%)
- **Medium**: Minor scaling, environment variables, ports, volumes
- **Low**: Labels, annotations, other metadata

## 📈 Enhanced Statistics

The system provides comprehensive drift statistics:

```json
{
  "statistics": {
    "total_records": 25,
    "active_drift": 3,
    "resolved_drift": 15,
    "no_drift": 7,
    "recent_active_drift": 1,
    "recent_resolutions": 2,
    "active_percentage": 12.0,
    "resolved_percentage": 60.0
  }
}

🔧 Configuration Options

Kubernetes Configuration

• config_path: Path to kubeconfig file
• context: Kubernetes context to use
• namespaces: List of namespaces to monitor
• resources: List of resource types to monitor
• skip_system_namespaces: Skip system namespaces

Git Configuration

• repository_url: Git repository URL
• default_branch: Branch to monitor
• clone_timeout: Timeout for repository cloning
• pull_timeout: Timeout for pulling updates

Drift Detection Configuration

• interval: Periodic analysis interval
• enable_periodic: Enable periodic drift detection

🐛 Troubleshooting

Common Issues

1. MongoDB Connection Failed

```bash # Check if MongoDB is running ps aux | grep mongod

# Start MongoDB if not running sudo mongod --dbpath=~/data/db ```

1. Kubernetes Connection Failed

```bash # Check kubectl configuration kubectl config current-context

# Test cluster connection kubectl get nodes ```

1. Git Repository Access Failed

``bash # Check Git repository URL in config # Ensure repository is accessible git ls-remote ``

1. Port Already in Use

```bash # Check if port 8080 is in use lsof -i :8080

# Kill process or change port in config ```

Log Analysis

DriftGuard uses structured logging with emojis:

• 🚀 System startup
• ⚠️ Drift detected
• ✅ Drift resolved
• 🔄 Drift continued
• 📊 Analysis completed

🚀 Production Deployment

Docker Deployment

# Build the container
docker build -t driftguard:latest backend/

# Run with environment variables
docker run -d \
  -p 8080:8080 \
  -e MONGODB_HOST=your-mongodb-host \
  -e KUBECONFIG=/path/to/kubeconfig \
  driftguard:latest

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: driftguard
  namespace: driftguard
spec:
  replicas: 1
  selector:
    matchLabels:
      app: driftguard
  template:
    metadata:
      labels:
        app: driftguard
    spec:
      containers:
      - name: driftguard
        image: driftguard:latest
        ports:
        - containerPort: 8080
        env:
        - name: MONGODB_HOST
          value: "mongodb-service"
        volumeMounts:
        - name: kubeconfig
          mountPath: /root/.kube
          readOnly: true
      volumes:
      - name: kubeconfig
        secret:
          secretName: driftguard-kubeconfig

Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

License

This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.

Support

For questions, feature requests, or contributions, please open an issue in this repository.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DriftGuard
• Source: DriftGuard/DriftGuard
• License: MIT

Install and usage instructions live in the source repository linked above.