Day 18 / 共 20 天 · 第 4 周 遥测/扩展/安装

istioctl CLI

网格出问题怎么排查？istioctl 是运维网格的瑞士军刀。今天看它的几个杀手锏命令：proxy-config（看 Envoy 实际配置）、proxy-status（对比期望 vs 实况）、analyze（静态体检）的源码实现。前 17 天你学的是"网格怎么运转"，今天学"网格出问题时怎么诊断"——把知识变成排障能力。

📍 你在整门课的位置 · 第 4 周「遥测 / 扩展 / 安装」（W1-3 全部 ✓）
D16 遥测→ D17 EnvoyFilter→ D18 istioctl→ D19 安装→ D20 收官
L01

命令树

🤔 痛点：写了 VirtualService 但流量不对，从哪查起？ 你 apply 了路由规则，可流量就是没按预期走。问题可能在三处：①配置本身写错了；②istiod 没生成对；③生成对了但 Envoy 没收到。不能靠猜——得有工具分别照亮这三处。
💡 本质：网格医生的"三件诊断工具" istioctl 就是网格的体检仪器，三件套各查一处：analyze=开工前查"配置有没有写错"（体检报告）；proxy-config=查"某个保安现在到底拿的什么执勤手册"（看 Envoy 实况）；proxy-status=查"哪个保安还没收到最新通知"（同步状态）。三件工具连的地方还不同——记住这点是今天的关键。
// istioctl/cmd/root.go:102 GetRootCmd 装配中心
// cli.NewCLIContext(rootOptions) 生成传给所有子命令的 ctx
// AddCommand 挂载：proxyconfig.ProxyConfig / analyze.Analyze / mesh.InstallCmd
//   / proxystatus / describe / tag / dashboard / version …
读法：istioctl 用 cobra 组织命令树，cli.Context 携带 kube client 等给所有子命令。InferPodInfoFromTypedResource 能把 deployment/foo 解析成真实 Pod（方便你不用记 Pod 全名）。核心命令：install/analyze/proxy-config/proxy-status。
L02

proxy-config

istioctl/pkg/proxyconfig/proxyconfig.go:1351 ProxyConfig（别名 pc），子命令 cluster/listener/route/endpoint/bootstrap/secret 等。

proxy-config = "看某个 Envoy 现在到底是什么配置" 你写了 VirtualService，但流量没按预期走——是 Istio 没生成对，还是 Envoy 没收到？istioctl proxy-config route <pod> 直接 dump 出那个 Envoy 当前实际生效的路由配置，让你眼见为实。类似 cluster/listener/endpoint/bootstrap/secret 各看一类。这是排查网格问题的第一利器——不用猜，直接看 Envoy 的真实配置（正是 Envoy 课 Day 18 的 /config_dump）。
L03

直连 Envoy admin

// proxyconfig.go:148 extractConfigDump
//   kubeClient.EnvoyDoWithPort(ctx, pod, ns, "GET", "config_dump", 15000)
//   —— 端口转发到 Pod 的 Envoy admin 口（15000）做 HTTP GET
// configdump.ConfigWriter{}.Prime(debug) 解析
读法：proxy-config 怎么拿到配置？直接端口转发到目标 Pod 里 Envoy 的 admin 端口（15000），GET /config_dump（Envoy 课 Day 18 讲的那个内省端点）。拿到原始 config_dump JSON 后本地解析、格式化输出。所以它看到的是"Envoy 自己报告的当前配置"——最真实。
⚠️ 常见误解：以为 proxy-config 看的是"istiod 生成的配置"。其实它直连 Envoy 的 15000 admin，看的是"Envoy 此刻实际生效的配置"。这正是它值钱的地方——排查时你要的就是"数据面到底是什么状态"，而不是"控制面以为是什么状态"（后者用 proxy-status 对账）。
L04

proxy-status

istioctl/pkg/proxystatus/proxystatus.go:77 XdsStatusCommand（别名 ps）：显示所有代理的 xDS 同步状态（NAME/CLUSTER/ISTIOD/VERSION/SUBSCRIBED TYPES）。

