linkerd-patterns

Linkerd のパターン

Kubernetes 向けの軽量でセキュリティを最優先したサービスメッシュ、Linkerd の本番環境向けパターンです。

このスキルを使用しない場合

• タスクが Linkerd のパターンに関係しない場合
• この範囲外の別のドメインやツールが必要な場合

手順

• 目標、制約、必要な入力を確認します。
• 関連するベストプラクティスを適用し、結果を検証します。
• 実行可能な手順と検証方法を提示します。

このスキルを使用する場合

• 軽量なサービスメッシュを設定する場合
• 自動 mTLS を実装する場合
• カナリアデプロイメント用のトラフィック分割を設定する場合
• ルートごとのメトリクス用にサービスプロファイルを設定する場合
• リトライとタイムアウトを実装する場合
• マルチクラスターのサービスメッシュを設定する場合

基本概念

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 が保護するのはメッシュ化された対象トラフィックであり、すべてのトラフィックが自動的に保護されるわけではありません。インジェクション、ID、明示的な認可を検証してください。認証されていない 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：リトライ付き Service Profile

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：サーバー認可ポリシー

# 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 のドキュメント
• サービスプロファイル
• 認可ポリシー

制限事項

• タスクが上記の範囲に明確に当てはまる場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認してください。