OpenTelemetry OBI 1.0 怎样迁移 Config v1 配置

如果你的 OpenTelemetry eBPF Instrumentation（OBI）仍然使用 Config v1，迁移到 1.0 时代的 Config v2 不建议直接手改一份 YAML 就上线。更稳妥的路径是：先保存旧文件和所有外部覆盖来源，再用 obi config migrate 生成新配置，用 obi config validate 检查结构，最后只挑一个代表性实例做 canary，对比遥测后再扩大范围。

官方地址：https://opentelemetry.io/docs/zero-code/obi/

OBI 1.0 把 Config v2 作为配置契约，Config v1 仍保留向后兼容，但已经冻结，不再获得新功能。迁移的重点不是把字段名称换一遍，而是确认旧配置的选择规则、导出方式、资源属性和环境变量覆盖，在新结构中仍表达了同样的运行意图。

先确认你迁移的是哪一种配置

OBI 的迁移文档区分 standalone 配置和 Collector receiver 配置。前者输入完整的 OBI Config v1 文件；后者只把 receiver component body 交给迁移命令，不能把完整的 Collector 配置文件原样传进去。两种模式的命令不同，混用时容易得到结构看似正确、实际无法嵌入的位置。

还要把“文件里写的配置”和“部署时真正生效的配置”分开。环境变量、命令行参数、Helm values、Kubernetes manifest 和 secret 注入都可能覆盖文件值，而迁移命令只读取你传入的文件。因此开始前至少记录 OBI 二进制版本或镜像摘要、Config v1 文件、启动参数以及环境变量清单。

用迁移命令生成一份可回滚的 Config v2

不要覆盖现有的 v1 文件，也不要把生成结果直接写入仓库的正式配置目录。下面的命令把标准输出和标准错误分开保存，并给临时目录设置较严格的权限。代码展示的是迁移写法，不代表本机已经执行过这些命令。

# 为迁移结果创建只允许当前用户访问的临时目录。
umask 077
migration_dir="$(mktemp -d)"

# 标准输出保存 Config v2，标准错误保存迁移报告，便于分别审阅。
obi config migrate ./obi-v1.yaml \
  > "${migration_dir}/obi-v2.yaml" \
  2> "${migration_dir}/migration-report.txt"

# 退出码为 0 才继续使用生成文件；1 是迁移失败，2 是命令参数错误。
status=$?
if [ "$status" -ne 0 ]; then
  # 保留报告路径，让人工处理具体的 v1 字段，而不是盲目重试。
  echo "migration failed, see ${migration_dir}/migration-report.txt" >&2
  exit "$status"
fi

# 迁移成功后再检查生成的 Config v2 结构。
obi config validate "${migration_dir}/obi-v2.yaml"

成功报告会以 migrated v1 config to OBI config v2 开头；失败报告会以 migration failed: 开头。这里把报告单独留存很重要，因为它不仅告诉你“失败”，还会指出需要人工改写的 Config v1 字段。

Config v1 到 v2，主要变化是配置边界

迁移工具会把旧配置拆入更明确的区域。发现规则通常进入 extensions.obi.capture.policy 和 extensions.obi.capture.rules，应用协议进入 capture.instrumentation，运行时探针进入 capture.runtimes；网络采集、eBPF 批处理、增强信息和 trace-log correlation 也各自拥有独立边界。

一个容易被忽略的行为差异是默认采集范围：没有选择字段的 Config v1 会关闭应用采集，而生成的 Config v2 默认包含 workload。迁移器会设置 default_action: exclude 尽量保留旧行为；不要在 canary 之前随意重排规则或删除这些显式默认值。

迁移报告提示失败时，优先处理这几类字段

并非所有 v1 语义都能一对一搬到 v2。比如 service_name 和 service_namespace 在 standalone OBI 中应改成顶层 resource 属性；Prometheus 的 export.path 没有可移植的 Config v2 对应字段，需要按实际 Collector 或 Prometheus exporter 的能力重做。

selector 也是风险集中区。Config v2 的 include rule 不会继承前一条规则中省略的 refinement；如果旧规则依赖这种继承，迁移器会失败。此时要把每条适用规则改成自包含的 exports 和 routes，再处理重叠顺序，而不是只把错误字段删掉。

