easzlab/kubeasz

kubeasz Docker镜像文档

一、镜像概述和主要用途

1.1 基本信息

该镜像是基于官方基础镜像（如Ubuntu/Debian）构建的容器化运行环境，用于在容器中执行kubeasz工具，实现Kubernetes集群的部署、管理和运维。kubeasz是一个轻量级Kubernetes集群部署工具，旨在简化Kubernetes的安装配置流程。

1.2 主要用途

• 在隔离容器环境中运行kubeasz，避免直接在宿主机安装依赖导致的环境冲突
• 标准化Kubernetes集群部署流程，确保不同环境下的部署一致性
• 快速搭建单节点或多节点Kubernetes集群，支持开发、测试及生产环境
• 集成kubeasz的集群管理功能，如节点扩缩容、版本升级、配置调整等

二、核心功能和特性

2.1 容器化隔离

• 基于容器技术实现kubeasz运行环境与宿主机隔离，避免系统依赖冲突
• 容器内预装kubeasz及所有必要依赖（如Ansible、kubectl、容器运行时等），无需额外配置

2.2 环境一致性

• 固定kubeasz版本及依赖组件版本，确保不同环境下部署的Kubernetes集群配置一致
• 支持通过环境变量动态调整部署参数，灵活适配不同集群需求

2.3 多版本支持

• 兼容主流Kubernetes版本（如v1.18+），可通过配置指定目标集群版本
• 支持多种网络插件（Calico、Flannel、Cilium等）和存储方案的集成

2.4 简化部署流程

• 容器启动后可直接执行kubeasz部署脚本，无需手动安装前置依赖
• 支持单节点快速部署（All-in-One模式）和多节点高可用（HA）部署

2.5 易于集成与扩展

• 支持挂载宿主机目录实现配置持久化和数据共享
• 可集成到CI/CD流程，实现集群部署的自动化和标准化

三、使用场景和适用范围

3.1 开发测试环境

• 快速搭建本地Kubernetes测试集群，验证应用兼容性
• 隔离不同版本Kubernetes集群的测试环境，避免相互干扰

3.2 生产环境部署

• 标准化企业级Kubernetes集群部署流程，降低人工操作风险
• 支持高可用模式部署，满足生产环境稳定性要求

3.3 多集群管理

• 在单台宿主机或多台服务器上通过容器化方式运行多个kubeasz实例，管理不同集群
• 统一集群部署策略，简化多集群版本升级和配置同步

3.4 教学与演示

• 作为Kubernetes部署教学工具，快速演示集群搭建全流程
• 降低学习者环境配置门槛，专注于集群部署逻辑理解

四、使用方法和配置说明

4.1 镜像拉取

从容器仓库拉取最新版本镜像（具体仓库地址需根据实际构建源确认，此处以示例仓库为例）：

bash
docker pull docker.xuanyuan.run/easzlab/kubeasz:latest

如需指定版本：

bash
docker pull docker.xuanyuan.run/easzlab/kubeasz:v3.0.0  # 替换为实际版本号

4.2 基本运行命令

4.2.1 单节点集群部署（All-in-One模式）

bash
docker run -itd \
  --name kubeasz-deploy \
  --privileged \
  -v /opt/kubeasz:/etc/kubeasz \  # 挂载配置目录（持久化集群配置）
  -v /var/lib/docker:/var/lib/docker \  # 共享宿主机Docker存储（如使用容器运行时）
  -v /etc/kubernetes:/etc/kubernetes \  # 挂载Kubernetes配置目录
  -e K8S_VERSION=v1.24.0 \  # 指定Kubernetes版本
  -e NETWORK_PLUGIN=calico \  # 指定网络插件
  easzlab/kubeasz:latest

4.2.2 进入容器执行部署

bash
docker exec -it kubeasz-deploy bash
# 在容器内执行kubeasz部署命令
cd /etc/kubeasz
./ezctl setup all-in-one

4.3 Docker Compose配置

创建docker-compose.yml文件：

yaml
version: '3'
services:
  kubeasz:
    image: docker.xuanyuan.run/easzlab/kubeasz:latest
    container_name: kubeasz-deploy
    privileged: true
    volumes:
      - /opt/kubeasz:/etc/kubeasz
      - /var/lib/docker:/var/lib/docker
      - /etc/kubernetes:/etc/kubernetes
      - /var/log/kubeasz:/var/log/kubeasz  # 挂载日志目录
    environment:
      - K8S_VERSION=v1.24.0
      - NETWORK_PLUGIN=calico
      - HA_MODE=false  # 是否启用高可用模式（true/false）
      - CLUSTER_NAME=my-k8s-cluster  # 集群名称
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

4.4 环境变量说明

4.5 配置参数

容器启动时可通过挂载自定义配置文件覆盖默认配置，配置文件路径：

• /etc/kubeasz/cluster.yml：集群基础配置（如节点信息、IP地址段）
• /etc/kubeasz/hosts：Ansible主机清单（多节点部署时指定节点角色）

示例：挂载自定义cluster.yml：

bash
docker run -itd \
  ...
  -v /path/to/custom-cluster.yml:/etc/kubeasz/cluster.yml \
  ...

4.6 容器操作

查看部署日志

bash
docker logs -f kubeasz-deploy
# 或查看挂载的日志文件
tail -f /var/log/kubeasz/deploy.log

停止/重启容器

bash
docker stop kubeasz-deploy
docker restart kubeasz-deploy

删除容器（保留配置）

bash
docker rm -f kubeasz-deploy

五、部署示例

5.1 单节点Kubernetes集群部署（docker run）

bash
# 拉取镜像
docker pull docker.xuanyuan.run/easzlab/kubeasz:latest

# 运行容器并部署单节点集群
docker run -it --name kubeasz-demo \
  --privileged \
  -v /opt/kubeasz-demo:/etc/kubeasz \
  -v /var/lib/docker:/var/lib/docker \
  -e K8S_VERSION=v1.25.0 \
  -e NETWORK_PLUGIN=flannel \
  docker.xuanyuan.run/easzlab/kubeasz:latest \
  /bin/bash -c "cd /etc/kubeasz && ./ezctl setup all-in-one"

5.2 高可用集群部署（Docker Compose）

docker-compose.yml：

yaml
version: '3'
services:
  kubeasz:
    image: docker.xuanyuan.run/easzlab/kubeasz:latest
    container_name: kubeasz-ha
    privileged: true
    volumes:
      - /opt/kubeasz-ha:/etc/kubeasz
      - /var/lib/docker:/var/lib/docker
      - /etc/kubernetes:/etc/kubernetes
      - /var/log/kubeasz-ha:/var/log/kubeasz
      - /path/to/hosts:/etc/kubeasz/hosts  # 挂载多节点主机清单
    environment:
      - K8S_VERSION=v1.24.0
      - HA_MODE=true
      - NETWORK_PLUGIN=calico
      - ETCD_VERSION=v3.5.4
    restart: unless-stopped

启动并进入容器执行高可用部署：

bash
docker-compose up -d
docker exec -it kubeasz-ha bash
cd /etc/kubeasz && ./ezctl setup ha