Istio 可观测性 Addons 实战指南：基于 samples/addons 快速部署 Prometheus、Grafana、Kiali 与分布式链路追踪

samples/addons/ 目录集中存放了与 Istio 集成的观测性组件示例部署清单，用于快速搭建一套可观测服务网格的基础设施。本文以 samples/addons/README.md 为核心骨架，结合仓库内每个 addon 的 YAML 清单逐项展开，帮助读者理解这些应用如何与 Istio 打通数据链路、如何在 istio-system 命名空间一键安装或选择性安装，以及默认参数、端口与常见注意事项，做到"既能跑起来，也明白为什么"。

定位与适用范围：这些应用不是 Istio，但让 Istio 更好用

仓库在 samples/addons/README.md 的开篇即明确：本目录包含的是与 Istio 集成的各类 addon 的示例部署。这些应用本身不属于 Istio 发行的一部分，却是充分发挥 Istio 可观测性能力（指标、日志、链路追踪、服务拓扑）的关键组件。换句话说，Istio 负责 Connect, secure, control, and observe services，而这些 addon 承担了 observe 环节中"指标存储、可视化、链路聚合"的具体工作。

需要特别注意的是适用边界：

• 这里的部署形态以"快速跑起来"为优先目标，经过专门优化，不一定适合生产环境。README 明确提示，若需要生产级部署，应参考各 addon 官方文档自行安装其生产级版本。
• 全部清单默认部署到 istio-system 命名空间，且工作负载上都带 sidecar.istio.io/inject: "false" 标签（详见各 YAML 中的 pod 模板），即这些监控组件自身不注入 Istio sidecar，避免观测系统被网格策略循环影响。

目录结构由两个平面组成，本文会依次展开：

samples/addons/
├── README.md                 # 本文的母文档
├── prometheus.yaml           # 指标采集与存储
├── grafana.yaml              # 指标可视化与官方 Istio 仪表盘
├── kiali.yaml                # 服务网格拓扑与健康观测台
├── jaeger.yaml               # 默认分布式链路追踪后端
├── loki.yaml                 # 日志聚合（Grafana 数据源之一）
└── extras/
    ├── prometheus-operator.yaml       # ServiceMonitor / PodMonitor 替代方案
    ├── prometheus-secure-metrics.yaml # 基于 mTLS 的安全指标采集替代方案
    ├── skywalking.yaml                # 另一可选链路追踪后端
    └── zipkin.yaml                    # 可替换 Jaeger 的追踪后端

快速开始：一条命令部署全部 addon

README 提供两种部署方式。一键部署全部 addon：

kubectl apply -f samples/addons

选择性部署单个 addon（例如只装 Prometheus）：

kubectl apply -f samples/addons/prometheus.yaml

两条命令都要求当前目录位于 Istio 仓库根目录下。kubectl apply -f samples/addons 会读取整个目录，其中 extras/ 子目录内的可选组件默认不会被安装，这也是后续"用 Zipkin 替换 Jaeger"等场景能够做到选择性安装的前提。

