consul-dataplane 镜像文档

1. 镜像概述和主要用途

consul-dataplane 是 HashiCorp Consul 生态的轻量级数据平面组件，用于将应用程序无缝接入 Consul 服务网格。其核心作用是作为应用与 Consul 控制平面之间的通信桥梁，简化应用与服务网格的集成过程，实现服务发现、流量管理、安全通信等服务网格核心能力。

2. 核心功能和特性

• 轻量级部署：可作为 sidecar 容器或独立进程运行，资源占用低，适合微服务架构。
• 自动服务注册与发现：自动向 Consul 控制平面注册应用服务，并发现网格内其他服务。
• 流量加密与安全：支持 mTLS 加密服务间通信，实现零信任安全模型。
• 流量管理：支持请求路由、负载均衡、故障注入等基础流量控制能力。
• 健康检查集成：内置健康检查机制，向 Consul 上报应用状态。
• 控制平面通信：与 Consul 控制平面（server 节点）实时同步配置和服务数据。

3. 使用场景和适用范围

适用场景

• 微服务架构中实现服务间可靠通信与流量治理。
• 基于 Consul 构建零信任安全体系（如 mTLS 加密、访问控制）。
• 跨环境（Kubernetes/虚拟机）应用接入统一服务网格。
• 需要动态服务发现、健康检查和配置更新的业务场景。

适用范围

• 开发、测试及生产环境。
• 已部署 Consul 控制平面（v1.11+ 推荐）的集群。
• 容器化（Docker/Kubernetes）或物理机/虚拟机部署的应用。

4. 使用方法和配置说明

4.1 基本使用（docker run）

通过以下命令启动 consul-dataplane 容器，将应用接入 Consul 服务网格：

docker run -d \
  --name=consul-dataplane \
  --network=host \  # 共享主机网络（或与应用容器共享网络命名空间）
  hashicorp/consul-dataplane:latest \
  -consul-server-addr="consul-server:8500" \  # Consul 控制平面地址
  -service-name="my-app" \                   # 注册的服务名称
  -service-port=8080 \                       # 应用监听端口
  -service-meta="version=1.0" \              # 服务元数据（可选）
  -enable-mtls=true                          # 启用 mTLS 加密（可选）

关键说明：

• --network=host：若应用与 dataplane 部署在同一主机，可共享网络以简化流量转发；容器化环境中建议与应用容器使用 --network=container:<app-container-id> 共享网络命名空间。
• -consul-server-addr：必填，指定 Consul 控制平面地址（格式：host:port，支持多个地址用逗号分隔）。
• -service-name 与 -service-port：必填，定义应用服务的名称和端口，用于服务注册。

4.2 Docker Compose 配置示例

以下示例展示应用容器与 consul-dataplane 作为 sidecar 协同部署的 docker-compose.yml：

version: '3.8'
services:
  my-app:
    image: my-app:latest  # 业务应用镜像
    ports:
      - "8080:8080"
    # 应用容器配置（如环境变量、挂载等）

  consul-dataplane:
    image: hashicorp/consul-dataplane:latest
    network_mode: "service:my-app"  # 与应用容器共享网络命名空间
    depends_on:
      - my-app
    command:
      - -consul-server-addr="consul-server:8500"
      - -service-name="my-app"
      - -service-port=8080
      - -health-check-http-path="/health"  # HTTP 健康检查路径（可选）
      - -log-level="info"  # 日志级别（可选，默认 info）

说明：

• network_mode: "service:my-app"：确保 dataplane 与应用容器共享网络，无需额外端口映射即可拦截流量。
• depends_on：确保应用容器启动后再启动 dataplane。

5. 配置参数说明

5.1 命令行参数

5.2 环境变量

支持通过环境变量传递配置（优先级低于命令行参数）：

6. 注意事项

• 网络配置：dataplane 需与应用共享网络（或通过端口映射拦截流量），确保流量可被正确转发至应用。
• 控制平面兼容性：需与 Consul 控制平面版本匹配（建议使用同一版本镜像）。
• 资源限制：生产环境建议限制 CPU/内存资源（如 --cpus=0.5 -m=256m），避免资源竞争。
• 日志与监控：通过 -log-level=debug 排查启动问题，可挂载日志目录（如 -v ./logs:/var/log/consul-dataplane）持久化日志。