# standalone OBI 的服务身份放在顶层 resource，而不是继续保留旧字段。
resource:
  attributes:
    - name: service.name
      value: checkout
    - name: service.namespace
      value: shop

# 环境变量覆盖要显式落到 Config v2 的对应位置，并保留默认值。
extensions:
  obi:
    version: '2.0'
    capture:
      engine:
        batching:
          wakeup_len: ${OTEL_EBPF_BPF_WAKEUP_LEN:-500}

上面的环境变量示例说明的是配置表达方式，不是推荐的固定数值。迁移命令不会自动把运行时环境变量映射成 Config v2 字段，也不会替你决定哪些覆盖应该继续保留。对敏感值尤其要审阅生成文件，避免把解析后的秘密提交进 Git。

Collector receiver 模式不要套用 standalone 命令

如果 OBI 作为 Collector receiver 使用，输入应是 receiver 本身的 Config v1 body，命令要增加 --mode=receiver。迁移完成并通过检查后，再把生成的 component body 放到 Collector 配置的 receivers.obi 下。

# receiver 模式只迁移 OBI receiver body，不读取完整 Collector 配置。
obi config migrate --mode=receiver ./obi-receiver-v1.yaml \
  > ./obi-receiver-v2.yaml \
  2> ./migration-report.txt

# receiver 模式的校验也要保留同一个模式参数。
obi config validate --mode=receiver ./obi-receiver-v2.yaml

standalone 的 Config v2 可能有 extensions.obi.capture 这一层，而 receiver component body 的字段会直接位于 version 旁边。把 standalone 文件直接粘进 receivers.obi，或者把 receiver body 当成完整配置执行，都会让层级错误变得难排查。

迁移后的正确落地方式是先灰度再扩大

obi config validate 检查的是 YAML 结构和 OBI 支持的 Config v2 字段，不会启动 OBI、连接 exporter、附加 eBPF 程序，也不会替你验证内核能力。因此通过 validate 只是“配置可以被接受”的一个信号，不等于线上行为已经等价。

更安全的发布顺序是：保留 v1 文件和旧版本二进制；选一个代表性实例；部署 v2；对比 trace、metric、service dependency、日志关联和数据量；确认没有额外的敏感字段采集或 cardinality 激增后，再逐步扩大。任何差异都先回到旧配置，而不是在大范围 rollout 中临时修改规则。

最后把迁移清单固定下来

OBI 1.0 的 Config v2 迁移可以概括为：文件转换交给 obi config migrate，结构检查交给 obi config validate，语义等价交给人工对照和 canary。最不能省略的是外部覆盖清单、敏感值审阅、selector 规则顺序以及旧版本回滚入口。

如果只是想尝试 OBI 的新版本，可以先在一个有代表性的 Linux 主机或 Kubernetes 工作负载上使用 v2；如果你依赖复杂的 Prometheus、selector refinement 或自定义 exporter，则应先读完迁移报告，再决定是否需要手工重构，而不是把“命令成功”当成“业务行为完全不变”。

Config v1 还能继续用吗？

可以继续兼容运行，但 Config v1 已冻结。新配置能力和更清晰的配置契约应以 Config v2 为准；长期维护的部署不建议继续扩大 v1 的使用范围。

为什么迁移输出里会出现秘密值？

迁移命令会解析源文件里的替换表达式，所以生成结果可能包含展开后的秘密。应把输出写到权限受限的临时目录，审阅后再决定哪些值通过环境变量或 secret 注入。

validate 通过后能直接全量发布吗？

不能仅凭 validate 决定全量发布。它不启动 OBI，也不检查内核能力和 exporter 连通性；还需要单实例 canary，对比实际遥测和采集量，并保留 v1 回滚路径。

本文依据 OpenTelemetry OBI 1.0 发布说明、Config v1/v2 迁移文档和官方配置示例整理：https://opentelemetry.io/blog/2026/obi-v1-release/、https://opentelemetry.io/docs/zero-code/obi/configure/migrate-to-config-v2/、https://opentelemetry.io/docs/zero-code/obi/configure/config-v2/。