datawire/tel2

Telepresence Traffic Manager & Traffic Agent (开源版) 技术文档

1. 镜像概述和主要用途

1.1 概述

Telepresence Traffic Manager & Traffic Agent (开源版) 是Telepresence工具链的核心组件镜像，包含Traffic Manager（流量管理器）和Traffic Agent（流量代理）两个核心模块。该镜像基于开源协议发布，专为Kubernetes环境设计，旨在解决微服务开发过程中“本地开发与集群环境隔离”的痛点。

1.2 主要用途

• 实现Kubernetes集群流量与本地开发环境的双向代理，支持将集群流量转发至本地服务，或本地服务访问集群内其他服务。
• 作为微服务本地开发调试的基础设施，无需频繁部署即可验证代码变更。
• 协调集群内服务流量路由、拦截和转发，简化微服务交互测试流程。

2. 核心功能和特性

2.1 核心功能

• 流量双向代理：支持集群流量（入站/出站）与本地开发环境的双向转发，实现“本地服务-集群服务”无缝通信。
• 轻量级Sidecar架构：Traffic Agent以Sidecar形式注入目标Pod，资源占用低（默认CPU < 100m，内存 < 64Mi），对集群性能影响极小。
• 动态流量拦截：通过Traffic Manager协调，支持按服务、端口、标签等维度动态配置流量拦截规则，精准控制流量路由。
• 原生Kubernetes集成：与Kubernetes API Server深度集成，支持通过CRD、注解（Annotation）或客户端工具配置流量策略。

2.2 关键特性

• 开源免费：基于Apache 2.0协议开源，无商业许可限制。
• 低侵入性：Agent仅需通过Pod注解或初始化注入，无需修改服务业务代码。
• 跨平台兼容：支持Kubernetes 1.21+集群，兼容主流容器运行时（Containerd、CRI-O）。
• 安全通信：Manager与Agent间通过TLS加密通信，保障流量转发安全性。

3. 使用场景和适用范围

3.1 典型使用场景

• Kubernetes服务本地开发调试：本地运行服务，直接接收集群流量，实时验证代码逻辑（如API接口、数据处理流程）。
• 微服务交互测试：本地服务可直接调用集群内依赖服务（如数据库、消息队列、其他微服务），无需在本地搭建完整依赖环境。
• 无需部署验证变更：开发阶段无需构建镜像、推送仓库、部署Pod，直接通过流量拦截验证代码变更效果。
• 多团队协作开发：多团队并行开发时，各自拦截目标服务流量至本地，避免集群资源冲突或相互干扰。

3.2 适用范围

• 用户：Kubernetes微服务开发团队、云原生开发者、需要频繁调试集群服务的个人开发者。
• 环境：生产/测试/开发环境的Kubernetes集群（1.21+），支持标准Kubernetes发行版（如EKS、GKE、AKS、Minikube、Kind）。

4. 使用方法和配置说明

4.1 前置条件

• 已部署Kubernetes集群（1.21+），且集群节点可访问外部网络（用于拉取镜像）。
• 本地安装kubectl（集群访问权限）和Telepresence客户端（v2.18+，用于与Manager交互，下载地址）。
• 集群内已创建命名空间（推荐telepresence，用于部署Traffic Manager）。

4.2 部署Traffic Manager到Kubernetes集群

Traffic Manager需部署在Kubernetes集群中，作为流量协调中心。推荐通过Helm或kubectl部署：

4.2.1 Helm部署（推荐）

bash
# 添加Telepresence Helm仓库
helm repo add telepresence https://www.getambassador.io/docs/telepresence/charts
helm repo update

# 部署Traffic Manager（默认命名空间：telepresence）
helm install traffic-manager telepresence/traffic-manager \
  --namespace telepresence \
  --create-namespace \
  --set image.repository=docker.io/datawire/telepresence-traffic-manager \  # 开源版镜像地址
  --set image.tag=<version>  # 替换为具体版本（如v2.18.0）

4.2.2 kubectl部署

通过官方Manifest部署：

bash
kubectl apply -f https://raw.githubusercontent.com/telepresenceio/telepresence/release/v2/charts/telepresence/crds/telepresence.io_trafficmanagers.yaml
kubectl apply -f https://raw.githubusercontent.com/telepresenceio/telepresence/release/v2/charts/telepresence/crds/telepresence.io_traficsplits.yaml

