Wraith Integrated Monitoring Stack

This project combines the wraith multi-protocol messaging system with a comprehensive monitoring stack, providing a unified Kubernetes deployment for both the application and its observability infrastructure.

Overview

This integrated project merges two components:

1. Wraith Application: Multi-protocol publisher/subscriber system supporting NATS, TCP, UDP, and Redis
2. Monitoring Stack: Prometheus metrics collection and Grafana visualization with custom dashboards

Components

Infrastructure

• NATS: Message broker for pub/sub communication
• Redis: In-memory data store for caching and messaging

Applications

• Wraith Server: Multi-protocol publisher that sends data and exposes Prometheus metrics
• Wraith Agent: Multi-protocol subscriber that receives data from the server

Monitoring

• Prometheus: Metrics collection and storage (automatically scrapes wraith-server:8000)
• Grafana: Visualization and dashboards with custom button panel plugin

Features

• Multi-protocol support (NATS, TCP, UDP, Redis)
• Binary data transmission (PDW, EDW)
• Prometheus metrics for timing and performance
• Built-In Test (BIT) functionality
• HTTP API for control
• Custom Grafana dashboards for visualization
• Unified Kubernetes deployment with CI/CD pipeline

Project Structure

wraith-dashboard/
├── wraith-common/                    # Shared Rust library
│   ├── src/                          # Common utilities and message definitions
│   │   ├── protocols/                # Protocol implementations (NATS, TCP, UDP, Redis)
│   │   ├── pdw.rs                    # Pulse Descriptor Word structures
│   │   ├── edw.rs                    # Emitter Descriptor Word structures
│   │   ├── msg.rs                    # Message definitions
│   │   └── utils.rs                  # Utility functions
│   └── Cargo.toml                    # Common library dependencies
├── wraith-server/                    # Multi-protocol server implementation
│   ├── src/main.rs                   # Server application
│   └── Cargo.toml                    # Server dependencies
├── wraith-agent/                     # Multi-protocol agent implementation
│   ├── src/main.rs                   # Agent application
│   └── Cargo.toml                    # Agent dependencies
├── k8s/                              # Kubernetes manifests
│   ├── base/                         # Base manifests
│   │   ├── infrastructure/           # NATS, Redis, Namespace
│   │   ├── monitoring/               # Prometheus, Grafana, Dashboards
│   │   ├── applications/             # Wraith Server & Agent
│   │   └── kustomization.yaml        # Base kustomization
│   └── overlays/
│       ├── local/                    # Local cluster configuration
│       └── remote/                   # Remote cluster configuration
├── .forgejo/workflows/ci.yml         # CI/CD pipeline
├── deploy.sh                         # Main deployment script
├── Earthfile                         # Build configuration for all images
├── Cargo.toml                        # Rust workspace configuration
├── Cargo.lock                        # Dependency lock file
└── README.md                         # This file

Prerequisites

• Kubernetes cluster (e.g., minikube, kind, or k3s)
• kubectl configured to connect to your cluster
• Earthly for building container images

Deployment Architecture

The deployment system consists of four cohesive components:

1. Earthfile - Build System

• Defines containerized build process for all components
• Multi-platform builds (linux/amd64, linux/arm64)
• Configurable registry and tag via build arguments
• Builds wraith-server, wraith-agent, and custom Grafana images

2. deploy.sh - Deployment Orchestrator

• Main deployment script that coordinates builds and deployments
• Handles both local and remote deployments
• Manages QEMU setup for cross-platform builds
• Provides helpful post-deployment commands

3. Kubernetes Manifests - Infrastructure as Code

• Uses Kustomize for environment-specific configurations
• Supports image registry and tag substitution
• Organized by component type (infrastructure, monitoring, applications)

4. CI/CD Pipeline - Automated Deployment

• Automated testing, building, and deployment
• Uses Earthly for consistent multi-platform container builds
• Deploys using the same deploy.sh script for consistency

Deployment

Quick Start with Deploy Script

The easiest way to deploy is using the provided script:

# For local clusters (minikube, kind, k3s)
./deploy.sh local

# For local with specific tag
./deploy.sh local localhost v2.0.0

# For remote clusters
./deploy.sh remote docker.io/myuser
./deploy.sh remote gcr.io/myproject v1.0.0

Usage: ./deploy.sh [local|remote] [registry] [tag]

Deployment Workflows

Local Development

./deploy.sh local
# This internally:
# 1. Runs: earthly --build-arg TAG=0.1-slim +all
# 2. Runs: kubectl apply -k k8s/overlays/local

Remote/Production Deployment

./deploy.sh remote gcr.io/myproject v1.2.3
# This internally:
# 1. Runs: earthly --push --build-arg REGISTRY=gcr.io/myproject --build-arg TAG=v1.2.3 +all-multiplatform
# 2. Runs: kubectl kustomize k8s/overlays/remote | sed substitutions | kubectl apply -f -

Manual Deployment

For Local Kubernetes Clusters

earthly --build-arg TAG=0.1-slim +all
kubectl apply -k k8s/overlays/local

