---

name: setup-service-mesh description: > 在 Kubernetes 集群中部署和配置服务网格（Istio 或 Linkerd），以实现 安全的服务间通信、流量管理、可观测性和策略执行。涵盖安装、mTLS 配置、流量路由、熔断器和与监控工具的集成。适用于微服务需要加密 服务间通信、金丝雀或 A/B 部署需要细粒度流量控制、无需修改应用即可 实现所有服务交互的可观测性，或需要一致的熔断和重试策略的场景。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: devops complexity: advanced language: multi tags: service-mesh, istio, linkerd, mtls, traffic-management, observability, kubernetes locale: zh-CN source_locale: en source_commit: 6f65f316 translator: claude-opus-4-6 translation_date: "2026-03-16"

设置服务网格

部署和配置服务网格，实现安全的服务间通信和高级流量管理。

适用场景

• 微服务架构需要加密的服务间通信
• 需要细粒度流量控制（金丝雀部署、A/B 测试、流量拆分）
• 需要在不修改应用的情况下观测所有服务交互
• 在基础设施层面强制执行安全策略（mTLS、授权）
• 跨服务一致地实现熔断、重试和超时
• 需要分布式追踪和服务依赖图

输入

• 必填：具有管理员权限的 Kubernetes 集群
• 必填：服务网格选择（Istio 或 Linkerd）
• 必填：需要启用服务网格的命名空间
• 可选：监控栈（Prometheus、Grafana、Jaeger）
• 可选：自定义流量管理需求
• 可选：mTLS 的证书机构配置

步骤

完整配置文件和模板请参阅扩展示例。

第 1 步：安装服务网格控制平面

选择并安装服务网格控制平面。

Istio 方案：

curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.20.2 sh -
istioctl install --set profile=production -y
kubectl get pods -n istio-system

Linkerd 方案：

curl -sL https://run.linkerd.io/install | sh
linkerd check --pre
linkerd install --ha | kubectl apply -f -
linkerd check

创建带资源限制和追踪配置的服务网格配置：

# service-mesh-config.yaml (abbreviated)
spec:
  profile: production
  meshConfig:
    enableTracing: true
  components:
    pilot:
      k8s:
        resources: { requests: { cpu: 500m, memory: 2Gi } }
# See EXAMPLES.md Step 1 for complete configuration

预期结果： 控制平面 pod 在 istio-system（Istio）或 linkerd（Linkerd）命名空间中运行。istioctl version 或 linkerd version 显示客户端和服务器版本一致。

失败处理：

• 检查集群是否有足够资源（生产环境至少需要 4 核 CPU、8GB RAM）
• 验证 Kubernetes 版本兼容性（查阅网格文档）
• 检查日志：kubectl logs -n istio-system -l app=istiod 或 kubectl logs -n linkerd -l linkerd.io/control-plane-component=controller
• 检查冲突的 CRD：kubectl get crd | grep istio 或 kubectl get crd | grep linkerd

第 2 步：启用自动 Sidecar 注入

为命名空间配置自动 Sidecar 代理注入。

Istio 方案：

# Label namespace for automatic injection
kubectl label namespace default istio-injection=enabled
kubectl get namespace -L istio-injection

Linkerd 方案：

# Annotate namespace for injection
kubectl annotate namespace default linkerd.io/inject=enabled

使用示例部署测试 Sidecar 注入：

# test-deployment.yaml (abbreviated)
apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: app
        image: nginx:alpine
# See EXAMPLES.md Step 2 for complete test deployment

应用并验证：

kubectl apply -f test-deployment.yaml
kubectl get pods -n default
# Expect 2/2 containers (app + proxy)

预期结果： 新 pod 显示 2/2 容器（应用 + Sidecar 代理）。Describe 输出显示 istio-proxy 或 linkerd-proxy 容器。日志显示代理启动成功。

失败处理：

• 检查命名空间标签/注解：kubectl get ns default -o yaml
• 验证 Mutating Webhook 处于活动状态：kubectl get mutatingwebhookconfiguration
• 检查注入日志：kubectl logs -n istio-system -l app=sidecar-injector（Istio）
• 手动注入进行测试：kubectl get deploy test-app -o yaml | istioctl kube-inject -f - | kubectl apply -f -

第 3 步：配置 mTLS 策略

