consul-dataplane 镜像文档

1. 镜像概述与主要用途

1.1 概述

consul-dataplane 是一个轻量级数据平面组件，用于将应用程序无缝接入 Consul 服务网格（Service Mesh）。作为 Consul 服务网格的关键组件，它负责处理服务间的流量转发、服务发现、安全通信等核心数据平面功能，简化应用与 Consul 控制平面的交互流程。

1.2 主要用途

核心用途是作为应用程序与 Consul 服务网格之间的桥梁，使应用无需直接集成 Consul SDK 即可利用服务网格的能力，包括服务注册与发现、流量管理（路由、负载均衡）、安全通信（mTLS 加密）等。

2. 核心功能与特性

• 服务网格接入：提供标准化接口，支持应用程序快速接入 Consul 服务网格，无需修改业务代码。
• 服务发现与注册：自动与 Consul 控制平面交互，完成服务注册，并动态获取服务实例信息，支持服务健康检查。
• 流量管理：支持服务间流量的动态路由、负载均衡、故障转移等流量控制策略，适配复杂微服务架构场景。
• 安全通信：集成 mTLS 加密功能，保障服务间通信的机密性与完整性，支持基于身份的访问控制。
• 轻量级设计：资源占用低，适合容器化环境（如 Docker、Kubernetes）部署，兼容主流容器编排平台。
• Consul 控制平面集成：与 Consul 服务器（控制平面）协同工作，实时同步服务配置、流量策略等元数据。

3. 使用场景与适用范围

3.1 使用场景

• 微服务架构治理：在微服务架构中，统一管理服务间通信，实现流量可视化、故障隔离、灰度发布等场景。
• 服务网格功能验证：开发或测试环境中，快速验证 Consul 服务网格的核心功能（如流量路由、安全通信）与应用的集成效果。
• 容器化应用部署：在 Docker 或 Kubernetes 环境中部署的应用，需通过服务网格实现服务发现与流量管理时的配套组件。

3.2 适用范围

• 需接入 Consul 服务网格的各类应用程序（支持 HTTP、gRPC 等主流协议）。
• 开发环境可使用本仓库的开发版镜像进行功能验证；生产环境必须使用 HashiCorp 官方提供的稳定版镜像（hashicorp/consul-dataplane）。

4. 使用方法与配置说明

4.1 镜像获取

• 开发版镜像：直接拉取当前仓库中的镜像（具体标签需参考仓库实际版本，仅建议用于开发测试）。
• 生产环境稳定版镜像：通过 Docker Hub 获取官方稳定镜像，建议指定具体版本标签以确保兼容性和稳定性。

# 拉取生产环境稳定版镜像（示例，版本号需替换为实际稳定版本）
docker pull hashicorp/consul-dataplane:1.2.3

4.2 基本使用方法（Docker Run 示例）

以下为使用 docker run 启动 consul-dataplane 并连接应用到 Consul 服务网格的基础示例，需根据实际环境调整参数：

docker run -d \
  --name consul-dataplane \
  --network=app-network \  # 与应用容器共享网络，确保流量互通
  -e CONSUL_HTTP_ADDR=consul-server:8500 \  # Consul 控制平面地址（如 Consul 服务器 IP:端口）
  -e SERVICE_NAME=my-app \  # 应用服务名称（需与 Consul 服务网格配置一致）
  -e SERVICE_PORT=8080 \    # 应用监听端口
  hashicorp/consul-dataplane:1.2.3 \  # 生产环境稳定版镜像
  consul-dataplane run  # 启动命令（具体子命令需参考官方文档）

4.3 核心配置参数与环境变量

consul-dataplane 支持通过环境变量或配置文件进行参数配置，以下为常用环境变量说明：

完整配置参数及详细说明请参考官方文档：consul-dataplane 使用说明。

4.4 与应用集成说明

consul-dataplane 通常以 sidecar 容器模式 部署：

• 与应用容器共享网络命名空间，确保流量可被拦截和转发；
• 应用需将出站流量指向 consul-dataplane 的代理端口（默认通常为 15001 等，具体需参考配置），入站流量由 consul-dataplane 接收并转发至应用端口。

5. 注意事项

• 镜像版本选择：本仓库的镜像是开发版（dev images），可能包含未稳定功能，禁止用于生产环境。生产环境必须使用 Docker Hub 上的 hashicorp/consul-dataplane 稳定版镜像，并指定具体版本标签（如 1.2.3）。
• 网络可达性：确保 consul-dataplane 与应用容器、Consul 控制平面之间网络互通，否则会导致服务注册失败或流量转发异常。
• 安全配置：若 Consul 控制平面启用 TLS 或 ACL 认证，需在 consul-dataplane 中配置对应的证书、令牌等参数（如 CONSUL_TLS_CA_FILE、CONSUL_HTTP_TOKEN）。