Kubeshark 常用 CLI 命令详解
逐条实测 Kubeshark v53.6.0 官方 CLI 的全部子命令(tap/proxy/clean/config/license/logs/pcapdump/mcp/scripts/console/pprof/version/completion),给出参数表、真实回显与使用场景,并覆盖 Helm 路径配套命令与 kubectl 侧诊断命令,形成一份「拿来即查」的命令手册。已在 Ubuntu 22.04 + k3s v1.34.1+k3s1 集群实测通过(2026-10-23,全部回显逐行照抄自实测环境)。
Kubeshark 常用 CLI 命令详解
目标:逐条实测 Kubeshark v53.6.0 官方 CLI 的全部子命令(tap/proxy/clean/config/license/logs/pcapdump/mcp/scripts/console/pprof/version/completion),给出参数表、真实回显与使用场景,并覆盖 Helm 路径配套命令与 kubectl 侧诊断命令,形成一份「拿来即查」的命令手册。已在 Ubuntu 22.04 + k3s v1.34.1+k3s1 集群实测通过(2026-10-23,全部回显逐行照抄自实测环境)。
一、环境信息
- 操作系统:Ubuntu 22.04 LTS(内核 6.8.0-138-generic)
- Kubernetes:k3s v1.34.1+k3s1 单节点(部署篇同款环境)
- Kubeshark CLI:v53.6.0(
/usr/local/bin/kubeshark,静态单文件 62,206,136 字节) - Helm:v3.17.3(Helm 路径命令章)
- 实测日期:2026-10-23
二、工具概览
kubeshark CLI 是单文件多子命令工具(Go 实现),v53.6.0 共 14 个子命令。执行 kubeshark --help 的完整实测回显:
kubeshark --help
Kubeshark: The API Traffic Analyzer for Kubernetes
An extensible Kubernetes-aware network sniffer and kernel tracer.
For more info: https://kubeshark.com
Usage:
kubeshark [command]
Available Commands:
clean Removes all Kubeshark resources
completion Generate the autocompletion script for the specified shell
config Generate Kubeshark config with default values
console Stream the scripting console logs into shell (temporarily non-functional — under refactoring after hub API changes)
help Help about any command
license Print the license loaded string
logs Create a ZIP file with logs for GitHub issues or troubleshooting
mcp Run MCP (Model Context Protocol) server for AI assistant integration
pcapdump Store all captured traffic (including decrypted TLS) in a PCAP file.
pprof Select a Kubeshark container and open the pprof web UI in the browser
proxy Open the web UI (front-end) in the browser via proxy/port-forward
scripts Watch the `scripting.source` and/or `scripting.sources` folders for changes and update the scripts
tap Capture the network traffic in your Kubernetes cluster
version Print version info
Flags:
--config-path string Set the config path, default: /.kubeshark/config.yaml
-d, --debug Enable debug mode
-h, --help help for kubeshark
--set strings Override values using --set
Use "kubeshark [command] --help" for more information about a command.
命令分类速查:
| 分类 | 命令 | 一句话职责 |
|---|---|---|
| 部署生命周期 | tap / proxy / clean | 安装捕获组件 / 重建 Web UI 转发 / 完整卸载 |
| 配置 | config / version / license | 默认配置导出与落盘 / 版本 / 许可查看 |
| 数据导出 | pcapdump / logs | 导出 PCAP(含解密流量)/ 打包诊断日志 |
| AI 集成 | mcp | 以 MCP 服务器形态向 AI 助手暴露流量查询 |
| 脚本扩展 | scripts / console | 监听脚本目录热更新 / 流式控制台日志(v53.6.0 临时不可用) |
| 性能诊断 | pprof | 打开组件 pprof 剖析界面 |
| 其他 | completion / help | shell 补全 / 帮助 |
⚠️ 注意:v53.6.0 没有
stop子命令(早期版本的 stop 已移除)。停止捕获组件即卸载(clean),或在 MCP 的 allow-destructive 模式下调 stop_kubeshark 工具(见 5.6 节)。停止后需要临时暂停转发而不动集群组件时,只需结束本机 port-forward 进程,集群内组件继续运行。
三、前置条件
kubeshark二进制已安装并在 PATH(kubeshark version返回 v53.6.0;安装方法见《Kubeshark Kubernetes 部署指南》 4.1 节);- kubeconfig 可用(
kubectl get nodes正常;否则 tap/proxy/logs/pcapdump 均报stat /.kube/config: no such file or directory,修法见部署篇 4.2 节); - shell 补全建议开启(一次性配置):
kubeshark completion bash > /etc/bash_completion.d/kubeshark
source /etc/bash_completion.d/kubeshark
(completion 支持 bash/zsh/fish/powershell 四种 shell,kubeshark completion --help 实测 Available Commands 列表原文如上。)
四、各命令详解
4.1 tap:部署捕获组件(核心命令)
tap 是一切的开始:按配置把 Kubeshark 组件部署进集群、等待就绪并自动建立 Web UI 端口转发。完整帮助(实测回显):
kubeshark tap --help
Capture the network traffic in your Kubernetes cluster
Usage:
kubeshark tap [POD REGEX] [flags]
Flags:
--docker-imagePullPolicy string ImagePullPolicy for the Docker images (default "Always")
--docker-imagePullSecrets strings ImagePullSecrets for the Docker images
-r, --docker-registry string The Docker registry that's hosting the images (default "docker.io/kubeshark")
-t, --docker-tag string The tag of the Docker images that are going to be pulled
--dryRun Preview of all pods matching the regex, without tapping them
--efsFileSytemIdAndPath string EFS file system ID
-e, --excludedNamespaces strings Excluded namespaces
-h, --help help for tap
--ingress-enabled Enable Ingress
-n, --namespaces strings Namespaces selector
--persistentStorage Enable persistent storage (PersistentVolumeClaim)
--persistentStorageStatic Persistent storage static provision
--proxy-front-port uint16 Provide a custom port for the proxy/port-forward (default 8899)
--proxy-host string Provide a custom host for the proxy/port-forward (default "127.0.0.1")
--release-helmChartPath string Path to a local Helm chart folder (overrides the remote Helm repo)
-s, --release-namespace string Release namespace of Kubeshark (default "default")
--resource-guard-enabled Enable/disable resource guard
--serviceMesh Capture the encrypted traffic if the cluster is configured with a service mesh and with mTLS (default true)
--storageClass string Override the default storage class of the PersistentVolumeClaim (per node) (default "standard")
--storageLimit string Override the default storage limit (per node) (default "10Gi")
--telemetry-enabled Enable/disable Telemetry (default true)
--tls Capture the traffic that's encrypted with OpenSSL or Go crypto/tls libraries (default true)
--watchdogEnabled Enable/disable watchdog
Global Flags:
--config-path string Set the config path, default: /.kubeshark/config.yaml
-d, --debug Enable debug mode
--set strings Override values using --set
核心参数解读:
--proxy-front-port(默认 8899)/--proxy-host(默认 127.0.0.1):Web UI 转发端口与绑定地址;8899 被占用时换端口(实测报错与修法见部署篇 4.6 节排障二);--dryRun:只预览将被捕获的 Pod,不部署(实测回显):
kubeshark tap --dryRun
2026-10-23T07:45:27Z INF tapRunner.go:139 > Targeted pod: demo-client-6cb6666488-cbj6f
2026-10-23T07:45:27Z INF tapRunner.go:139 > Targeted pod: demo-nginx-57669875d8-chmsf
2026-10-23T07:45:27Z INF tapRunner.go:139 > Targeted pod: kubeshark-front-568b59dd44-5h2g8
2026-10-23T07:45:27Z INF tapRunner.go:139 > Targeted pod: kubeshark-hub-5f5cbf87cf-hvhrv
2026-10-23T07:45:27Z INF tapRunner.go:139 > Targeted pod: kubeshark-worker-daemon-set-nsbz2
2026-10-23T07:45:27Z INF tapRunner.go:139 > Targeted pod: coredns-7896679cc-fz6vk
- 位置参数
[POD REGEX]:正则圈定捕获目标(如kubeshark tap "payment-"只捕获 payment 前缀 Pod); -n/-e:命名空间包含/排除;--tls(默认 true):是否启用 eBPF 解密追踪;-t:镜像 tag(默认跟随 Chart);- 执行成功后的完整部署日志与解读见部署篇 4.4 节(实测回显含 Chart 下载、21 资源创建、Pod 就绪与端口转发全过程)。
⚠️ 注意:tap 的旗标是驼峰风格(
--dryRun、--ingress-enabled混合)。实测 kebab 风格的--dry-run会报Error: unknown flag: --dry-run,以本节帮助原文为准。
4.2 proxy:重建 Web UI 端口转发
proxy 单独管理端口转发,适用三种场景:helm 路径部署后的首次访问、tap 转发进程意外退出后的恢复、换端口/换绑定地址。帮助与实测回显:
kubeshark proxy --help
Open the web UI (front-end) in the browser via proxy/port-forward
Usage:
kubeshark proxy [flags]
Flags:
-h, --help help for proxy
--proxy-front-port uint16 Provide a custom port for the proxy/port-forward (default 8899)
--proxy-host string Provide a custom host for the proxy/port-forward (default "127.0.0.1")
-s, --release-namespace string Release namespace of Kubeshark (default "default")
Global Flags:
--config-path string Set the config path, default: /.kubeshark/config.yaml
-d, --debug Enable debug mode
--set strings Override values using --set
kubeshark proxy
2026-10-23T07:25:08Z INF proxy.go:32 > Starting proxy... namespace=default proxy-host=127.0.0.1 service=kubeshark-front src-port=8899
2026-10-23T07:25:08Z INF proxyRunner.go:103 > Kubeshark is available at: url=http://127.0.0.1:8899
2026-10-23T07:25:08Z ERR browser.go:26 > While trying to open a browser error="exec: \"xdg-open\": executable file not found in $PATH"
验证转发已通(实测回显):
curl -sI http://127.0.0.1:8899 | head -1
HTTP/1.1 200 OK
4.3 clean:完整卸载
clean 卸载 Kubeshark 的全部集群资源(Helm release + RBAC + ConfigMap + Secret + NetworkPolicy),不动业务负载。帮助与实测回显(节选,完整 21 资源删除清单见部署篇 5.1 节):
kubeshark clean --help
Removes all Kubeshark resources
Usage:
kubeshark clean [flags]
Flags:
-h, --help help for clean
-s, --release-namespace string Release namespace of Kubeshark (default "default")
Global Flags:
--config-path string Set the config path, default: /.kubeshark/config.yaml
-d, --debug Enable debug mode
--set strings Override values using --set
kubeshark clean
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-cluster-role-default" ClusterRole
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-config-map" ConfigMap
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-secret" Secret
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-service-account" ServiceAccount
2026-10-23T07:28:03Z INF helm.go:177 > Starting delete for "kubeshark-worker-network-policy" NetworkPolicy
2026-10-23T07:28:03Z INF helm.go:177 > purge requested for kubeshark
2026-10-23T07:28:03Z INF clean.go:28 > Uninstalled the Helm release: kubeshark
卸载后验证(实测):
helm list -n default
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
4.4 config:默认配置导出与落盘
kubeshark config --help
Generate Kubeshark config with default values
Usage:
kubeshark config [flags]
Flags:
-h, --help help for config
-r, --regenerate Regenerate the config file with default values to path /.kubeshark/config.yaml
Global Flags:
--config-path string Set the config path, default: /.kubeshark/config.yaml
-d, --debug Enable debug mode
--set strings Override values using --set
两种用法(均实测):
kubeshark config:把 333 行默认配置打印到标准输出(首部节选见《Kubeshark 配置参数详解》 3.1 节);kubeshark config -r:写入$HOME/.kubeshark/config.yaml(HOME 为空时为 /.kubeshark/config.yaml),退出码 0,实测文件 5965 字节/333 行;--config-path可另指路径。
4.5 version 与 license:版本与许可查看
kubeshark version
v53.6.0
kubeshark license --help
Print the license loaded string
Usage:
kubeshark license [flags]
Flags:
-h, --help help for license
Global Flags:
--config-path string Set the config path, default: /.kubeshark/config.yaml
-d, --debug Enable debug mode
--set strings Override values using --set
kubeshark license 读取当前生效的许可串;未配置许可时(license: "")实测输出为空。许可的获取与注入(--set license=<license>)见部署篇 7.1 节。
4.6 logs:打包诊断日志
把 hub/worker/front 全部容器日志打成 ZIP,供提 issue 或离线分析:
kubeshark logs --help
Create a ZIP file with logs for GitHub issues or troubleshooting
Usage:
kubeshark logs [flags]
Flags:
-f, --file string Path for zip file (default current <pwd>\kubeshark_logs.zip)
-g, --grep string Regexp to do grepping on the logs
-h, --help help for logs
Global Flags:
--config-path string Set the config path, default: /.kubeshark/config.yaml
-d, --debug Enable debug mode
--set strings Override values using --set
实测(指定输出路径):
kubeshark logs -f /tmp/kubeshark_logs.zip
2026-10-23T07:31:07Z INF provider.go:178 > container=tracer namespace=default pod=kubeshark-worker-daemon-set-nsbz2
2026-10-23T07:31:07Z ERR kubesharkLogsUtils.go:78 > Failed write file! error="failed to open file /root/.kubeshark/config.yaml, open /root/.kubeshark/config.yaml: no such file or directory"
2026-10-23T07:31:07Z INF kubesharkLogsUtils.go:83 > You can find the ZIP file with all logs at: path=/tmp/kubeshark_logs.zip
ls -lh /tmp/kubeshark_logs.zip
-rw-r--r-- 1 root root 14K Oct 23 07:31 /tmp/kubeshark_logs.zip
⚠️ 注意:中间那行
Failed write file! ... config.yaml: no such file or directory是本地尚无配置文件导致的附带警告,不影响 ZIP 生成(实测 ZIP 正常产出且包含 tracer 容器日志)。-g支持对日志先做正则过滤再打包。
4.7 pcapdump:导出 PCAP(含解密后流量)
把 Worker 捕获的原始 PCAP(含已解密的 TLS 明文)从集群拷回本地:
kubeshark pcapdump --help
Store all captured traffic (including decrypted TLS) in a PCAP file.
Usage:
kubeshark pcapdump [flags]
Flags:
--debug Enable debug logging
--dest string Local destination path for copied PCAP files (can not be used together with --enabled)
-h, --help help for pcapdump
--kubeconfig string Path for kubeconfig (if not provided the default location will be checked)
--time string Time interval (e.g., 10m, 1h) in the past for which the pcaps are copied
Global Flags:
--config-path string Set the config path, default: /.kubeshark/config.yaml
--set strings Override values using --set
实测(先建目录再导出最近 15 分钟):
mkdir -p /tmp/ks-pcap
kubeshark pcapdump --dest /tmp/ks-pcap --time 15m
2026-10-23T07:49:29Z INF versionCheck.go:24 > Checking for a newer version...
2026-10-23T07:49:29Z INF pcapDump.go:89 > Copying PCAP files
2026-10-23T07:49:29Z INF pcapDumpRunner.go:327 > No pcaps available to copy on the workers
--dest目录必须事先存在,否则实测报错Error: directory does not exist: /tmp/ks-pcap;- 本次嵌套实验环境中 Worker 原始 PCAP 池为空(
No pcaps available to copy on the workers),故无文件落盘;正常捕获的集群会拷出分片 .pcap 文件,可直接用 Wireshark 打开分析; --time支持如10m、1h的回溯区间。
4.8 mcp:AI 助手集成(MCP 服务器)
以 MCP(Model Context Protocol)服务器形态把 Kubeshark 的 L7 流量查询暴露给 AI 助手。帮助信息中的工具清单与两种模式(实测 --list-tools 回显,节选):
kubeshark mcp --url http://127.0.0.1:8899 --list-tools
MCP Tools
=========
URL Mode: http://127.0.0.1:8899
Cluster management tools disabled (Kubeshark managed externally)
Local Tools:
check_kubeshark_status Check if Kubeshark is running
get_file_url Resolve a relative path to a full download URL
download_file Download a file from Kubeshark to local disk
Traffic Analysis Tools:
list_api_calls Query L7 API transactions (HTTP, GraphQL, DNS, TLS, ...
list_l4_flows List L4 (TCP/UDP) network flows showing real-time co...
get_l4_flow_summary Get high-level summary of L4 connectivity including ...
get_dissection_status Get current L7 protocol dissection (parsing) status ...
enable_dissection Enable L7 protocol dissection on all workers to start...
disable_dissection Disable L7 protocol dissection on all workers - only...
get_raw_capture_status Get raw PCAP capture status - required for creating ...
get_data_boundaries Get time boundaries of available PCAP data per node ...
get_l7_data_boundaries Get time boundaries of available L7 dissected API ca...
list_snapshots List all snapshots with their status, size, and time...
create_snapshot Create a new snapshot from raw PCAP data for a speci...
get_snapshot Get details of a specific snapshot including status,...
delete_snapshot Delete a snapshot and all associated PCAP data. By d...
rename_snapshot Rename a snapshot's display name
export_snapshot_pcap Export snapshot as a merged PCAP file for analysis i...
两种连接模式(kubeshark mcp --help 实测原文):
- kube 模式(默认):读 kubeconfig 直连集群,具备
check_kubeshark_status / start_kubeshark / stop_kubeshark三个集群管理工具,但 start/stop 默认禁用,需--allow-destructive开启; - URL 模式(
--url http://127.0.0.1:8899):不依赖 kubectl,直连已发布的 Kubeshark;start/stop 被禁用(只读),可配--token(ServiceAccount/bearer 令牌,如kubectl create token kubeshark-cli --audience kubeshark-hub)访问开启了认证的 Hub。
配置进 Claude Desktop 的 JSON 片段(官方帮助原文):
{
"mcpServers": {
"kubeshark": {
"command": "/path/to/kubeshark",
"args": ["mcp", "--url", "https://kubeshark.example.com"]
}
}
}
4.9 scripts / console / pprof:脚本与性能诊断
三者均为辅助命令,帮助回显如下:
kubeshark scripts --help
Watch the `scripting.source` and/or `scripting.sources` folders for changes and update the scripts
Usage:
kubeshark scripts [flags]
Flags:
-h, --help help for scripts
--proxy-front-port uint16 Provide a custom port for the Kubeshark (default 8899)
--proxy-host string Provide a custom host for the Kubeshark (default "127.0.0.1")
-s, --release-namespace string Release namespace of Kubeshark (default "default")
...
scripts:常驻监听本地脚本目录,变更即推送集群热加载(脚本开发时配合scripting.watchScripts使用);console:流式输出脚本控制台日志。v53.6.0 官方注明临时不可用(--help 原文:temporarily non-functional — under refactoring after hub API changes,Hub 已把控制台日志迁移到 Connect-RPC 流式服务,客户端尚未跟进),调用无日志输出属预期;pprof:选定一个 Kubeshark 组件容器并打开 Go pprof 剖析 Web 界面(默认端口 8000、flamegraph 视图,--pprof-port/--pprof-view可调),需先在对应组件开启tap.pprof.enabled=true。
4.10 completion:shell 补全
支持 bash/zsh/fish/powershell(帮助回显见第三章),bash 一次性安装示例:
kubeshark completion bash | sudo tee /etc/bash_completion.d/kubeshark >/dev/null
五、Helm 路径与诊断命令
5.1 Helm 通道命令(部署/升级/查看/回滚)
与 CLI 并行的部署通道,核心四条(均在实测环境验证,完整回显见《Kubeshark Kubernetes 部署指南》第五章):
helm repo add kubeshark https://helm.kubeshark.com # 添加官方仓库(实测输出 "kubeshark" has been added to your repositories)
helm search repo kubeshark # 查 Chart 版本(实测 kubeshark/kubeshark 53.6.0)
helm install kubeshark kubeshark/kubeshark --namespace default --set tap.capture.dissection.stopAfter=24h
helm upgrade kubeshark kubeshark/kubeshark --namespace default --reuse-values --set <参数>=<值> --wait
helm get values kubeshark -n default # 查看当前生效 values
helm rollback kubeshark <revision> -n default # 版本回滚
💡 说明:
kubeshark tap内部也是执行 Helm 安装(实测日志下载的就是 kubeshark-53.6.0.tgz),因此两条通道装出的组件完全同构;--reuse-values用于在既有配置上叠加变更,漏写会把未显式指定的项重置为 Chart 默认。
5.2 kubectl 侧诊断命令
日常巡检与排障最常用的六条(全部实测):
kubectl get pods # 组件健康:kubeshark-front / kubeshark-hub 应 1/1 Running,worker DaemonSet 2/2
kubectl get ds # Worker 守护进程集(DESIRED/CURRENT/READY 应一致)
kubectl describe pod -l app.kubeshark.com/app=worker # Worker 事件(特权/挂载类错误在此暴露)
kubectl logs -l app.kubeshark.com/app=hub --tail=50 # Hub 日志(授权拒绝、快照错误在 trace 级别可见)
kubectl logs <worker-pod> -c sniffer --tail=20 # Worker sniffer 容器日志(抓包与存储)
kubectl logs <worker-pod> -c tracer --tail=20 # Worker tracer 容器日志(eBPF 追踪)
进程参数复核(验证配置是否真下发,实测回显见《Kubeshark 配置参数详解》 3.4 节):
ps -ef | grep "[h]ub -port" # Hub:-capture-stop-after / -snapshot-size-limit / -dissector-*
ps -ef | grep "[w]orker -i any" # Worker:-packet-capture / -storage-size / -capture-db-max-size / -metrics-port
5.3 端口转发兜底:kubectl port-forward
不依赖 kubeshark CLI 的兜底转发(helm 输出的官方提示之一):
kubectl port-forward -n default service/kubeshark-front 8899:80
Forwarding from 127.0.0.1:8899 -> 80
(转发建立后访问 http://127.0.0.1:8899/,与 kubeshark proxy 效果一致;进程 Ctrl+C 结束。)
六、注意事项
- tap 是前台进程:Ctrl+C 会断开端口转发,但集群内组件不受影响;重连用
kubeshark proxy。 - 没有 stop 子命令:v53.6.0 停止=卸载(
clean);MCP 的 stop_kubeshark 属破坏性操作,默认禁用需--allow-destructive。 - 清理顺序:先
kubeshark clean再删本机二进制;clean 不会删除 demo 等业务负载(实测验证)。 - 重复执行 8899 冲突:旧转发进程残留时报
bind: address already in use(实测原文见部署篇排障二),先 kill 旧进程。 - 离线环境:tap/logs/pcapdump 启动时的
Checking for a newer version...在离线时返回Failed to get the latest release.(实测出现过),不影响功能。 - 子命令旗标风格不统一:camel(
--dryRun)与 kebab(--ingress-enabled)混用,先看--help再敲。
七、常见问题(FAQ)
Q1:所有命令都报 stat /.kube/config: no such file or directory?
kubeconfig 未配置:export KUBECONFIG=/etc/rancher/k3s/k3s.yaml 或复制到 ~/.kube/config(部署篇排障实录一)。
Q2:kubeshark license 输出为空?
未注入许可(默认 license: "")。Community 许可从 License Portal 领取后 --set license=<license> 注入;未配置许可也可经 Dashboard 登录激活互补 COMMUNITY 许可。
Q3:console 命令没有输出? v53.6.0 已知状态:官方在 --help 中注明该命令临时不可用(Hub 端已迁 Connect-RPC,客户端重构中),等待后续版本。
Q4:pcapdump 报 directory does not exist?
--dest 目标目录需先创建(实测踩坑);目录存在但仍提示 No pcaps available 时,检查 raw capture 是否开启(tap.capture.raw.enabled: true)且确有捕获时长。
Q5:日志 ZIP 里缺某个容器?
logs 按 Pod 逐容器收集(实测输出逐行打印 container=tracer ...);确认对应 Pod 处于 Running,异常退出容器的历史日志先 kubectl logs --previous 人工留存。
八、参考链接
- 官方 CLI 文档:https://docs.kubeshark.com/en/cli
- MCP 集成文档:https://docs.kubeshark.com/en/mcp
- GitHub Releases(二进制下载):https://github.com/kubeshark/kubeshark/releases
- 站内系列:《Kubeshark Kubernetes 部署指南》、《Kubeshark 配置参数详解》、《Kubeshark 介绍与选型指南》