从 MeshConfig 迁移到 Istio Telemetry API：提升网格观测性和灵活性

通过迁移到 Telemetry API 配置 SkyWalking 提供商，从而提升 Istio 网格的追踪能力和灵活性。

阅读原文请转到：https://jimmysong.io/blog/migrate-to-istio-telemetry-api/

Istio 的 Telemetry API 是替代传统 MeshConfig 遥测配置的现代化方式，提供了更灵活的工具来定义服务网格中的 Tracing 、Metrics 和 Access Logging 。相比传统的 EnvoyFilter 和 MeshConfig，Telemetry API 更具模块化、动态更新和跨层次配置能力。

在本篇中，我们将详解如何使用 Telemetry API 配置 Istio 遥测功能，涵盖 Tracing、Metrics 和 Logging 的具体实现，同时展示如何迁移过时的 MeshConfig 配置。

Telemetry API 发展历程

Istio 的遥测能力在早期版本中依赖于较为传统的配置方法，如 Mixer 和 MeshConfig 的 configOverride，这些方法虽然能够满足基本需求，但在复杂场景下显得力不从心。为了解决这些问题，Istio 引入了基于 CRD 的 Telemetry API。

关键版本更新

为了帮助读者了解 Telemetry API 的进化过程，以下是一些重要版本的更新信息：

1. Istio 1.11：引入 Telemetry API（Alpha），提供了基本的指标和日志自定义功能。
1. Istio 1.13：支持 OpenTelemetry 日志记录、自定义追踪服务名称，以及更强的日志过滤功能。
1. Istio 1.18 ：默认不再安装 Prometheus 的 EnvoyFilter，完全依赖 Telemetry API 定义遥测行为。
1. Istio 1.22：Telemetry API 升级为稳定版（v1），全面支持生产环境需求。

为什么迁移到 Telemetry API？

尽管传统的 MeshConfig 和 EnvoyFilter 提供了基础的遥测能力，但它们的配置方式在灵活性、动态性和扩展性方面存在诸多限制。为了更清晰地理解这些局限性，我们将从几个关键维度展开说明。

使用 MeshConfig 和 EnvoyFilter 的复杂性

在介绍具体问题之前，我们先了解一下 MeshConfig 和 EnvoyFilter 的定位：MeshConfig 适用于全局配置，而 EnvoyFilter 用于细粒度的自定义。但正是这种分工，导致了它们在管理上的复杂性。

1. 配置方式分散

• MeshConfig 用于集中定义全局网格行为，例如访问日志路径、追踪采样率和指标维度。虽然适合简单场景，但无法满足命名空间级或工作负载级的需求。

• EnvoyFilter 则可以覆盖或扩展 Envoy 的配置，允许更细粒度的控制。但这种方式直接操作 Envoy 内部结构（xDS 字段），配置语言复杂且容易出错。示例：通过 MeshConfig 配置访问日志

go 复制代码

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    accessLogFile: /dev/stdout

问题：

示例：通过 EnvoyFilter 自定义指标

go 复制代码

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: custom-metric-filter
  namespace: mynamespace
spec:
  workloadSelector:
    labels:
      app: myapp  # 选择特定的工作负载
  configPatches:
    - applyTo: HTTP_FILTER
      match:
        context: SIDECAR_INBOUND  # 匹配入站流量
      patch:
        operation: ADD
        filterClass: STATS  # 指定为统计过滤器
        value:
          name: istio.request_operation  # 自定义指标名称
          typed_config:
            "@type": type.googleapis.com/udpa.type.v1.TypedStruct
            type_url: type.googleapis.com/envoy.extensions.filters.http.wasm.v3.Wasm
            value:
              config:
                configuration: |
                  "attributes": [
                    {
                      "output_attribute": "istio_operationId",
                      "match": [
                        {
                          "value": "GetReviews",
                          "condition": "request.url_path == '/reviews' && request.method == 'GET'"
                        }
                      ]
                    }
                  ]
              vm_config:
                runtime: envoy.wasm.runtime.null
                code:
                  local: { inline_string: "envoy.wasm.attributegen" }

问题：

• 配置语法复杂且冗长，需深入理解 Envoy 的结构。
• 易于出错，调试和维护成本高。

• 无法为特定服务或命名空间设置不同的日志路径。
• 需要重新应用整个配置，动态性不足。

2. 动态性不足

虽然现代微服务环境强调动态调整配置，但 MeshConfig 和 EnvoyFilter 的动态性支持有限：

• MeshConfig：修改配置通常需要重启代理或重新应用整个配置，导致服务中断。
• EnvoyFilter：更新流程复杂，调整单个参数也需重新部署相关代理实例。

3. 多租户支持困难

在多租户环境中，针对不同命名空间或工作负载自定义遥测配置非常重要。然而：

• MeshConfig：无法针对命名空间或工作负载进行差异化设置。
• EnvoyFilter：需要编写多个过滤器配置，增加了管理复杂性。

4. 难以扩展和调试

• MeshConfig 和 EnvoyFilter 对新需求（如 OpenTelemetry）支持较慢。
• EnvoyFilter 的调试难度高，需要深入分析 Envoy 日志和行为。

