How stern/stern works
Project Type and Purpose
• This is a Go-based command-line tool (“stern”) that tails logs from multiple Kubernetes pods and containers simultaneously.
• It acts as a client to the Kubernetes API server, watches for Pods, streams their logs, colorizes and formats them, and writes output to stdout or files.
High-Level File Structure
• /cmd directory: CLI entry-point code (flag parsing, help, completion, version, template support, config loading, command dispatch).
• main.go: Imports cmd and invokes the CLI.
• Dockerfile / Makefile / goreleaser.yaml: Build and release pipelines.
• hack/: Scripts to generate and verify documentation.
• Tests are co-located in both cmd and stern packages.
Key Architecture Components
a. CLI Frontend
• Component: “stern CLI”
• Responsibilities: parse flags & config, build query expressions, handle stdin or template inputs, initialize watcher and tailer modules.
b. Kubernetes API Client
• Component: “k8s API Server” (external service) and “client-go” integration layer
• Responsibilities: list/watch pods, fetch pod definitions, stream logs.
c. Pod & Container Watcher
• Component: “Watcher”
• Responsibilities: subscribe to Pod events, match resources against regex or <resource>/<name>, dispatch add/remove events.
d. Log Tailer
• Component: “LogStreamer” instances
• Responsibilities: concurrent pods/log streams per container, respecting --tail, --no-follow, --max-log-requests.
e. Container State Manager
• Component: “ContainerState”
• Responsibilities: track container lifecycle (running, waiting, terminated), filter by --container-state.
f. Formatter & Template Engine
• Component: “TemplateFormatter”
• Responsibilities: apply Go‐text templates or predefined outputs (raw, json, extjson), colorize fields using ANSI SGR codes, incorporate timestamp formatting.
g. Output
• Component: stdout / stderr (or piped consumer)
• Responsibilities: deliver final log lines to the user or other tools (e.g., jq).
h. Configuration
• Component: config file (~/.config/stern/config.yaml) or env vars
Relationships and Data Flows
1. User invokes stern CLI → flags & config are parsed by cmd module
2. cmd module constructs a “Query” object → passed to Watcher
3. Watcher uses client-go → subscribes to Pod list/watch from Kubernetes API
4. On pod add: Watcher spawns one or more LogStreamer per container via LogTailer
5. LogStreamer establishes a stream (pods/log API) → emits raw log lines
6. Raw lines pass through ContainerState filters → forwarded to TemplateFormatter
8. On pod/container termination: LogStreamer closes stream; Watcher cleans up resources
Architectural Patterns and Principles
• Modular layering: CLI layer (cmd) decoupled from core streaming logic (stern package)
• Concurrency: fan-out of per‐container log streams with limits (--max-log-requests)
• Observer pattern: Watcher reacting to Kubernetes Pod events
• Strategy pattern: pluggable output formats (default, raw, json, custom Go templates)
Technologies and Frameworks
• Go modules (go.mod)
• client-go (Kubernetes API client)
• text/template (for custom formatting)
• Docker (for containerized runs)
• GitHub Actions / GoReleaser (CI/CD pipelines)