Kubetail Documentation

The Kubetail Dashboard UI is a React-based static website designed to interface with the Kubetail Dashboard server. It provides a clean user interface for querying Kubernetes data.

Key technical details:

• Data Fetching: Uses Apollo Client for GraphQL queries to the server and standard fetch() for REST API authentication requests.
• Language: Written in TypeScript for high type safety.
• Development Tooling: Uses vite for development.
• Deployment: In production, it is deployed as a static website hosted directly by the Kubetail Dashboard server.

The Kubetail Dashboard Server is a Go-based HTTP server that hosts the Kubetail dashboard web application frontend and manages its backend services.

Key Responsibilities:

• Frontend Hosting: Serves the dashboard web app (packaged as a static site in the website directory in production).
• Backend Proxying: Proxies frontend requests to the user's Kubernetes API and the Kubetail API running inside the cluster.
• Authentication: Provides custom authentication functionality.
• API Interfaces: Responds to Kubernetes-related queries via a GraphQL endpoint (powered by gqlgen) and handles other requests via a REST API.

Technical Stack:

• Web Framework: Gin
• Kubernetes Integration: Kubernetes Go-client

The crates workspace contains the Rust-based modules used within the Kubetail ecosystem. The primary modules are:

• cluster_agent: The Kubetail Cluster Agent.
• rgkl: RipGrep for Kubernetes Logs (RGKL).

For specific details on how to use or configure these individual modules, refer to their respective directory READMEs.

Kubetail is a real-time logging dashboard for Kubernetes designed to tail logs across multi-container workloads.

Core Mechanics:

• Direct API Access: Kubetail uses your cluster's Kubernetes API to fetch logs directly. This means data stays within your possession and no external log forwarding is required by default.
• Workload Merging: It merges logs from all containers within a workload (e.g., a Deployment or DaemonSet) into a single, chronological timeline.
• Lifecycle Tracking: It tracks container lifecycle events via the Kubernetes API to keep the log timeline in sync as containers are created, stopped, or replaced.
• Filtering: Users can filter logs by workload type (Deployment, CronJob, etc.), time ranges, node properties (AZ, CPU architecture, Node ID), and via grep-style searches.

Use the Makefile to maintain code quality across all Go modules in the workspace.

• Linting: make modules-lint
• Vetting: make modules-vet

To set up a local development environment using TLS, you must first generate a Certificate Authority (CA). This involves creating a 4096-bit RSA private key and then using that key to create a self-signed CA certificate valid for 10 years (3650 days).

# 1. Generate the CA private key
openssl genpkey \
  -algorithm RSA \
  -out ca.key \
  -pkeyopt rsa_keygen_bits:4096

# 2. Create the self-signed CA cert (10 years valid)
openssl req -x509 \
  -new -nodes \
  -key ca.key \
  -config csr.cnf \
  -days 3650 \
  -out ca.crt

You can run tests and quality checks using either the standard Go toolchain or the project's Makefile.

Using Go Toolchain

To run the test suite directly:

go test ./...

Using Makefile

From the project root, use the following commands:

• Run tests for all modules (including dashboard): make modules-test
• Run linter: make modules-lint
• Run code vetting: make modules-vet
• Run all Dashboard checks at once: make modules-all

# Run tests for all modules including dashboard
make modules-test

# Run linter
make modules-lint

# Run code vetting
make modules-vet

# Run all Dashboard checks at once
make modules-all

If you are contributing to the Rust packages in the crates workspace, use the following Cargo commands to maintain code quality and build the project:

Linting and Formatting

• Check formatting: Ensures code adheres to the project's style guidelines.
• Run Clippy: Runs the Rust linter and treats warnings as errors to ensure high code quality.

Testing and Building

• Run tests: Executes the test suite for the workspace.
• Run builder: Compiles the workspace in release mode for optimized performance.

# Run linter
cargo fmt --all -- --check

# Run clippy
cargo clippy --all -- -D warnings

# Run tests
cargo test

# Run builder
cargo build --release

If you are modifying protobuf definitions within the shared module, use the go generate command to trigger the gRPC code generation process.

go generate ./...