# Kubetail

_Kubetail is a real-time logging dashboard for Kubernetes_ 

<a href="https://youtu.be/q9rV9gHQb4Q">
  <img width="350" alt="demo-thumbnail" src="https://github.com/user-attachments/assets/3b528e7e-5f8a-4bfd-86a1-0b70691b8a4c">
</a>

Demo: [https://www.kubetail.com/demo](https://www.kubetail.com/demo)

<a href="https://discord.gg/CmsmWAVkvX"><img src="https://img.shields.io/discord/1212031524216770650?logo=Discord&style=flat-square&logoColor=FFFFFF&labelColor=5B65F0&label=Discord&color=64B73A"></a>
[![Slack](https://img.shields.io/badge/Slack-kubetail-364954?logo=slack&labelColor=4D1C51)](https://kubernetes.slack.com/archives/C08SHG1GR37)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
[![Contributor Resources](https://img.shields.io/badge/Contributor%20Resources-purple?style=flat-square)](https://github.com/kubetail-org)

English | [简体中文](.github/README.zh-CN.md) | [日本語](.github/README.ja.md) | [한국어](.github/README.ko.md) | [Deutsch](.github/README.de.md) | [Español](.github/README.es.md) | [Português](.github/README.pt-BR.md) | [Français](.github/README.fr.md)

## Introduction

<img src="https://github.com/user-attachments/assets/3713a774-1b3a-41f9-8e9d-9331bbf8acac" width="300" title="Kubetail">

<br>
<br>

**Kubetail** is a general-purpose logging dashboard for Kubernetes, optimized for tailing logs across multi-container workloads in real-time. With Kubetail, you can view logs from all the containers in a workload (e.g. Deployment or DaemonSet) merged into a single, chronological timeline, delivered to your browser or terminal.

The primary entry point for Kubetail is the `kubetail` CLI tool, which can launch a local web dashboard on your desktop or stream raw logs directly to your terminal. Behind the scenes, Kubetail uses your cluster's Kubernetes API to fetch logs directly from your cluster, so it works out of the box without needing to forward your logs to an external service. Kubetail also uses your Kubernetes API to track container lifecycle events in order to keep your 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.

Our goal is to build the most powerful, user-friendly logging platform for Kubernetes and we'd love your help. If you notice a bug or have a suggestion please create a GitHub Issue or send us an email (hello@kubetail.com)!

## Features

* Clean, easy-to-use interface
* View log messages in real-time
* Filter logs by:
  * Workload (e.g. Deployment, CronJob, StatefulSet)
  * Absolute or relative time range
  * Node properties (e.g. availability zone, CPU architecture, node ID)
  * Grep 
* Uses your Kubernetes API to retrieve log messages so data never leaves your possession (private by default)
* Switch between multiple clusters (Desktop-only)
* Run anywhere: Desktop, Cluster, Docker

## Quickstart

### Installation

To install `kubetail` you can use [Homebrew](https://brew.sh/):

```console
brew install kubetail
```

<details>
  <summary>See 15 other options (e.g. Krew, Snap, Winget, Ubuntu, Fedora, SUSE, Alpine, Arch, Gentoo, Nix, asdf, Chocolatey, Scoop, MacPorts)</summary>
  
  ```console
  # Krew
  kubectl krew install kubetail

  # Snap
  sudo snap install kubetail

  # Winget
  winget install kubetail
  
  # Chocolatey
  choco install kubetail

  # Scoop
  scoop install kubetail

  # MacPorts
  sudo port install kubetail

  # Ubuntu/Mint (apt)
  sudo add-apt-repository ppa:kubetail/kubetail
  sudo apt update && sudo apt install kubetail-cli

  # Fedora/CentOS/RHEL/Amazonlinux/Mageia (copr)
  dnf copr enable kubetail/kubetail
  dnf install kubetail

  # SUSE (zypper)
  zypper addrepo 'https://download.opensuse.org/repositories/home:/kubetail/$releasever/' kubetail
  zypper refresh && zypper install kubetail-cli

  # Alpine (apk)
  apk add kubetail --repository=https://dl-cdn.alpinelinux.org/alpine/edge/testing

  # Arch Linux (AUR)
  yay -S --noconfirm kubetail-cli

  # Gentoo (GURU)
  ACCEPT_KEYWORDS="~$(portageq envvar ARCH)" emerge dev-util/kubetail

  # Nix (Flake)
  nix profile add github:kubetail-org/kubetail-nix

  # Nix (Classic)
  nix-env -i -f https://github.com/kubetail-org/kubetail-nix/archive/refs/heads/main.tar.gz

  # asdf
  asdf plugin add kubetail https://github.com/kubetail-org/asdf-kubetail.git
  asdf install kubetail latest
  ```
</details>

If you prefer, you can also download it from the [release binaries](https://github.com/kubetail-org/kubetail/releases/latest) or use our install script:

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

### Usage

Here are some ways to use `kubetail`:

**1. Start the web dashboard (GUI)**

```console
kubetail serve
```

**2. View logs in your terminal**

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

**3. Enable advanced features (by installing Kubetail API)**

```console
kubetail cluster install
```

**4. Initialize a local config file**

```console
kubetail config init
```

See the documentation for a full list of [commands](https://www.kubetail.com/docs/cli#subcommands). Have fun tailing your logs!

## Run Anywhere

In addition to running Kubetail on your desktop you can also run it in these environments:

* [Cluster](https://www.kubetail.com/docs/getting-started/cluster/install)
* [Docker](https://www.kubetail.com/docs/getting-started/docker)
* [Minikube](https://www.kubetail.com/docs/getting-started/cluster/install#minikube)

## Documentation

Visit our full documentation at [https://www.kubetail.com](https://www.kubetail.com/)

## Roadmap and Status

This is our high-level plan for the Kubetail project, in order:

|   | Step                                                  | Status |
| - | ----------------------------------------------------- | ------ |
| 1 | Real-time container logs                              | ✅     |
| 2 | Real-time search and polished user experience         | 🛠️     |
| 3 | Real-time system logs (e.g. systemd, k8s events)      | 🔲     |
| 4 | Basic customizability (e.g. colors, time formats)     | 🔲     |
| 5 | Message parsing and metrics                           | 🔲     |
| 6 | Historic data (e.g. log archives, metrics timeseries) | 🔲     |
| 7 | Kubetail API and developer-facing client libraries    | 🔲     |
| N | World Peace                                           | 🔲     |

And here are some additional details:

**Real-time container logs**

Users can view the container logs from the pods currently running inside their clusters quickly and easily using a web dashboard. Users can view container logs organized by workloads and follow log messages as ephemeral containers get created and deleted. They can also narrow their viewing window by timestamp and filter logs by source properties such as region, zone and node.

**Real-time search and polished user experience**

Users can install Kubetail easily on their desktops and in their clusters. By default, Kubetail will use only the Kubernetes API to fetch basic data such as running workloads and container logs. If a user wants more advanced functionality they can install Kubetail custom services in their cluster (i.e. "Kubetail Cluster API" and "Kubetail Cluster Agent", collectively known as the "Kubetail API") and gain access to features such as log search, log file sizes and last event timestamps. The entire experience of installing, upgrading and uninstalling the Kubetail API is very polished and users are able to view their logs with equally powerful tools in the browser and the terminal using the Kubetail web dashboard and CLI tool.

**Real-time system logs**

Users who install the Kubetail API gain immediate access to their node-level logs (e.g. systemd) and cluster-level logs (e.g. kubernetes events) and view them in an integrated interface that shows their container logs in context with other system information such as CPU utilization, memory usage and disk space. System logs are viewable in real-time, in the same merged timeline with other logs. Users can filter system logs by timestamp and source properties.

**Basic customizability**

Users can fully customize their Kubetail experience when using the web dashboard and CLI tool by modifying their user settings. The user settings are modifiable by hand using a config file or via the dashboard UI. The experience is very polished and works seamlessly across upgrades that may add/remove/modify user settings. Users have the option to sync their settings across multiple devices.

## Development

### Repository Structure

This monorepo contains the following modules:

* Kubetail CLI ([modules/cli](modules/cli))
* Kubetail Cluster API ([modules/cluster-api](modules/cluster-api))
* Kubetail Cluster Agent ([crates/cluster_agent](crates/cluster_agent))
* Kubetail Dashboard ([modules/dashboard](modules/dashboard))

It also contains the source code for the Kubetail Dashboard's frontend:

* Dashboard UI ([dashboard-ui](dashboard-ui))

### Setting up the Development Environment

#### Dependencies

* [Go](https://go.dev/)
* [pnpm](https://pnpm.io/)
* [Tilt](https://tilt.dev/)
* [Tilt-compatible cluster](https://docs.tilt.dev/choosing_clusters.html) (e.g. [minikube](https://minikube.sigs.k8s.io/docs/), [kind](https://kind.sigs.k8s.io/docs/user/quick-start/), [docker-desktop](https://docs.tilt.dev/choosing_clusters.html#docker-for-desktop))
* [ctlptl](https://github.com/tilt-dev/ctlptl) (optional)

#### Next steps

1. Create a [Tilt-compatible](https://docs.tilt.dev/choosing_clusters.html) Kubernetes Dev Cluster:

```console
# minikube
ctlptl apply -f hack/ctlptl/minikube.yaml

# kind
ctlptl apply -f hack/ctlptl/kind.yaml

# docker-desktop
ctlptl apply -f hack/ctlptl/docker-desktop.yaml
```

2. Start the dev environment:

```console
tilt up
```

3. Start the Dashboard server:

```console
cd modules/dashboard
go run cmd/main.go -c hack/config.yaml
```

4. Run the Dashboard UI locally:

```console
cd dashboard-ui
pnpm install
pnpm dev
```

Now access the dashboard at [http://localhost:5173](http://localhost:5173).

<details>
  <summary><h3>Rust Development (Optional)</h3></summary>
  
  By default, the dev environment uses a pre-built image for the Rust-based cluster-agent. If you're working on the Rust code, you can use the `KUBETAIL_RUST_DEV_MODE` environment variable to enable a development mode that compiles the Rust code and syncs the binary into the cluster. There are two modes available:

  | Mode     | Description                                                                                               |
  | -------- | --------------------------------------------------------------------------------------------------------- |
  | `docker` | Compiles the Rust code inside a Docker container. No local Rust toolchain required.                       |
  | `local`  | Compiles the Rust code on your machine using cross-compilation. Faster rebuilds but requires local setup. |

  #### Docker mode

  To use Docker mode, run Tilt with the `KUBETAIL_RUST_DEV_MODE` env variable set to `docker`:

  ```console
  KUBETAIL_RUST_DEV_MODE=docker tilt up
  ```

  #### Local mode

  Local mode requires additional dependencies and setup but offers faster rebuild times.

  ##### Dependencies

  * [rustup](https://rustup.rs)
  * [protobuf](https://protobuf.dev/installation/)

  ##### Setup

  First, install the Rust target required for your architecture:

  ```console
  # x86_64
  rustup target add x86_64-unknown-linux-musl

  # aarch64
  rustup target add aarch64-unknown-linux-musl
  ```

  Next, install the tools required by Rust cross compiler:

  ```console
  # macOS (Homebrew)
  brew install FiloSottile/musl-cross/musl-cross

  # Linux (Ubuntu)
  apt-get install musl-tools
  ```

  On macOS, add this to your `~/.cargo/config.toml` file:

  ```
  [target.x86_64-unknown-linux-musl]
  linker = "x86_64-linux-musl-gcc"

  [target.aarch64-unknown-linux-musl]
  linker = "aarch64-linux-musl-gcc"
  ```

  Finally, run Tilt with the `KUBETAIL_RUST_DEV_MODE` env variable set to `local`:

  ```console
  KUBETAIL_RUST_DEV_MODE=local tilt up
  ```
</details>

## Build

### CLI Tool

To build the Kubetail CLI tool executable (`kubetail`), run the following command:

```console
make
```

When the build process finishes you can find the executable in the local `bin/` directory.

### Dashboard

To build a docker image for a production deployment of the Kubetail Dashboard server, run the following command:

```console
docker build -f build/package/Dockerfile.dashboard -t kubetail-dashboard:latest .
```

### Cluster API

To build a docker image for a production deployment of the Kubetail Cluster API server, run the following command:

```console
docker build -f build/package/Dockerfile.cluster-api -t kubetail-cluster-api:latest .
```

### Cluster Agent

To build a docker image for a production deployment of the Kubetail Cluster Agent, run the following command:

```console
docker build -f build/package/Dockerfile.cluster-agent -t kubetail-cluster-agent:latest .
```

## Get Involved

We're building the most **user-friendly**, **cost-effective**, and **secure** logging platform for Kubernetes and we'd love your contributions! Here's how you can help:

* UI/UX design
* React frontend development
* Reporting issues and suggesting features

Reach us at hello@kubetail.com, or join our [Discord server](https://discord.gg/CmsmWAVkvX) or [Slack channel](https://join.slack.com/t/kubetail/shared_invite/zt-2cq01cbm8-e1kbLT3EmcLPpHSeoFYm1w).