弃用传统 MeshConfig 的遥测配置

鉴于上述局限性，Istio 社区已经将传统的 MeshConfig 遥测配置标记为弃用。以下示例展示了这些配置的使用方式及其不足之处：

• Access Logging 配置：
go 复制代码
```
meshConfig:
  accessLogFile: /dev/stdout
```

• Trace Sampling 配置：

go 复制代码

meshConfig:
  enableTracing: true
  extensionProviders:
  - name: zipkin
    zipkin:
      service: zipkin.istio-system.svc.cluster.local
      port: 9411

• 自定义 Metrics 标签：

go 复制代码

meshConfig:
  telemetry:
    v2:
      prometheus:
        configOverride:
          inboundSidecar:
            metrics:
              - name: requests_total
                dimensions:
                  user-agent: request.headers['User-Agent']

通过上述例子可以看出，这些配置的灵活性和扩展性明显不足，难以应对复杂的生产环境需求。

Telemetry API 的优势

在传统配置方式的基础上，Telemetry API 带来了多项改进，使其更适合现代化的服务网格管理需求：

1. 模块化设计：Tracing、Metrics 和 Access Logging 独立配置，清晰简洁。
1. 动态更新：支持实时更新配置，无需重启代理。
1. 层级化支持：允许全局、命名空间和工作负载级别的配置覆盖。
1. 简单直观：使用声明式语法，无需深入理解 Envoy 的内部结构。

Istio Telemetry API 配置示例

全局配置示例

为帮助理解 Telemetry API 的具体使用，我们以全局配置示例作为开始：

go 复制代码

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: mesh-default
  namespace: istio-system
spec:
  accessLogging:
  - providers:
    - name: envoy # better to use a built-in one
  tracing:
  - providers:
    - name: "skywalking"
    randomSamplingPercentage: 100.00
  metrics:
  - overrides:
    - match:
        metric: REQUEST_COUNT
        mode: CLIENT
      tagOverrides:
        x_user_email:
          value: |
            'x-user-email' in request.headers ? request.headers['x-user-email'] : 'empty'
    providers:
    - name: prometheus

使用 Telemetry API 配置 SkyWalking

我们再以配置 SkyWalking 的采样率和 span tag 为例，演示如何使用 Telemetry API。

检查 Istio 版本与 CRD

• 如果使用 Istio 1.22 或更高版本，使用 telemetry.istio.io/v1。
• 对于 Istio 1.18 至 1.21 的用户，使用 telemetry.istio.io/v1alpha1。

通过以下命令检查 Telemetry API 的 CRD 是否已安装：

go 复制代码

kubectl get crds | grep telemetry

部署 SkyWalking

在集群中部署 SkyWalking OAP 服务：

go 复制代码

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.24/samples/addons/extras/skywalking.yaml

检查服务状态：

go 复制代码

kubectl get pods -n istio-system -l app=skywalking-oap

配置 MeshConfig 添加 SkyWalking 提供商

在 Istio 的 MeshConfig 中定义 SkyWalking 提供商。

go 复制代码

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio
  namespace: istio-system
data:
  mesh: |-
    enableTracing: true
    extensionProviders:
    - name: "skywalking"
      skywalking:
        service: "tracing.istio-system.svc.cluster.local"
        port: 11800

使用 Telemetry API 配置采样率

通过 Telemetry API，将 SkyWalking 设置为默认的 Tracing 提供商，并定义采样率。

你可以从使用 Telemetry API 从多个层级配置采样率，为了节约篇幅，我们仅演示在命名空间范围配置采样率，其他层级的配置请参考 Telemetry API[1]。

go 复制代码

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: namespace-override
  namespace: default
spec:
  tracing:
  - providers:
      - name: skywalking
    randomSamplingPercentage: 50
    customTags:
      env:
        literal:
          value: production

说明：

• providers.name：指定 SkyWalking 为默认的 Tracing 提供商。
• randomSamplingPercentage：覆盖命名空间级别配置，设置 50% 的采样率。
• customTags：为所有追踪数据添加 env=production 标签。

验证配置

访问网格中的服务（如 Bookinfo[2] 示例应用）生成流量：

go 复制代码

curl http://$GATEWAY_URL/productpage

查看追踪数据：

go 复制代码

istioctl dashboard skywalking

打开浏览器访问 http://localhost:8080，在追踪界面中查看生成的追踪信息。
Skywalking Tracing

点击一个span后，你可以看到其中的追加的 env: production tag。
Skywalking Span

总结

Telemetry API 通过其模块化设计、动态更新和多层级支持，大幅降低了服务网格中遥测配置的复杂性。相比 MeshConfig 和 EnvoyFilter，Telemetry API 是一套更灵活、高效的现代化解决方案。我们强烈推荐迁移到 Telemetry API，以充分利用其功能。

引用链接

[1] Telemetry API: https://istio.io/latest/docs/tasks/observability/telemetry/
[2] Bookinfo: https://istio.io/latest/docs/examples/bookinfo/