# KHI (Kubernetes History Inspector): timeline and topology views from audit logs

> KHI is an agentless Kubernetes log visualization tool that turns audit log streams from the kube-apiserver into interactive timeline and topology views. It runs in a Docker container and has no authentication layer, so the port binding in every docker run command is the first thing to get right.

**GoogleCloudPlatform/khi** — A log viewer for Kubernetes troubleshooting

- Repository: https://github.com/GoogleCloudPlatform/khi
- Stars: 2,085 · Forks: 98
- Language: Go
- License: Apache-2.0
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/googlecloudplatform-khi

## KHI reads kube-apiserver audit logs, so workloads that bypass the API server stay invisible

KHI's design centres on the audit log stream from the Kubernetes API server. The tool installs no agent into the cluster; it reads what the API server has already recorded, which is why the project can call itself agentless. That design decision simplifies setup but sets the scope firmly: any workload event that does not touch the kube-apiserver does not appear in KHI at all.

For teams debugging GKE incidents, this is a reasonable trade-off. Deployments, pod scheduling, ConfigMap edits and service account bindings all go through the API server, and they all produce audit entries. KHI transforms those entries into two views: a timeline that shows when resource states changed, and a topology that maps relationships between resources.

The tool targets engineers who already have logs but need to reason about what happened across several Kubernetes components at once. Raw log lines spread across Cloud Logging do not show the order in which a failing pod was created, evicted, rescheduled and finally terminated. KHI builds that sequence into a visual chart, making the ordering of events something you read rather than something you reconstruct by scanning timestamps.

## Timeline view records manifest diffs; topology view builds resource relationships from audit records alone

The timeline view serves two distinct purposes. It draws status change timings as chart bars so that overlapping events on different resources line up on the same horizontal axis, which makes causal chains visible across components. It also extracts manifest diffs from the audit log, so the exact field that changed is visible alongside when it changed.

The topology view has a narrower data source than it might appear: it derives resource relationships entirely from the kube-apiserver audit stream, pulling nothing from Cloud Asset Inventory or any other log backend. That constraint matters because it means the topology reflects what the audit log recorded, not a live query against the cluster.

Cloud Asset Inventory enters the picture as a supplementary source, used optionally to reconstruct initial state snapshots for resources that existed before the audit window began. Any resource that predates the earliest audit record and was not tracked in Cloud Asset Inventory starts the topology without a history.

## One Docker command in Cloud Shell; Application Default Credentials for a local machine

The README gives Cloud Shell as the easiest starting point, because the metadata server is already available there and no credential setup is needed. The command is:

```bash
docker run -p 127.0.0.1:8080:8080 gcr.io/kubernetes-history-inspector/release:latest
```

After the container starts, opening http://localhost:8080 in Chrome brings up the KHI web interface.

On a local machine without a metadata server, the credential path goes through Application Default Credentials. The steps for Linux, macOS or WSL are:

```bash
gcloud auth application-default login
docker run \
 -p 127.0.0.1:8080:8080 \
 -v ~/.config/gcloud/application_default_credentials.json:/root/.config/gcloud/application_default_credentials.json:ro \
 gcr.io/kubernetes-history-inspector/release:latest
```

The volume mount makes the credentials file readable inside the container as read-only. On Windows PowerShell the path changes to $env:APPDATA\gcloud\application_default_credentials.json, and the line continuation character changes from \ to the backtick.

Each example in the README uses -p 127.0.0.1:8080:8080 rather than the shorter -p 8080:8080. That distinction has security consequences covered in the section below.

## Cloud Logging feeds Google Cloud clusters; OSS Kubernetes depends on log file upload

KHI's supported cluster list covers six Google Cloud product types: Google Kubernetes Engine, Cloud Composer, GKE on AWS, GKE on Azure, GDCV for Baremetal and GDCV for VMware. All of them use Cloud Logging as the primary log source.

For Kubernetes clusters running outside Google Cloud, the path is different. The OSS Kubernetes path uses kube-apiserver audit logs formatted as JSONlines, uploaded as files rather than streamed from a hosted logging service. The setup guide at docs/en/setup-guide/oss-kubernetes-clusters.md walks through an example using Loki.

Teams on EKS or AKS need their own pipeline to produce audit logs in the JSONlines format and make them available for upload to KHI. Cloud Logging handles that automatically for GKE clusters. A cluster that was not configured to record all API server requests at installation time will have gaps in any KHI view, and KHI provides no mechanism to fill those gaps retroactively.

## The Dockerfile sets HOST to 0.0.0.0, but each docker run example restricts to 127.0.0.1

There is a gap between what the container image is configured to do and what the README's run commands enforce. The Dockerfile sets ENV HOST=0.0.0.0, which tells the KHI server to bind on all network interfaces inside the container. The README then warns not to expose the port on the internet, and each of its docker run examples uses -p 127.0.0.1:8080:8080, which restricts the host-side port mapping to the loopback address.

That combination works correctly: the container listens broadly inside its own network namespace, and the host forwards traffic only from localhost. But anyone who follows a standard Docker tutorial and writes -p 8080:8080 instead of -p 127.0.0.1:8080:8080 will expose an unauthenticated KHI interface to the local network. The README repeats the warning in a highlighted note, but the Dockerfile itself offers no default restriction.

