etcd 镜像文档（k8s.gcr.io/etcd 标签镜像）

镜像概述和主要用途

概述

本镜像为 etcd 的 Docker 镜像，是 k8s.gcr.io/etcd 仓库中部分标签的镜像，提供与上游 etcd 一致的功能和特性。etcd 是一个分布式、可靠的键值存储系统，基于 Raft 共识算法实现数据一致性，专为共享配置和服务发现设计。

主要用途

• 作为 Kubernetes 集群控制平面的核心组件，存储集群配置、状态数据（如节点、Pod、Service 等资源信息）。
• 独立用于分布式系统的键值存储场景，如服务注册与发现、配置管理、分布式锁等。

核心功能和特性

• 分布式键值存储：支持键值对数据的存储与检索，键可包含层级结构（如 /registry/pods/my-pod）。
• 强一致性保证：基于 Raft 共识算法，确保分布式环境下数据的一致性和可靠性。
• 高可用性：支持多节点集群部署，自动故障转移，保障服务持续可用。
• Watch 机制：客户端可监听键或前缀的变化，实时获取数据更新。
• 版本化数据：每个键的修改生成新版本，支持历史版本查询和数据回滚。
• Kubernetes 兼容性：镜像标签与 Kubernetes 版本匹配（如 v3.5.10 对应 Kubernetes 1.24+），确保集群组件兼容性。
• 轻量级与高性能：基于 Go 语言开发，资源占用低，支持高并发读写操作。

使用场景和适用范围

使用场景

• Kubernetes 集群部署：作为控制平面关键组件，存储集群状态数据（如节点、Pod、Service 等资源元数据）。
• 分布式配置管理：存储分布式应用的动态配置，支持多节点配置同步。
• 服务注册与发现：存储服务实例地址，供客户端查询和发现服务。
• 分布式锁：基于 Raft 一致性实现分布式锁，协调多节点并发操作。

适用范围

• 环境：开发环境、测试环境、生产环境的 Kubernetes 集群或独立分布式系统。
• 规模：支持从小型测试集群到大型生产集群的不同规模部署。

使用方法和配置说明

拉取镜像

通过 Docker 命令拉取镜像，指定标签（标签列表需参考上游 k8s.gcr.io/etcd 仓库，如 v3.5.10）：

docker pull <镜像仓库地址>/etcd:<tag>  # 替换 <镜像仓库地址> 和 <tag>，例如原镜像地址为 k8s.gcr.io/etcd

基本运行示例（单节点模式）

适用于开发或测试环境，快速启动单节点 etcd 服务：

docker run -d \
  --name etcd-single \
  --publish 2379:2379 \  # 客户端通信端口
  --publish 2380:2380 \  # 节点间通信端口（集群模式使用）
  --volume etcd-data:/var/lib/etcd \  # 数据持久化（Docker 卷）
  <镜像仓库地址>/etcd:<tag> \
  etcd \
  --name=etcd-node-1 \  # 节点名称（集群内唯一）
  --data-dir=/var/lib/etcd \  # 数据存储目录
  --advertise-client-urls=[***] \  # 客户端通信地址（对外暴露）
  --listen-client-urls=[***] \  # 监听客户端连接地址（容器内）
  --initial-advertise-peer-urls=[***] \  # 节点间通信地址（对外暴露）
  --listen-peer-urls=[***] \  # 监听节点间连接地址（容器内）
  --initial-cluster=etcd-node-1=[***] \  # 初始集群配置（单节点）
  --initial-cluster-token=etcd-cluster-token \  # 集群令牌（确保唯一性）
  --initial-cluster-state=new  # 集群状态（new 表示新建集群）

集群模式示例（3 节点，Docker Compose）

适用于测试环境模拟 etcd 集群，使用 Docker Compose 编排 3 个节点：

创建 docker-compose.yml 文件：

version: '3'
services:
  etcd-1:
    image: <镜像仓库地址>/etcd:<tag>
    container_name: etcd-1
    ports:
      - "2379:2379"  # 客户端端口
      - "2380:2380"  # 节点间通信端口
    volumes:
      - etcd-data-1:/var/lib/etcd
    command:
      - etcd
      - --name=etcd-1
      - --data-dir=/var/lib/etcd
      - --advertise-client-urls=[***]
      - --listen-client-urls=[***]
      - --initial-advertise-peer-urls=[***]
      - --listen-peer-urls=[***]
      - --initial-cluster=etcd-1=[***]
      - --initial-cluster-token=etcd-cluster-token
      - --initial-cluster-state=new
    networks:
      - etcd-net

  etcd-2:
    image: <镜像仓库地址>/etcd:<tag>
    container_name: etcd-2
    ports:
      - "2381:2379"
      - "2382:2380"
    volumes:
      - etcd-data-2:/var/lib/etcd
    command:
      - etcd
      - --name=etcd-2
      - --data-dir=/var/lib/etcd
      - --advertise-client-urls=[***]
      - --listen-client-urls=[***]
      - --initial-advertise-peer-urls=[***]
      - --listen-peer-urls=[***]
      - --initial-cluster=etcd-1=[***]
      - --initial-cluster-token=etcd-cluster-token
      - --initial-cluster-state=new
    networks:
      - etcd-net

  etcd-3:
    image: <镜像仓库地址>/etcd:<tag>
    container_name: etcd-3
    ports:
      - "2383:2379"
      - "2384:2380"
    volumes:
      - etcd-data-3:/var/lib/etcd
    command:
      - etcd
      - --name=etcd-3
      - --data-dir=/var/lib/etcd
      - --advertise-client-urls=[***]
      - --listen-client-urls=[***]
      - --initial-advertise-peer-urls=[***]
      - --listen-peer-urls=[***]
      - --initial-cluster=etcd-1=[***]
      - --initial-cluster-token=etcd-cluster-token
      - --initial-cluster-state=new
    networks:
      - etcd-net

volumes:
  etcd-data-1:
  etcd-data-2:
  etcd-data-3:

networks:
  etcd-net:
    driver: bridge

启动集群：

docker-compose up -d

数据持久化

etcd 数据需持久化存储以避免容器重启后数据丢失，支持以下两种方式：

• Docker 卷（推荐）：由 Docker 管理存储目录，如上述示例中的 etcd-data:/var/lib/etcd。
• 绑定挂载：指定主机目录作为数据存储路径：

  docker run -d \
    --name etcd \
    -v /host/path/to/etcd/data:/var/lib/etcd \  # 主机目录绑定到容器内数据目录
    <镜像仓库地址>/etcd:<tag> \
    ...  # 其他参数
  

配置参数说明

etcd 主要通过命令行参数配置，常用参数说明如下：

客户端交互示例

使用 etcdctl 工具（容器内已内置）与 etcd 服务交互：

1. 进入容器：

   docker exec -it etcd-single sh
   

2. 存储键值对：

   etcdctl put /my-key "my-value"
   

3. 获取键值对：

   etcdctl get /my-key
   

4. 监听键变化：

   etcdctl watch /my-key  # 另一个终端执行 put 操作，此终端会输出变化
   

注意事项

• 镜像标签选择：需根据 Kubernetes 集群版本选择匹配的 etcd 标签（如 Kubernetes 1.24 推荐 etcd v3.5.10+），避免版本不兼容。
• 生产环境配置：生产环境需部署多节点集群（至少 3 节点），启用 HTTPS 加密通信，配置数据备份策略。
• 资源限制：根据集群规模调整容器 CPU/内存资源限制，避免资源不足影响性能。
• 备份与恢复：定期通过 etcdctl snapshot save 备份数据，确保故障时可恢复。