启用双向 TLS 实现安全的服务间通信。

Istio 方案：

# mtls-policy.yaml (abbreviated)
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: istio-system
spec:
  mtls:
    mode: STRICT
# See EXAMPLES.md Step 3 for per-namespace and permissive mode examples

Linkerd 方案：

# Linkerd enforces mTLS by default for meshed pods
linkerd viz tap deploy/test-app -n default
# Check for 🔒 (lock) symbol

应用并验证：

kubectl apply -f mtls-policy.yaml
# Istio: verify mTLS status
istioctl authn tls-check $(kubectl get pod -n default -l app=test-app -o jsonpath='{.items[0].metadata.name}') -n default

预期结果： 网格化服务之间的所有连接显示 mTLS 已启用。Istio tls-check 显示状态为 "OK"。Linkerd tap 输出显示所有连接带锁图标。服务日志显示无 TLS 错误。

失败处理：

• 检查证书签发：kubectl get certificates -A（cert-manager）
• 验证 CA 是否健康：kubectl logs -n istio-system -l app=istiod | grep -i cert
• 先使用 PERMISSIVE 模式测试，再切换到 STRICT
• 检查无 Sidecar 的服务：kubectl get pods --all-namespaces -o json | jq '.items[] | select(.spec.containers | length == 1) | .metadata.name'

第 4 步：实现流量管理规则

配置智能流量路由、重试和熔断。

创建流量管理策略：

# traffic-management.yaml (abbreviated)
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
spec:
  http:
  - match:
    - uri: { prefix: /api/v2 }
    route:
    - destination: { host: api-service, subset: v2 }
      weight: 10
    - destination: { host: api-service, subset: v1 }
      weight: 90
    retries: { attempts: 3, perTryTimeout: 2s }
# See EXAMPLES.md Step 4 for complete routing, circuit breaker, and gateway configs

Linkerd 流量拆分方案：

apiVersion: split.smi-spec.io/v1alpha2
kind: TrafficSplit
spec:
  service: api-service
  backends:
  - service: api-service-v1
    weight: 900
  - service: api-service-v2
    weight: 100

应用并测试：

kubectl apply -f traffic-management.yaml
# Test traffic distribution
for i in {1..100}; do curl -s http://api.example.com/api/v2 | grep version; done | sort | uniq -c
# Monitor: istioctl dashboard kiali or linkerd viz dashboard

预期结果： 流量按定义权重拆分。熔断器在连续错误后触发。重试在瞬时故障时发生。Kiali/Linkerd 仪表板显示流量可视化。

失败处理：

• 验证目标主机是否可解析：kubectl get svc -n production
• 检查子集标签是否与 pod 标签匹配：kubectl get pods -n production --show-labels
• 检查 Pilot 日志：kubectl logs -n istio-system -l app=istiod
• 先不使用熔断器测试，然后逐步添加
• 使用 istioctl analyze 检查配置：istioctl analyze -n production

第 5 步：集成可观测性栈

将服务网格遥测连接到监控和追踪系统。

安装可观测性插件：

# Istio: Prometheus, Grafana, Kiali, Jaeger
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/addons/prometheus.yaml
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/addons/grafana.yaml
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/addons/kiali.yaml
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.20/samples/addons/jaeger.yaml

# Linkerd
linkerd viz install | kubectl apply -f -
linkerd jaeger install | kubectl apply -f -

配置自定义指标和仪表板：

# service-monitor.yaml (abbreviated)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: istio-mesh-metrics
spec:
  selector: { matchLabels: { app: istiod } }
  endpoints:
  - port: http-monitoring
    interval: 30s
# See EXAMPLES.md Step 5 for Grafana dashboards and telemetry config

访问仪表板：

istioctl dashboard grafana  # or: linkerd viz dashboard
istioctl dashboard kiali
istioctl dashboard jaeger

预期结果： 仪表板显示服务拓扑、请求速率、延迟百分位数和错误率。Jaeger 中可查看分布式追踪。Prometheus 成功抓取网格指标。自定义指标出现在查询中。

失败处理：

• 验证 Prometheus 抓取：kubectl get servicemonitor -A
• 检查插件 pod 是否运行：kubectl get pods -n istio-system
• 检查遥测配置：istioctl proxy-config log <pod-name> -n <namespace>
• 验证网格配置启用了遥测：kubectl get configmap istio -n istio-system -o yaml | grep -A 5 enableTracing
• 如果端口转发失败，检查端口冲突

