云原生开发工具微服务网络【免费下载链接】telepresenceLocal development against a remote Kubernetes or OpenShift cluster项目地址https://gitcode.com/gh_mirrors/te/telepresence点击查看免费下载导读telepresence list是 Telepresence 本地开发工作流中最常用的状态查询命令用于在已连接远程 Kubernetes 或 OpenShift 集群后列出当前集群中所有工作负载Workload及其被拦截intercept、摄取ingest、替换replace与 Wiretap 的实时状态。阅读本文后你将掌握该命令的完整参数体系、默认文本输出与结构化 JSON/YAML 输出的解析方法并能结合源码理解其背后的 gRPC 调用链路与位图过滤机制从而在调试本地开发环境时快速定位问题。本文以官方 CLI 参考文档 docs/reference/cli/telepresence_list.md 为骨架结合仓库源码对每个参数和输出字段做了纵深解析。命令概述list 能告诉你什么telepresence list的作用是列出当前拦截List current intercepts。它需要在一个已建立的 Telepresence 会话中运行命令定义在 pkg/client/cli/cmd/list.go其核心执行逻辑会先确保本地 daemonuser daemon已连接然后通过 gRPC 向本地 user daemon 发起查询请求源码中注解ann.Session: ann.Required即表明该命令必须在会话建立后才能执行。输出对象是集群中的工作负载Workload包括 Deployment、StatefulSet、ReplicaSet、Rollout 等 Kubernetes 工作负载资源WorkloadResourceType字段而非 Pod 或 Service。每个工作负载会附带其当前状态是否被拦截、被替换、被 Wiretap、被摄取以及是否安装了 traffic-agent。命令语法与参数详解基本用法telepresence list [flags]命令不接受位置参数源码中Args: cobra.NoArgs所有行为都由 flags 控制。本地 Flags完整继承自官方文档参数简写默认值说明--agents-afalse只显示已安装 traffic-agent 的工作负载--debug无false在输出中包含调试信息如拦截 ID、端口映射、可达 URL、挂载点--help-hfalse显示 list 命令的帮助--ingests-gfalse只显示正在被摄取的 workload--intercepts-ifalse只显示正在被拦截的 workload--namespace-n指定本次 CLI 请求的 namespace 作用域--replacements-rfalse只显示正在被替换的 workload--wiretaps-tfalse只显示正在被 Wiretap 的 workload全局 Flags以下 flags 为 Telepresence CLI 全局参数对所有子命令生效参数默认值说明--config string无Telepresence 配置文件路径--format stringdefault输出格式支持json、yaml、json-stream、default--progress stringauto进度输出类型auto、tty、plain、json、quiet--use string无唯一标识 daemon 容器的匹配表达式隐藏的历史参数源码补充在 pkg/client/cli/cmd/list.go 中还有两个已被隐藏并弃用的 flags官方参考文档未列出但旧脚本中可能出现--only-interceptable简写-o已弃用提示 Redundant since all workloads are eligible for ingest, intercept, or replace所有工作负载都可被 ingest、intercept 或 replace因此该开关已无意义。--watch简写-w已弃用提示改用--output json-stream即--format json-stream实现持续监听。另外--namespace参数支持 shell 自动补全当用户按下 Tab 时CLI 会通过 user daemon 的GetNamespacesRPC 从集群获取 namespace 列表进行补全见 pkg/client/cli/cmd/list.go。过滤机制位图过滤器与默认行为list命令的过滤逻辑分为两层CLI 层将用户传入的 flags 翻译成 gRPC 请求中的ListRequest.filter位图服务端再按位图筛选工作负载。客户端翻译逻辑从源码 pkg/client/cli/cmd/list.go 可以看到初始过滤器为ListRequest_UNSPECIFIED值 0表示不过滤。每指定一个过滤 flag就通过按位或|把对应的位加入过滤器--intercepts对应INTERCEPTS、--replacements对应REPLACEMENTS、--ingests对应INGESTS、--wiretaps对应WIRETAPS。特殊规则当没有指定任何过滤 flag 且使用了--agents时过滤器被设为INSTALLED_AGENTS即只看已安装 agent 的 workload。gRPC 协议定义过滤器是位图枚举定义在 rpc/connector/connector.protoenum Filter { UNSPECIFIED 0; // 不过滤 INTERCEPTS 1; // 拦截 REPLACEMENTS 2; // 替换 INGESTS 4; // 摄取 WIRETAPS 8; // Wiretap INSTALLED_AGENTS 16; // 已安装 traffic-agent EVERYTHING 31; // 全部1|2|4|8|16 }正是因为采用位图多个过滤 flag 可以自由组合例如telepresence list -i -g会同时显示被拦截和被摄取的 workload。服务端筛选逻辑服务端实现在 pkg/client/userd/trafficmgr/session.go 的getInfosForWorkloads函数中。它遍历指定 namespace 的每个 workload根据拦截信息InterceptInfo判断该 workload 的拦截类型Replace、Wiretap或普通 intercept累加filterMatch位图然后执行判定if filter ! 0 filterfilterMatch 0 { return // 不满足过滤条件跳过该 workload }即请求中的 filter 位与 workload 实际拥有的状态位没有任何交集时该 workload 被排除。最终结果按 workload 名称排序后返回给 CLI。默认文本输出解读未指定--format时list输出的是对齐好的文本表格。输出格式由 pkg/client/cli/cmd/list.go 的printList函数控制每行格式为资源类型 名称[: 状态描述]其中资源类型小写显示如deployment、statefulset、replicaset、rollout当结果横跨多个 namespace 时名称后会自动带上.namespace后缀以避免歧义状态描述由state()函数根据 workload 的实际状态生成。状态描述的取值状态描述通过 pkg/client/cli/intercept/describe_intercepts.go 与 pkg/client/cli/cmd/list.go 共同生成主要分以下几类状态含义intercepted该 workload 当前有一个或多个活跃拦截随后会逐条列出拦截详情replaced该 workload 的容器已被替换telepresence replace场景wiretapped该 workload 正处于 Wiretap 监听状态ingested该 workload 正被摄取telepresence ingest场景ready to attach (traffic-agent already installed)已安装 traffic-agent可以随时拦截ready to attach (traffic-agent not yet installed)尚未安装 traffic-agent但可以发起拦截安装会按需自动进行unable to attach (traffic-agent not installed): 原因当前无法拦截NotInterceptableReason字段说明了原因progressing...工作负载正在滚动更新NotInterceptableReason Progressing当 workload 同时存在多种状态时例如既有拦截又有摄取DescribeIntercepts会按replaced、intercepted、wiretapped、ingested的顺序分段输出每种状态下列出对应的详细条目。无结果时的输出当集群中没有匹配的工作负载时文本模式输出No Workloads (Deployments, StatefulSets, ReplicaSets, or Rollouts)对应源码 pkg/client/cli/cmd/list.go。--debug获取拦截的完整调试信息--debug是排查拦截问题最常用的参数。它会在文本输出中追加每个拦截的详细信息字段由 pkg/client/cli/intercept/info.go 的WriteTo方法生成ID拦截的唯一标识仅在--debug下显示State拦截状态如ACTIVE、WAITING等若有错误信息会追加显示Workload kind工作负载类型端口映射以容器端口 - 本地端口 协议的形式展示如8080/TCP - 8080 TCPPod 端口映射也一并列出拦截详情拦截名/PodIP - TargetHost以及匹配过滤器描述基于 header 与 path 过滤器生成Reachable via可达 URL 列表若有 header 过滤器还会附带可直接使用的 curl 示例命令Volume Mount Point卷挂载点本地路径若有挂载。重要用途--debug输出的拦截 ID 是调用 Telepresence REST API 的关键凭据。在 docs/reference/restapi.md 中明确说明The ID of the intercept must be known. It will be visible asIDin the output oftelepresence list --debug. 例如在 API 服务器运行于端口 9980、拦截使用--http-header xy启动时可先执行telepresence list --debug找到 ID再用该 ID 调用 REST 接口验证 header 匹配是否生效。另外--debug下端口与协议信息也用于挂载定位在 docs/reference/volume.md 中提到使用--mounttrue生成随机挂载点时可通过telepresence list的输出找到挂载点位置。结构化输出--format json / yaml / json-streamlist是 Telepresence CLI 中最早支持结构化输出的命令之一。结构化输出由 pkg/client/cli/output/output.go 提供支持WantsFormatted检测到--format非default时printList会改为调用output.Object直接输出WorkloadInfo对象数组。JSON/YAML 输出telepresence list --format json telepresence list --format yaml输出的顶层是WorkloadInfo对象数组每个对象的字段与 rpc/connector/connector.proto 中的WorkloadInfo消息一一对应JSON 标签见 pkg/client/cli/intercept/info.goname工作负载名称namespace所在 namespacenot_interceptable_reason不可拦截的原因空表示可以拦截intercept_info拦截信息数组manager.InterceptInfoingest_info摄取信息数组IngestInfoworkload_resource_type资源类型Deployment、StatefulSet、ReplicaSet、Rolloutuid、agent_version工作负载 UID 与已安装 agent 版本desired_replicas、ready_replicas期望/就绪副本数services关联的 Service 列表其中每个拦截条目的详细字段id、name、disposition、workload_kind、target_host、target_port、pod_ports、header_filters、path_filters、access_urls、pod_ip、global、replace、wiretap等在Info结构体中都有对应的 JSON/YAML 标签方便下游脚本直接消费。json-stream持续监听工作负载变化telepresence list --format json-stream这是--watch的替代方案。从 pkg/client/cli/cmd/list.go 可以看到当输出格式为json-stream时CLI 不再调用一次性ListRPC而是改走WatchWorkloads双向流 RPCproto 定义见 rpc/connector/connector.proto持续接收WorkloadInfoSnapshot每当集群中的工作负载状态发生变化拦截创建/删除、agent 安装等就立即输出一份新的 JSON 快照直到用户按 CtrlC 中断。这在脚本中可用于实时追踪拦截状态变化。--format 与 --output 的关系在 pkg/client/cli/output/output.go 中可以看到推荐使用--format它输出干净的结构化对象不带任何包装旧的--outputjson/yaml仍保留兼容但会把文本命令的输出包装进{cmd, stdout, stderr, err}信封对象两个 flags 同时使用时会被拒绝并提示--output已弃用。底层调用链路从 CLI 到集群telepresence list的完整数据链路如下CLI 层pkg/client/cli/cmd/list.go解析 flags、组装ListRequest{Filter, Namespace}通过connect.InitCommand确保会话就绪然后调用 user daemon 的 gRPC 客户端userD.List(...)。对于大集群还会依据配置中的grpc.maxReceiveSize动态调大接收消息上限默认 20 MB见 pkg/client/cli/cmd/list.go因为list 可能非常长。user daemon 层pkg/client/userd/daemon/grpc.go 的List接收请求后交由会话管理组件执行。trafficmgr 层pkg/client/userd/trafficmgr/session.go遍历 workload 缓存合并 traffic manager 上报的拦截/摄取信息与 agent 安装信息按位图过滤器筛选并排序返回WorkloadInfoSnapshot。输出层pkg/client/cli/cmd/list.go 与 pkg/client/cli/intercept/info.go按default或结构化格式渲染。该流程的过滤与排序行为有对应的单元测试覆盖例如 pkg/client/userd/trafficmgr/workload_snapshot_test.go 中对ListRequest_INTERCEPTS、ListRequest_INTERCEPTS|ListRequest_REPLACEMENTS等组合的断言可作为理解过滤语义的参考。典型使用场景与组合技巧快速确认拦截是否生效执行telepresence list确认目标 workload 状态变为intercepted且显示本地端口映射。只查看已被拦截的 workloadtelepresence list --intercepts或-i。获取 REST API 所需的拦截 IDtelepresence list --debug从输出的ID字段取值。在脚本中消费结构化数据telepresence list --format json配合jq解析例如提取所有intercept_info非空的工作负载名称。持续追踪状态变化telepresence list --format json-stream每行即一个最新快照。限定 namespacetelepresence list --namespace staging避免多 namespace 输出混乱配合-n时名称后缀不再自动添加见 pkg/client/cli/cmd/list.go。与其他功能的关联Rest API 调试list --debug输出的拦截 ID 是 REST API 调用如验证 header 匹配的入参。卷挂载随机挂载点可通过list输出中的Volume Mount Point定位详见 volume.md。Attachment 工作负载通过telepresence attach创建的工作负载同样会出现在telepresence list中并可被拦截详见 attachments/cli.md。拦截/摄取/替换/Wiretap 命令list展示的是这些命令telepresence intercept、telepresence ingest、telepresence replace、telepresence wiretap在集群侧留下的状态结果是验证整个本地开发会话的总览仪表盘。赞分享云原生开发工具微服务网络【免费下载链接】telepresenceLocal development against a remote Kubernetes or OpenShift cluster项目地址https://gitcode.com/gh_mirrors/te/telepresence点击查看免费下载相关推荐Telepresence list-contexts 命令详解查看与筛选 Kubernetes 上下文Telepresence list contexts 命令详解查看与筛选 Kubernetes 上下文 telepresence list contexts云原生开发工具微服务网络在远端集群联调中查看容器状态telepresence compose ps 命令全面解析在远端集群联调中查看容器状态telepresence compose ps 命令全面解析 telepresence compose ps 是 Telepres云原生开发工具微服务网络telepresence compose run 命令详解在远程 Kubernetes 集群上下文中执行一次性容器命令telepresence compose run 命令详解在远程 Kubernetes 集群上下文中执行一次性容器命令 telepresence compos云原生开发工具微服务网络上一篇Protoactor-go终极指南深入解析Go语言分布式Actor系统设计原理下一篇AirSim 飞行日志回放Playback基于 MavLinkTest 实现真实与模拟飞行的同屏对比创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考