【Linkerd】linkerd2-proxy-api：专用 gRPC 与 xDS 寻址差

第 5 篇 把 destination Pod 四容器分工钉到可排障粒度；istio-xds 第 14 篇 用一篇对照说明 Linkerd 不是 xDS 实现。中间仍缺一层：控制面与 linkerd2-proxy 之间到底有哪些 gRPC 服务、每条 RPC 回答什么问题、以及排障口令为何是「查 destination.Get 流」而不是「查 EDS NACK」。

本篇钉协议内核：linkerd2-proxy-api 仓库定义的 destination / identity / inbound / tap 四套 API，以及它们与 istiod/xDS 在寻址方式与错误语义上的机制差。不把 Linkerd 写成「轻量 istiod」或 xDS 子集。

本篇在系列中的位置

篇目	核心内容
第 5 篇 · destination 架构	四容器 Pod、Informer 驱动
第 6 篇 · linkerd2-proxy-api	四套 gRPC、专用 API vs xDS、错误语义
第 7 篇 · 服务发现流	per-target Get、EndpointTranslator
系列目录	关键问题、阅读路径

版本锚定：Linkerd 2.20（源码 tag version-2.20；公告 2026-06-23）。linkerd2 go.mod 钉 github.com/linkerd/linkerd2-proxy-api v0.20.0。机制叙述对齐该 tag 的 proto 定义与 controller/api/destination/server.go；不以 linkerd.io/docs/ live 站点冒充 2.20。无真实 Linkerd 集群则不粘贴伪造 gRPC 日志或 linkerd check 输出。

一、destination / identity / inbound / tap

linkerd2-proxy-api 仓库 README 写明：该仓库包含 Linkerd Proxy 与控制面通信的 gRPC 绑定，API 设计为 Kubernetes 无关的运行时配置抽象。四套服务分工如下。

与 第 4 篇 的 CSR 路径、第 5 篇 的四容器拓扑衔接：destination 容器实现 destination / GetProfile RPC；identity Deployment 实现 identity RPC；policy 容器参与 inbound 策略求值；tap 是数据面向控制面的反向查询。

flowchart LR
  proxy["linkerd2-proxy"] -->|"destination.Get"| dest["destination controller"]
  proxy -->|"identity CSR"| ident["linkerd-identity"]
  proxy -->|"inbound policy"| pol["policy container"]
  tapcp["tap / viz"] -->|"tap query"| proxy

图：四套 API 的调用方向。节点为英文；正文用中文解释。出站发现走 destination；身份走 identity；入站授权走 inbound；观测走 tap。

二、专用 API vs xDS

xDS（见 istio-xds/）是与具体数据面解耦的通用资源协议：Envoy 按 类型 + 资源名 订阅 LDS/RDS/CDS/EDS 等，istiod 按类型推送 DiscoveryResponse。Linkerd 走的是相反取舍：linkerd2-proxy-api 只为 linkerd2-proxy 定制，不追求多数据面复用。

寻址差是排障的第一分叉：

destination.proto 注释写清：Get 给定 destination 后返回长连接流；控制器在订阅开始必须尽快推送首条消息；客户端重连前可暂用陈旧缓存，但收到首条新消息前不得假定端点仍有效。这是 per-target 流模型，不是「订阅 EDS 类型下所有 Cluster」。

工程含义：把 Linkerd 当成「另一个 istiod」会在第一步指错组件——出站无端点应查 destination Get 流与 EndpointSlice 翻译，而不是查 xDS EDS 快照或 NACK 计数。

三、gRPC 错误非 ACK/NACK

istio-xds 第 11 篇 讨论 istiod 如何处理 NACK——这套复杂度来自 xDS 作为通用协议必须应对「任意客户端以任意方式拒绝任意资源类型」。

Linkerd 专用 API 没有资源级 ACK/NACK 状态机。destination.Get 要么建立流并持续收 Update，要么在 gRPC 层失败：

• 非法 authority → InvalidArgument（如 IP 直查、Get 不支持 IP 查询——见 server.go）
• Service 不存在 → NotFound
• 内部/Informer 错误 → Internal 或订阅错误
• 流落后过多 → endpointTranslator 队列溢出后关闭流（endpoint_updates_queue_overflow 指标）

错误处理落在 标准 gRPC 状态码 + 客户端重连，而非 xDS 的 DiscoveryRequest 错误详情与 nonce 协商。这不是「更简单所以更好」的论断，而是可验证的机制事实：协议通用性与资源级协商复杂度是同一设计选择的两面（istio-xds/14 已述，本篇不重复优劣判断）。

四、对照 istio-xds/14（不重写）

istio-xds 第 14 篇 从 Istio 读者视角对照了三组件拆分、按目标查询 vs 类型订阅、SDS vs CSR 身份路径。本篇从 Linkerd 系列内侧补三点，避免读者在两系列间来回时对不上口径：

1. 组件拓扑：destination ∥ identity ∥ proxy-injector 三 Deployment，destination Pod 内再拆 destination / sp-validator / policy / 反身 proxy 四容器（第 5 篇）。
2. L7 信息来源：Istio 走 VirtualService/HTTPRoute → RDS；Linkerd 走 ServiceProfile → GetProfile 流（第 9 篇）。
3. 身份路径：Istio 走 SDS 通用资源推送（envoy/11）；Linkerd 走 identity 专用 CSR（第 4 篇）。

不重写 istiod 推送图、NACK/warming 全书——那些留在 istio-xds/。本系列后续 第 7 篇 展开 Get 流内的 EndpointTranslator；第 13 篇 把「查流」收进五轴口诀。

五、proto 版本边界

机制结论必须钉版本对：

边界门：

• 2.20 之后的 live 文档能力不得写入正文当当前事实（见 PLAN.md §7.1）。
• linkerd2-proxy-api 独立发版（v0.20.0 等），与 linkerd2 小版本通过 go.mod 对齐；升级控制面须核对 proxy 与 API crate 是否同代。
• inbound API 与 policy CRD（policy.linkerd.io）在 2.20 并存；Gateway API HTTPRoute 等资源的 policy-validator 校验见 第 8 篇、第 11 篇。

排障时「proto 字段是否存在」以 v0.20.0 的 .proto 为准，不以记忆或第三方博客为准。

参考资料

规范 / 官方文档 / 源码（A）

• linkerd/linkerd2-proxy-api README；proto/destination.proto、proto/inbound.proto 等 @ v0.20.0
• linkerd/linkerd2 tag version-2.20：go.mod（linkerd2-proxy-api v0.20.0）；controller/api/destination/server.go（Get RPC）
• Linkerd Architecture（destination / identity / proxy-injector 职责）

站内对照（A/B）

• istio-xds/14 · Linkerd 对照
• istio-xds/11 · NACK 与 PushOrder
• 第 5 篇 · destination 架构
• PLAN.md §六、§九篇 06

学术谱系（A）

• McCanne & Jacobson, The BSD Packet Filter, USENIX Winter 1993（控制面「专用协议 vs 通用协议」谱系对照）

上一篇：destination 架构

下一篇：服务发现流：per-target Get 与 EndpointTranslator