setup-service-mesh

pjt222

업데이트됨 5 days ago

7 조회

디자인aidesign

정보

이 스킬은 쿠버네티스 클러스터에 서비스 메시 계층을 추가하기 위해 Istio 또는 Linkerd를 배포하고 구성합니다. 코드 변경 없이 보안 mTLS 통신, 배포를 위한 고급 트래픽 관리, 가시성을 제공합니다. 마이크로서비스가 암호화된 서비스 간 통신, 세밀한 트래픽 제어 또는 통합 정책 적용이 필요할 때 사용하십시오.

빠른 설치

Claude Code

문서

設置服務網格

部署並配置服務網格以提供安全之服務間通訊與進階流量管理。

適用時機

微服務架構需加密之服務間通訊
需細粒度之流量控制（金絲雀部署、A/B 測試、流量分割）
需跨所有服務互動之可觀察性而無需應用變更
於基礎設施層強制安全策略（mTLS、授權）
跨服務一致地實作斷路、重試與超時
需分散式追蹤與服務依賴圖

輸入

必要：具管理員存取之 Kubernetes 集群
必要：服務網格之選擇（Istio 或 Linkerd）
必要：欲啟用服務網格之命名空間
選擇性：監控堆疊（Prometheus、Grafana、Jaeger）
選擇性：自訂流量管理要求
選擇性：mTLS 之憑證機構配置

步驟

詳見 Extended Examples 取得完整配置文件與範本。

步驟一：安裝服務網格控制平面

選擇並安裝服務網格控制平面。

對 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

步驟二：啟用自動 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 -

步驟三：配置 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 顯示 STATUS 為「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'

步驟四：實作流量管理規則

配置智慧之流量路由、重試與斷路。

建立流量管理策略：

# 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

步驟五：整合可觀察性堆疊

將服務網格遙測連至監控與追蹤系統。

安裝可觀察性附加元件：

# 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
若 port-forward 失敗，檢查連接埠衝突

步驟六：驗證並監控網格健康

執行全面健康檢查並設置持續監控。

# 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 之 sidecar 加 100-200MB 記憶體。確保集群有足夠容量。於注入配置中設適當資源限制。
配置衝突：對同主機之多個 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 minor 版本，Linkerd 通常支援最後 3 Kubernetes 版本。

GitHub 저장소

pjt222/agent-almanac

경로: i18n/wenyan-lite/skills/setup-service-mesh

agentsagentskillsai-assisted-developmentclaude-codeskillsteams

연관 스킬

executing-plans

디자인

executing-plans 스킬은 검토 체크포인트가 포함된 통제된 배치로 실행할 완전한 구현 계획이 있을 때 사용합니다. 이 스킬은 계획을 불러와 비판적으로 검토한 후, 소규모 배치(기본값 3개 작업)로 작업을 실행하면서 각 배치 사이에 진행 상황을 아키텍트 검토를 위해 보고합니다. 이를 통해 내재된 품질 관리 체크포인트를 갖춘 체계적인 구현이 보장됩니다.

스킬 보기

requesting-code-review

디자인

이 스킬은 코드 변경 사항을 요구 사항에 따라 분석하기 위해 코드 리뷰어 하위 에이전트를 호출합니다. 작업 완료 후, 주요 기능 구현 후, 또는 메인 브랜치에 병합하기 전에 사용해야 합니다. 이 리뷰는 현재 구현체와 원래 계획을 비교하여 문제를 조기에 발견하는 데 도움이 됩니다.

스킬 보기

connect-mcp-server

디자인

이 스킬은 개발자들이 HTTP, stdio 또는 SSE 전송 방식을 통해 MCP 서버를 Claude Code에 연결하는 포괄적인 가이드를 제공합니다. GitHub, Notion 및 사용자 정의 API와 같은 외부 서비스를 통합하기 위한 설치, 구성, 인증 및 보안을 다룹니다. MCP 통합 설정, 외부 도구 구성 또는 Claude의 모델 컨텍스트 프로토콜 작업 시 활용하세요.

스킬 보기

web-cli-teleport

디자인

이 스킬은 작업 분석을 기반으로 개발자가 Claude Code 웹 인터페이스와 CLI 인터페이스 중 선택할 수 있도록 돕고, 두 환경 간 원활한 세션 텔레포트를 가능하게 합니다. 웹, CLI 또는 모바일 환경 전환 시 세션 상태와 컨텍스트를 관리하여 워크플로를 최적화합니다. 다양한 단계에서 서로 다른 도구가 필요한 복잡한 프로젝트에 사용하세요.

스킬 보기

setup-service-mesh

정보

빠른 설치

Claude Code

문서

設置服務網格

適用時機

輸入

步驟

步驟一：安裝服務網格控制平面

步驟二：啟用自動 sidecar 注入

步驟三：配置 mTLS 策略

步驟四：實作流量管理規則

步驟五：整合可觀察性堆疊

步驟六：驗證並監控網格健康

驗證

常見陷阱

相關技能

GitHub 저장소

연관 스킬

executing-plans

requesting-code-review

connect-mcp-server

web-cli-teleport