orb8

eBPF-powered observability toolkit for Kubernetes with first-class GPU telemetry

Crate Documentation

orb8 (orbit) is a high-performance observability toolkit built with Rust and eBPF, designed specifically for Kubernetes clusters running AI/ML workloads. It provides deep, low-level visibility into container networking, system calls, resource utilization, and GPU performance with minimal overhead.

The name "orb8" represents orbiting around your cluster infrastructure, continuously observing and monitoring from all angles.

Why orb8?

Existing Kubernetes observability tools either focus on high-level metrics or security-specific use cases. orb8 fills the gap by providing:

• AI Cluster Optimized: Built for large-scale GPU/TPU/Trainium workloads (GPU telemetry planned for v0.4.0)
• eBPF Performance: Sub-1% CPU overhead with zero-copy packet inspection
• Kubernetes Native: Auto-discovery of pods, namespaces, and nodes via Kubernetes API
• Minimal Overhead: Designed for production environments running massive compute clusters

Features

Current (v0.0.2)

• Network Flow Tracking: TCP/UDP/ICMP flow monitoring with 5-tuple extraction
• gRPC API: Agent exposes QueryFlows, StreamEvents, GetStatus on port 9090
• K8s Pod Enrichment: Maps network events to pods via Kubernetes API
• Flow Aggregation: 5-tuple flow aggregation with 30-second expiration
• Ring Buffer: Efficient kernel-to-userspace event communication

Planned

• System Call Monitoring: Security anomaly detection via syscall pattern analysis (v0.3.0 - Phase 6)
• GPU Telemetry (v0.4.0 - Phase 7):
  • GPU utilization tracking per pod (via DCGM)
  • GPU memory usage monitoring
  • Experimental: CUDA kernel execution tracing (feasibility TBD)
  • Multi-GPU workload balancing insights

Kubernetes Integration

• Auto-discovery of cluster resources
• CRD-based configuration for selective tracing
• Prometheus metrics exporter
• Real-time CLI dashboard
• Namespace and pod-level filtering

Installation

Prerequisites

For Building:

• Rust 1.75+ (stable)
• Rust nightly toolchain with rust-src component
• bpf-linker (install via cargo install bpf-linker)

For Running eBPF Programs:

• Linux kernel 5.8+ with BTF support
• Kubernetes cluster 1.25+ (for production deployment)

Platform-Specific:

• macOS: Lima + QEMU (for VM-based eBPF testing), 20GB free disk space
• Linux: Native support, no VM needed
• Windows: Use WSL2, follow Linux instructions

Future Features:

• CUDA 11.0+ (for GPU telemetry, v0.8.0+)

From crates.io (Recommended)

# Install the CLI
cargo install orb8-cli

# Install the agent (requires Linux with eBPF support)
cargo install orb8-agent

From Source

git clone https://github.com/Ignoramuss/orb8.git
cd orb8
cargo build --release

Deploy to Kubernetes

kubectl apply -f deploy/orb8-daemonset.yaml

Quick Start

Note: orb8 v0.0.2 includes working network flow capture, CLI, and gRPC API.

Using the CLI (v0.0.2)

# Start the agent (requires Linux with eBPF support, or use Lima VM on macOS)
orb8-agent

# In another terminal, use the CLI to interact with the agent:

# Check agent status
orb8 status
# Output:
# Agent Status
# ----------------------------------------
# Node:             your-hostname
# Version:          0.0.2
# Health:           OK
# Events Processed: 150
# Active Flows:     3

# Generate some network traffic
ping -c 5 127.0.0.1

# Query aggregated flows
orb8 flows
# Output:
# NAMESPACE/POD        PROTOCOL    SOURCE            DESTINATION      DIR     BYTES  PACKETS
# unknown/cgroup-0     ICMP   127.0.0.1:0       127.0.0.1:0    ingress    588B        6

# Stream live network events
orb8 trace network --duration 30s
# Output:
# Streaming network events from localhost:9090...
# NAMESPACE/POD        PROTOCOL    SOURCE            DESTINATION      DIR     BYTES     TIME
# unknown/cgroup-0     ICMP   127.0.0.1:0       127.0.0.1:0    ingress     98B  14:30:45

Testing with gRPC (Alternative)

# Start the agent in Lima VM
make run-agent

# Query agent status via gRPC
grpcurl -plaintext -proto orb8-proto/proto/orb8.proto \
  localhost:9090 orb8.v1.OrbitAgentService/GetStatus

# Query captured flows via gRPC
grpcurl -plaintext -proto orb8-proto/proto/orb8.proto \
  localhost:9090 orb8.v1.OrbitAgentService/QueryFlows