从 manifests/addons/gen.sh 可以印证这些 YAML 的实际来源：它们并非手写，而是仓库维护者使用 helm template 渲染各上游 Helm chart（如 prometheus-community 的 prometheus chart 28.13.0、Grafana 官方 chart、Kiali 官方 chart、Loki chart），再配合 manifests/addons/ 下的 values 文件与预生成仪表盘 JSON 产物，最终固化为 samples/addons/*.yaml 的"开箱即用快照"。因此读者在集群中看到的多对象 YAML 中带有 # Source: <chart>/templates/... 注释即源于此。

Prometheus：服务网格指标采集与存储

作用与定位

Prometheus 是开源监控系统与时序数据库，与 Istio 配合用于记录反映 Istio 自身及网格内应用健康状态的指标。采集到的指标可进一步交给 Grafana、Kiali 等可视化工具消费。

仓库清单中的实现细节

查看 prometheus.yaml 可以看到部署的核心组成（helm chart prometheus-28.13.0、Prometheus 镜像 prom/prometheus:v3.10.0，约 550 行），对象包括：

对象	名称	说明
ServiceAccount	prometheus	Pod 运行身份，用于向 Kubernetes API 鉴权拉取服务发现信息
ClusterRole / ClusterRoleBinding	prometheus	授予对 nodes、services、endpoints、endpointslices、pods、ingresses、configmaps 等资源的 get/list/watch 权限，以及 /metrics 非资源路径访问权
ConfigMap	prometheus	内含完整 prometheus.yml 抓取配置
Service	prometheus	集群内 ClusterIP:9090，供 Grafana（http://prometheus:9090）等消费
Deployment	prometheus	Recreate 策略单副本，含 prometheus-server 与配置热加载容器 prometheus-server-configmap-reload（监听配置变更调用 /-/reload）

其核心抓取配置 prometheus.yml 值得展开说明：

• 全局参数：scrape_interval: 15s、evaluation_interval: 1m、scrape_timeout: 10s；存储保留 --storage.tsdb.retention.time=15d。
• 内置抓取任务覆盖 Kubernetes 常规目标：kubernetes-api-servers（HTTPS + ServiceAccount token 鉴权）、kubernetes-nodes 与 kubernetes-nodes-cadvisor（节点与 cadvisor 指标）、kubernetes-pods（按 prometheus.io/scrape: "true" 注解发现应用 Pod）、kubernetes-service-endpoints、kubernetes-services（对接 blackbox 探活）、prometheus 自身与 prometheus-pushgateway。
• 与 Istio 对接的关键：kubernetes-pods 任务通过 relabel 保留 prometheus.istio.io/... 及常规 prometheus.io/* 注解的 Pod 目标，并将命名空间、Pod 名、节点等元数据落为 namespace、pod、node 标签。Istio sidecar 的 Envoy 指标端点 :15020/stats/prometheus 正是通过该任务被发现的。另有 kubernetes-pods-slow / kubernetes-service-endpoints-slow 任务，把带 prometheus.io/scrape_slow: "true" 的目标以 5m 间隔、30s 超时单独采集，避免慢端点拖垮常规采集。

安全采集替代方案

如果希望指标抓取走 mTLS，仓库提供 prometheus-secure-metrics.yaml 作为独立替代（两文件定义了同名资源，切勿同时应用）。其头部注释清晰说明了比普通版本多出的能力：

• 为 Prometheus 注入 Istio sidecar 以签发工作负载证书（通过 OUTPUT_CERTS 写入 /etc/istio-certs 供 prometheus-server 做 mTLS 客户端认证），同时以 INBOUND_CAPTURE_PORTS: "" 关闭入站流量劫持，使 sidecar 仅承担证书供给角色；
• 新增两个预设 mTLS 抓取任务：istio-secure-merged-metrics 抓取 prometheus.istio.io/secure-port 注解端口（该注解由注入器在配置 ENVOY_SECURE_MERGED_METRICS_PORT 时自动写入），istio-secure-envoy-metrics 抓取需手动设置的 prometheus.istio.io/secure-envoy-port 注解。

安装方式（与默认版本二选一）：

kubectl apply -n istio-system -f samples/addons/extras/prometheus-secure-metrics.yaml

Grafana：官方仪表盘与多数据源接线

作用与定位

Grafana 是开源监控可视化方案，用于为 Istio 配置仪表盘。这一份约 1100 行的清单由 Grafana chart 9.2.2（镜像 grafana/grafana:12.0.1）渲染而成，并内嵌了 Istio 官方仪表盘 JSON 与预置数据源，是理解"Istio 指标如何直接可见"的最佳样本。

提供哪些仪表盘

README 列出了 6 块核心仪表盘，结合仓库内 istio-grafana-dashboards 与 istio-services-grafana-dashboards 两个 ConfigMap 中的实际 JSON（见 grafana.yaml 后半部分），其含义对应关系如下：

仪表盘	关注内容	仓库内对应 JSON 键
Mesh Dashboard	网格内全部服务的总览（流量、成功率、HTTP/gRPC 与 TCP 工作负载表、组件版本）	istio-mesh-dashboard.json
Service Dashboard	单个服务的指标细分（按服务、来源工作负载、mTLS 与否下钻）	istio-service-dashboard.json
Workload Dashboard	单个工作负载的指标细分	istio-workload-dashboard.json
Performance Dashboard	网格资源占用（每 1k rps 的 vCPU、内存、吞吐）	istio-performance-dashboard.json
Control Plane Dashboard	控制面健康与性能（Istiod xDS push、内存/CPU/Goroutine、Webhook 校验与注入成功率）	pilot-dashboard.json
WASM Extension Dashboard	网格级 WebAssembly 扩展运行时与加载状态	istio-extension-dashboard.json

此外仓库还随 ztunnel-dashboard.json（位于 istio-grafana-dashboards）提供面向 ambient 模式数据面组件 ztunnel 的进程/网络/操作面板。仪表盘查询大量基于 istio_requests_total、istio_request_duration_milliseconds_bucket、istio_tcp_*_bytes_total、istio_build 等 Istio 标准指标，并对 connection_security_policy="mutual_tls" 场景单独成图，可直观判断流量是否真正启用了 mTLS。

数据源与供给机制

Grafana 的 ConfigMap 中 datasources.yaml 预置了两个数据源：

• Prometheus（默认数据源）：http://prometheus:9090，timeInterval: 15s；
• Loki：http://loki:3100（配合下方 Loki addon 使用）。

dashboardproviders.yaml 注册两个基于文件的 provider，folder 均为 istio：istio 与 istio-services，其路径 /var/lib/grafana/dashboards/istio 与 /var/lib/grafana/dashboards/istio-services 分别挂载自上面两个仪表盘 ConfigMap——这就是"apply 后打开 Grafana 即可看到全部 Istio 面板"的实现原理。Dashboard JSON 分为两组 ConfigMap，是为了规避单个 ConfigMap 的尺寸上限（详见 manifests/addons/gen.sh 中的注释与 compressDashboard 逻辑）。

默认访问凭据

仓库清单中的部署对环境变量做了如下设定，仅适合快速体验：

• GF_AUTH_ANONYMOUS_ENABLED=true、GF_AUTH_ANONYMOUS_ORG_ROLE=Admin（匿名即管理员）；
• GF_AUTH_BASIC_ENABLED=false；
• 管理员账号/密码为 admin/admin（GF_SECURITY_ADMIN_USER / GF_SECURITY_ADMIN_PASSWORD）。

Kiali：服务网格观测与配置台

Kiali（chart kiali-server-2.31.0，镜像 quay.io/kiali/kiali:v2.31）是 Istio 的观测控制台：通过推断服务网格拓扑帮助理解网格结构，同时给出网格健康状况、详细指标；可与 Grafana 做基础集成以便发起高级查询，并通过 Jaeger 获得分布式追踪视图。

从清单的 config.yaml 可以归纳其关键配置：

• 认证策略：auth.strategy: anonymous（匿名访问），适合快速试用；生产场景应改为 openid / openshift / token 等策略。
• 服务地址：server.port: 20001、web_root: /kiali，Service 暴露 20001（http）与 9090（http-metrics）两个端口，Deployment 探针均指向 /kiali/healthz。
• 数据源接线：external_services.prometheus.enabled: true；tracing.enabled: false 为默认值，接入 Jaeger 需据此调整。istio.root_namespace: istio-system。
• 资源画像：请求 cpu: 10m / memory: 64Mi、上限 memory: 1Gi，可用于评估在自身集群中的开销。
• 权限模型：配套 ClusterRole 覆盖核心资源（pods/services/namespaces/deployments/statefulsets 等），并授予对 networking.istio.io、security.istio.io、extensions.istio.io、telemetry.istio.io 等全部 CRD 以及 gateway.networking.k8s.io 各类 Gateway API 资源的读写与 watch 权限（cluster_wide_access: true），这正是 Kiali 能展示拓扑、下发/校验配置的基础。清单中 pod_annotations 里的 holdApplicationUntilProxyStarts 提示 Kiali 自身亦可被纳入 sidecar 管控，只是本示例显式禁用了注入。

Jaeger：默认的端到端分布式追踪后端

作用

Jaeger 是开源端到端分布式追踪系统，用于监控与排查复杂分布式系统中的事务。README 归纳其典型用途：

• 分布式上下文传播
• 分布式事务监控
• 根因分析
• 服务依赖分析
• 性能 / 延迟优化

部署细节与端口矩阵

本仓库的 Jaeger 清单使用新版镜像 jaegertracing/jaeger:2.17.0，以 OTel Collector 框架承载，配置完全由 ConfigMap jaeger/config.yaml 驱动（注释标明其组合自上游 badger 与 all-in-one 样例配置）。值得注意的机制包括：

• 统一接收面：同时启用 otlp（gRPC 4317 / HTTP 4318）、jaeger（14250 gRPC、14268 thrift_http、6831/6832 thrift_compact/binary）与 zipkin（9411）接收器，链路进入后经 batch 处理器写入 badger_storage（ephemeral: false，落盘到 /badger，注意这是 emptyDir 卷，Pod 重建即清空）。
• 远程采样：通过 remote_sampling 扩展暴露 HTTP 5778 / gRPC 5779，默认采样概率配置为 1（全量采样），便于体验阶段拿到完整链路；生产可按需改为 adaptive 策略。
• 服务命名约定（对 Istio 至关重要）：清单特意创建了一个名为 zipkin 的 Service（9411 端口、selector 指向 Jaeger Pod），并在注释中说明："Jaeger 实现了 Zipkin API。为支持追踪后端互换，我们使用名为 Zipkin 的 Service"。Istio 默认按 zipkin 服务名上报 tracing 数据，因此无论背后跑的是 Jaeger 还是真实 Zipkin，网格侧配置无需改动。

清单中的服务与端口速查：

Service	端口	用途
tracing	80 → target 16686	Jaeger Query Web UI（另暴露 16685 gRPC 查询）
zipkin	9411	Istio 上报 Zipkin API 的固定入口（selector: app=jaeger）
jaeger-collector	14268 / 14250 / 9411 / 4317 / 4318	collector 各协议入口

用 Zipkin 替换 Jaeger

Zipkin 是分布式追踪系统，负责采集与检索延迟定位所需时序数据。它作为 Jaeger 的替代品，默认不随 samples/addons 部署。README 给出的替换步骤：

kubectl apply -f samples/addons/extras/zipkin.yaml

随后删除已无用的 Jaeger 部署：

kubectl delete deployment jaeger

或者一开始就跳过 Jaeger——这正是 README 建议的选择性安装（见"快速开始"一节）。替换清单会创建镜像 openzipkin/zipkin-slim:3.4.0 的 Deployment（内存存储 STORAGE_METHOD=mem，重启即丢数据）以及同名的 tracing（80→9411）与 zipkin（9411）Service，保证 Istio 侧上报入口不变。另可参考 extras/skywalking.yaml（Apache SkyWalking OAP 9.7.0，gRPC 11800 / HTTP 12800，同样暴露名为 tracing 的服务），了解同类后端在仓库中的接线模式。

Loki：网格日志聚合

虽然 README 正文未单列，但 loki.yaml 与 Grafana 的 Loki 数据源是配套出现的（Grafana datasources.yaml 中第二数据源即指向 http://loki:3100）。清单部署 Grafana Loki 3.6.11 单二进制模式：StatefulSet 单副本并申请 10Gi PVC（volumeClaimTemplates），HTTP 3100 / gRPC 9095 / memberlist 7946，以 -target=all 运行；配套 k8s-sidecar 容器负责把带 loki_rule 标签的 ConfigMap 同步为告警规则文件。启用日志聚合后，可在 Grafana 中将服务网格日志与指标、追踪做关联分析。

Prometheus Operator 路线：ServiceMonitor 与 PodMonitor

方案说明

Prometheus Operator 负责管理与运维 Prometheus 实例。作为标准 Prometheus 部署的替代路线，仓库提供：

• 一个 ServiceMonitor（istio-component-monitor）：通过 istio: pilot 标签匹配控制面 Service，抓取其 http-monitoring 端口（即 istiod 的指标端点）；
• 一个 PodMonitor（envoy-stats-monitor）：通过 namespaceSelector.any: true 发现全部命名空间中容器名为 istio-proxy、且带 prometheus.io/scrape 注解的 Pod，按 15s 间隔抓取 Envoy 的 /stats/prometheus。

使用前提是集群中已部署 Prometheus Operator，然后执行：

kubectl apply -f samples/addons/extras/prometheus-operator.yaml

三条官方注意事项（务必逐条核对）

README 以 Note / Warning 标注了三条约束：

Note：示例 PodMonitor 依赖已开启的 metrics merging（指标合并）。该能力在 Istio 中默认开启。

Note：这里的配置只针对 Istio 部署，不会抓取 Kubernetes 组件的指标；集群监控（kubelet、kube-state-metrics 等）需另行配置。

Warning：当示例 PodMonitor 用于 OpenShift Monitoring 时，必须在所有存在 istio-proxy 的命名空间中创建它——因为 OpenShift 出于租户隔离会忽略 namespaceSelector。

访问各观测台 UI

仓库的 istioctl 内置了便捷的端口转发命令。在 istioctl/pkg/dashboard 中可以看到它根据标签选择器定位 addon Pod，并在本地端口转发后自动打开浏览器（browser 默认 true、绑定地址可配）。各子命令与默认端口为：

子命令	默认本地端口	定位方式
istioctl dashboard prometheus	9090	app.kubernetes.io/name=prometheus
istioctl dashboard grafana	3000	app.kubernetes.io/name=grafana
istioctl dashboard kiali	20001	app.kubernetes.io/name=kiali
istioctl dashboard jaeger	16686	app=jaeger
istioctl dashboard zipkin	9411	app=zipkin
istioctl dashboard skywalking	8080	skywalking 相关 Pod

支持短别名 istioctl dash <addon> 与 istioctl d <addon>。不依赖 istioctl 时，也可用通用方式手动转发，例如：

# 方式一：istioctl 子命令
istioctl dashboard grafana

# 方式二：通用 kubectl port-forward（以 Grafana 为例）
kubectl -n istio-system port-forward svc/grafana 3000:3000
# 浏览器访问 http://localhost:3000（本示例清单为匿名 Admin）

# 以 Kiali 为例
kubectl -n istio-system port-forward svc/kiali 20001:20001
# 浏览器访问 http://localhost:20001/kiali

如何升级与重新生成这些清单

这些快照不是一成不变的：上游 addon 发布新版本后，仓库通过 manifests/addons/gen.sh 重新渲染（依赖 helm、jsonnet/jb 等工具），其流程包括：

1. 以 helm template + manifests/addons/values-*.yaml 渲染 prometheus / grafana / kiali / loki 基础资源；
2. 用 jsonnet 从 manifests/addons/dashboards 下的 .libsonnet 生成 mesh、pilot、ztunnel 等动态仪表盘，再连同 istio-*.json 静态仪表盘 jq -c 压缩为单行；
3. 用 kubectl create configmap --dry-run=client -o yaml 将仪表盘固化到 istio-grafana-dashboards 与 istio-services-grafana-dashboards 两个 ConfigMap，最终拼装输出到 samples/addons。

因此在生产或长期运行环境里，建议不要直接修改这些生成文件，而是调整上方 values 与仪表盘源文件后重新生成，或干脆基于各上游 chart 自行安装生产级实例。

常见问题与排查思路

• apply 后 Dashboard 仍是空：优先确认 Prometheus 是否已采集到数据。可打开 Prometheus 查询 istio_requests_total；若空，检查业务命名空间是否开启注入、业务 Pod 是否带 prometheus.io/scrape: "true" 注解，并确认网格侧已启用对应的指标（服务端默认可观测）。另需确认 Grafana 数据源 Prometheus 指向 http://prometheus:9090 可达。
• 想换追踪后端：默认上报目标是 zipkin 服务，Jaeger、Zipkin、SkyWalking 的 extras 均实现了该固定入口，按上文替换步骤操作即可；注意内存/emptyDir 存储的组件在重启后历史链路会丢失。
• 抓不到某些 Pod 指标：对照 prometheus.yaml 的 relabel 规则，检查 Pod 是否处于 Running（规则会丢弃 Pending/Succeeded/Failed/Completed），以及注解是否拼写正确（prometheus.io/scrape、prometheus.io/port 等）。
• 使用 Prometheus Operator 路线却无数据：依次核对三条官方注意事项——指标合并是否开启、是否只抓了 Istio 范围、在 OpenShift 上是否已把 PodMonitor 复制到每个存在 istio-proxy 的命名空间。

结语

istioctl 服务网格的数据面与控制面固然重要，但"看得见"才是可运维性的前提。通过 samples/addons 这套开箱即用的清单，可以在几分钟内获得指标（Prometheus）、可视化（Grafana 官方仪表盘与 Kiali 拓扑）、追踪（Jaeger / Zipkin / SkyWalking）与日志（Loki）的完整观测栈。理解每个清单背后的端口约定、数据源接线、固定 Service 命名（zipkin、tracing）与权限模型，既能保证"快速跑通"，也为日后替换为生产级部署或迁移到 Prometheus Operator 体系保留了清晰的决策依据。