CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Kubernetes-based NTP (Network Time Protocol) monitoring system that consists of two main components:

Reporter: A DaemonSet that runs on each node to collect NTP metrics via chronyc
Frontend: A web interface that aggregates data from all reporters and displays it in a terminal-style UI

Architecture

The system follows a two-tier architecture:

Reporter Service (reporter/)
- Python Flask application running on port 9898
- Deployed as a DaemonSet to collect metrics from every Kubernetes node
- Uses chronyc command to query NTP status from the local chrony daemon
- Exposes /fragment.json endpoint with node-specific NTP data
Frontend Service (frontend/)
- Python Flask application running on port 8080
- Single replica deployment that aggregates data from all reporter pods
- Renders a terminal-style UI showing NTP status across the entire cluster
- Provides both HTML interface and JSON API endpoints

Development Commands

Building and Deploying

# Build reporter image
docker build -t git.dws.rip/dws/ntp/reporter:v8 reporter/

# Build frontend image
docker build -t git.dws.rip/dws/ntp/frontend:v11 frontend/

# Deploy to Kubernetes
kubectl apply -f manifest.yaml

Local Development

# Run reporter locally (requires chrony to be installed)
cd reporter && python main.py

# Run frontend locally
cd frontend && python main.py

Testing

# Test reporter endpoint
curl http://localhost:9898/fragment.json

# Test frontend aggregation
curl http://localhost:8080/api/fragments

Key Configuration

Reporter Service: Uses host network (hostNetwork: true) to access node's chrony daemon
Environment Variables:
- REPORTER_SERVICE: Kubernetes service name for discovering reporter pods
- NODE_ID, PUBLIC_IP, BIND_IP: Node-specific values from Kubernetes downward API
Service Discovery: Frontend uses DNS resolution to find all reporter pod IPs

Data Flow

Each reporter pod runs chronyc tracking and chronyc sources commands
Reporter parses CSV output and exposes via /fragment.json
Frontend resolves all reporter IPs via Kubernetes DNS
Frontend aggregates data and renders ASCII tables in terminal UI
Real-time clock sync via JavaScript using server time API

Dependencies

Reporter: Flask, chrony (system package)
Frontend: Flask, requests, texttable
Both use Python 3.10 slim base images

2.6 KiB Raw Permalink Blame History