【Tetragon / eBPF】Agent 生命周期：BTF、安装形态与三条策略加载路径
内容提要
本文介绍Tetragon v1.7.0中策略加载与Sensor/Hook轴的关键问题：BTF发现失败会导致程序挂不上，需检查内核vmlinux路径；DaemonSet与主机安装共用agent，但依赖host网络和BPF能力；v1.7.0默认gRPC改用Unix socket，裸二进制仍为TCP；kubectl、gRPC、静态文件三条加载路径共用collectionKey映射，撞名时优先排查路径而非选择器YAML。
延伸解读
BTF 失败是策略无事件的首要排查点
Tetragon 的 TracingPolicy hook 依赖内核 BTF 做类型校验与 CO-RE 重定位。若 BTF 发现失败，agent 会中止内核自动发现，导致后续 sensor 无法加载，策略即使 apply 也可能无事件。排障时应先检查 /sys/kernel/btf/vmlinux 是否存在、发行版是否裁掉 BTF，以及 --btf 或 TETRAGON_BTF 是否指向正确路径。BTF 是硬前置，失败时往往到不了“策略已加载”状态。
安装形态影响进程可见性，而非策略语法
DaemonSet 与主机安装共用同一 agent 二进制，差别在于如何让进程看到全部主机 PID/cgroup。DaemonSet 默认 hostNetwork: true 且需 privileged 能力，若被修改，会出现 Pod Running 但几乎无主机进程事件，这是安装形态问题，不是选择器写错。主机安装则需检查 systemd unit 的 ExecStart 是否带正确的 --server-address、--btf 等参数。两种形态下 collectionKey 语义相同，不要假设存在两套策略命名空
v1.7.0 默认 gRPC 地址变更，升级需同步客户端
v1.7.0 的 Helm 默认 gRPC 地址从 localhost:54321 改为 Unix socket（/var/run/tetragon/tetragon.sock），但裸二进制 flag 默认仍是 TCP localhost。升级后 tetra 连不上，优先检查客户端是否还在打 54321，而不是怀疑策略未加载。同时需确认 socket 文件对排障用户可见，并更新所有第三方 gRPC 客户端，避免旁路进程监听旧端口。
三条加载路径共用 collectionKey，撞名先查路径
kubectl、gRPC、静态文件三条加载路径最终都进入同一个 collectionKey{name, namespace} map。若同名集合已被其他路径占用，再次添加会失败。因此“改了 CR 不生效”时，应优先检查是否被 gRPC 或静态文件先占用，而不是修改选择器 YAML。v1.7.0 没有 domain sharding，也不存在 tetra tracingpolicy domains 命令，分域是后续版本话题。
Q&A
Tetragon agent 启动时 BTF 发现失败会导致什么？如何排查？
BTF 发现失败会导致 agent 启动中止，后续 sensor 无法加载，策略无法生效。排查时先检查 /sys/kernel/btf/vmlinux 是否存在，发行版是否裁掉 BTF，或 --btf 参数是否指向正确路径。也可通过 TETRAGON_BTF 环境变量指定。
Tetragon 在 Kubernetes DaemonSet 和主机安装两种部署形态下有何区别？
两者共用同一 agent 二进制和 sensor 加载逻辑，但 DaemonSet 默认 hostNetwork: true 且需要 privileged 能力以挂载 BPF，配置通过 Helm values 注入；主机安装则直接以 root 运行，配置通过 systemd unit 或命令行。DaemonSet 默认启用 TracingPolicy CRD，主机安装通常走文件或 gRPC。
Tetragon v1.7.0 默认 gRPC 地址是什么？升级后 tetra 连不上怎么办？
v1.7.0 默认 Helm 安装使用 Unix socket：unix:///var/run/tetragon/tetragon.sock。裸二进制默认仍是 localhost:54321。升级后 tetra 连不上，优先检查客户端是否仍连接 54321，并确保 socket 文件存在且权限正确。
Tetragon 中 kubectl、gRPC 和静态文件三条策略加载路径是如何共存的？
三条路径都通过 sensors.Manager.AddTracingPolicy 加载，使用 collectionKey{name, namespace} 作为键写入同一个 collectionMap。如果同名集合已存在且状态不是加载错误，再次添加会失败。因此撞名时优先检查是否被其他路径占用，而不是修改选择器 YAML。
Tetragon 中 BTF 校验失败时，警告和硬失败有什么区别？
警告（ValidationWarnError）表示类型不完全匹配但仍继续加载，但事件字段可能缺失或类型漂移；硬失败（ValidationFailedError）表示找不到原型等严重问题，策略被拒绝。警告不等于正确挂载，需要关注。
Tetragon 中策略已 apply 但无事件，可能的原因有哪些？
常见原因包括：BTF 发现失败导致 agent 启动中止；DaemonSet 未使用 hostNetwork 或缺少特权导致看不到主机进程；gRPC 地址变更导致客户端连不上；同名策略被其他加载路径占用。需按这些方向排查。