Network Monitoring (Enhanced in v0.1.0)

# Monitor network flows for all pods in a namespace (coming)
orb8 trace network --namespace default

# Track DNS queries across the cluster (coming)
orb8 trace dns --all-namespaces

System Call Analysis (Coming in v0.3.0)

# Monitor syscalls for security anomalies
orb8 trace syscall --pod suspicious-pod-456

GPU Telemetry (Planned for v0.4.0)

# Monitor GPU utilization for AI workloads
orb8 trace gpu --namespace ml-training

Testing

Quick Test (v0.0.2)

macOS:

# Terminal 1: Start agent
make dev          # First time only - creates VM (~5 min)
make run-agent    # Starts agent with sudo

# Terminal 2: Use CLI
make shell
orb8 status                        # Check agent health
ping -c 5 127.0.0.1                # Generate traffic
orb8 flows                         # View aggregated flows
orb8 trace network --duration 10s  # Stream live events

Linux:

# Terminal 1: Start agent
make run-agent    # Starts agent with sudo

# Terminal 2: Use CLI
orb8 status
ping -c 5 127.0.0.1
orb8 flows
orb8 trace network --duration 10s

Expected output from orb8 status:

Agent Status
----------------------------------------
Node:             your-hostname
Version:          0.0.2
Health:           OK
Events Processed: 150
Active Flows:     3

Running Tests

make test           # Run all tests
make verify-setup   # Verify environment is configured correctly

Build Commands

Architecture

orb8 consists of three main components:

1. eBPF Probe Manager: Dynamically loads and manages eBPF programs for network and syscall tracing (GPU planned)
2. Kubernetes Controller: Watches cluster resources and orchestrates probe deployment
3. Metrics Pipeline: Aggregates eBPF events and exports to Prometheus/CLI

See docs/ARCHITECTURE.md for detailed design documentation.

Comparison with Existing Tools

Note: orb8 is in active development. The table shows planned capabilities (see Roadmap for timeline).

Roadmap

See ROADMAP.md for the full development plan.

Current Status: Phase 2 Complete, Phase 3 In Progress

Completed:

• Phase 0: Foundation & Monorepo Setup
• Phase 1: eBPF Infrastructure (probe loading, ring buffer)
• Phase 2: Container Identification (K8s pod enrichment, gRPC API)

In Progress:

• Phase 3: Network Tracing MVP (CLI commands, public release)

Planned:

• v0.1.0: Network Tracing MVP (Phase 3)
• v0.2.0: Cluster Mode with Metrics (Phase 4-5)
• v0.3.0: Syscall Monitoring (Phase 6)
• v0.4.0: GPU Telemetry (Phase 7)
• v1.0.0: Production Ready (Phase 8)

Platform Support

orb8 requires Linux for eBPF functionality.

macOS

Development uses Lima/QEMU to provide a Linux VM with full eBPF support. Your code is automatically mounted from macOS into the VM.

Linux

Native development with direct kernel access. No VM required.

Windows

Use WSL2 and follow Linux instructions.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Development Workflow

Step 1: Verify your environment

make verify-setup

Step 2: Build, test, and install

Linux:

make magic-local    # Native build, test, install
cargo build         # Or build manually
cargo test          # Run tests

macOS (Phase 1.1 - build infrastructure):

make magic-local    # Fast local testing
# eBPF compiles to bytecode but doesn't load (no kernel)

macOS (Phase 1.2+ - actual eBPF execution):

make magic          # Full VM-based testing
make shell          # Enter VM
orb8 --help

Expected output for Phase 1.1: Both platforms will show:

warning: target filter `bins` specified, but no targets matched
Finished `release` profile [optimized]

This is expected - probe binaries come in Phase 1.2.

Manual Development Setup

Linux:

# Verify environment
make verify-setup

# Build and test
cargo build
cargo test

# For Phase 1.1 specifically
cargo build -p orb8-probes          # eBPF build infrastructure
cargo clippy -p orb8-probes -- -D warnings

macOS:

# Quick setup (no VM)
make verify-setup
cargo build -p orb8-probes

# Full setup (with VM for eBPF execution)
make dev            # Creates VM (5-10 min first time)
make shell          # Enter VM
cargo build
cargo test

See docs/DEVELOPMENT.md for detailed setup instructions and troubleshooting.

License

Apache License 2.0 - see LICENSE for details.

Acknowledgments

Built with:

• aya - Rust eBPF library
• kube-rs - Kubernetes API client
• ratatui - Terminal UI framework

Contact

• GitHub: @Ignoramuss
• Issues: GitHub Issues

Note: This project is in early development. GPU telemetry features (Phase 7) will require specific hardware and driver configurations when implemented.