kubetail / modules
CLAUDE.md1.8k starsChanged 7 days agoApache-2.0View on GitHub
Four Go modules under one go.work: cli, dashboard, cluster-api and shared. This file holds what every module follows; each module's guide adds its own. From the repo root, make vet-go adds a GOOS=windows pass, scripts/check-go-fix.sh and staticcheck. CI runs all three. make vet-go-changed runs go vet and go fix on the changed packages alone, with their importers, on this platform; ALL_PLATFORMS=1 adds the other two. Ignore a staticcheck finding with //lint:ignore <check> <reason> on the line above it. From modules/,…
Trending
Less talk lately.about the whole repository
Who's talking about kubetail-org/kubetail
- A Hacker News story“Show HN: Kubetail – Real-time log search for Kubernetes”Hacker News · May 1, 2025 · 126 points
- A Hacker News story“Show HN: Kubetail – Web-based real-time log viewer for Kubernetes”Hacker News · Feb 13, 2024 · 70 points
- @damyr.fr“Sur Kube tu as github.com/kubetail-org..., mais le graph d'event manque faut avouer”Bluesky · May 26, 2025 · 4 likes
- @matsuu.bsky.social“k8sのログをブラウザ経由で参照できるダッシュボード実装。pod単位のほか、deploymentやdaemonsetの単位で複数Podのログをまとめてのリアルタイム表示もできる。正規表現による絞り込みも可。”Bluesky · May 4, 2025 · 4 likes
- @chrisshort.net“kubetail-org/kubetail: Real-time logging dashboard for Kubernetes. View logs in a terminal or a browser. …”Bluesky · May 22, 2026 · 1 likes
The biggest 5 of 27 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 27
Talked about on GitHub, Bluesky and Hacker News (27 times).
On GitHub · 20
- Oct 24, 2025🐋 Release kubetail-0.15.4 — kubetail-org/helm-charts1 reaction
- Oct 22, 2026chore(deps): update kubetail to v0.18.1 — uniget-org/tools0 reactions · 2 comments
- Jul 13, 2026💎 Knowledge Update & Optimization: 13 Jul 2026 — nubenetes/awesome-kubernetes0 reactions · 40 comments
- Jul 12, 2026💎 Knowledge Update & Optimization: 12 Jul 2026 — nubenetes/awesome-kubernetes0 reactions · 40 comments
- Jul 12, 2026💎 Knowledge Update & Optimization: 12 Jul 2026 — nubenetes/awesome-kubernetes0 reactions · 40 comments
15 more on GitHub
- Jun 25, 2026x/vulndb: potential Go vuln in github.com/kubetail-org/kubetail/modules/cli: GHSA-v8j7-hp7c-738f — golang/vulndb0 reactions · 1 comment
- Feb 5, 2026feat(kubetail): add package — brioche-dev/brioche-packages0 reactions
- Dec 8, 2025add kubetail — ai-solution-eng/frameworks0 reactions
- Oct 4, 2025feat: add kubetail plugin — asdf-vm/asdf-plugins0 reactions
- Sep 28, 2025Add kubetail plugin — kubernetes-sigs/krew-index0 reactions · 8 comments
- Sep 26, 2025new naming conflict with a project — johanhaleby/kubetail0 reactions · 2 comments
- Sep 19, 2025dev-util/kubetail-bin: add 0.7.5, 0.8.2 — gentoo/gentoo0 reactions · 6 comments
- Sep 18, 2025[Request]: kubetail — ScoopInstaller/Main0 reactions · 1 comment
- Jul 11, 2025🎣 Patch release — kubetail-org/helm-charts0 reactions
- Jul 9, 2025Add Real-Time Log Streaming with Kubetail — kubestellar/ui0 reactions · 5 comments
- Jun 21, 2025TypeScript definitions missing in v8 — nmn/react-timeago0 reactions · 1 comment
- May 21, 2025kubetail-org/kubetail: 一个通用的 Kubernetes 日志仪表板,可以暴漏在浏览器当中查看。 — awesome-ops/awesome-ops.github.io0 reactions
- May 20, 2025Integrate Kubetail graphical Logs for pods and jobs into Kubestellar — kubestellar/ui0 reactions · 9 comments
- May 2, 2025Vendoring a package using "local" imports from another directory? — openSUSE/obs-service-go_modules0 reactions
- Feb 2, 2025new addon: kubetail — kubernetes/minikube0 reactions · 26 comments
On Bluesky · 5
- May 26, 2025Sur Kube tu as github.com/kubetail-org..., mais le graph d'event manque faut avouer — @damyr.fr4 likes and reposts · 1 reply
- May 4, 2025k8sのログをブラウザ経由で参照できるダッシュボード実装。pod単位のほか、deploymentやdaemonsetの単位で複数Podのログをまとめてのリアルタイム表示もできる。正規表現による絞り込みも可。 — @matsuu.bsky.social4 likes and reposts
- May 22, 2026kubetail-org/kubetail: Real-time logging dashboard for Kubernetes. View logs in a terminal or a browser. Run anywhere - desktop, cluster,… — @chrisshort.net1 likes and repost
- May 1, 2025Show HN: Kubetail – Real-time log search for Kubernetes Hi Everyone! Kubetail is a general-purp... https://github.com/kubetail-org/kubetail… — @kubernetes.activitypub.awakari.com.ap.brid.gy1 likes and repost
- Feb 13, 2024Show HN: Kubetail – Web-based real-time log viewer for Kubernetes Discussion — @hn100.bsky.social1 likes and repost
On Hacker News · 2
- May 1, 2025Show HN: Kubetail – Real-time log search for Kubernetes126 points · 35 comments
- Feb 13, 2024Show HN: Kubetail – Web-based real-time log viewer for Kubernetes70 points · 33 comments
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- crates/CLAUDE.mdCLAUDE.md
- dashboard-ui/CLAUDE.mdCLAUDE.md
- e2e/CLAUDE.mdCLAUDE.md
- proto/CLAUDE.mdCLAUDE.md
- release-cliSkill
- release-clusterSkill
- release-notesSkill
- release-versionSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 46
After editing a schema:
- Very specific: line 68
Tests run on Linux, macOS and Windows in CI: Use t.TempDir(), t.Setenv and filepath.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
modules — Go workspace
Four Go modules under one go.work: cli, dashboard, cluster-api and shared. This file holds what every module follows; each module's guide adds its own.
- Imports point one way.
sharedimports no sibling.dashboardandcluster-apiimportsharedalone.cliimportssharedand exactly two Dashboard packages,dashboard/pkg/appanddashboard/pkg/config. Nothing importscliorcluster-api. - Each module builds without
go.work, as the release builds do. Everygo.modcarries areplacefor each sibling it imports and a completego.sum. A new import of a sibling module needs thereplace, and aCOPYin the component's Dockerfile underbuild/package/. → ADR: each Go module builds without go.work - Every module pins
fsnotifyto v1.8.0 with areplace; keep the four in step. → ADR: pin fsnotify to v1.8.0 - Go is 1.26; CI and the Dockerfiles pin the patch version (
go-versionin.github/actions/setup-environment/action.yml).
Checks
cd modules/<module>
go fmt ./... # CI fails if `gofmt -l .` prints anything
go vet ./...
go test -race ./...From the repo root, make vet-go adds a GOOS=windows pass, scripts/check-go-fix.sh and staticcheck. CI runs all three. make vet-go-changed runs go vet and go fix on the changed packages alone, with their importers, on this platform; ALL_PLATFORMS=1 adds the other two. Ignore a staticcheck finding with //lint:ignore <check> <reason> on the line above it.
From modules/, go test -race github.com/kubetail-org/kubetail/modules/... covers the workspace, as make lint-go, vet-go and test-go do from the repo root. A change to shared runs the workspace's tests. CI tests from a vendored tree (go work vendor); don't commit modules/vendor.
Coverage is measured across the workspace: every test binary counts every package (-coverpkg), so a shared line that the Dashboard's tests reach is covered. make cover-changed runs only the changed packages' tests; FULL=1 runs them all, as CI does. → ADR: measure Go coverage across the workspace
go generate ./... in a module runs its generators: gqlgen in dashboard and cluster-api, protoc in shared, a copy of config/default/cli.* in cli.
Conventions
context.Contextis the first parameter, and it carries the caller's identity. Pass the request's context down; never start a Kubernetes or gRPC call fromcontext.Background()on a request path.- Each environment is an implementation behind one interface, picked by a factory that switches on
config.Environment:ConnectionManager,Proxy,HealthMonitor. Behaviour that differs by environment goes in both implementations. A resolver checks the environment itself only to refuse an operation that exists in one alone. - Errors: wrap with
fmt.Errorf("doing x: %w", err)when the caller could not otherwise tell where it failed; sentinels areerrors.New, tested witherrors.Is. A resolver that refuses a request returns one of theErr*values inshared/graphql/errors(ErrForbidden,ErrUnauthenticated,ErrValidationError,ErrServiceUnavailable…), whoseextensions.codeis what a client matches on. - Logging is zerolog's global logger, imported as
zlog "github.com/rs/zerolog/log".zlog.Fatal()is for startup only. Never log a token, a cookie or a request body. - A constructor is
NewX(required…, opts ...Option)where there is anything optional. Exported options are production knobs; a seam only tests need is an unexported option, field or constructor (newClientForTest). - An interface sits beside its implementation (
k8shelpers.ConnectionManager,logs.Stream). A small unexported interface on the consumer's side is fine as a test seam. - Mocks are hand-written testify mocks in a
mock/subpackage of the package they fake (k8shelpers/mock). No mock generator. A method added to the interface is added to the mock. - A method that needs its caller to hold the lock ends in
_UNSAFE; the method that takes the lock and calls it has the plain name. - Fan-out to subscribers is
github.com/kubetail-org/megaphone. Don't hand-roll a subscriber map. - Use the current standard library:
any,new(expr),wg.Go(...), range over an integer,slicesandmaps. CI fails whengo fixwould rewrite a file. - Imports are grouped, a blank line between groups: standard library, third-party,
modules/shared/..., then the module's own packages. - File names follow their directory: kebab-case in
sharedand the older Dashboard packages, snake_case incli. In a directory that mixes them, a new file is snake_case.
The GraphQL servers
dashboard and cluster-api have the same shape: graph/schema.graphqls is the one schema file, graph/server.go builds the handler and its transports, graph/resolver.go holds the Resolver struct and its dependencies, and gqlgen.yml binds GraphQL types straight to Go types (the Kubernetes API types in dashboard, the protobuf messages in cluster-api).
After editing a schema:
cd modules/<module> && go generate ./... # gqlgen
cd dashboard-ui && pnpm graphql-codegen # the UI's types, generated from both schemaslogRecordsFetchandlogRecordsFollowexist in both schemas with the same signature, since the UI sends one set of documents to whichever server is in use. Change both together.graph/schema.resolvers.gois rewritten by gqlgen, which keeps the bodies. A new field arrives as a stub that panics withnot implemented. Anything that is not a resolver method goes in another file (schema.helpers.go,resolver.go), or gqlgen moves it to the end of the file.- Neither server sets an error presenter. Whatever error a resolver returns reaches the client with its message, a client-go error included. For a failure the client should understand, return an
Err*value or a message written for it. - In a subscription resolver, report a failure with
transport.AddSubscriptionError(ctx, …), then close the channel, and stop whenctxis done (logRecordsFollowin either server). @validateadds an error and still passes the value on; a field marked@nullIfValidationFailedthen resolves to null.- A new long-lived connection type is cancelled by
app.NotifyShutdownand counted forapp.DrainWithContext, as WebSockets are (cmd/main.go).
Tests
The repo-wide rules are the root guide's Testing conventions.
- testify
assertandrequire, plainfunc TestX(t *testing.T), table-driven witht.Runwhere cases repeat. No testifysuitein new tests. - White-box by default (
package foo). An externalpackage foo_testonly to pin a public contract, and it says so. - To wait,
selecton a channel againsttime.Afteror a context deadline, or userequire.Eventually.drainAllincli/internal/clusterapi/stream_test.goshows the shape. - A test passes in any order, at any
-cpu, run repeatedly. The nightlystress.ymlruns every test with-shuffle=on,-countand several-cpuvalues, with and without-race, and opens an issue per failing test. Its report script isscripts/stress.go. - Tests run on Linux, macOS and Windows in CI. Use
t.TempDir(),t.Setenvandfilepath. A test closes what it opens before it ends, since Windows removes no open file. A platform-specific test goes in a platform-named file (foo_unix_test.go,//go:build !windows), never behind aruntime.GOOScheck. shared/testutils.NewWebTestClient(t, handler)is the HTTP client for app and GraphQL tests: it keeps cookies, sendsSec-Fetch-Site: same-originand replays the lastX-CSRF-Tokenon unsafe methods. Prime it withclient.Get("/api/auth/session"), anddefer client.Teardown().- Kubernetes is faked with
k8s.io/client-go/kubernetes/fakeandk8shelpers/mock.MockConnectionManager; a server withhttptest; a gRPC peer with a realgrpc.NewServer()on127.0.0.1:0. NewAppindashboardandcluster-apibuilds the real dependencies and passes them to the unexportednewApp, which tests call with fakes. Every route and middleware is mounted either way.- One package variable is swapped by tests,
inClusterConfigFnink8shelpers. New seams are parameters or fields.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

