datawire/ambassador-telepresence-agent

Telepresence Traffic Agent (企业版) Docker镜像文档

镜像概述与主要用途

Telepresence Traffic Agent (企业版) 是一款专为企业级Kubernetes环境设计的流量代理组件，作为Telepresence企业版解决方案的核心部分，用于实现本地开发环境与远程Kubernetes集群服务之间的流量路由、代理和管理。通过该镜像，开发人员可在本地开发环境中直接与集群内服务交互，无需将本地服务部署至集群即可进行调试和测试，同时支持企业级网络策略、安全要求和高级流量控制能力。

核心功能与特性

企业级流量管理

• 支持细粒度流量路由规则，可基于请求头、路径、IP等维度定向转发流量
• 提供流量优先级控制，确保关键业务流量优先处理
• 支持流量镜像（Traffic Mirroring），可将生产流量复制到测试服务进行验证

增强安全性

• 内置TLS加密通信，支持自定义CA证书和企业级PKI集成
• 基于RBAC的访问控制，限制代理权限范围
• 支持网络策略合规性检查，确保流量转发符合企业安全规范

企业级部署与可靠性

• 多集群流量代理支持，可跨多个Kubernetes集群路由流量
• 高可用性设计，支持自动故障转移和健康检查
• 与企业级监控工具（如Prometheus、Grafana）集成，提供流量指标可视化

高级网络功能

• 双向流量代理，支持本地服务接收集群流量和主动访问集群服务
• 透明DNS解析，自动将集群服务域名解析至本地代理
• 支持TCP、UDP和HTTP/HTTPS协议的流量代理

使用场景与适用范围

适用场景

• 企业级微服务开发：团队在本地开发环境调试运行中的Kubernetes微服务，需与集群内其他服务交互
• 跨集群服务调试：多集群部署的应用，需要在本地开发环境访问不同集群的服务
• 生产流量测试：将部分生产流量安全地路由至本地开发服务进行测试验证
• 企业安全合规要求：需要满足严格的网络隔离、加密和访问控制要求的开发场景

适用范围

• 企业级Kubernetes集群（EKS、GKE、AKS或自管理Kubernetes）
• 微服务架构开发团队，尤其是中大型团队
• 需要本地开发与集群服务紧密集成的DevOps流程
• 对网络安全性、可靠性有较高要求的***、电商、政务等行业

使用方法与配置说明

前置条件

• 已安装Telepresence企业版客户端（telepresence CLI）
• 具有Kubernetes集群管理员或编辑权限
• 集群已配置容器运行时支持（Docker、containerd等）

基本部署流程

Telepresence Traffic Agent通常通过Telepresence CLI自动部署至Kubernetes集群，无需手动运行Docker镜像。部署步骤如下：

1. 登录Telepresence企业版控制器（如使用企业版管理平台）：

   bash
   telepresence login --controller=https://<telepresence-controller-url> --token=<enterprise-token>
   

2. 连接至Kubernetes集群，自动部署Traffic Agent：

   bash
   telepresence connect --agent-image=docker.io/datawire/telepresence-agent-enterprise:latest
   

   说明：--agent-image参数指定使用企业版Traffic Agent镜像，默认会部署为DaemonSet至集群的telepresence命名空间。

手动配置（高级用户）

如需自定义部署，可通过Kubernetes DaemonSet配置文件部署该镜像，示例配置片段如下：

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: telepresence-agent
  namespace: telepresence
spec:
  selector:
    matchLabels:
      app: telepresence-agent
  template:
    metadata:
      labels:
        app: telepresence-agent
    spec:
      containers:
      - name: agent
        image: docker.xuanyuan.run/datawire/telepresence-agent-enterprise:latest
        env:
        - name: AGENT_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: LOG_LEVEL
          value: "info"  # 可选：debug, info, warn, error
        - name: TLS_CERT_PATH
          value: "/etc/telepresence/tls/cert"
        - name: TLS_KEY_PATH
          value: "/etc/telepresence/tls/key"
        ports:
        - containerPort: 8080  # 代理服务端口
        volumeMounts:
        - name: tls-volume
          mountPath: "/etc/telepresence/tls"
          readOnly: true
      volumes:
      - name: tls-volume
        secret:
          secretName: telepresence-agent-tls  # 包含TLS证书的Secret

配置参数说明

环境变量

命令行参数（通过Telepresence CLI传递）

故障排除与常见问题

常见问题解决

1. Agent启动失败：检查命名空间权限、TLS证书是否有效、资源是否充足
2. 流量路由异常：通过telepresence status查看代理状态，检查流量规则配置
3. 多集群连接问题：确保CLUSTER_NAME配置唯一，网络策略允许跨集群通信

日志查看

查看集群中Agent容器日志：

bash
kubectl logs -n telepresence -l app=telepresence-agent -c agent

官方支持

企业版用户可通过Telepresence企业支持渠道获取帮助，包括技术支持热线、工单系统和专属客户经理支持。