# 部署Manager Deployment
kubectl create namespace telepresence --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -n telepresence -f https://raw.githubusercontent.com/telepresenceio/telepresence/release/v2/examples/manifests/traffic-manager.yaml

4.3 Traffic Agent配置与注入

Traffic Agent通过Sidecar形式注入目标Pod，支持两种配置方式：

4.3.1 自动注入（推荐）

通过Pod注解触发Agent自动注入：

yaml
# 目标服务Deployment示例（添加注解以启用Agent）
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
  namespace: default
spec:
  template:
    metadata:
      annotations:
        telepresence.getambassador.io/inject: "true"  # 启用Agent注入
        telepresence.getambassador.io/agent-image: "docker.io/datawire/telepresence-traffic-agent:<version>"  # 开源版Agent镜像地址
    spec:
      containers:
      - name: main-container
        image: my-service:latest

4.3.2 手动注入

通过telepresence客户端手动注入Agent（需先安装客户端）：

bash
# 拦截目标服务（自动注入Agent并配置流量规则）
telepresence intercept my-service --port 8080:80  # 将集群中my-service的80端口流量转发至本地8080端口

4.4 流量拦截与本地调试示例

以下为“拦截集群流量到本地服务”的完整流程：

1. 启动本地服务：在本地运行待调试服务（如监听localhost:8080）。
2. 拦截集群流量：

   bash
   # 拦截default命名空间下的my-service服务，将80端口流量转发至本地8080端口
   telepresence intercept my-service --namespace default --port 8080:80
   

3. 验证拦截效果：
   • 集群内访问my-service.default.svc.cluster.local:80，流量将被转发至本地localhost:8080。
   • 本地服务可通过http://my-db.default.svc.cluster.local访问集群内的数据库服务（无需本地部署）。
4. 停止拦截：

   bash
   telepresence leave my-service  # 停止拦截，恢复集群原有流量路由
   

5. 配置参数与环境变量

5.1 Traffic Manager配置参数

5.2 Traffic Agent配置参数（通过Pod注解）

6. Docker部署方案示例

6.1 本地测试Traffic Manager（单节点Docker运行）

注意：该方式仅用于本地功能验证，生产环境需部署至Kubernetes集群。

bash
docker run -d \
  --name telepresence-manager \
  -p 8080:8080 \
  -e LOG_LEVEL=debug \
  -e NAMESPACE=telepresence \
  -v $HOME/.kube/config:/root/.kube/config:ro \  # 挂载本地kubeconfig以访问集群
  docker.io/datawire/telepresence-traffic-manager:<version>

6.2 Kubernetes部署Manifest示例（Manager）

yaml
# traffic-manager-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: traffic-manager
  namespace: telepresence
spec:
  replicas: 1
  selector:
    matchLabels:
      app: traffic-manager
  template:
    metadata:
      labels:
        app: traffic-manager
    spec:
      containers:
      - name: traffic-manager
        image: docker.io/datawire/telepresence-traffic-manager:<version>
        ports:
        - containerPort: 8080
        env:
        - name: LOG_LEVEL
          value: "info"
        - name: PORT
          value: "8080"
        resources:
          limits:
            cpu: 200m
            memory: 128Mi
          requests:
            cpu: 100m
            memory: 64Mi

6. 适用范围与限制

6.1 适用范围

• 支持Kubernetes 1.21+集群，兼容x86_64/arm64架构。
• 适用于微服务数量≤50的中小型团队，或单服务本地开发场景。

6.2 限制（开源版vs商业版）

• 不支持“团队协作流量隔离”（如按用户/标签隔离流量）。
• 无UI控制台，需通过命令行或Kubernetes API配置。
• 高级流量控制功能（如流量镜像、熔断策略）需依赖商业版。

7. 镜像信息

• 官方仓库：docker.io/datawire/telepresence-traffic-manager（Manager）、docker.io/datawire/telepresence-traffic-agent（Agent）
• 开源协议：Apache License 2.0
• 最新版本：参考https://github.com/telepresenceio/telepresence/releases