KHI has no authentication mechanism. The README states that KHI is not providing any authentication or authorization features and is intended to be accessed from its local user. Cloud Logging credentials in the mounted ADC file are the closest thing to an access boundary here.

## GOMEMLIMIT defaults to 10000 MiB, and only the latest Google Chrome is tested

The Dockerfile sets ENV GOMEMLIMIT=10000MiB. This is a Go runtime environment variable that instructs the garbage collector to keep heap memory below that limit before triggering more aggressive collection. At 10000 MiB, the default assumes the container has substantial memory available.

The README does not document memory guidance or scaling recommendations for large log sets. An engineer running KHI on a laptop with Docker memory limits lower than 10000 MiB may see the Go runtime constrained before the Dockerfile limit takes effect, depending on Docker Desktop settings.

Browser support narrows the audience in a different way. KHI is tested only on the latest version of Google Chrome. Other browsers may work, but the project provides no support if they do not. For teams whose workstation policy restricts which browsers are installed, that is a concrete constraint to verify before starting a rollout.

## Job mode runs analysis queries and exits, for CI/CD pipelines and alert triggers

A separate operating mode covers the case where a team wants KHI to produce output without a browser session. KHI calls this Job Mode, and the documentation says it is designed for automated workflows including CI/CD pipelines and alert triggers. Job Mode runs the analysis queries and exits, so a pipeline step can collect KHI output without keeping a long-lived container running.

The full configuration is at docs/en/setup-guide/job-mode.md, and Job Mode uses the same container image as the interactive server, so the deployment step is identical and the credential requirements are unchanged. Nothing changes about how credentials are supplied; the difference is only whether the web server starts.

This is the path for embedding KHI results into existing incident response tools. A pipeline that fires on an alert, collects a KHI analysis of the surrounding time window, and posts the output to a monitoring chat channel is the scenario Job Mode documentation targets.

## Not an officially supported Google product; building from source requires Go 1.26 and the Angular toolchain

A disclaimer in the documentation notes that KHI is not an officially supported Google Cloud product. Issues and feature requests go to the GitHub issue tracker, handled on a best-effort basis. There is no Google Cloud support contract for this tool.

Building from source requires Go 1.26, which both go.mod and the Dockerfile confirm. The Dockerfile uses FROM golang:1.26 AS builder, and go.mod declares go 1.26.0 as the minimum version. The repository also contains an Angular frontend under web/, with a package.json at the repository root listing prettier and markdownlint-cli2 as dev dependencies. A full build assembles the Go backend and the Angular frontend before producing the final binary. The development guide is at docs/en/development-contribution/development-guide.md.

The latest release is v0.59.0, published on 2026-09-18. The last push was on 2026-10-06, and the repository is not archived.

## Conclusion

KHI is worth it for a Google Cloud infrastructure team that needs to correlate events across GKE components and wants a timeline rather than raw log lines. The agentless Docker deployment is the right default for an on-demand troubleshooting session. Avoid it if your cluster workloads bypass the API server entirely, because those events will not appear in any view. Before running it outside Cloud Shell, verify that your Docker port binding uses 127.0.0.1:8080:8080 and not the bare 8080:8080 mapping, since the container image sets HOST to 0.0.0.0 and the tool has no authentication layer.

## FAQ

### What is KHI (Kubernetes History Inspector)?

KHI is an agentless Kubernetes log visualization tool that turns kube-apiserver audit logs into interactive timeline and topology views. It is part of the GoogleCloudPlatform organization on GitHub and is distributed under the Apache-2.0 license.

### How do I run KHI on a local machine without Cloud Shell?

Run gcloud auth application-default login, then use docker run with the -v flag to mount the credentials file at ~/.config/gcloud/application_default_credentials.json into the container. The README gives the full command for Linux, macOS, WSL and Windows PowerShell.

### Does KHI work with Kubernetes clusters outside Google Cloud?

Yes, through log file upload. The OSS Kubernetes path accepts kube-apiserver audit logs formatted as JSONlines. The setup guide at docs/en/setup-guide/oss-kubernetes-clusters.md walks through an example using Loki as the source.

### What browsers does KHI support?

KHI is tested only on the latest version of Google Chrome. Other browsers may work, but the project provides no support if they do not.

### Can KHI run in automated pipelines without opening a web browser?

Yes. Job Mode runs analysis queries and exits without starting the web server. It is documented as suitable for CI/CD workflows and alert triggers, and the setup guide is at docs/en/setup-guide/job-mode.md.

## Sources

- [GoogleCloudPlatform/khi on GitHub](https://github.com/GoogleCloudPlatform/khi)
- [Issues](https://github.com/GoogleCloudPlatform/khi/issues)
- [License: Apache-2.0](https://github.com/GoogleCloudPlatform/khi/blob/main/LICENSE)
- [README](https://github.com/GoogleCloudPlatform/khi/blob/main/README.md)
- [Releases](https://github.com/GoogleCloudPlatform/khi/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/googlecloudplatform-khi