# Kubetail

> Kubetail is a free, open-source, real-time logging dashboard for Kubernetes, optimized for tailing logs across multi-container workloads in real-time.

With Kubetail, users can view logs from all the containers in a workload (e.g. Deployment or DaemonSet) merged into a single, chronological timeline, delivered to a browser or terminal.

The primary entry point for Kubetail is the `kubetail` CLI tool, which can launch a local web dashboard on a user's desktop or stream raw logs directly to their terminal. Behind the scenes, Kubetail uses the Kubernetes API to fetch logs directly from the user's cluster, so it works out of the box without needing to forward logs to an external service. Kubetail also uses the Kubernetes API to track container lifecycle events in order to keep the log timeline in sync as containers start, stop or get replaced. This makes it easy to follow logs seamlessly as user requests move from one ephemeral container to another across services.

## Links

- Website: https://www.kubetail.com
- Documentation: https://docs.kubetail.com
- GitHub: https://github.com/kubetail-org/kubetail
- Demo: https://demo.kubetail.com
- Helm Charts: https://github.com/kubetail-org/helm-charts

## Quick Start

Install the CLI using your preferred package manager:

**macOS:**

```sh
brew install kubetail
# or
kubectl krew install kubetail
# or
sudo port install kubetail
# or
nix profile add github:kubetail-org/kubetail-nix
# or
nix-env -i -f https://github.com/kubetail-org/kubetail-nix/archive/refs/heads/main.tar.gz
# or
asdf plugin add kubetail https://github.com/kubetail-org/asdf-kubetail.git
asdf install kubetail latest
```

**Linux:**

```sh
brew install kubetail
# or
kubectl krew install kubetail
# or
sudo snap install kubetail
# or
sudo add-apt-repository ppa:kubetail/kubetail
sudo apt update && sudo apt install kubetail-cli
# or
dnf copr enable kubetail/kubetail
dnf install kubetail
# or
zypper addrepo 'https://download.opensuse.org/repositories/home:/kubetail/$releasever/' kubetail
zypper refresh && zypper install kubetail-cli
# or
apk add kubetail --repository=https://dl-cdn.alpinelinux.org/alpine/edge/testing
# or
yay -S --noconfirm kubetail-cli
# or
ACCEPT_KEYWORDS="~$(portageq envvar ARCH)" emerge dev-util/kubetail
# or
nix profile add github:kubetail-org/kubetail-nix
# or
nix-env -i -f https://github.com/kubetail-org/kubetail-nix/archive/refs/heads/main.tar.gz
# or
asdf plugin add kubetail https://github.com/kubetail-org/asdf-kubetail.git
asdf install kubetail latest
```

**Windows:**

```sh
winget install kubetail
# or
krew install kubetail
# or
choco install kubetail
# or
scoop install kubetail
```

**shell:**

```sh
curl -sS https://www.kubetail.com/install.sh | bash
```

