linkerd-patterns

Linkerd 模式

Linkerd 服务网格的生产实践模式——这是一款面向 Kubernetes 的轻量、安全优先的服务网格。

以下情况不要使用此技能

• 任务与 Linkerd 模式无关
• 需要使用此范围之外的其他领域或工具

指令

• 明确目标、约束和所需输入。
• 应用相关最佳实践并验证结果。
• 提供可执行的步骤和验证方法。

以下情况请使用此技能

• 设置轻量级服务网格
• 实现自动 mTLS
• 配置流量拆分以进行金丝雀部署
• 设置 ServiceProfile，以获取按路由统计的指标
• 实现重试和超时
• 多集群服务网格

核心概念

1. Linkerd 架构

┌─────────────────────────────────────────────┐
│                Control Plane                 │
│  ┌─────────┐ ┌──────────┐ ┌──────────────┐ │
│  │ destination │ │ identity │ │ proxy-inject │ │
│  └─────────┘ └──────────┘ └──────────────┘ │
└─────────────────────────────────────────────┘
                      │
┌─────────────────────────────────────────────┐
│                 Data Plane                   │
│  ┌─────┐    ┌─────┐    ┌─────┐             │
│  │proxy│────│proxy│────│proxy│             │
│  └─────┘    └─────┘    └─────┘             │
│     │           │           │               │
│  ┌──┴──┐    ┌──┴──┐    ┌──┴──┐            │
│  │ app │    │ app │    │ app │            │
│  └─────┘    └─────┘    └─────┘            │
└─────────────────────────────────────────────┘

2. 关键资源

资源	用途
ServiceProfile	按路由统计指标、重试和超时
TrafficSplit	金丝雀部署、A/B 测试
Server	定义服务端策略
ServerAuthorization	访问控制策略

版本和部署边界

示例混用了特定版本的 API 和不完整的清单。渲染或应用前，请检查已安装的 Linkerd/Kubernetes CRD 以及受支持的 Gateway API/SMI 版本；Deployment 片段省略了必需的选择器和容器。mTLS 仅保护符合条件的网格流量，并非自动保护所有流量；请验证注入、身份和显式授权。宽泛的未认证 CIDR 示例需要经过有意批准的例外。固定并审核安装程序和镜像版本，针对确切的上下文/命名空间预览渲染后的更改，并确保保留发布和回滚所需的访问权限。Tap/日志输出可能会泄露敏感流量信息。

模板

模板 1：安装网格

# Install CLI
brew install linkerd

# Alternative: download the official installer, inspect it, then execute it
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install -o "$tmpdir/linkerd-install.sh"
cat "$tmpdir/linkerd-install.sh"  # review the full installer before executing
sh "$tmpdir/linkerd-install.sh"

# Validate cluster
linkerd check --pre

# Install CRDs
linkerd install --crds | kubectl apply -f -

# Install control plane
linkerd install | kubectl apply -f -

# Verify installation
linkerd check

# Install viz extension (optional)
linkerd viz install | kubectl apply -f -

模板 2：注入命名空间

# Automatic injection for namespace
apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  annotations:
    linkerd.io/inject: enabled
---
# Or inject specific deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  annotations:
    linkerd.io/inject: enabled
spec:
  template:
    metadata:
      annotations:
        linkerd.io/inject: enabled

模板 3：带重试的 ServiceProfile

apiVersion: linkerd.io/v1alpha2
kind: ServiceProfile
metadata:
  name: my-service.my-namespace.svc.cluster.local
  namespace: my-namespace
spec:
  routes:
    - name: GET /api/users
      condition:
        method: GET
        pathRegex: /api/users
      responseClasses:
        - condition:
            status:
              min: 500
              max: 599
          isFailure: true
      isRetryable: true
    - name: POST /api/users
      condition:
        method: POST
        pathRegex: /api/users
      # POST not retryable by default
      isRetryable: false
    - name: GET /api/users/{id}
      condition:
        method: GET
        pathRegex: /api/users/[^/]+
      timeout: 5s
      isRetryable: true
  retryBudget:
    retryRatio: 0.2
    minRetriesPerSecond: 10
    ttl: 10s

模板 4：流量拆分（金丝雀）

apiVersion: split.smi-spec.io/v1alpha1
kind: TrafficSplit
metadata:
  name: my-service-canary
  namespace: my-namespace
spec:
  service: my-service
  backends:
    - service: my-service-stable
      weight: 900m  # 90%
    - service: my-service-canary
      weight: 100m  # 10%

模板 5：Server 授权策略

# Define the server
apiVersion: policy.linkerd.io/v1beta1
kind: Server
metadata:
  name: my-service-http
  namespace: my-namespace
spec:
  podSelector:
    matchLabels:
      app: my-service
  port: http
  proxyProtocol: HTTP/1
---
# Allow traffic from specific clients
apiVersion: policy.linkerd.io/v1beta1
kind: ServerAuthorization
metadata:
  name: allow-frontend
  namespace: my-namespace
spec:
  server:
    name: my-service-http
  client:
    meshTLS:
      serviceAccounts:
        - name: frontend
          namespace: my-namespace
---
# Allow unauthenticated traffic (e.g., from ingress)
apiVersion: policy.linkerd.io/v1beta1
kind: ServerAuthorization
metadata:
  name: allow-ingress
  namespace: my-namespace
spec:
  server:
    name: my-service-http
  client:
    unauthenticated: true
    networks:
      - cidr: 10.0.0.0/8

模板 6：用于高级路由的 HTTPRoute

apiVersion: policy.linkerd.io/v1beta2
kind: HTTPRoute
metadata:
  name: my-route
  namespace: my-namespace
spec:
  parentRefs:
    - name: my-service
      kind: Service
      group: ""
      port: 8080
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/v2
          headers:
            - name: x-api-version
              value: v2
      backendRefs:
        - name: my-service-v2
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: my-service-v1
          port: 8080

模板 7：多集群设置

# On each cluster, install with cluster credentials
linkerd multicluster install | kubectl apply -f -

# Link clusters
linkerd multicluster link --cluster-name west \
  --api-server-address https://west.example.com:6443 \
  | kubectl apply -f -

# Export a service to other clusters
kubectl label svc/my-service mirror.linkerd.io/exported=true

# Verify cross-cluster connectivity
linkerd multicluster check
linkerd multicluster gateways

监控命令

# Live traffic view
linkerd viz top deploy/my-app

# Per-route metrics
linkerd viz routes deploy/my-app

# Check proxy status
linkerd viz stat deploy -n my-namespace

# View service dependencies
linkerd viz edges deploy -n my-namespace

# Dashboard
linkerd viz dashboard

调试

# Check injection status
linkerd check --proxy -n my-namespace

# View proxy logs
kubectl logs deploy/my-app -c linkerd-proxy

# Debug identity/TLS
linkerd identity -n my-namespace

# Tap traffic (live)
linkerd viz tap deploy/my-app --to deploy/my-backend

最佳实践

建议

• 在所有位置启用 mTLS - Linkerd 会自动启用
• 使用 ServiceProfiles - 获取按路由统计的指标和重试
• 设置重试预算 - 防止重试风暴
• 监控黄金指标 - 成功率、延迟、吞吐量

不建议

• 不要跳过检查 - 每次更改后都运行 linkerd check
• 不要过度配置 - Linkerd 的默认设置很合理
• 不要忽视 ServiceProfiles - 它们可启用高级功能
• 不要忘记超时设置 - 为每条路由设置合适的值

资源

• Linkerd 文档
• ServiceProfile
• 授权策略

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，请暂停并请求澄清。