Pole Sidecar 数据面

使用 Pole Sidecar 承载本地路由、负载均衡与治理扩展点的实践指南。

Pole Sidecar 适合业务语言多样、SDK 接入成本高，或希望把治理放到旁路代理的场景。它在本地执行转发，但服务发现与治理事实仍来自 Lattice Hub 控制面。

sidecar data plane

何时选择 Sidecar

选 Sidecar	选 SDK
多语言 / 不便改代码	Rust 应用可直接嵌入
需要统一入口做转发与拦截	希望 Proxyless、少一跳
与 Controller 注入结合	已有成熟 SDK 治理链

两者不互斥：部分服务用 SDK，部分服务用 Sidecar 是常见组合。

快速启动

仓库：pole-sidecar。要求 Rust 1.74+。

cargo build
RUST_LOG=info cargo run

自定义配置：

SIDECAR_CONFIG=./my-sidecar.toml RUST_LOG=debug cargo run

最小配置示例（仓库 sidecar.toml）：

[inbound_http]
addr = "0.0.0.0:8080"

[[routes]]
name = "http_api"
prefix = "/api/"
cluster = "backend_http"

[[routes]]
name = "grpc_helloworld"
grpc_prefix = "/helloworld.Greeter/"
cluster = "backend_grpc"

[[clusters]]
name = "backend_http"
endpoints = ["127.0.0.1:9000"]
lb_policy = "round_robin"
tls = false

[[clusters]]
name = "backend_grpc"
endpoints = ["127.0.0.1:50051"]
lb_policy = "round_robin"
tls = false

路由与协议规则

匹配顺序：先 grpc_prefix，再 prefix。
gRPC 识别：HTTP/2 且 content-type 以 application/grpc 开头。
入站默认 HTTP/1.1 与 HTTP/2（含 gRPC-h2c）。
负载均衡当前为简单轮询；生产前按版本确认是否已扩展其他策略。

社区 Demo

入口	说明
本地样例	`pole-sidecar/sidecar.toml` + `RUST_LOG=info cargo run`
设计文档	`pole-sidecar/docs/design/`
K8s 注入	`pole-controller` 的 `sidecarInject.mode=dns
SDK 对照	`pole-client-rust/examples/{discover,config}.rs`（Proxyless）

cd pole-sidecar
cargo build
# 先起一个本机上游，例如 127.0.0.1:9000，再：
RUST_LOG=info cargo run
# 或
SIDECAR_CONFIG=./sidecar.toml RUST_LOG=debug cargo run

怎么触发验证

本地转发：对 Sidecar inbound（默认 0.0.0.0:8080）发请求：

curl -sS -D - http://127.0.0.1:8080/api/hello
# 期望按 [[routes]] prefix=/api/ 转发到 cluster backend_http 的 endpoints

gRPC 前缀：content-type: application/grpc 且 path 匹配 grpc_prefix 时走对应 cluster。
K8s：装好 controller 并注入后，检查 Pod 是否多出 sidecar 容器、应用就绪探针仍绿、出站是否打到预期上游。
与治理联调（演进中）：在控制面发布路由/限流 active release，再观察 Sidecar 拦截器/转发是否变化；区分“规则未发布”和“代理未消费”。

效果是什么

场景	预期效果
HTTP `prefix=/api/` 命中	请求转发到 `backend_http` endpoints（轮询）
gRPC `grpc_prefix` 命中	HTTP/2 gRPC 转到 `backend_grpc`
路由未命中	本地拒绝/未转发（以当前 Sidecar 版本行为为准）
dns 注入	通过 DNS 拦截做发现，侵入较低
mesh 注入	流量劫持，治理拦截更深
仅改本地 TOML、未发控制面规则	本地路由可变，但不应把 TOML 当作集群级治理真相源

与控制面协作

正确职责划分：

控制面维护服务、实例、配置与治理规则的 active 视图。
Sidecar 拉取或接收这些视图，不在本地重新定义事实。
拦截器扩展点（ACL、限流、熔断、指标）应围绕 active 配置工作。
变更仍走 Console/API 的发布链；不要把 Sidecar 本地文件当成长期真相源。

当前骨架已具备请求阶段与上游阶段回调占位。接入真实治理前，先打通发现与路由，再逐个打开拦截器。

与 Controller 注入配合

在 Kubernetes 中可由 pole-controller 注入 Sidecar：

dns 模式：DNS 拦截，适合渐进。
mesh 模式：流量劫持，治理更深。

注入后检查：

应用是否仍通过就绪探针
出站是否打到预期集群
控制面规则变更是否反映到代理行为

观测建议

分协议观察 HTTP/1.1、HTTP/2、gRPC-h2c 的吞吐与尾延迟。
记录路由未命中、上游失败、拦截器拒绝。
与控制面 History / DiscoverEvent 对照，区分“规则未发布”和“代理执行问题”。

检查清单

Sidecar 配置中的 cluster endpoints 正确
路由前缀无冲突，gRPC 服务 path 完整
控制面 active 规则已发布
本地可访问上游，超时与重试可接受
日志级别在排障时可提升到 debug
未把 Sidecar 描述成控制面替代品