Launch the web dashboard (opens at http://localhost:7500):

```sh
kubetail serve
```

Or stream logs directly in your terminal:

```sh
kubetail logs -f deployments/my-app
```

Create a config file:

```sh
kubetail config init
```

Install cluster-side resources for advanced features (e.g. search):

```sh
kubetail cluster install
```

## Key Features

### Real-time Log Tailing

View logs from all containers in a workload merged into a single chronological timeline. Kubetail tracks container lifecycle events so log streams stay connected as containers restart or get replaced.

### Web Dashboard

A browser-based GUI with:
- Workload list showing all Kubernetes workloads
- Logging console with real-time log tailing
- Multi-workload view — select multiple workloads and view merged logs
- Health status panel for backend services

### CLI

The `kubetail` CLI provides:
- `kubetail serve` — launch the web dashboard locally
- `kubetail logs` — stream logs directly to your terminal with time-range and node-property filters
- `kubetail cluster install/uninstall` — manage cluster-side resources
- `kubetail config init` — create a local config file

### Log Search

Real-time log search powered by ripgrep. With the optional cluster agent installed, search filtering happens on-node before any data leaves the cluster.

### Container Lifecycle Tracking

Kubetail tracks container start, stop, and replacement events using the Kubernetes API. Log streams follow containers seamlessly as they move between nodes.

### Multiple Cluster Support

When using the desktop CLI, Kubetail detects clusters from your kubeconfig file and lets you switch between them in the dashboard.

### Privacy

Logs never leave your cluster. Kubetail reads logs directly from the Kubernetes API or from on-node log files. No data is sent to external services.

## Architecture

Kubetail is composed of a small number of focused tools and services.

### Components

**Kubetail CLI**
- Written in Go
- Bundles the Dashboard for local use
- Main commands: `kubetail serve` (web UI), `kubetail logs` (terminal streaming)
- `kubetail cluster` subcommand manages optional cluster-side resources via embedded Helm client

**Kubetail Dashboard**
- **Dashboard UI** — React SPA built with Vite. Communicates with the server via GraphQL: queries/mutations over HTTP, real-time log subscriptions over WebSocket
- **Dashboard Server** — Go HTTP server that serves static UI assets, handles authentication/session management, and fetches log data. Supports two backends: Kubernetes API (default) and Kubetail API (optional)

**Kubetail Cluster API** (optional)
- Go HTTP server running as a Deployment in-cluster
- Exposes GraphQL API to the Dashboard Server
- Acts as gRPC dispatcher to per-node Cluster Agents
- Fans out log requests, gathers streamed responses, merges into single stream
- Enables features unavailable in Kubernetes API mode: search, log file metadata

**Kubetail Cluster Agent** (optional)
- Rust-based gRPC server running as a DaemonSet (one per node)
- Reads container log files directly from `/var/log/containers`
- Uses inotify for filesystem notifications (no polling)
- Applies ripgrep-based text filtering on-node before transfer
- Caches SubjectAccessReview results for authorization

### Deployment Topologies

**Desktop**
The `kubetail` CLI is installed locally and uses your kubeconfig for authentication. Running `kubetail serve` starts the Dashboard Server locally. No cluster-side installation required, but installing the Kubetail API enables advanced features.

**Cluster**
The full stack is installed as Kubernetes resources via Helm or YAML manifests. The Dashboard Server runs as a Deployment in the `kubetail-system` namespace, accessed via `kubectl port-forward`, `kubectl proxy`, or ingress. Preferred for shared team environments.

**Docker**
The CLI is packaged as a Docker image (`kubetail/kubetail-cli`). Mount your kubeconfig for local use, or deploy as a pod with `--in-cluster` flag for service account authentication.

### Log Delivery Pipelines

**Kubernetes API (default)**
Logs flow through the Kubernetes API. One long-lived HTTP connection per container. Text filtering applied on the Dashboard Server. Works with any cluster out of the box.

**Kubetail API (optional)**
When Cluster API and Cluster Agent are deployed, logs flow through the Kubetail API stack. Log data never touches the kube-apiserver — the kube-apiserver is used only for metadata and authorization. Text filtering happens on-node before transfer.

### Communication Protocols

| Link                             | Protocol                                    |
| -------------------------------- | ------------------------------------------- |
| Browser ↔ Dashboard Server       | GraphQL over WebSocket (graphql-ws) + HTTPS |
| Dashboard Server ↔ kube-apiserver| HTTP/HTTPS (client-go)                      |
| Dashboard Server ↔ Cluster API   | gRPC over HTTP/2                            |
| Cluster API ↔ Cluster Agent      | gRPC over HTTP/2 (optional mTLS)            |
| Cluster Agent ↔ node disk        | Local file I/O + inotify                    |

## Resource Usage

Typical resource usage (e.g. for the demo site):

| Component     | Memory | CPU    |
| ------------- | ------ | ------ |
| Dashboard     | ~21MB  | ~3.00m |
| Cluster API   | ~21MB  | ~3.00m |
| Cluster Agent | ~7MB   | ~4.00m |

## Development vs. Production

### Development
Kubetail is designed for debugging distributed systems where a single request touches many services. View logs from multiple services merged chronologically, trace requests end-to-end, and reproduce issues without reconstructing events from individual pod logs.

### Production
Kubetail complements full observability platforms (Datadog, Grafana, Loki, etc.). Use Kubetail for live debugging and real-time tailing; use your primary platform for long-term retention, alerting, and historical analysis. During incidents, Kubetail only requires the kube-apiserver to be reachable — it works even when your observability stack is degraded.

## Security and Access Control

### Log Privacy
All log data stays within your infrastructure. In Kubernetes API mode, logs flow from kubelet to kube-apiserver to Dashboard Server. In Kubetail API mode, logs flow from disk to Cluster Agent to Cluster API to Dashboard Server — all within the cluster network.

### Access Control
- **Desktop CLI** — uses kubeconfig credentials; inherits existing RBAC permissions
- **Cluster deployment** — uses Kubernetes service accounts and RBAC
- The Cluster Agent caches SubjectAccessReview results for authorization checks

## Compatibility

- Works with all Kubernetes distributions and vendors using Kubernetes v1.18 or newer
- Supported on macOS, Linux, and Windows

## Community and Support

- Email: hello@kubetail.com
- GitHub Issues: https://github.com/kubetail-org/kubetail/issues
- Discord: https://discord.gg/CmsmWAVkvX
- Slack: https://join.slack.com/t/kubetail/shared_invite/zt-2cq01cbm8-e1kbLT3EmcLPpHSeoFYm1w
- Twitter/X: https://x.com/kubetail

## License

Kubetail is open source, licensed under the Apache 2.0 License. The dashboard, CLI, and all associated tools are free and will always remain free.

## Full Documentation

For comprehensive documentation including installation guides, configuration reference, and CLI reference, see:
- Documentation site: https://docs.kubetail.com
- Abridged docs for LLMs: https://docs.kubetail.com/llms-small.txt
- Complete docs for LLMs: https://docs.kubetail.com/llms-full.txt