This is the full developer documentation for Kubetail # Kubetail Docs > Kubetail is a real-time logging tool for Kubernetes. Welcome to our documentation site! ## Next steps [Section titled “Next steps”](#next-steps) Introduction Learn what Kubetail is and how it helps you view your Kubernetes logs in real-time. [Read more →](/concepts/introduction) Run on Desktop Install and run Kubetail on your desktop. [Get started →](/guides/desktop/installation) Run in Cluster Install and run Kubetail in your cluster. [Get started →](/guides/cluster/installation) Use with Docker Run Kubetail using Docker anywhere. [Get started →](/guides/docker/introduction) Web Dashboard Explore Kubetail’s web-based GUI for browsing and tailing logs. [Learn more →](/concepts/gui-overview) CLI Reference View all available CLI commands and options. [Read reference →](/reference/cli) # Architecture > How Kubetail's components fit together — CLI, Dashboard, Cluster API, and Cluster Agent — across desktop, cluster, and docker deployment topologies. Kubetail is composed of a small number of focused tools and services. Some are required; others are optional and unlock additional capabilities. This page describes deployment topologies, log delivery pipelines and individual components in detail. *** ## Deployment topologies [Section titled “Deployment topologies”](#deployment-topologies) Kubetail can be deployed in three distinct ways depending on your environment and access requirements. Each topology uses the same underlying components but differs in how they are installed, accessed, and configured. ### Desktop [Section titled “Desktop”](#desktop) In the most common topology, the `kubetail` CLI is installed on your local machine and uses your kubeconfig file to authenticate against your clusters. This is convenient because `kubetail` inherits the same RBAC permissions as `kubectl` and you can access your logs without making any other changes. On your desktop, running `kubetail serve` starts the Dashboard Server locally, which serves the Dashboard UI and proxies log requests to the cluster’s Kubernetes API on your behalf. You can also use `kubteail logs` to stream logs directly to your terminal. No cluster-side installation is required to get started but if you install the Kubetail API in your cluster then `kubetail` will use it automatically to enable advanced features (e.g. search). See the [Desktop installation guide](/guides/desktop/installation) for setup instructions. ### Cluster [Section titled “Cluster”](#cluster) The entire Kubetail stack can be installed as Kubernetes resources inside your cluster using Helm or YAML manifests. In this topology, the Dashboard Server runs as a Deployment in the `kubetail` namespace and is accessed from your browser via `kubectl port-forward`, `kubectl proxy`, or an ingress resource. This is the preferred approach for shared team environments or when you want persistent, always-on access without relying on a local CLI. See the [Cluster installation guide](/guides/cluster/installation) for setup instructions. ### Docker [Section titled “Docker”](#docker) The `kubetail` CLI has been packaged as a Docker image ([`kubetail/kubetail-cli`](https://hub.docker.com/r/kubetail/kubetail-cli)) so it can be run inside a container without a local installation. Locally, you can mount your `.kube/config` file into the container and use `docker run` or `docker-compose` to start the dashboard. The image can also be deployed as a pod inside a cluster, using the `--in-cluster` flag to authenticate against the pod’s service account credentials instead of a kubeconfig file. See the [Docker introduction](/guides/docker/introduction) for more information about Docker deployment options. *** ## Log delivery pipelines [Section titled “Log delivery pipelines”](#log-delivery-pipelines) By default, Kubetail uses the Kubernetes API to fetch logs. To enable advanced features such as last-event timestamps and search you can install the Kubetail Cluster API and Kubetail Cluster Agent (collectively known as the “Kubetail API”). What follows describes each mode in more detail. ### Kubernetes API (default) [Section titled “Kubernetes API (default)”](#kubernetes-api-default) When no Cluster API is configured, logs flow through the Kubernetes API. For example, here’s the path of a request from the web dashboard to files on disk using the Kubernetes API: ```plaintext +---------------------------------+ | Kubetail Dashboard UI (Browser) | +---------------------------------+ │ │ GraphQL over WebSocket ▼ +---------------------------------+ | Kubetail Dashboard Server | +---------------------------------+ │ │ HTTP GET /api/v1/namespaces/{ns}/pods/{pod}/log ▼ +---------------------------------+ | kube-apiserver | +---------------------------------+ │ │ HTTP → kubelet /containerLogs ▼ +---------------------------------+ | kubelet (node) | +---------------------------------+ │ │ file read ▼ +---------------------------------+ | Pod log file (disk) | +---------------------------------+ ``` This path works with any Kubernetes cluster out of the box. Every open log view holds one long-lived HTTP connection from the Dashboard Server to the kube-apiserver per container being tailed. Text filtering is applied on the Kubetail Dashboard Server as the log stream arrives. ### Kubetail API (optional) [Section titled “Kubetail API (optional)”](#kubetail-api-optional) When the Cluster API and Cluster Agent are deployed then the Kubetail Dashboard Server will route requests through the “Kubetail API” stack. For example, here’s the path of a request from the web dashboard to files on disk using Kubetail API: ```plaintext +---------------------------------+ | Kubetail Dashboard UI (Browser) | +---------------------------------+ │ │ GraphQL over WebSocket ▼ +---------------------------------+ | Kubetail Dashboard Server | +---------------------------------+ │ │ GraphQL over WebSocket ▼ +---------------------------------+ | Cluster API | +---------------------------------+ │ │ gRPC - one stream per log file ▼ +---------------------------------+ | Cluster Agent (one per node) | +---------------------------------+ │ │ file read + inotify watches ▼ +---------------------------------+ | Pod log file (disk) | +---------------------------------+ ``` In this pipeline, log data never touches the kube-apiserver and text filtering happens on the node before transfer. The kube-apiserver is used only for workload metadata requests and authorization checks. *** ## Components [Section titled “Components”](#components) ### Kubetail CLI [Section titled “Kubetail CLI”](#kubetail-cli) The `kubetail` CLI is the primary entry point for Kubetail on the desktop. The tool is written in Go and bundles the Dashboard so it can run the web UI locally. Its two main commands are `kubetail serve`, which starts the Dashboard server and opens the web UI, and `kubetail logs`, which streams logs directly to your terminal. The `kubetail cluster` subcommand manages the optional cluster-side resources using an embedded Helm client. See the [CLI reference](/reference/cli) for a full list of commands and flags. ### Kubetail Dashboard [Section titled “Kubetail Dashboard”](#kubetail-dashboard) The Kubetail Dashboard consists of two parts that are deployed together: * **Dashboard UI** — a React-based single-page application built with Vite and served as static assets by the Dashboard Server. The browser communicates with the Dashboard server exclusively over GraphQL: queries and mutations over HTTP, and real-time log subscriptions over a persistent WebSocket connection. All requests to the Kubernetes API or to any cluster-side Kubetail services are proxied through the server. * **Dashboard server** — a Go-based http server that serves the static UI assets, handles authentication and session management, and fetches log data on behalf of the browser. It supports two log backends: the Kubernetes API (default, no extra installation required) and the Kubetail API (optional, if cluster-side resources are installed). See the [Dashboard reference](/reference/dashboard) for configuration options. ### Kubetail Cluster API [Section titled “Kubetail Cluster API”](#kubetail-cluster-api) The Cluster API is a Go-based HTTP server that runs as a single Deployment inside the cluster. It exposes a GraphQL API to the Dashboard Server and acts as a gRPC dispatcher to the per-node Cluster Agents. When a log request arrives, the Cluster API fans out to the relevant Cluster Agent(s), gathers their streamed responses, and merges them into a single stream back to the Dashboard server. Because log data flows entirely over the cluster-internal network, it never touches the kube-apiserver. The Cluster API also unlocks capabilities unavailable in Kubernetes API mode such as search and log file metadata (sizes, timestamps). See the [Cluster API reference](/reference/cluster-api) for configuration options. ### Kubetail Cluster Agent [Section titled “Kubetail Cluster Agent”](#kubetail-cluster-agent) The Cluster Agent is a Rust-based gRPC server that runs as a DaemonSet — one pod per node. It is the only Kubetail component that touches the filesystem directly, reading container log files from `/var/log/containers` on the node. It: * Watches pod log files using OS-level filesystem notifications (inotify on Linux), so new lines are detected without polling * Streams new log lines to the Cluster API over gRPC as they are written * Applies ripgrep-based text filtering on the node before any data leaves, so only matching lines are transferred * Caches Kubernetes SubjectAccessReview results to authorize requests without repeated API calls See the [Cluster Agent reference](/reference/cluster-agent) for configuration options. *** ## Communication protocols [Section titled “Communication protocols”](#communication-protocols) | Link | Protocol | Notes | | --------------------------------- | ------------------------------------------- | ---------------------------------------------------------- | | Browser ↔ Dashboard Server | GraphQL over WebSocket (graphql-ws) + HTTPS | Queries and real-time subscriptions on a single connection | | Dashboard Server ↔ kube-apiserver | HTTP/HTTPS (client-go) | Kubernetes API mode only; one stream per container | | Dashboard Server ↔ Cluster API | gRPC over HTTP/2 | Cluster API mode only; optional TLS | | Cluster API ↔ Cluster Agent | gRPC over HTTP/2 | Optional mTLS; dispatched via grpc-dispatcher-go | | Cluster Agent ↔ node disk | Local file I/O + inotify | No network; direct read of `/var/log/containers/` | *** Tip For a deeper look at the performance implications of each topology, see the [Performance](/concepts/performance) page. # Development vs. Production > Kubetail complements your observability stack. Use it to trace requests across ephemeral containers during development, or tail logs during incidents. Kubetail works well in both development and production environments though the value proposition differs at each stage. *** ## Development [Section titled “Development”](#development) Distributed systems are hard to debug because a single user request can touch many services. Kubetail is designed exactly for this scenario. Using Kubetail, you can view logs from multiple services merged in a chronological timeline across all the containers in the workloads and watch requests flow through your system in real-time. Because Kubetail tracks container lifecycle events, log streams stay connected as containers restart or get replaced. This makes it easy to trace the path of a request end-to-end and reproduce issues without needing to reconstruct events using individual pod logs. To start using Kubetail in development, just install the `kubetail` CLI and run `kubetail serve` to view logs in your browser, or `kubetal logs` to stream logs to your terminal (see [Quickstart](/tutorials/getting-started/quickstart)). No cluster-side installation is required, and no log forwarding pipeline needs to be configured first. *** ## Production [Section titled “Production”](#production) Kubetail also scales up to production smoothly. You can use Kubetail to ensure your traffic flows are working as expected, and you can also use Kubetail to spot check your service logs in real-time to make sure they aren’t producing any errors. ### Complement your existing logging stack [Section titled “Complement your existing logging stack”](#complement-your-existing-logging-stack) Kubetail is not a replacement for a full observability platform. Tools like Datadog, Grafana, ClickHouse, VictoriaMetrics, Honeycomb, Dash0, and Loki are designed for long-term log retention, alerting, metric correlation, and historical analysis at scale. Kubetail’s strength is real-time visibility and live log tailing, which pairs well with platforms that are optimized for storage and querying. A common pattern is to use Kubetail for live debugging and your primary logging platform for everything else: metrics dashboards, alerts, and post-incident analysis. ### Debugging outages [Section titled “Debugging outages”](#debugging-outages) Kubetail has an important operational advantage during incidents: **it only requires the kube-apiserver to be reachable**. It does not depend on an external logging service being up, or a remote storage backend responding. When your cluster is on fire and your observability stack is degraded, Kubetail can still give you a live view into what your containers are doing right now. # Overview > A tour of the Kubetail web dashboard: browsing workloads, opening the logging console, and checking the health status of backend services. The Kubetail web dashboard is a browser-based GUI that gives you a birds-eye view of your Kubernetes workloads and lets you follow multiple log streams in real-time. You can run the dashboard in two ways: * **On your desktop** — use the `kubetail` CLI to start a local dashboard server that authenticates against your cluster using your kubeconfig file. No cluster-side installation required. (See [Run on Desktop > Installation](/guides/desktop/installation)) * **In your cluster** — deploy the dashboard as a Kubernetes workload using Helm or YAML manifests, then access it via `kubectl port-forward`, `kubectl proxy`, or an ingress resource. (See [Run in Cluster > Installation](/guides/cluster/installation)) *** ## Workloads [Section titled “Workloads”](#workloads) When you open the dashboard the first thing you’ll see is a list of all your Kubernetes workloads:   From here you can: * Click **View** next to any workload to open its log console in a new tab * Select multiple workloads using their checkboxes, then click **Open in Console** to view their logs merged into a single timeline *** ## Logs [Section titled “Logs”](#logs) Once you select the logs you want to view and click through to the console you’ll see a real-time tail of the logs:   The dashboard supports two log delivery pipelines: | Pipeline | Requires cluster install? | Features | | -------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------ | | [Kubernetes API (Basic)](/guides/dashboard/basic-features) | No | Real-time log tailing, basic filtering | | [Kubetail API (Advanced)](/guides/dashboard/advanced-features) | Yes | All basic features + log file sizes, last event timestamps, search | By default the dashboard uses the Kubernetes API pipeline. Installing the Kubetail API in your cluster enables the advanced pipeline automatically. Tip For a deeper look at how each pipeline works, see the [Architecture](/concepts/architecture#log-delivery-pipelines) page. *** ## Health status [Section titled “Health status”](#health-status) Click on the status dot in the lower-right corner to see the health of the dashboard’s backend server, your cluster’s Kubernetes API, and the optional Kubetail Cluster API:   # Introduction > Kubetail is a real-time Kubernetes logging dashboard. Tail logs from all containers in a workload in a single timeline, in your browser or terminal. **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 is the `kubetail` CLI tool, which can launch a local web dashboard on your desktop or stream raw logs directly to your terminal. By default, 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 logs to an external service. It also tracks container lifecycle events to keep your log timeline in sync as containers start, stop, or get replaced. This makes it easy to follow logs seamlessly as requests move from one ephemeral container to another across services. For more advanced features like log file sizes, last event timestamps, and search, you can install the **Kubetail API** into your cluster. It consists of an API server and a small cluster agent running on each node (see [Architecture](/concepts/architecture) for more details). The cluster agent is written in Rust and designed to be extremely performant (\~3MB memory, \~4.00m CPU). Kubetail also supports multiple deployment options — you can run the web dashboard in your cluster and expose it with an ingress, or run the CLI in a Docker container on your desktop or inside a cluster (see [Deployment Topologies](/concepts/architecture#deployment-topologies)). 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 (). Have fun tailing your logs! Tip If you need help or want to make a suggestion: * Send us an email at * Create a [GitHub Issue](https://github.com/kubetail-org/kubetail/issues) * Chat with us on [Discord](https://discord.gg/CmsmWAVkvX) * Join our [Slack](https://join.slack.com/t/kubetail/shared_invite/zt-2cq01cbm8-e1kbLT3EmcLPpHSeoFYm1w) * Send us a [tweet](https://x.com/kubetail) # Security and Privacy > Kubetail keeps log data in your possession from cluster to desktop. All access control is delegated to Kubernetes RBAC. Kubetail is designed to keep your log data in your possession from cluster to desktop and to ensure that cluster admins stay in control of who can access it. This page explains how Kubetail handles privacy and security by design. *** ## Log privacy [Section titled “Log privacy”](#log-privacy) Kubetail has no cloud logging backend so when you view logs, your data travels directly from your cluster to your device without going to an external service first. The path depends on the deployment topology: * **Desktop**: Logs flow from pod log files on disk, through the kube-apiserver (or Kubetail API, if installed), to the Dashboard server running on your local machine, and finally to your browser. The entire path is within your cluster and your desktop. * **Cluster**: Logs flow from pod log files on disk, through the kube-apiserver (or Kubetail API), to the Dashboard server running inside the cluster — all over the cluster-internal network. Logs reach your browser only after you connect via `kubectl port-forward`, `kubectl proxy`, or an ingress you control. In either case, you stay in posession of your log data from beginning to end (see [Architecture](/concepts/architecture) for more details). *** ## Access control [Section titled “Access control”](#access-control) Kubetail delegates all access control to Kubernetes RBAC, so your cluster admin retains full control over who can view which logs. ### Kubetail CLI [Section titled “Kubetail CLI”](#kubetail-cli) On the desktop, Kubetail inherits the RBAC permissions of the active kubeconfig context — the same permissions used by `kubectl`. If a user can run `kubectl logs` against a pod, they can view those logs in Kubetail as well. If they can’t, Kubetail will deny the request. Before opening any log stream, Kubetail checks permissions using the Kubernetes `SelfSubjectAccessReview` API. Cluster admins can scope access as narrowly as needed using standard Kubernetes RBAC resources. ### Kubetail API [Section titled “Kubetail API”](#kubetail-api) When the optional Kubetail API is installed in the cluster, every request from the Dashboard server to the Cluster API includes the user’s Kubernetes service account token. The Cluster API and Cluster Agent both validate that token against the Kubernetes authorization API before serving any data. This means access to logs through the Kubetail API is governed by the same RBAC policies that apply to any other Kubernetes API operation. No separate permission system is introduced. A user who lacks `get` and `watch` access to `pods/log` in a given namespace will receive no log data from that namespace, regardless of how they connect. *** ## Summary [Section titled “Summary”](#summary) | Property | Behavior | | -------------------------------- | --------------------------------- | | Log data leaves your environment | Never | | Cloud logging backend | No | | Access control mechanism | Kubernetes RBAC | | Auth method (desktop) | kubeconfig credentials | | Auth method (cluster) | Kubernetes service account tokens | # Configuration > Configure Kubetail's cluster components — Dashboard, Cluster API, and Cluster Agent — by overriding runtimeConfig values in the Helm chart. When Kubetail is deployed in a cluster, each component — the Dashboard, Cluster API, and Cluster Agent — is configured independently using a YAML config file mounted into the container. The Helm chart manages these files for you via ConfigMaps, but you can customize any setting by overriding the chart’s `runtimeConfig` fields. *** ## How configuration works [Section titled “How configuration works”](#how-configuration-works) Each component reads its config from a file passed via the `--config` flag at startup: ```sh dashboard --config /etc/kubetail/config.yaml cluster-api --config /etc/kubetail/config.yaml cluster-agent --config /etc/kubetail/config.yaml ``` The config file is mounted from a ConfigMap created by the Helm chart. To customize a component’s settings, pass your overrides under `kubetail..runtimeConfig` in your Helm values: ```yaml kubetail: dashboard: runtimeConfig: logging: level: debug clusterAPI: runtimeConfig: logging: level: debug ``` Tip All config files support environment variable expansion using `${VARIABLE_NAME}` syntax, which is useful for injecting secrets at runtime. *** ## Dashboard [Section titled “Dashboard”](#dashboard) The Dashboard is the web server that hosts the UI and proxies requests from the browser to the cluster. In the cluster environment it runs as a Deployment in the `kubetail` namespace. For the full configuration reference see the [Dashboard reference](/reference/dashboard). *** ## Cluster API [Section titled “Cluster API”](#cluster-api) The Cluster API is is the backend server that proxies requests from the Dashboard to the Cluster Agent instances running on each node. In the cluster it runs as a Deployment in the `kubetail` namespace. For the full configuration reference see the [Cluster API reference](/reference/cluster-api). *** ## Cluster Agent [Section titled “Cluster Agent”](#cluster-agent) The Cluster Agent is the small, Rust-based program that runs on each node and reads container log files directly from the node filesystem. In the cluster it runs as a DaemonSet in the `kubetail` namespace. For the full configuration reference see the [Cluster Agent reference](/reference/cluster-agent). # Ingress > Expose the Kubetail dashboard outside your cluster using a Kubernetes Ingress. Includes a Traefik example with HTTP Basic auth and TLS via cert-manager. After installing Kubetail in your cluster, the Dashboard is accessible via `kubectl port-forward` or `kubectl proxy` by default. If you want persistent, browser-friendly access without running a local proxy command, you can also expose it using a Kubernetes Ingress resource. *** ## Overview [Section titled “Overview”](#overview) The Helm chart includes built-in support for creating an Ingress resource for the Dashboard. It’s disabled by default but you can use your chart’s values to enable and configure it. The Dashboard service listens on port `8080` inside the cluster. Your Ingress controller needs to route traffic to that port. *** ## Enabling the Ingress [Section titled “Enabling the Ingress”](#enabling-the-ingress) To enable the Ingress, set `kubetail.dashboard.ingress.enabled` to `true` and configure at least one rule: ```yaml kubetail: dashboard: ingress: enabled: true name: kubetail annotations: traefik.ingress.kubernetes.io/router.middlewares: kubetail-kubetail-auth@kubernetescrd className: traefik rules: - host: kubetail.example.com http: paths: - path: / pathType: Prefix ``` Then, apply the values to your release: ```sh helm upgrade kubetail kubetail/kubetail \ --namespace kubetail \ --values values.yaml ``` *** ## TLS termination [Section titled “TLS termination”](#tls-termination) To enable HTTPS, add a `tls` block referencing a Secret that contains your certificate: ```yaml kubetail: dashboard: ingress: enabled: true className: nginx rules: - host: kubetail.example.com http: paths: - path: / pathType: Prefix backend: service: name: kubetail-dashboard port: number: 8080 tls: - hosts: - kubetail.example.com secretName: kubetail-tls ``` If you are using [cert-manager](https://cert-manager.io), you can automate certificate provisioning by adding the appropriate annotation to the Ingress: ```yaml kubetail: dashboard: ingress: annotations: cert-manager.io/cluster-issuer: letsencrypt-prod ``` Tip When you serve the Dashboard over HTTPS, set `session.cookie.secure: true` in the Dashboard’s `runtimeConfig` so the session cookie is only transmitted over secure connections. It’s also good practice to use a `__Host-` prefix for the cookie name. ```yaml kubetail: dashboard: runtimeConfig: session: cookie: name: __Host-session secure: true ``` Tip When you deploy the Dashboard behind a proxy, some requests may fail same-origin checks (e.g. if host ≠ origin) and get rejected (e.g. WebSocket connections). To fix this you can use the `allowedOrigins` option: ```yaml kubetail: dashboard: runtimeConfig: allowedOrigins: - https://kubetail.example.com ``` *** Note Only the Dashboard is exposed via Ingress. The Cluster API and Cluster Agent communicate over the cluster-internal network and do not need external exposure. # Installation > Install Kubetail inside your Kubernetes cluster using Helm or a YAML manifest, then access the dashboard via kubectl port-forward or kubectl proxy. To run Kubetail inside your Kubernetes cluster, you can install the application and its required resources using Helm or do it manually with YAML manifests. ## Helm [Section titled “Helm”](#helm) To install Kubetail using [helm](https://helm.sh), first add the Kubetail org’s chart repository, then install the “kubetail” chart: ```sh helm repo add kubetail https://kubetail-org.github.io/helm-charts/ helm install kubetail kubetail/kubetail --namespace kubetail --create-namespace ``` For more information on how to configure the helm chart see the chart’s [values.yaml](https://github.com/kubetail-org/helm-charts/blob/main/charts/kubetail/values.yaml) file. To verify that the installation worked, you can inspect the application’s pods: ```sh kubectl get pods -n kubetail ``` ## YAML Manifest [Section titled “YAML Manifest”](#yaml-manifest) For cluster-based authentication use [kubetail-clusterauth.yaml](https://github.com/kubetail-org/helm-charts/releases/latest/download/kubetail-clusterauth.yaml): ```sh kubectl apply -f https://github.com/kubetail-org/helm-charts/releases/latest/download/kubetail-clusterauth.yaml ``` For token-based authentication use [kubetail-tokenauth.yaml](https://github.com/kubetail-org/helm-charts/releases/latest/download/kubetail-clusterauth.yaml): ```sh kubectl apply -f https://github.com/kubetail-org/helm-charts/releases/latest/download/kubetail-tokenauth.yaml ``` To verify that the installation worked, you can inspect the application’s pods: ```sh kubectl get pods -n kubetail ``` ## Next Steps [Section titled “Next Steps”](#next-steps) Once Kubetail is running inside your cluster, you can access it using your usual access methods such as `kubectl port-forward`: * **`kubectl port-forward`** ```sh kubectl port-forward -n kubetail svc/kubetail-dashboard 8080:8080 ``` Visit To make the Kubetail web dashboard easier to access you can also expose it using an `Ingress` or `GatewayAPI` route (see [Ingress](/guides/cluster/ingress)). For more information about the Kubetail Dashboard, check out the documentation [here](/dashboard). Tip In addition to running Kubetail in your cluster you can also run it in these environments: * [Desktop](/guides/desktop/installation) * [Docker](/guides/docker/installation) # Monitoring > Monitor a Kubetail cluster deployment: health endpoints (/healthz), liveness and readiness probes, and structured JSON log output for each component. Kubetail exposes health check endpoints and structured log output on each component. This page describes how to monitor the health of Kubetail itself when it is deployed inside your cluster. *** ## Health checks [Section titled “Health checks”](#health-checks) Each component exposes a health endpoint that your cluster’s liveness and readiness probes use to determine pod health. ### Dashboard and Cluster API [Section titled “Dashboard and Cluster API”](#dashboard-and-cluster-api) Both the Dashboard and the Cluster API expose an HTTP health endpoint: ```plaintext GET /healthz ``` The Helm chart configures liveness and readiness probes against this endpoint automatically. You can use the same endpoint to check component status manually: ```sh kubectl exec -n kubetail deploy/kubetail-dashboard -- \ wget -qO- http://localhost:8080/healthz ``` ### Cluster Agent [Section titled “Cluster Agent”](#cluster-agent) The Cluster Agent exposes a standard [gRPC health](https://grpc.github.io/grpc/core/md_doc_health-checking.html) service on its gRPC port (`:50051`). The Helm chart uses `grpc_health_probe` inside the container to check readiness and liveness. *** ## Logging [Section titled “Logging”](#logging) All three components emit structured logs in JSON format by default. Each log entry includes a timestamp, log level, and contextual fields such as a `request_id` for tracing individual requests through the system. ### Log levels [Section titled “Log levels”](#log-levels) | Level | Description | | ---------- | ---------------------------------------------------------- | | `debug` | Verbose output, including internal request routing details | | `info` | Normal operational messages (default) | | `warn` | Recoverable issues that may need attention | | `error` | Failures that affect request handling | | `disabled` | No log output | ### Configuration [Section titled “Configuration”](#configuration) Log level and format are configured per component via `runtimeConfig` in your Helm values: ```yaml kubetail: dashboard: runtimeConfig: logging: level: info format: json # json or pretty access-log: enabled: true hide-health-checks: true # suppress /healthz from access logs clusterAPI: runtimeConfig: logging: level: info format: json access-log: enabled: true hide-health-checks: true clusterAgent: runtimeConfig: logging: level: info format: json ``` Tip Use `format: pretty` during development for human-readable log output. In production, `format: json` integrates better with log aggregation tools. ### Access logs [Section titled “Access logs”](#access-logs) The Dashboard and Cluster API include an HTTP access log that records each incoming request. Access log entries include the HTTP method, path, status code, duration, remote address, and request ID. You can suppress health check requests from the access log to reduce noise: ```yaml logging: access-log: enabled: true hide-health-checks: true ``` *** ## Checking pod readiness [Section titled “Checking pod readiness”](#checking-pod-readiness) To check the overall health of the Kubetail deployment: ```sh kubectl get pods -n kubetail ``` All pods should show `Running` status with readiness probes passing. If a pod is not ready, inspect its events and logs: ```sh kubectl describe pod -n kubetail kubectl logs -n kubetail ``` # RBAC & Permissions > The RBAC resources the Kubetail Helm chart creates — ServiceAccounts, ClusterRoles, and ClusterRoleBindings — and the permissions each component needs. Kubetail delegates access control to Kubernetes RBAC. This page explains what RBAC resources the Helm chart creates and how each component uses them. *** ## Overview [Section titled “Overview”](#overview) The Helm chart creates a dedicated ServiceAccount, ClusterRole, and ClusterRoleBinding for each component. Each component runs with only the permissions it needs to do its job — the principle of least privilege applies throughout. | Component | Kind | ServiceAccount | | ------------- | ---------- | ------------------------ | | Dashboard | Deployment | `kubetail-dashboard` | | Cluster API | Deployment | `kubetail-cluster-api` | | Cluster Agent | DaemonSet | `kubetail-cluster-agent` | *** ## Dashboard [Section titled “Dashboard”](#dashboard) The Dashboard needs broad read access to the Kubernetes API so it can enumerate workloads and stream logs on behalf of users. It also needs permission to create token reviews to validate user credentials. **ClusterRole** — cluster-wide read access: ```yaml rules: - apiGroups: [""] resources: [namespaces, nodes] verbs: [get, list, watch] - apiGroups: ["", apps, batch] resources: - cronjobs - daemonsets - deployments - jobs - pods - pods/log - replicasets - statefulsets verbs: [get, list, watch] - apiGroups: [authentication.k8s.io] resources: [tokenreviews] verbs: [create] ``` **Role** — namespace-scoped access within `kubetail`: ```yaml rules: - apiGroups: [discovery.k8s.io] resources: [endpointslices] verbs: [list, watch] ``` The `endpointslices` permission is used by the Dashboard to monitor the health of Cluster API pods in real time. *** ## Cluster API [Section titled “Cluster API”](#cluster-api) The Cluster API needs the same read access to workload resources as the Dashboard, because it also serves workload metadata through its GraphQL API. **ClusterRole** — cluster-wide read access: ```yaml rules: - apiGroups: [""] resources: [nodes] verbs: [get, list, watch] - apiGroups: ["", apps, batch] resources: - cronjobs - daemonsets - deployments - jobs - pods - pods/log - replicasets - statefulsets verbs: [get, list, watch] ``` **Role** — namespace-scoped access within `kubetail`: ```yaml rules: - apiGroups: [discovery.k8s.io] resources: [endpointslices] verbs: [list, watch] ``` The `endpointslices` permission allows the Cluster API to track which Cluster Agent pods are ready so it can route log requests to healthy agents. *** ## Cluster Agent [Section titled “Cluster Agent”](#cluster-agent) The Cluster Agent reads log files directly from the node filesystem and does not need Kubernetes API access to fetch logs. Its service account is used only so that requests from the Cluster API can be authorized — the agent validates the incoming bearer token against the Kubernetes API before serving any data. The Cluster Agent service account has no ClusterRole or Role by default. Authorization decisions are made by calling the Kubernetes `SubjectAccessReview` API using the token supplied by the caller, so the caller’s own RBAC permissions determine what they can access. *** ## How authorization works [Section titled “How authorization works”](#how-authorization-works) When a user opens a log view in the Dashboard, the following authorization flow occurs: 1. The Dashboard creates a short-lived Kubernetes service account token on behalf of the authenticated user. 2. The Dashboard forwards that token to the Cluster API in the `Authorization` header. 3. The Cluster API forwards the token to the relevant Cluster Agent(s). 4. Each Cluster Agent validates the token by calling the Kubernetes `SubjectAccessReview` API and checks whether the token holder has `get` permission on `pods/log` in the requested namespace. 5. If the check passes, the agent streams log data. If not, it returns a permission denied error. This means a user who cannot run `kubectl logs` against a pod cannot view those logs in Kubetail either, regardless of how they connect. No additional Kubetail-specific permissions are required. Tip To understand which permissions your users need, see the [Security and Privacy](/concepts/security-and-privacy) page. # Advanced Features > Advanced Kubetail dashboard features that require the Kubetail API: log file sizes, last event timestamps, and on-node grep-powered log search. Advanced features require installing the **Kubetail API** inside your cluster. Once the Kubetail API is installed, log requests are routed through a dedicated in-cluster service instead of the kube-apiserver, providing access to features that aren’t available in the Kubernetes API. *** ## Installing the Kubetail API [Section titled “Installing the Kubetail API”](#installing-the-kubetail-api) If you’re using the `kubetail` CLI tool, you can install the Kubetail API using the `kubetail cluster` command: ```sh kubetail cluster install ``` This installs the API using the Kubetail Helm chart so you can manage it with Helm independently afterwards if you want. See the [`cluster` command reference](/reference/cli#kubetail-cluster) for more details. You can also install the Kubetail API using Helm directly. See the [Cluster installation guide](/guides/cluster/installation) for instructions. *** ## Log file metadata [Section titled “Log file metadata”](#log-file-metadata) Once the Kubetail API is installed, the workload list will show log file sizes and last event timestamps:   This metadata is collected by the Cluster Agent directly from the log files on each node and surfaced through the Cluster API. It is not available through the Kubernetes API alone. *** ## Log search [Section titled “Log search”](#log-search) With the Kubetail API installed, a search input appears in the logging console header where you can enter a plain string or a `/regex/` pattern to filter the log stream. Matching happens on each node before any data is sent to the dashboard so only lines that match are transmitted, which keeps bandwidth low even against high-volume workloads.   Tip For a detailed explanation of the Kubetail API logging pipeline, see the [Architecture](/concepts/architecture#log-delivery-pipelines) page. # Basic Features > Kubetail dashboard features available with no extra installs: multi-cluster support, workload filters, real-time log tailing, and container-level log filtering. By default, Kubetail uses your **Kubernetes API** to watch your workloads and fetch log data. All of the features described here are available in the Kubetail web dashboard without any additional installs. *** ## Multiple clusters [Section titled “Multiple clusters”](#multiple-clusters) Kubetail reads your kubeconfig file to discover available clusters and uses the credentials defined there to authenticate against each one. When you have more than one context configured, a cluster picker appears in the top navigation bar so you can switch between them. Kubetail watches the kubeconfig file for changes and refreshes the list automatically, so newly added contexts appear without a restart.   *** ## Workload filters [Section titled “Workload filters”](#workload-filters) On the dashboard home page you can see all your workloads in real-time and narrow the view by namespace, workload type and search.   *** ## Real-time tail [Section titled “Real-time tail”](#real-time-tail) Selecting a workload opens the logging console, which starts tailing all of its container logs simultaneously. New log lines stream in as they are written and you can scroll up to see previous lines. You can also use the viewer controls to jump to the beginning of the stream, jump to a specific time or jump to the end to resume tailing.   *** ## Container lifecycle tracking [Section titled “Container lifecycle tracking”](#container-lifecycle-tracking) Kubetail watches Kubernetes pod events in real time. When a new pod or container starts — during a rolling update, a crash-restart, or a scale-out — its logs are added to the active stream automatically. When a pod is deleted its log source is removed from the stream. You do not need to reopen the console or manually refresh to see these changes. *** ## Log filters [Section titled “Log filters”](#log-filters) In the logging console you can filter logs by: * **Container** — show only specific containers by name. * **Node** — show only containers running on a particular node. * **Region / Zone** — filter by cloud region or availability zone (sourced from `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` node labels). * **OS / Arch** — filter by operating system or CPU architecture (sourced from `kubernetes.io/os` and `kubernetes.io/arch` node labels). Any combination of filters can be applied at once and removing all filters returns the full stream. # Authentication > Kubetail uses your local kubeconfig for auth, inheriting all standard credential types: client certs, bearer tokens, exec plugins, and OIDC providers. The `kubetail` CLI tool uses your local **kubeconfig** file to authenticate against your Kubernetes clusters. In-cluster permissions are handled by cluster RBAC. *** ## Kubeconfig [Section titled “Kubeconfig”](#kubeconfig) When you run a `kubetail` command that requires authentication (e.g. `kubetail serve`, `kubetail logs`), Kubetail reads your local kubeconfig file and uses the credentials defined there to connect to each cluster context. All standard kubeconfig credential types are supported: | Credential type | kubeconfig field(s) | | ------------------------ | ----------------------------------------------------------- | | Client certificate / key | `client-certificate`, `client-key` | | Bearer token | `token`, `tokenFile` | | Exec credential plugin | `exec` (e.g. `aws eks get-token`, `gke-gcloud-auth-plugin`) | | OIDC / auth-provider | `auth-provider` | Kubetail watches the kubeconfig file for changes and picks up new or updated contexts without a restart. Tip To use a different kubeconfig file you can: * Use the `--kubeconfig` CLI flag * Use the `general.kubeconfig` option in your local settings file * Use the standard `KUBECONFIG` env variable *** ## RBAC permissions [Section titled “RBAC permissions”](#rbac-permissions) `kubtail` uses the permissions of the kubeconfig user. At a minimum, it needs read access to the resources it monitors: | Resource | API group | Verbs | | ------------ | --------- | ---------------- | | cronjobs | batch | get, list, watch | | daemonsets | apps | get, list, watch | | deployments | apps | get, list, watch | | jobs | batch | get, list, watch | | namespaces | core | get, list, watch | | nodes | core | get, list, watch | | pods | core | get, list, watch | | pods/log | core | get, list, watch | | replicasets | apps | get, list, watch | | statefulsets | apps | get, list, watch | `kubetail` will automatically detect when a user only has access to a limited set of namespaces. # Configuration > Configure the Kubetail CLI with a YAML, JSON, or TOML file. Covers kubeconfig path, logs defaults (head, tail, columns), and serve host and port. The `kubetail` CLI tool can be configured using a local config file. If a config file is not found, Kubetail will use the defaults shown below. The file supports YAML, JSON, and TOML formats and values can reference environment variables using `${VARIABLE_NAME}` syntax. *** ## Initialization [Section titled “Initialization”](#initialization) The default config file path is `~/.kubetail/config.yaml`. You can initialize the config by placing a file in the default location or by using the CLI `config init` command to do it for you: ```sh kubetail config init ``` Tip The `config init` command accepts a `--format` flag to choose a different initialization format. See [CLI reference](/reference/cli#kubetail-config-init) for more details. *** ## Usage [Section titled “Usage”](#usage) Everytime you run a `kubetail` command, it will automatically look for a config file in the default location. You can specify a different path with the global `--config` flag: ```sh kubetail serve --config /path/to/config.yaml ``` Tip The order of precedence for settings is: 1. Defaults 2. Config file 3. CLI flags *** ## Defaults [Section titled “Defaults”](#defaults) * YAML ```yaml ## Kubetail CLI Configuration File # # This file defines the behavior for the kubetail CLI tool, # including logs command defaults and dashboard server settings. # ## version ## # # Schema version for the configuration file # version: 1 ## general ## # general: ## kubeconfig ## # # Path to the kubeconfig file to use for CLI requests. # If empty, the default path (~/.kube/config) or KUBECONFIG env var is used. # # Default value: "" # kubeconfig: "" ## commands ## # commands: ## logs ## # # Settings specific to the 'logs' subcommand # logs: ## kube-context ## # # The specific Kubernetes context to use. # If empty, the current active context is used. # # Default value: "" # kube-context: "" ## head ## # # The number of lines to show from the beginning of the log buffer # # Default value: 10 # head: 10 ## tail ## # # The number of lines to show from the end of the log buffer # # Default value: 10 # tail: 10 ## columns ## # # Full set of output columns for 'logs' records. # Allowed values: timestamp,dot,node,region,zone,os,arch,namespace,pod,container # # Default value: ["timestamp", "dot"] # columns: - timestamp - dot ## serve ## # # Settings for the dashboard server # serve: ## host ## # # The network interface the server should bind to. # # Default value: localhost # host: localhost ## port ## # # The TCP port the server will listen on. # # Default value: 7500 # port: 7500 ## skip-open ## # # If true, the CLI will not automatically open the browser # when the server starts. # # Default value: false # skip-open: false ## dashboard ## # # Settings for the web dashboard UI # dashboard: ## columns ## # # The default columns to show when displaying log records. # # Default value: ["timestamp", "dot"] # columns: - timestamp - dot ``` * TOML ```toml # Kubetail CLI Configuration File # # Defines behavior for the kubetail CLI tool, including # logs command defaults and dashboard server settings. # Schema version for the configuration file version = 1 [general] # Path to kubeconfig. If empty, uses ~/.kube/config or KUBECONFIG env var. kubeconfig = "" [commands.logs] # Specific Kubernetes context to use. If empty, uses active context. kube-context = "" # Number of lines to show from the beginning of the log buffer head = 10 # Number of lines to show from the end of the log buffer tail = 10 # Full set of output columns for 'logs' records. # Allowed values: timestamp,dot,node,region,zone,os,arch,namespace,pod,container columns = ["timestamp", "dot"] [commands.serve] # Network interface the server binds to host = "localhost" # TCP port the server listens on port = 7500 # If true, don't automatically open browser when server starts skip-open = false [dashboard] # The default columns to show when displaying log records. columns = ["timestamp", "dot"] ``` * JSON ```json { "version": 1, "general": { "kubeconfig": "" }, "commands": { "logs": { "kube-context": "", "head": 10, "tail": 10, "columns": ["timestamp", "dot"] }, "serve": { "host": "localhost", "port": 7500, "skip-open": false }, "dashboard": { "columns": ["timestamp", "dot"] } } } ``` Tip Environment variable expansion is supported. For example: ```yaml commands: serve: port: ${MY_KUBETAIL_PORT} ``` # Installation > Install the Kubetail CLI on macOS, Linux, or Windows via Homebrew, apt, winget, krew, snap, and more — or download the binary or use the install script. The `kubetail` CLI Tool is the primary entrypoint for Kubetail on your desktop. To install it, you can use your favorite package manager: * macOS **Homebrew** ```sh brew install kubetail ``` **Krew** ```sh kubectl krew install kubetail ``` **MacPorts** ```sh sudo port install kubetail ``` **Nix (Flake)** ```sh nix profile add github:kubetail-org/kubetail-nix ``` **Nix (Classic)** ```sh nix-env -i -f https://github.com/kubetail-org/kubetail-nix/archive/refs/heads/main.tar.gz ``` **asdf** ```sh asdf plugin add kubetail https://github.com/kubetail-org/asdf-kubetail.git asdf install kubetail latest ``` * Linux **Homebrew** ```sh brew install kubetail ``` **Krew** ```sh kubectl krew install kubetail ``` **Snap** ```sh sudo snap install kubetail ``` **Ubuntu/Mint (apt)** ```sh sudo add-apt-repository ppa:kubetail/kubetail sudo apt update && sudo apt install kubetail-cli ``` **Fedora/CentOS/RHEL/Amazonlinux/Mageia (copr)** ```sh dnf copr enable kubetail/kubetail dnf install kubetail ``` **SUSE (zypper)** ```sh zypper addrepo 'https://download.opensuse.org/repositories/home:/kubetail/$releasever/' kubetail zypper refresh && zypper install kubetail-cli ``` **Alpine (apk)** ```sh apk add kubetail --repository=https://dl-cdn.alpinelinux.org/alpine/edge/testing ``` **Arch (AUR)** ```sh yay -S --noconfirm kubetail-cli ``` **Gentoo (GURU)** ```sh ACCEPT_KEYWORDS="~$(portageq envvar ARCH)" emerge dev-util/kubetail ``` **Nix (Flake)** ```sh nix profile add github:kubetail-org/kubetail-nix ``` **Nix (Classic)** ```sh nix-env -i -f https://github.com/kubetail-org/kubetail-nix/archive/refs/heads/main.tar.gz ``` **asdf** ```sh asdf plugin add kubetail https://github.com/kubetail-org/asdf-kubetail.git asdf install kubetail latest ``` * Windows **Winget** ```sh winget install kubetail ``` **Krew** ```sh krew install kubetail ``` **Chocolatey** ```sh choco install kubetail ``` **Scoop** ```sh scoop install kubetail ``` *** 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: ```sh curl -sS https://www.kubetail.com/install.sh | bash ``` Tip In addition to running Kubetail on your desktop you can also run it in these environments: * [Cluster](/guides/cluster/installation) * [Docker](/guides/docker/installation) # Viewing Logs > View Kubernetes logs with Kubetail: launch the web dashboard with `kubetail serve` or stream logs directly to your terminal with `kubetail logs`. After [installing](/guides/desktop/installation) Kubetail you can start the web dashboard with `kubetail serve` or stream logs to your terminal with `kubetail logs`. *** ## Web Dashboard (GUI) [Section titled “Web Dashboard (GUI)”](#web-dashboard-gui) The web dashboard provides a browser-based interface for browsing and filtering logs across your Kubernetes workloads. Start it with `kubetail serve` and it will open automatically at [`http://localhost:7500`](http://localhost:7500). From the dashboard you can select workloads and pods, view their log output in real time, and switch between cluster contexts without leaving the browser. For a full walkthrough of the dashboard features, see the [Web Dashboard (GUI) guide](/concepts/gui-overview). *** ## Terminal [Section titled “Terminal”](#terminal)   The `kubetail logs` command lets you fetch and stream logs directly in your terminal. You can target individual pods, deployments, or any other workload type, and combine multiple sources from different namespaces in a single command: ```sh kubetail logs frontend:deployments/web backend:deployments/api ``` **Tailing** By default, `kubetail logs` returns the last 10 records. Use `--head` to read from the beginning, `--all` to return everything, or `--follow` to stream new records continuously: ```sh # Stream new records from a deployment kubetail logs deployments/web --follow # Return the first 50 records kubetail logs deployments/web --head=50 # Return all records and keep following kubetail logs deployments/web --all --follow ``` **Choosing columns** The output table includes `timestamp` and `dot` columns by default. You can customize what is shown using `--columns`, `--add-columns`, or `--remove-columns`. Available columns are: `timestamp`, `dot`, `node`, `region`, `zone`, `os`, `arch`, `namespace`, `pod`, `container`. ```sh # Add namespace and pod columns to the defaults kubetail logs deployments/web --add-columns pod,container # Show only raw log messages with no metadata kubetail logs deployments/web --raw ``` **Filtering by time window** Use `--since` and `--until` (inclusive) or `--after` and `--before` (exclusive) to scope logs to a specific time range. Both ISO 8601 timestamps and durations are accepted: ```sh # Records from the last 30 minutes kubetail logs deployments/web --since PT30M --all # Records between two timestamps kubetail logs deployments/web --since 2024-01-01T00:00:00Z --until 2024-01-02T00:00:00Z --all ``` **Filtering by source** Use `--node`, `--zone`, `--region`, `--os`, and `--arch` to restrict which pods contribute to the output. Each flag accepts a comma-separated list of values: ```sh # Only show logs from pods running on a specific node kubetail logs deployments/web --node=ip-10-0-1-42 # Only show logs from pods in a specific availability zone kubetail logs deployments/web --zone=us-east-1a # Combine filters kubetail logs deployments/web --region=us-east-1 --arch=amd64 ``` **Filtering by content** Use `--grep` with a regular expression to filter log lines: ```sh kubetail logs deployments/web --grep "ERROR" --force --all ``` Note: The `--force` flag is required when using `--grep` because filtering happens client-side so it could download more data than expected. **Container lifecycle tracking** Kubetail watches Kubernetes pod events in real time. When a new pod or container starts — during a rolling update, a crash-restart, or a scale-out — its logs are added to the active stream automatically. You do not need to restart your stream to see these changes. Tip For a complete list of flags and source syntax options, see the [`kubetail logs` CLI reference](/reference/cli#kubetail-logs). *** ## Advanced features [Section titled “Advanced features”](#advanced-features) To enable advanced features that aren’t available in the Kubernetes API (e.g. log file sizes, last event timestamps, search) you can install Kubetail’s in-cluster services to gain lower-level access to your log files on disk (known as the **Kubetail API**). The Kubetail API consists of a [Kubetail Cluster API](/reference/cluster-api) instance that runs as a Deployment and per-node [Kubetail Cluster Agent](/reference/cluster-agent) that runs as a DaemonSet. The cluster agent is a small, Rust-based program that reads container log files directly fom the node filesystem, then streams them to the API on demand. This is especially useful when grepping logs at scale because the agent can filter out lines before sending them to the client. You can manage the Kubetail API installation using the `kubetail cluster` command: ```sh # Install the Kubetail API into your cluster kubetail cluster install # Upgrade to the latest version kubetail cluster upgrade # Remove the Kubetail API from your cluster kubetail cluster uninstall ``` Once the Kubetail API is installed, Kubetail will automatically enable advanced features in the UI. Tip All `kubetail cluster` subcommands accept a `--kube-context` flag to target a specific cluster context. The `kubetail cluster` command uses Helm under the hood so you can customize the installation with Helm afterwards if you want. If you prefer to manage the installation with Helm directly, see the [Helm chart reference](/reference/helm-chart). # Docker Compose > Use docker compose with the kubetail-cli image to mount your kubeconfig and start the Kubetail dashboard server at localhost:7500. To use the CLI tool locally with `docker-compose` you can use this [docker-compose.yml](https://raw.githubusercontent.com/kubetail-org/kubetail/refs/heads/main/config/examples/docker-compose.yml) config file to get started: ```sh curl -LO https://raw.githubusercontent.com/kubetail-org/kubetail/refs/heads/main/config/examples/docker-compose.yml docker-compose up ``` This will mount your local `.kube/config` file into a `kubetail-cli` container and start the dashboard server at . Tip You can also the the `kubetail-cli` docker image with: * [Docker Run](/guides/docker/docker-run) * [Kubernetes Pod](/guides/docker/kubernetes-pod) # Docker Run > Use `docker run` with the kubetail-cli image to tail Kubernetes logs or open an interactive shell — mount your kubeconfig for cluster access. To use the CLI tool locally with `docker run` you need to mount your local `.kube/config` file into a `kubetail-cli` container: ```sh docker run --rm -it \ -v ~/.kube/config:/root/.kube/config:ro \ kubetail/kubetail-cli logs \ --kubeconfig /root/.kube/config \ -f \ deployments/my-app ``` You can also use the `sh` entrypoint to start an interactive session: ```sh docker run --rm -it \ -v ~/.kube/config:/root/.kube/config:ro \ --entrypoint sh \ kubetail/kubetail-cli ``` Tip You can also the the `kubetail-cli` docker image with: * [Docker Compose](/guides/docker/docker-compose) * [Kubernetes Pod](/guides/docker/kubernetes-pod) # Installation > Pull the kubetail-cli image from Docker Hub (kubetail/kubetail-cli) or GHCR to run the Kubetail CLI in a container without installing it locally. To run the Kubetail CLI tool (`kubetail`) inside a container you can use the [`kubetail-cli`](https://hub.docker.com/r/kubetail/kubetail-cli) docker image. The image is published to Docker Hub and the GitHub Container Registry on every release: | Registry | Image | | ---------- | ----------------------------------- | | Docker Hub | `kubetail/kubetail-cli` | | GHCR | `ghcr.io/kubetail-org/kubetail-cli` | Two variants are available: | Tag suffix | Base image | Description | | ---------- | ---------- | --------------------------------------- | | *(none)* | `scratch` | Minimal image, smallest footprint | | `-alpine` | `alpine` | Includes a shell and standard utilities | ## Docker Run [Section titled “Docker Run”](#docker-run) To use the CLI tool locally with `docker run` you need to mount your local `.kube/config` file into a `kubetail-cli` container: ```sh docker run --rm -it \ -v ~/.kube/config:/root/.kube/config:ro \ kubetail/kubetail-cli logs \ --kubeconfig /root/.kube/config \ -f \ deployments/my-app ``` You can also use the `sh` entrypoint to start an interactive session: ```sh docker run --rm -it \ -v ~/.kube/config:/root/.kube/config:ro \ --entrypoint sh \ kubetail/kubetail-cli ``` ## Docker Compose [Section titled “Docker Compose”](#docker-compose) To use the CLI tool locally with `docker-compose` you can use this [docker-compose.yml](https://raw.githubusercontent.com/kubetail-org/kubetail/refs/heads/main/config/examples/docker-compose.yml) config file to get started: ```sh curl -LO https://raw.githubusercontent.com/kubetail-org/kubetail/refs/heads/main/config/examples/docker-compose.yml docker-compose up ``` This will mount your local `.kube/config` file into a `kubetail-cli` container and start the dashboard server at . ## Kubernetes Pod [Section titled “Kubernetes Pod”](#kubernetes-pod) To use the CLI tool inside a cluster you can use this [`kubetail-cli-pod.yaml`](https://raw.githubusercontent.com/kubetail-org/kubetail/refs/heads/main/config/examples/kubetail-cli-pod.yaml) manifest file to get started: ```sh kubectl add -f https://raw.githubusercontent.com/kubetail-org/kubetail/refs/heads/main/config/examples/kubetail-cli-pod.yaml ``` This will start a `kubetail-cli` container inside the default namespace with access to pod logs in the same namespace. Once the pod is running you can `exec` into it and run CLI commands using the `--in-cluster` flag: ```sh kubectl exec -it kubetail-cli -- sh # ./kubetail logs --in-cluster -f deployments/my-app ``` # Introduction > Run the Kubetail CLI as a container using the kubetail-cli Docker image — locally with docker run or docker compose, or inside a cluster as a pod. To run the Kubetail CLI tool (`kubetail`) inside a container you can use the [`kubetail-cli`](https://hub.docker.com/r/kubetail/kubetail-cli) docker image. The image is published to Docker Hub and the GitHub Container Registry on every release: | Registry | Image | | ---------- | ----------------------------------- | | Docker Hub | `kubetail/kubetail-cli` | | GHCR | `ghcr.io/kubetail-org/kubetail-cli` | Two variants are available: | Tag suffix | Base image | Description | | ---------- | ---------- | --------------------------------------- | | *(none)* | `scratch` | Minimal image, smallest footprint | | `-alpine` | `alpine` | Includes a shell and standard utilities | Running `kubetail` inside docker lets you integrate Kubetail into your local docker development workflows and also allows you to debug your logs from inside your cluster. Tip Here are some common ways to run `kubetail` inside docker: * [Docker Run](/guides/docker/docker-run) * [Docker Compose](/guides/docker/docker-compose) * [Kubernetes Pod](/guides/docker/kubernetes-pod) # Kubernetes Pod > Deploy the Kubetail CLI as a Kubernetes pod using kubetail-cli-pod.yaml, then exec in and tail logs using the --in-cluster flag. To use the CLI tool inside a cluster you can use this [`kubetail-cli-pod.yaml`](https://raw.githubusercontent.com/kubetail-org/kubetail/refs/heads/main/config/examples/kubetail-cli-pod.yaml) manifest file to get started: ```sh kubectl add -f https://raw.githubusercontent.com/kubetail-org/kubetail/refs/heads/main/config/examples/kubetail-cli-pod.yaml ``` This will start a `kubetail-cli` container inside the default namespace with access to pod logs in the same namespace. Once the pod is running you can `exec` into it and run CLI commands using the `--in-cluster` flag: ```sh kubectl exec -it kubetail-cli -- sh # ./kubetail logs --in-cluster -f deployments/my-app ``` Tip You can also the the `kubetail-cli` docker image with: * [Docker Run](/guides/docker/docker-run) * [Docker Compose](/guides/docker/docker-compose) # Usage # Minikube > Install Kubetail as a built-in minikube addon (available since v1.36.0) with one command, then open the dashboard via minikube service. As of [minikube](https://minikube.sigs.k8s.io/docs/) v1.36.0, you can install Kubetail as an addon: ```sh minikube addons enable kubetail ``` Once the Kubetail pods are running in the cluster you can access it via a service: ```sh minikube service -n kubetail-system kubetail-dashboard ``` # CLI Reference > Kubetail CLI reference: serve, logs (sources, filters, time ranges), cluster (install/upgrade/uninstall/repo), config init, and configuration file format. The `kubetail` CLI is the primary entry point for Kubetail on your desktop. You can use it to start the web dashboard, stream logs to your terminal or manage Kubetail resources in your cluster. ## Global flags [Section titled “Global flags”](#global-flags) These flags are available on all commands: | Flag | Default | Description | | -------------- | ------------------------- | --------------------------------------- | | `--kubeconfig` | | Path to kubeconfig file | | `--in-cluster` | `false` | Use in-cluster Kubernetes configuration | | `-c, --config` | `~/.kubetail/config.yaml` | Path to config file | ## Commands [Section titled “Commands”](#commands) ### `kubetail serve` [Section titled “kubetail serve”](#kubetail-serve) Start the dashboard server and open the web UI in your default browser. ```sh kubetail serve [flags] ``` **Flags** | Flag | Default | Description | | ----------------- | ----------- | -------------------------------------------------------- | | `-p, --port` | `7500` | Port number to listen on | | `--host` | `localhost` | Host address to bind to | | `-l, --log-level` | `info` | Log level (`debug`, `info`, `warn`, `error`, `disabled`) | | `--skip-open` | `false` | Skip opening the browser | **Examples** ```sh # Start the dashboard (opens at http://localhost:7500) kubetail serve # Use a custom port kubetail serve --port 8080 # Start without opening the browser kubetail serve --skip-open ``` *** ### `kubetail logs` [Section titled “kubetail logs”](#kubetail-logs) Fetch logs for a container or a set of workload containers. ```sh kubetail logs [source1] [source2] ... [flags] ``` **Sources** A source identifies which pods/containers to stream logs from. Sources use the following syntax: ```plaintext [namespace:][/name[/container]] ``` | Example | Description | | ---------------------------- | ----------------------------------------------- | | `web-abc123` | Pod named `web-abc123` in the default namespace | | `deployments/web` | `web` deployment in the default namespace | | `deployments/*` | All deployments in the default namespace | | `deployments/web/container1` | Specific container in a deployment | | `deployments/web/*` | All containers in a deployment | | `frontend:web-abc123` | Pod in the `frontend` namespace | | `frontend:deployments/web` | Deployment in the `frontend` namespace | Multiple sources can be specified: ```sh kubetail logs ``` **Flags** | Flag | Default | Description | | ------------------ | ------- | ----------------------------------------------------------- | | `--kube-context` | | Kubeconfig context to use | | `-h, --head[=N]` | `10` | Return the first N records | | `-t, --tail[=N]` | `10` | Return the last N records | | `--all` | `false` | Return all records | | `-f, --follow` | `false` | Stream new records | | `--since` | | Include records from the specified point (inclusive) | | `--until` | | Include records up to the specified point (inclusive) | | `--after` | | Include records strictly after the specified point | | `--before` | | Include records strictly before the specified point | | `-g, --grep` | | Filter records by a regular expression (requires `--force`) | | `--region` | | Filter source pods by region (comma-separated) | | `--zone` | | Filter source pods by zone (comma-separated) | | `--os` | | Filter source pods by operating system (comma-separated) | | `--arch` | | Filter source pods by CPU architecture (comma-separated) | | `--node` | | Filter source pods by node name (comma-separated) | | `--raw` | `false` | Output only raw log messages without metadata | | `--columns` | | Set output columns (overrides defaults) | | `--add-columns` | | Add output columns to the defaults | | `--remove-columns` | | Remove output columns from the defaults | | `--with-cursors` | `false` | Show paging cursors | | `--hide-header` | `false` | Hide table header | | `--all-containers` | `false` | Show logs from all containers in a pod | | `--force` | `false` | Force command (required when using `--grep`) | The `--columns`, `--add-columns`, and `--remove-columns` flags accept a comma-separated list of column names: `timestamp`, `dot`, `node`, `region`, `zone`, `os`, `arch`, `namespace`, `pod`, `container`. The `--head`, `--tail`, and `--all` flags are mutually exclusive. The `--since` and `--after` flags are mutually exclusive, as are `--until` and `--before`. The `--since`, `--until`, `--after`, and `--before` flags accept: * An ISO 8601 timestamp (e.g. `2006-01-02T15:04:05Z07:00`) * An ISO 8601 duration relative to now (e.g. `PT30M` for 30 minutes ago) — only for `--since` and `--until` **Default behavior**: tail mode (last 10 records) unless `--since` is specified, in which case head mode is used. **Examples** ```sh # Tail the last 10 records from a pod kubetail logs nginx # Tail a deployment kubetail logs deployments/web # Follow new records kubetail logs deployments/web --follow # Return all records and follow kubetail logs deployments/web --all --follow # Return first 100 records kubetail logs nginx --head=100 # Return records from the last 30 minutes kubetail logs nginx --since PT30M --all # Return records between two timestamps kubetail logs nginx --since 2006-01-02T15:04:05Z --until 2007-01-02T15:04:05Z --all # Filter by regex (requires --force) kubetail logs nginx --grep "GET /about" --force # Filter pods by region kubetail logs deployments/web --region=us-east-1 # Output raw log messages only kubetail logs nginx --raw ``` *** ### `kubetail cluster` [Section titled “kubetail cluster”](#kubetail-cluster) Manage Kubetail cluster resources using Helm under the hood (Helm does not need to be installed separately). ```sh kubetail cluster [flags] ``` #### `kubetail cluster install` [Section titled “kubetail cluster install”](#kubetail-cluster-install) Create a new Kubetail release in the cluster. ```sh kubetail cluster install [flags] ``` **Flags** | Flag | Default | Description | | ---------------- | ------- | ------------------------------------- | | `--kube-context` | | Name of the kubeconfig context to use | **Examples** ```sh kubetail cluster install ``` #### `kubetail cluster upgrade` [Section titled “kubetail cluster upgrade”](#kubetail-cluster-upgrade) Upgrade an existing Kubetail release to the latest chart version available locally. ```sh kubetail cluster upgrade [flags] ``` **Flags** | Flag | Default | Description | | ---------------- | ------- | ------------------------------------- | | `--kube-context` | | Name of the kubeconfig context to use | **Examples** ```sh kubetail cluster upgrade ``` #### `kubetail cluster uninstall` [Section titled “kubetail cluster uninstall”](#kubetail-cluster-uninstall) Remove an existing Kubetail release from the cluster. ```sh kubetail cluster uninstall [flags] ``` **Flags** | Flag | Default | Description | | ---------------- | ------- | ------------------------------------- | | `--kube-context` | | Name of the kubeconfig context to use | **Examples** ```sh kubetail cluster uninstall ``` #### `kubetail cluster list` [Section titled “kubetail cluster list”](#kubetail-cluster-list) List currently installed Kubetail releases. ```sh kubetail cluster list [flags] ``` **Flags** | Flag | Default | Description | | ---------------- | ------- | ------------------------------------- | | `--kube-context` | | Name of the kubeconfig context to use | **Examples** ```sh kubetail cluster list ``` #### `kubetail cluster repo` [Section titled “kubetail cluster repo”](#kubetail-cluster-repo) Manage Kubetail’s Helm chart repository (`https://kubetail-org.github.io/helm-charts/`). ```sh kubetail cluster repo ``` | Subcommand | Description | | ---------- | ---------------------------------------------- | | `add` | Add the Kubetail chart repository to Helm | | `update` | Update the Kubetail chart repository in Helm | | `remove` | Remove the Kubetail chart repository from Helm | **Examples** ```sh kubetail cluster repo add kubetail cluster repo update kubetail cluster repo remove ``` *** ### `kubetail config` [Section titled “kubetail config”](#kubetail-config) Manage the Kubetail CLI configuration. ```sh kubetail config ``` #### `kubetail config init` [Section titled “kubetail config init”](#kubetail-config-init) Create a default configuration file. ```sh kubetail config init [flags] ``` **Flags** | Flag | Default | Description | | ---------- | ------------------------- | -------------------------------------------------- | | `--path` | `~/.kubetail/config.yaml` | Target path for the configuration file | | `--format` | `yaml` | Configuration file format (`yaml`, `json`, `toml`) | | `--force` | `false` | Overwrite an existing configuration file | **Examples** ```sh # Create default config at ~/.kubetail/config.yaml kubetail config init # Create config in JSON format kubetail config init --format json # Overwrite an existing config file kubetail config init --force # Write config to a custom path kubetail config init --path /etc/kubetail/config.yaml ``` ## Configuration [Section titled “Configuration”](#configuration) The CLI can be configured using a YAML (or JSON/TOML) config file. By default it is read from `~/.kubetail/config.yaml`. Use `kubetail config init` to generate a default config file, or pass a custom path with the `-c` / `--config` global flag. * YAML ```yaml ## Kubetail CLI Configuration File # # This file defines the behavior for the kubetail CLI tool, # including logs command defaults and dashboard server settings. # ## version ## # # Schema version for the configuration file # version: 1 ## general ## # general: ## kubeconfig ## # # Path to the kubeconfig file to use for CLI requests. # If empty, the default path (~/.kube/config) or KUBECONFIG env var is used. # # Default value: "" # kubeconfig: "" ## commands ## # commands: ## logs ## # # Settings specific to the 'logs' subcommand # logs: ## kube-context ## # # The specific Kubernetes context to use. # If empty, the current active context is used. # # Default value: "" # kube-context: "" ## head ## # # The number of lines to show from the beginning of the log buffer # # Default value: 10 # head: 10 ## tail ## # # The number of lines to show from the end of the log buffer # # Default value: 10 # tail: 10 ## columns ## # # Full set of output columns for 'logs' records. # Allowed values: timestamp,dot,node,region,zone,os,arch,namespace,pod, container # # Default value: ["timestamp", "dot"] # columns: - timestamp - dot ## serve ## # # Settings for the dashboard server # serve: ## host ## # # The network interface the server should bind to. # # Default value: localhost # host: localhost ## port ## # # The TCP port the server will listen on. # # Default value: 7500 # port: 7500 ## skip-open ## # # If true, the CLI will not automatically open the browser # when the server starts. # # Default value: false # skip-open: false ## dashboard ## # # Settings for the web dashboard UI # dashboard: ## columns ## # # The default columns to show when displaying log records. # # Default value: ["timestamp", "dot"] # columns: - timestamp - dot ``` * TOML ```toml # Kubetail CLI Configuration File # # Defines behavior for the kubetail CLI tool, including # logs command defaults and dashboard server settings. # Schema version for the configuration file version = 1 [general] # Path to kubeconfig. If empty, uses ~/.kube/config or KUBECONFIG env var. kubeconfig = "" [commands.logs] # Specific Kubernetes context to use. If empty, uses active context. kube-context = "" # Number of lines to show from the beginning of the log buffer head = 10 # Number of lines to show from the end of the log buffer tail = 10 # Full set of output columns for 'logs' records. # Allowed values: timestamp,dot,node,region,zone,os,arch,namespace,pod,container columns = ["timestamp", "dot"] [commands.serve] # Network interface the server binds to host = "localhost" # TCP port the server listens on port = 7500 # If true, don't automatically open browser when server starts skip-open = false [dashboard] # The default columns to show when displaying log records. columns = ["timestamp", "dot"] ``` * JSON ```json { "version": 1, "general": { "kubeconfig": "" }, "commands": { "logs": { "kube-context": "", "head": 10, "tail": 10, "columns": ["timestamp", "dot"] }, "serve": { "host": "localhost", "port": 7500, "skip-open": false } }, "dashboard": { "columns": ["timestamp", "dot"] } } ``` # Cluster Agent Reference > Kubetail Cluster Agent reference: Docker image variants, startup flags, and YAML configuration for the Rust-based gRPC server running on each cluster node. The Kubetail Cluster Agent is a Rust-based gRPC server that runs as a DaemonSet on each node in your Kubernetes cluster. It reads container log files directly from the node filesystem and streams them to the Cluster API on demand. The server executable is compiled from the source code located in the Kubetail repo at [crates/cluster\_agent](https://github.com/kubetail-org/kubetail/tree/main/crates/cluster_agent) and is typically deployed using the `kubetail-cluster-agent` docker image (see below). It’s possible to run `kubetail-cluster-agent` as a standalone container but we recommend deploying it with the official Kubetail [helm chart](/reference/helm-chart). ## Docker image [Section titled “Docker image”](#docker-image) The `kubetail-cluster-agent` docker image is published to Docker Hub and the GitHub Container Registry on every release: | Registry | Image | | ---------- | --------------------------------------------- | | Docker Hub | `kubetail/kubetail-cluster-agent` | | GHCR | `ghcr.io/kubetail-org/kubetail-cluster-agent` | Two variants are available: | Tag suffix | Base image | Description | | ---------- | ---------- | --------------------------------------- | | *(none)* | `scratch` | Minimal image, smallest footprint | | `-alpine` | `alpine` | Includes a shell and standard utilities | ## Entrypoint [Section titled “Entrypoint”](#entrypoint) The default container entrypoint is `/cluster-agent/cluster-agent`: ```sh cluster-agent --config [flags] ``` ## Flags [Section titled “Flags”](#flags) | Flag | Short | Default | Description | | ---------- | ----- | ------- | ---------------------------------------------------- | | `--config` | `-c` | | Path to configuration file (**required**) | | `--addr` | `-a` | | Address to listen for connections (overrides config) | ## Configuration [Section titled “Configuration”](#configuration) The Cluster Agent is configured exclusively via a config file. The path must be passed with `-c` / `--config` on every invocation. Environment variables can be referenced in the config file using standard shell syntax. ```sh cluster-agent --config /etc/kubetail/cluster-agent.yaml ``` * YAML ```yaml ## Kubetail Cluster Agent Configuration File # # This file defines the behavior for the kubetail cluster agent, # which runs in Kubernetes clusters to stream and process container logs. # ## addr ## # # The network address and port the gRPC server should bind to. # # Default value: :50051 # addr: :50051 ## container-logs-dir ## # # The directory path where Kubernetes stores container log files. # This is typically a mount from the host node's filesystem. # # Default value: /var/log/containers # container-logs-dir: /var/log/containers ## logging ## # # Configuration for the agent's logging output # logging: ## enabled ## # # Whether logging is enabled for the agent. # # Default value: true # enabled: true ## level ## # # The minimum log level to output. # Valid values: debug, info, warn, error # # Default value: info # level: info ## format ## # # The format of log output. # Valid values: json, pretty # # Default value: json # format: json ## tls ## # # TLS configuration for secure gRPC connections # tls: ## enabled ## # # Whether TLS is enabled for gRPC connections. # # Default value: false # enabled: false ## cert-file ## # # Path to the TLS certificate file. # # Default value: "" # cert-file: "" ## key-file ## # # Path to the TLS private key file. # # Default value: "" # key-file: "" ## ca-file ## # # Path to the CA certificate file used to verify client certificates. # Required when client-auth is set to require-and-verify. # # Default value: "" # ca-file: "" ## client-auth ## # # The client authentication policy for incoming gRPC connections. # Valid values: none, require-and-verify # # Default value: none # client-auth: none ``` # Cluster API Reference > Kubetail Cluster API reference: Docker image variants, startup flags, and YAML configuration for TLS, logging, CSRF, and cluster-agent connections. The Kubetail Cluster API is a Go-based HTTP server that provides the GraphQL API used by the Dashboard to perform cluster operations. The server executable is compiled from the source code located in the Kubetail repo at [modules/cluster-api](https://github.com/kubetail-org/kubetail/tree/main/modules/cluster-api) and is typically deployed using the `kubetail-cluster-api` docker image (see below). It’s possible to run `kubetail-cluster-api` as a standalone container but we recommend deploying it with the official Kubetail [helm chart](/reference/helm-chart). ## Docker image [Section titled “Docker image”](#docker-image) The `kubetail-cluster-api` docker image is published to Docker Hub and the GitHub Container Registry on every release: | Registry | Image | | ---------- | ------------------------------------------- | | Docker Hub | `kubetail/kubetail-cluster-api` | | GHCR | `ghcr.io/kubetail-org/kubetail-cluster-api` | Two variants are available: | Tag suffix | Base image | Description | | ---------- | ---------- | --------------------------------------- | | *(none)* | `scratch` | Minimal image, smallest footprint | | `-alpine` | `alpine` | Includes a shell and standard utilities | ## Entrypoint [Section titled “Entrypoint”](#entrypoint) The default container entrypoint is `/cluster-api/cluster-api`: ```sh cluster-api [flags] ``` ## Flags [Section titled “Flags”](#flags) | Flag | Short | Default | Description | | ------------ | ----- | --------- | ------------------------------------------------------------------ | | `--config` | `-c` | | Path to configuration file (e.g. `/etc/kubetail/cluster-api.yaml`) | | `--addr` | `-a` | `:8080` | Host address to bind to | | `--gin-mode` | | `release` | Gin framework mode (`release`, `debug`) | ## Configuration [Section titled “Configuration”](#configuration) The Cluster API can be configured using a YAML, JSON, or TOML config file. Pass the path to the file with `-c` / `--config`. Environment variables can be referenced in the config file using `${VARIABLE_NAME}` syntax. ```sh cluster-api --config /etc/kubetail/cluster-api.yaml ``` * YAML ```yaml ## Kubetail Cluster API Configuration File # # This file defines the behavior for the kubetail cluster API server, # which provides the GraphQL API for cluster operations. # ## allowed-namespaces ## # # List of namespaces the API is allowed to access. # If empty, all namespaces are accessible. # # Default value: [] # allowed-namespaces: [] ## addr ## # # The network address and port the HTTP server should bind to. # # Default value: :8080 # addr: ":8080" ## base-path ## # # The base URL path for all API endpoints. # # Default value: / # base-path: / ## gin-mode ## # # The Gin framework mode. # Valid values: debug, release # # Default value: release # gin-mode: release ## cluster-agent ## # # Configuration for connecting to the cluster agent # cluster-agent: ## dispatch-url ## # # The URL used to connect to the cluster agent. # Supports kubernetes:// scheme for in-cluster service discovery. # # Default value: kubernetes://kubetail-cluster-agent:50051 # dispatch-url: kubernetes://kubetail-cluster-agent:50051 ## tls ## # # TLS configuration for cluster agent connections # tls: ## enabled ## # # Whether TLS is enabled for cluster agent connections. # # Default value: false # enabled: false ## cert-file ## # # Path to the TLS certificate file. # # Default value: "" # cert-file: "" ## key-file ## # # Path to the TLS private key file. # # Default value: "" # key-file: "" ## ca-file ## # # Path to the CA certificate file used to verify the cluster agent's certificate. # # Default value: "" # ca-file: "" ## server-name ## # # The server name used for TLS verification. # If empty, the hostname from dispatch-url is used. # # Default value: "" # server-name: "" ## logging ## # # Configuration for the API server's logging output # logging: ## enabled ## # # Whether logging is enabled for the server. # # Default value: true # enabled: true ## level ## # # The minimum log level to output. # Valid values: debug, info, warn, error, disabled # # Default value: info # level: info ## format ## # # The format of log output. # Valid values: json, pretty # # Default value: json # format: json ## access-log ## # # Configuration for HTTP access logging # access-log: ## enabled ## # # Whether access logging is enabled. # # Default value: true # enabled: true ## hide-health-checks ## # # Whether to omit health check requests (/healthz) from the access log. # # Default value: false # hide-health-checks: false ## tls ## # # TLS configuration for the HTTP server # tls: ## enabled ## # # Whether TLS is enabled. # # Default value: false # enabled: false ## cert-file ## # # Path to the TLS certificate file. # # Default value: "" # cert-file: "" ## key-file ## # # Path to the TLS private key file. # # Default value: "" # key-file: "" ``` # Dashboard Reference > Kubetail Dashboard server reference: Docker image variants, startup flags, and YAML options for auth, sessions, TLS, CSRF, and the Cluster API connection. The Kubetail Dashboard is a Go-based HTTP server that hosts the Dashboard web UI and provides the backend API that the web UI uses to interact with your Kubernetes clusters. The server executable is compiled from the source code located in the Kubetail repo at [modules/dashboard](https://github.com/kubetail-org/kubetail/tree/main/modules/dashboard) and is typically deployed using the `kubetail-dashboard` docker image (see below). It’s possible to run `kubetail-dashboard` as a standalone container but we recommend deploying it with the official Kubetail [helm chart](/reference/helm-chart). ## Docker image [Section titled “Docker image”](#docker-image) The `kubetail-dashboard` docker image is published to Docker Hub and the GitHub Container Registry on every release: | Registry | Image | | ---------- | ----------------------------------------- | | Docker Hub | `kubetail/kubetail-dashboard` | | GHCR | `ghcr.io/kubetail-org/kubetail-dashboard` | Two variants are available: | Tag suffix | Base image | Description | | ---------- | ---------- | --------------------------------------- | | *(none)* | `scratch` | Minimal image, smallest footprint | | `-alpine` | `alpine` | Includes a shell and standard utilities | ## Entrypoint [Section titled “Entrypoint”](#entrypoint) The default container entrypoint is `/dashboard/dashboard`: ```sh dashboard [flags] ``` ## Flags [Section titled “Flags”](#flags) | Flag | Short | Default | Description | | ------------ | ----- | --------- | ---------------------------------------------------------------- | | `--config` | `-c` | | Path to configuration file (e.g. `/etc/kubetail/dashboard.yaml`) | | `--addr` | `-a` | `:8080` | Host address to bind to | | `--gin-mode` | | `release` | Gin framework mode (`release`, `debug`) | ## Configuration [Section titled “Configuration”](#configuration) The dashboard can be configured using a YAML, JSON, or TOML config file. Pass the path to the file with `-c` / `--config`. Environment variables can be referenced in the config file using `${VARIABLE_NAME}` syntax. ```sh dashboard --config /etc/kubetail/dashboard.yaml ``` * YAML ```yaml ## Kubetail Dashboard Configuration File # # This file defines the behavior for the kubetail dashboard server, # which serves the web UI and provides the backend API for the dashboard. # ## allowed-namespaces ## # # List of namespaces the dashboard is allowed to access. # If empty, all namespaces are accessible. # # Default value: [] # allowed-namespaces: [] ## allowed-origins ## # # Additional origins (in addition to same-origin) accepted on WebSocket # upgrade requests. Each entry must be a fully-qualified origin — # scheme://host[:port] with no path. Comparison is case-insensitive on # host and normalizes default ports (so https://example.com matches # https://example.com:443). # # Use this when running the dashboard behind a reverse proxy that # rewrites Host or terminates TLS without preserving scheme — direct # same-origin matching against r.Host/r.TLS would otherwise reject # legitimate browser requests. List the public-facing origin(s) the # dashboard is served at. # # Examples: # - https://kubetail.example.com # - https://kubetail.example.com:8443 # # Default value: [] # allowed-origins: [] ## kubeconfig ## # # Path to the kubeconfig file to use for Kubernetes API requests. # If empty, the default path (~/.kube/config) or KUBECONFIG env var is used. # # Default value: "" # kubeconfig: "" ## addr ## # # The network address and port the HTTP server should bind to. # # Default value: :8080 # addr: ":8080" ## auth-mode ## # # The authentication mode for the dashboard. # Valid values: auto, token # # Default value: auto # auth-mode: auto ## base-path ## # # The base URL path for all dashboard endpoints. # # Default value: / # base-path: / ## cluster-api-endpoint ## # # The URL of the Cluster API server. # If empty, the Cluster API integration is disabled. # # Default value: "" # cluster-api-endpoint: "" ## environment ## # # The environment the dashboard is running in. # Valid values: desktop, cluster # # Default value: cluster # environment: cluster ## gin-mode ## # # The Gin framework mode. # Valid values: debug, release # # Default value: release # gin-mode: release ## logging ## # # Configuration for the dashboard server's logging output # logging: ## enabled ## # # Whether logging is enabled for the server. # # Default value: true # enabled: true ## level ## # # The minimum log level to output. # Valid values: debug, info, warn, error, disabled # # Default value: info # level: info ## format ## # # The format of log output. # Valid values: json, pretty # # Default value: json # format: json ## access-log ## # # Configuration for HTTP access logging # access-log: ## enabled ## # # Whether access logging is enabled. # # Default value: true # enabled: true ## hide-health-checks ## # # Whether to omit health check requests (/healthz) from the access log. # # Default value: false # hide-health-checks: false ## session ## # # Session management settings # session: ## key-pairs ## # # One or more signing/encryption key pairs for session cookies. The first # pair is used for new cookies; additional pairs are accepted for reading # only, enabling zero-downtime key rotation. # # Each pair has: # signing-key (required) — hex-encoded HMAC signing key; 32 or 64 raw bytes recommended # encryption-key (optional) — hex-encoded AES encryption key; 16, 24, or 32 raw bytes # # When empty and a local-storage-dir is configured, a random pair is # generated and persisted to disk on first startup. # key-pairs: [] ## cookie ## # # Session cookie configuration # cookie: ## name ## # # The name of the session cookie. # # Default value: kubetail_dashboard_session # name: kubetail_dashboard_session ## path ## # # The URL path for which the cookie is valid. # # Default value: / # path: / ## domain ## # # The domain for which the cookie is valid. # If empty, the cookie is valid for the current domain only. # # Default value: "" # domain: "" ## max-age ## # # The maximum age of the cookie in seconds. # # Default value: 2592000 (30 days) # max-age: 2592000 ## secure ## # # Whether the cookie should only be sent over HTTPS. # # Default value: false # secure: false ## http-only ## # # Whether the cookie is inaccessible to JavaScript. # # Default value: true # http-only: true ## same-site ## # # The SameSite attribute for the cookie. # Valid values: strict, lax, none # # Default value: lax # same-site: lax ## tls ## # # TLS configuration for the HTTP server # tls: ## enabled ## # # Whether TLS is enabled. # # Default value: false # enabled: false ## cert-file ## # # Path to the TLS certificate file. # # Default value: "" # cert-file: "" ## key-file ## # # Path to the TLS private key file. # # Default value: "" # key-file: "" ## ui ## # # UI-specific configuration options # ui: ## cluster-api-enabled ## # # Whether the Cluster API integration is enabled in the UI. # # Default value: true # cluster-api-enabled: true ``` # Helm Chart Reference > Kubetail Helm chart reference: deploy the full Kubetail stack into Kubernetes, configure components via runtimeConfig, and manage upgrades and uninstalls. The Kubetail Helm chart deploys the full Kubetail stack into a Kubernetes cluster. It is published our helm chart repository located at and the source code is located in the [kubetail-org/helm-charts](https://github.com/kubetail-org/helm-charts) repo under `charts/kubetail`. The chart deploys three components: | Component | Kind | Description | | ------------- | ---------- | --------------------------------------------- | | Dashboard | Deployment | Web UI and backend API | | Cluster API | Deployment | GraphQL API for cluster operations | | Cluster Agent | DaemonSet | Per-node agent that reads container log files | ## Install [Section titled “Install”](#install) Add the `kubetail` Helm repository: ```sh helm repo add kubetail https://kubetail-org.github.io/helm-charts/ ``` Install the chart into a dedicated namespace: ```sh helm install kubetail kubetail/kubetail --namespace kubetail --create-namespace ``` By default, the chart autogenerates the dashboard session signing and encryption keys (`KUBETAIL_DASHBOARD_SESSION_SIGNING_KEY1` and `KUBETAIL_DASHBOARD_SESSION_ENCRYPTION_KEY1`) and stores them in a Kubernetes Secret so they are preserved across upgrades. ## Upgrade [Section titled “Upgrade”](#upgrade) Pull the latest chart index, then upgrade the release: ```sh helm repo update kubetail helm upgrade kubetail kubetail/kubetail --namespace kubetail ``` ## Uninstall [Section titled “Uninstall”](#uninstall) ```sh helm uninstall kubetail --namespace kubetail ``` ## Values [Section titled “Values”](#values) ### Chart [Section titled “Chart”](#chart) | Parameter | Type | Default | Description | | ------------------- | ------ | ------- | -------------------------------------- | | `fullnameOverride` | string | `null` | Override the chart’s computed fullname | | `nameOverride` | string | `null` | Override the chart’s name | | `namespaceOverride` | string | `null` | Override the release’s namespace | ### General [Section titled “General”](#general) | Parameter | Type | Default | Description | | ------------------------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------- | | `kubetail.allowedNamespaces` | array | `[]` | Restrict all components to these namespaces | | `kubetail.secrets.KUBETAIL_DASHBOARD_SESSION_SIGNING_KEY1` | string | `null` | Hex-encoded dashboard session signing key (autogenerated if null) | | `kubetail.secrets.KUBETAIL_DASHBOARD_SESSION_ENCRYPTION_KEY1` | string | `null` | Hex-encoded dashboard session encryption key (autogenerated if null) | | `kubetail.secrets.KUBETAIL_DASHBOARD_SESSION_SIGNING_KEY2` | string | `null` | Hex-encoded previous-slot signing key for rotation (no autogeneration) | | `kubetail.secrets.KUBETAIL_DASHBOARD_SESSION_ENCRYPTION_KEY2` | string | `null` | Hex-encoded previous-slot encryption key for rotation (no autogeneration) | | `kubetail.global.annotations` | map | `{}` | Extra annotations added to all resources | | `kubetail.global.labels` | map | `{}` | Extra labels added to all resources | ### Dashboard [Section titled “Dashboard”](#dashboard) | Parameter | Type | Default | Description | | ---------------------------------------------------- | ------ | ----------------------------------- | --------------------------------------------------------------------------------- | | `kubetail.dashboard.enabled` | bool | `true` | Enable or disable the Dashboard component | | `kubetail.dashboard.authMode` | string | `"auto"` | Auth mode (`auto`, `token`) | | `kubetail.dashboard.runtimeConfig` | map | *see values.yaml* | Dashboard runtime configuration (see [Dashboard reference](/reference/dashboard)) | | `kubetail.dashboard.image.registry` | string | `"ghcr.io"` | Image registry | | `kubetail.dashboard.image.repository` | string | `"kubetail-org/kubetail-dashboard"` | Image repository | | `kubetail.dashboard.image.tag` | string | *see values.yaml* | Image tag | | `kubetail.dashboard.image.digest` | string | `null` | Override image tag with a digest | | `kubetail.dashboard.image.pullPolicy` | string | `"IfNotPresent"` | Image pull policy | | `kubetail.dashboard.container.name` | string | `"kubetail-dashboard"` | Container name | | `kubetail.dashboard.container.extraEnv` | array | `[]` | Additional environment variables | | `kubetail.dashboard.container.extraEnvFrom` | array | `[]` | Additional envFrom sources | | `kubetail.dashboard.container.securityContext` | map | *see values.yaml* | Container security context | | `kubetail.dashboard.container.resources` | map | `{}` | CPU/memory resource requests and limits | | `kubetail.dashboard.podTemplate.annotations` | map | `{}` | Additional pod annotations | | `kubetail.dashboard.podTemplate.labels` | map | `{}` | Additional pod labels | | `kubetail.dashboard.podTemplate.extraContainers` | array | `[]` | Additional sidecar containers | | `kubetail.dashboard.podTemplate.imagePullSecrets` | array | `[]` | Image pull secrets | | `kubetail.dashboard.podTemplate.securityContext` | map | `{}` | Pod security context | | `kubetail.dashboard.podTemplate.affinity` | map | `{}` | Pod affinity rules | | `kubetail.dashboard.podTemplate.nodeSelector` | map | `{}` | Node selector | | `kubetail.dashboard.podTemplate.tolerations` | array | `[]` | Pod tolerations | | `kubetail.dashboard.configMap.name` | string | `null` | Override ConfigMap name | | `kubetail.dashboard.configMap.annotations` | map | `{}` | Additional ConfigMap annotations | | `kubetail.dashboard.configMap.labels` | map | `{}` | Additional ConfigMap labels | | `kubetail.dashboard.deployment.name` | string | `null` | Override Deployment name | | `kubetail.dashboard.deployment.annotations` | map | `{}` | Additional Deployment annotations | | `kubetail.dashboard.deployment.labels` | map | `{}` | Additional Deployment labels | | `kubetail.dashboard.deployment.replicas` | int | `1` | Number of replicas | | `kubetail.dashboard.deployment.revisionHistoryLimit` | int | `5` | Revision history limit | | `kubetail.dashboard.deployment.strategy` | map | `{type: RollingUpdate}` | Deployment update strategy | | `kubetail.dashboard.ingress.enabled` | bool | `false` | Create an Ingress resource | | `kubetail.dashboard.ingress.name` | string | `null` | Override Ingress name | | `kubetail.dashboard.ingress.annotations` | map | `{}` | Additional Ingress annotations | | `kubetail.dashboard.ingress.labels` | map | `{}` | Additional Ingress labels | | `kubetail.dashboard.ingress.rules` | array | `[]` | Ingress rules | | `kubetail.dashboard.ingress.tls` | array | `[]` | Ingress TLS configuration | | `kubetail.dashboard.ingress.className` | string | `null` | Ingress class name | | `kubetail.dashboard.rbac.name` | string | `null` | Override RBAC resource names | | `kubetail.dashboard.rbac.annotations` | map | `{}` | Additional RBAC annotations | | `kubetail.dashboard.rbac.labels` | map | `{}` | Additional RBAC labels | | `kubetail.dashboard.secret.enabled` | bool | `true` | Create a Secret resource | | `kubetail.dashboard.secret.name` | string | `null` | Override Secret name | | `kubetail.dashboard.secret.annotations` | map | `{}` | Additional Secret annotations | | `kubetail.dashboard.secret.labels` | map | `{}` | Additional Secret labels | | `kubetail.dashboard.service.name` | string | `null` | Override Service name | | `kubetail.dashboard.service.annotations` | map | `{}` | Additional Service annotations | | `kubetail.dashboard.service.labels` | map | `{}` | Additional Service labels | | `kubetail.dashboard.service.ports.http` | int | `8080` | Service HTTP port | | `kubetail.dashboard.serviceAccount.name` | string | `null` | Override ServiceAccount name | | `kubetail.dashboard.serviceAccount.annotations` | map | `{}` | Additional ServiceAccount annotations | | `kubetail.dashboard.serviceAccount.labels` | map | `{}` | Additional ServiceAccount labels | ### Cluster API [Section titled “Cluster API”](#cluster-api) | Parameter | Type | Default | Description | | ----------------------------------------------------- | ------ | ------------------------------------- | --------------------------------------------------------------------------------------- | | `kubetail.clusterAPI.enabled` | bool | `true` | Enable or disable the Cluster API component | | `kubetail.clusterAPI.runtimeConfig` | map | *see values.yaml* | Cluster API runtime configuration (see [Cluster API reference](/reference/cluster-api)) | | `kubetail.clusterAPI.image.registry` | string | `"ghcr.io"` | Image registry | | `kubetail.clusterAPI.image.repository` | string | `"kubetail-org/kubetail-cluster-api"` | Image repository | | `kubetail.clusterAPI.image.tag` | string | *see values.yaml* | Image tag | | `kubetail.clusterAPI.image.digest` | string | `null` | Override image tag with a digest | | `kubetail.clusterAPI.image.pullPolicy` | string | `"IfNotPresent"` | Image pull policy | | `kubetail.clusterAPI.container.name` | string | `"kubetail-cluster-api"` | Container name | | `kubetail.clusterAPI.container.extraEnv` | array | `[]` | Additional environment variables | | `kubetail.clusterAPI.container.extraEnvFrom` | array | `[]` | Additional envFrom sources | | `kubetail.clusterAPI.container.securityContext` | map | *see values.yaml* | Container security context | | `kubetail.clusterAPI.container.resources` | map | `{}` | CPU/memory resource requests and limits | | `kubetail.clusterAPI.podTemplate.annotations` | map | `{}` | Additional pod annotations | | `kubetail.clusterAPI.podTemplate.labels` | map | `{}` | Additional pod labels | | `kubetail.clusterAPI.podTemplate.extraContainers` | array | `[]` | Additional sidecar containers | | `kubetail.clusterAPI.podTemplate.imagePullSecrets` | array | `[]` | Image pull secrets | | `kubetail.clusterAPI.podTemplate.securityContext` | map | `{}` | Pod security context | | `kubetail.clusterAPI.podTemplate.affinity` | map | `{}` | Pod affinity rules | | `kubetail.clusterAPI.podTemplate.nodeSelector` | map | `{}` | Node selector | | `kubetail.clusterAPI.podTemplate.tolerations` | array | `[]` | Pod tolerations | | `kubetail.clusterAPI.configMap.name` | string | `null` | Override ConfigMap name | | `kubetail.clusterAPI.configMap.annotations` | map | `{}` | Additional ConfigMap annotations | | `kubetail.clusterAPI.configMap.labels` | map | `{}` | Additional ConfigMap labels | | `kubetail.clusterAPI.deployment.name` | string | `null` | Override Deployment name | | `kubetail.clusterAPI.deployment.annotations` | map | `{}` | Additional Deployment annotations | | `kubetail.clusterAPI.deployment.labels` | map | `{}` | Additional Deployment labels | | `kubetail.clusterAPI.deployment.replicas` | int | `1` | Number of replicas | | `kubetail.clusterAPI.deployment.revisionHistoryLimit` | int | `5` | Revision history limit | | `kubetail.clusterAPI.deployment.strategy` | map | `{type: RollingUpdate}` | Deployment update strategy | | `kubetail.clusterAPI.rbac.name` | string | `null` | Override RBAC resource names | | `kubetail.clusterAPI.rbac.annotations` | map | `{}` | Additional RBAC annotations | | `kubetail.clusterAPI.rbac.labels` | map | `{}` | Additional RBAC labels | | `kubetail.clusterAPI.secret.enabled` | bool | `true` | Create a Secret resource | | `kubetail.clusterAPI.secret.name` | string | `null` | Override Secret name | | `kubetail.clusterAPI.secret.annotations` | map | `{}` | Additional Secret annotations | | `kubetail.clusterAPI.secret.labels` | map | `{}` | Additional Secret labels | | `kubetail.clusterAPI.service.name` | string | `null` | Override Service name | | `kubetail.clusterAPI.service.annotations` | map | `{}` | Additional Service annotations | | `kubetail.clusterAPI.service.labels` | map | `{}` | Additional Service labels | | `kubetail.clusterAPI.service.ports.http` | int | `8080` | Service HTTP port | | `kubetail.clusterAPI.serviceAccount.name` | string | `null` | Override ServiceAccount name | | `kubetail.clusterAPI.serviceAccount.annotations` | map | `{}` | Additional ServiceAccount annotations | | `kubetail.clusterAPI.serviceAccount.labels` | map | `{}` | Additional ServiceAccount labels | ### Cluster Agent [Section titled “Cluster Agent”](#cluster-agent) | Parameter | Type | Default | Description | | ---------------------------------------------------- | ------ | --------------------------------------- | --------------------------------------------------------------------------------------------- | | `kubetail.clusterAgent.enabled` | bool | `true` | Enable or disable the Cluster Agent component | | `kubetail.clusterAgent.runtimeConfig` | map | *see values.yaml* | Cluster Agent runtime configuration (see [Cluster Agent reference](/reference/cluster-agent)) | | `kubetail.clusterAgent.image.registry` | string | `"ghcr.io"` | Image registry | | `kubetail.clusterAgent.image.repository` | string | `"kubetail-org/kubetail-cluster-agent"` | Image repository | | `kubetail.clusterAgent.image.tag` | string | *see values.yaml* | Image tag | | `kubetail.clusterAgent.image.digest` | string | `null` | Override image tag with a digest | | `kubetail.clusterAgent.image.pullPolicy` | string | `"IfNotPresent"` | Image pull policy | | `kubetail.clusterAgent.container.name` | string | `"kubetail-cluster-agent"` | Container name | | `kubetail.clusterAgent.container.extraEnv` | array | `[]` | Additional environment variables | | `kubetail.clusterAgent.container.extraEnvFrom` | array | `[]` | Additional envFrom sources | | `kubetail.clusterAgent.container.securityContext` | map | *see values.yaml* | Container security context | | `kubetail.clusterAgent.container.resources` | map | `{}` | CPU/memory resource requests and limits | | `kubetail.clusterAgent.podTemplate.annotations` | map | `{}` | Additional pod annotations | | `kubetail.clusterAgent.podTemplate.labels` | map | `{}` | Additional pod labels | | `kubetail.clusterAgent.podTemplate.extraContainers` | array | `[]` | Additional sidecar containers | | `kubetail.clusterAgent.podTemplate.imagePullSecrets` | array | `[]` | Image pull secrets | | `kubetail.clusterAgent.podTemplate.securityContext` | map | `{fsGroup: 0}` | Pod security context | | `kubetail.clusterAgent.podTemplate.affinity` | map | `{}` | Pod affinity rules | | `kubetail.clusterAgent.podTemplate.nodeSelector` | map | `{}` | Node selector | | `kubetail.clusterAgent.podTemplate.tolerations` | array | *see values.yaml* | Pod tolerations (master/control-plane nodes tolerated by default) | | `kubetail.clusterAgent.configMap.name` | string | `null` | Override ConfigMap name | | `kubetail.clusterAgent.configMap.annotations` | map | `{}` | Additional ConfigMap annotations | | `kubetail.clusterAgent.configMap.labels` | map | `{}` | Additional ConfigMap labels | | `kubetail.clusterAgent.daemonSet.name` | string | `null` | Override DaemonSet name | | `kubetail.clusterAgent.daemonSet.annotations` | map | `{}` | Additional DaemonSet annotations | | `kubetail.clusterAgent.daemonSet.labels` | map | `{}` | Additional DaemonSet labels | | `kubetail.clusterAgent.networkPolicy.enabled` | bool | `true` | Create a NetworkPolicy resource | | `kubetail.clusterAgent.networkPolicy.name` | string | `null` | Override NetworkPolicy name | | `kubetail.clusterAgent.networkPolicy.annotations` | map | `{}` | Additional NetworkPolicy annotations | | `kubetail.clusterAgent.networkPolicy.labels` | map | `{}` | Additional NetworkPolicy labels | | `kubetail.clusterAgent.rbac.name` | string | `null` | Override RBAC resource names | | `kubetail.clusterAgent.rbac.annotations` | map | `{}` | Additional RBAC annotations | | `kubetail.clusterAgent.rbac.labels` | map | `{}` | Additional RBAC labels | | `kubetail.clusterAgent.service.name` | string | `null` | Override Service name | | `kubetail.clusterAgent.service.annotations` | map | `{}` | Additional Service annotations | | `kubetail.clusterAgent.service.labels` | map | `{}` | Additional Service labels | | `kubetail.clusterAgent.serviceAccount.name` | string | `null` | Override ServiceAccount name | | `kubetail.clusterAgent.serviceAccount.annotations` | map | `{}` | Additional ServiceAccount annotations | | `kubetail.clusterAgent.serviceAccount.labels` | map | `{}` | Additional ServiceAccount labels | # Quickstart > Install the Kubetail CLI and start tailing Kubernetes logs in minutes — launch the web dashboard with `kubetail serve` or stream to your terminal. ## Installation [Section titled “Installation”](#installation) The `kubetail` CLI Tool is the primary entrypoint for Kubetail on your desktop. To install it, you can use your favorite package manager: * macOS **Homebrew** ```sh brew install kubetail ``` **Krew** ```sh kubectl krew install kubetail ``` **MacPorts** ```sh sudo port install kubetail ``` **Nix (Flake)** ```sh nix profile add github:kubetail-org/kubetail-nix ``` **Nix (Classic)** ```sh nix-env -i -f https://github.com/kubetail-org/kubetail-nix/archive/refs/heads/main.tar.gz ``` **asdf** ```sh asdf plugin add kubetail https://github.com/kubetail-org/asdf-kubetail.git asdf install kubetail latest ``` * Linux **Homebrew** ```sh brew install kubetail ``` **Krew** ```sh kubectl krew install kubetail ``` **Snap** ```sh sudo snap install kubetail ``` **Ubuntu/Mint (apt)** ```sh sudo add-apt-repository ppa:kubetail/kubetail sudo apt update && sudo apt install kubetail-cli ``` **Fedora/CentOS/RHEL/Amazonlinux/Mageia (copr)** ```sh dnf copr enable kubetail/kubetail dnf install kubetail ``` **SUSE (zypper)** ```sh zypper addrepo 'https://download.opensuse.org/repositories/home:/kubetail/$releasever/' kubetail zypper refresh && zypper install kubetail-cli ``` **Alpine (apk)** ```sh apk add kubetail --repository=https://dl-cdn.alpinelinux.org/alpine/edge/testing ``` **Arch (AUR)** ```sh yay -S --noconfirm kubetail-cli ``` **Gentoo (GURU)** ```sh ACCEPT_KEYWORDS="~$(portageq envvar ARCH)" emerge dev-util/kubetail ``` **Nix (Flake)** ```sh nix profile add github:kubetail-org/kubetail-nix ``` **Nix (Classic)** ```sh nix-env -i -f https://github.com/kubetail-org/kubetail-nix/archive/refs/heads/main.tar.gz ``` **asdf** ```sh asdf plugin add kubetail https://github.com/kubetail-org/asdf-kubetail.git asdf install kubetail latest ``` * Windows **Winget** ```sh winget install kubetail ``` **Krew** ```sh krew install kubetail ``` **Chocolatey** ```sh choco install kubetail ``` **Scoop** ```sh scoop install kubetail ``` *** 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: ```sh curl -sS https://www.kubetail.com/install.sh | bash ``` *** ## Usage [Section titled “Usage”](#usage) Once installed, you’re ready to start tailing logs. The `kubetail` CLI tool uses your kubeconfig file for authentication so you’ll be able to access the same clusters as `kubectl`. See the [CLI reference](/reference/cli) for a full list of commands. * **Web Dashboard** Launch the web dashboard using the [`serve`](/reference/cli#kubetail-serve) command (will open at ): ```sh kubetail serve ``` * **Terminal** Stream logs directly in your terminal with the [`logs`](/reference/cli#kubetail-logs) command: ```sh kubetail logs -f deployments/my-app ``` * **Configure** Create a local config file at `~/.kubetail/config.yaml` using the [`config init`](/reference/cli#kubetail-config) command: ```sh kubetail config init ``` * **Advanced Features** Install cluster-side resources using the [`cluster install`](/reference/cli#kubetail-cluster) command to enable advanced features (e.g. search): ```sh kubetail cluster install ``` Tip In addition to running Kubetail on your desktop you can also run it in these environments: * [Cluster](/guides/cluster/installation) * [Docker](/guides/docker/installation)