第 6 步：验证和监控网格健康状态

执行全面的健康检查并设置持续监控。

# Istio validation
istioctl analyze --all-namespaces
istioctl verify-install
istioctl proxy-status

# Linkerd validation
linkerd check
linkerd viz check
linkerd diagnostics policy

# Check proxy sync status
kubectl get pods -n production -o json | \
  jq '.items[] | {name: .metadata.name, proxy: .status.containerStatuses[] | select(.name=="istio-proxy").ready}'

# Monitor control plane health
kubectl get pods -n istio-system -w
kubectl top pods -n istio-system

创建健康检查脚本和告警：

#!/bin/bash
# mesh-health-check.sh (abbreviated)
echo "=== Service Mesh Health Check ==="
kubectl get pods -n istio-system
istioctl analyze --all-namespaces
# See EXAMPLES.md Step 6 for complete health check script and alert configs

预期结果： 所有分析检查通过，无警告。proxy-status 显示所有代理已同步。mTLS 检查确认加密。指标显示流量正常流动。控制平面 pod 稳定，资源使用率低。

失败处理：

• 解决 istioctl analyze 输出中的特定问题
• 检查各 pod 的代理日志：kubectl logs <pod> -c istio-proxy -n <namespace>
• 验证网络策略没有阻止网格流量
• 检查控制平面日志中的错误：kubectl logs -n istio-system deploy/istiod --tail=100
• 重启有问题的代理：kubectl rollout restart deploy/<deployment> -n <namespace>

验证清单

• 控制平面 pod 运行正常（istiod/linkerd-controller）
• Sidecar 代理已注入所有应用 pod（2/2 容器）
• mTLS 已启用且功能正常（使用 tls-check/tap 验证）
• 流量管理规则正确路由请求（使用 curl 测试验证）
• 熔断器在重复失败时触发（使用故障注入测试）
• 可观测性仪表板显示指标（Grafana/Kiali/Linkerd Viz）
• Jaeger 中捕获了示例请求的分布式追踪
• istioctl analyze/linkerd check 无配置警告
• 代理同步状态显示所有代理已同步
• 服务间通信已加密（在日志/仪表板中验证）

常见问题

• 资源耗尽：服务网格为每个 pod 的 Sidecar 增加 100-200MB 内存。确保集群有足够容量。在注入配置中设置适当的资源限制。

• 配置冲突：同一主机有多个 VirtualService 会导致未定义行为。使用单个 VirtualService 配合多个匹配条件，而非多个 VirtualService。

• 证书过期：mTLS 证书自动轮换，但 CA 根证书必须手动管理。使用 kubectl get certificate -A 监控证书过期并设置告警。

• Sidecar 未注入：在命名空间打标签之前创建的 pod 不会有 Sidecar。必须重新创建：kubectl rollout restart deploy/<name> -n <namespace>。

• DNS 解析问题：服务网格拦截 DNS。跨命名空间调用使用完全限定名称（service.namespace.svc.cluster.local）。

• 端口命名要求：Istio 要求端口名遵循协议名称模式（如 http-web、tcp-db）。未命名端口默认为 TCP 透传。

• 需要渐进式部署：不要在生产环境立即启用 STRICT mTLS。迁移期间使用 PERMISSIVE 模式，验证所有服务都已纳入网格，然后切换到 STRICT。

• 可观测性开销：100% 追踪采样会导致性能问题。生产环境使用 1-10%：在网格配置中设置 sampling: 1.0。

• Gateway 与 VirtualService 混淆：Gateway 配置入口（负载均衡器），VirtualService 配置路由。外部流量两者都需要。

• 版本兼容性：确保网格版本与 Kubernetes 版本兼容。Istio 支持 n-1 小版本，Linkerd 通常支持最近 3 个 Kubernetes 版本。

相关技能

• configure-ingress-networking - Gateway 配置与网格入口互补
• deploy-to-kubernetes - 与服务网格配合使用的应用部署模式
• setup-prometheus-monitoring - 网格指标的 Prometheus 集成
• manage-kubernetes-secrets - mTLS 的证书管理
• enforce-policy-as-code - 与网格授权配合使用的 OPA 策略