proxy-status = "谁和控制面失同步了" 大规模网格里，怎么快速知道"哪些 Envoy 的配置还没跟上最新"？istioctl proxy-status 列出所有代理，显示每个的 CDS/LDS/EDS/RDS 是 SYNCED（已同步）还是 STALE（陈旧）。如果某个代理一直 STALE，说明它和 istiod 之间有问题（网络、配置错误 NACK 等）。这是网格健康的"仪表盘"——一眼看出哪里失同步。
L05

期望 vs 实况

// proxystatus.go:120 单代理 diff：
//   EnvoyDo(..., "config_dump") 取代理实况（142）
//   DiscoveryRequest{TypeUrl: TypeDebugConfigDump} 向 istiod 要"期望配置"（148）
//   compare.NewXdsComparator(...).Diff()（156）对比
对比"istiod 想给的" vs "Envoy 实际有的" 更强的用法：istioctl proxy-status <pod> 会同时取两份配置——从 Envoy admin 拿"它实际生效的"，从 istiod 的 debug 接口拿"它应该收到的（期望）"，然后 diff。如果两者不一致，说明推送出了问题（可能 NACK 了、可能网络丢了）。这是"控制面期望 vs 数据面实况"的对账工具——精确定位"配置没生效"的根因。用的是 istiod 的 debug TypeUrl（statusgen.go 的 /syncz、/config_dump）。
L06

analyze 体检

istioctl/pkg/analyze/analyze.go:90 Analyze：用一组分析器（analyzers.AllCombined()）对配置做静态体检——不用真跑，就能发现"引用了不存在的服务""两条 VirtualService 冲突""mTLS 配置矛盾"等问题。

读法：istioctl analyze 是"配置 linter"——apply 之前先体检，catch 常见错误。可分析活集群或本地文件。proxy-config 看"现在是什么"、proxy-status 看"同步了吗"、analyze 看"配置对不对"——三件排查利器各司其职。
📝 举个例子：一次真实排查（错误驱动） 现象：frontend 调 reviews 老是 503。
① 先 istioctl analyze → 报"VirtualService 引用了不存在的 subset" → 若命中，直接改配置收工；
② 没报错？再 istioctl proxy-status → 看 frontend 的 CDS/EDS 是不是 STALE（没同步上）；
③ 显示 SYNCED？最后 istioctl proxy-config cluster frontend-xxx → 看 Envoy 里 reviews 的 cluster 有没有健康端点。三步层层缩小范围，把"玄学 503"变成可定位的问题。
L07

两种传输

命令连谁
proxy-config直连代理自己的 Envoy admin（15000）
proxy-status / version -x走 istiod 的 xDS/debug（15012，ADS + debug TypeUrl）
读法：两类命令连不同地方：看"数据面实况"→ 连 Envoy admin；看"控制面视角/对账"→ 连 istiod。multixds 处理多个 istiod 实例（端口转发到每个 istiod Pod 的 15012）。都用 K8s 端口转发 + bearer token 认证。
你的 istioctl 目标 Pod 的 Envoy admin:15000 /config_dump（数据面实况） istiod xDS/debug:15012（控制面期望） proxy-config proxy-status proxy-status <pod> 会同时取两边做 diff（期望 vs 实况）
两类命令连不同地方：看"数据面实况"→ 直连 Envoy admin(15000)；看"控制面视角/对账"→ 连 istiod(15012)。
L08

今日小结 + 动手

🧠 今天你应该能回答

  • istioctl 命令树怎么组织？cli.Context 干嘛？
  • proxy-config 怎么拿到 Envoy 实际配置？
  • proxy-status 显示什么？STALE 意味着什么？
  • 单代理 diff 对比哪两份配置？
  • analyze 是什么？三件排查利器各看什么？

✋ 动手

cd /Users/bitmart/work/codes/github/higress-group/istio
grep -n 'func ProxyConfig\|EnvoyDoWithPort' istioctl/pkg/proxyconfig/proxyconfig.go
grep -n 'func XdsStatusCommand\|TypeDebugConfigDump' istioctl/pkg/proxystatus/proxystatus.go
grep -n 'func Analyze' istioctl/pkg/analyze/analyze.go
明天预告 · Day 19：Operator 与安装——istioctl install 怎么把 Istio 装进集群？新版 render 模型（客户端渲染 Helm + server-side apply）、IstioOperator 配置、profiles。
← Day 17 EnvoyFilter Day 19 · Operator 与安装 →