For Remote Kubernetes Clusters

# Build and push multi-platform images (amd64 + arm64) to your registry
earthly --push --build-arg REGISTRY=your-registry.com --build-arg TAG=v1.0.0 +all-multiplatform

# Deploy with registry substitution
kubectl kustomize k8s/overlays/remote | sed 's|your-registry.com|your-actual-registry.com|g' | sed 's|0.1-slim|v1.0.0|g' | kubectl apply -f -

Multi-Platform Support: Remote deployments automatically build for both linux/amd64 and linux/arm64 architectures, ensuring compatibility with ARM-based clusters.

Configuration Management

Image Registry and Tags

• Default: localhost/wraith-*:0.1-slim (local development)
• CI/CD: $REGISTRY/$REPO_OWNER/wraith-*:$COMMIT_SHA (versioned by commit)
• Production: Configurable via deploy.sh parameters

Environment-Specific Configurations

• Local: Uses k8s/overlays/local - localhost registry, local cluster settings
• Remote: Uses k8s/overlays/remote - configurable registry, production settings

What Gets Deployed

All deployment methods deploy:

• Infrastructure services: NATS, Redis, namespace
• Wraith applications: server and agent
• Monitoring stack: Prometheus, Grafana with custom dashboards

Images Built:

• wraith-server:${TAG} - Multi-protocol server
• wraith-agent:${TAG} - NATS agent
• localhost/grafana:10.0.3-wraith - Custom Grafana with button panel plugin

Application Configuration

Wraith Server

The server supports multiple protocols simultaneously and can be controlled via HTTP API:

• HTTP API: Port 80 for control commands
• Metrics: Port 8000 for Prometheus scraping
• TCP: Port 9001 for TCP communication
• UDP: Port 9002 for UDP communication
• NATS: Connects to nats.wraith.svc.cluster.local:4222
• Redis: Connects to redis.wraith.svc.cluster.local:6379

Wraith Agent

The agent receives data from all protocols and connects to the server for coordination:

• HTTP: Port 80 for status and control
• TCP: Port 55555 for TCP communication
• UDP: Port 55556 for UDP communication
• NATS: Connects to nats.wraith.svc.cluster.local:4222

Monitoring Integration

• Prometheus automatically scrapes metrics from wraith-server:8000
• Grafana provides visualization dashboards
• Custom button panel plugin enables interactive controls

Usage

HTTP API Commands

Send data using all protocols:

curl -X POST -H "Content-Type: application/json" \
  -d '{"SEND": true}' \
  http://wraith-server.wraith.svc/post

Send data using specific protocol:

curl -X POST -H "Content-Type: application/json" \
  -d '{"SEND": true, "protocol": "NATS"}' \
  http://wraith-server.wraith.svc/post

Run Built-In Test (BIT):

curl -X POST -H "Content-Type: application/json" \
  -d '{"BIT": true}' \
  http://wraith-server.wraith.svc/post

Accessing Services

After deployment, services are available within the cluster:

• Wraith Server: http://wraith-server.wraith.svc
• Prometheus: http://prometheus.wraith.svc:9090
• Grafana: http://grafana.wraith.svc:3000

For external access, use port-forwarding:

# Access Grafana locally
kubectl port-forward -n wraith svc/grafana 3000:3000

# Access Prometheus locally
kubectl port-forward -n wraith svc/prometheus 9090:9090

# Check deployment status
kubectl get pods -n wraith

Monitoring and Metrics

The integrated monitoring provides:

• Real-time Metrics: Automatic collection of wraith-server performance data
• Custom Dashboards: Pre-configured Grafana dashboards for wraith metrics
• Interactive Controls: Button panel plugin for triggering actions
• Historical Data: Prometheus storage for trend analysis

CI/CD Pipeline

The automated pipeline includes:

1. Lint: Code quality checks with clippy and rustfmt
2. Unit Tests: Rust unit and integration tests
3. Integration Tests: Cross-component testing
4. Build: Uses Earthly for multi-platform container builds
5. Deploy: Deploys to staging environment using deploy.sh
6. Acceptance Tests: End-to-end validation

The CI/CD system uses the same deployment tools as manual deployments, ensuring consistency across all environments.

Cleanup

To remove all deployed resources:

kubectl delete -k k8s/base

Development

The organized structure supports:

• Independent component development
• Easy testing of individual protocols
• Modular deployment options
• Consistent build and deployment processes
• Future extensibility for additional monitoring components

Troubleshooting

Check pod status:

kubectl get pods -n wraith

View logs:

kubectl logs -n wraith deployment/wraith-server
kubectl logs -n wraith deployment/wraith-agent
kubectl logs -n wraith deployment/prometheus
kubectl logs -n wraith deployment/grafana

Verify services:

kubectl get svc -n wraith

Check deployment status:

kubectl rollout status deployment/wraith-server -n wraith
kubectl rollout status deployment/wraith-agent -n wraith

This architecture ensures consistency across all deployment scenarios while maintaining flexibility for different environments and use cases.