mirantis/kubeadm-dind-cluster

kubeadm-dind-cluster

镜像概述和主要用途

kubeadm-dind-cluster是一个基于kubeadm和DIND（Docker in Docker）的Kubernetes多节点集群解决方案，主要面向Kubernetes开发者及扩展Kubernetes的项目。它支持本地开发工作流和利用远程高性能机器/云实例构建Kubernetes、启动测试集群及运行e2e测试。与Minikube相比，它更适合Kubernetes本身的开发，尤其在CI环境（如Travis）中可避免嵌套虚拟化问题。

核心功能和特性

• 多节点支持：可创建包含主节点和多个工作节点的Kubernetes集群
• 标准部署流程：基于kubeadm实现，更接近生产环境集群配置
• 版本兼容性：支持Kubernetes 1.8.x、1.9.x和1.10.x版本
• 快速启动与重启：相比虚拟机方案，集群启动和重启速度更快
• 源码集成：支持从Kubernetes源码构建并部署集群
• e2e测试支持：可运行Kubernetes conformance测试及自定义测试
• IPv6模式：提供实验性IPv6-only集群支持
• 集群状态转储：支持将集群状态导出为文本或base64压缩格式，便于问题诊断
• 远程Docker支持：可在远程Docker环境（如GCE实例）上构建和运行集群
• 灵活配置：支持自定义CNI插件（bridge、flannel、calico、weave等）

使用场景和适用范围

• Kubernetes核心组件开发与测试
• 扩展Kubernetes的项目（如Virtlet）开发
• 需要多节点环境的Kubernetes功能测试
• CI/CD流水线中的自动化测试（如Travis、Circle CI）
• 在资源受限环境中运行Kubernetes多节点集群
• 远程高性能机器上的Kubernetes构建与测试

系统要求

• Docker 1.12+（推荐）
• kubectl版本需与使用的Kubernetes版本匹配（如使用hyperkube 1.9.x时，建议使用kubectl 1.9.x）
• 不支持btrfs存储驱动（可通过设置RUN_ON_BTRFS_ANYWAY环境变量强制运行，但不推荐）
• 默认使用Docker化构建，无需本地安装Go环境（可通过设置KUBEADM_DIND_LOCAL变量启用本地构建）

Mac OS X特殊要求

• 需安装md5sha1sum（可通过brew install md5sha1sum获取）
• 从源码构建Kubernetes时，需确保可本地构建kubectl（make WHAT=cmd/kubectl可正常运行）

使用方法和配置说明

使用预配置脚本

针对Kubernetes 1.8、1.9和1.10版本提供预配置脚本，适合快速启动特定版本集群：

shell
# 下载对应版本脚本（以1.8为例，可替换为1.9或1.10）
$ wget https://cdn.rawgit.com/Mirantis/kubeadm-dind-cluster/master/fixed/dind-cluster-v1.8.sh
$ chmod +x dind-cluster-v1.8.sh

# 启动集群
$ ./dind-cluster-v1.8.sh up

# 将kubectl添加到PATH
$ export PATH="$HOME/.kubeadm-dind-cluster:$PATH"

# 验证集群状态
$ kubectl get nodes
NAME          STATUS    AGE       VERSION
kube-master   Ready     6m        v1.8.6
kube-node-1   Ready     5m        v1.8.6
kube-node-2   Ready     5m        v1.8.6

# Kubernetes Dashboard地址：http://localhost:8080/api/v1/namespaces/kube-system/services/kubernetes-dashboard:/proxy

# 重启集群（比首次启动快）
$ ./dind-cluster-v1.8.sh up

# 停止集群
$ ./dind-cluster-v1.8.sh down

# 清理DIND容器和卷（切换Kubernetes版本时必须执行）
$ ./dind-cluster-v1.8.sh clean

与Kubernetes源码一起使用

适用于需要从源码构建并测试Kubernetes的场景：

shell
# 克隆kubeadm-dind-cluster仓库
$ git clone git@github.com:Mirantis/kubeadm-dind-cluster.git ~/dind

# 进入Kubernetes源码目录
$ cd ~/work/kubernetes/src/k8s.io/kubernetes

# 设置环境变量以构建kubeadm和hyperkube
$ export BUILD_KUBEADM=y
$ export BUILD_HYPERKUBE=y

# 构建二进制文件、镜像并启动集群
$ ~/dind/dind-cluster.sh up

# 验证集群状态
$ kubectl get nodes
NAME          STATUS         AGE
kube-master   Ready,master   1m
kube-node-1   Ready          34s
kube-node-2   Ready          34s

# Kubernetes Dashboard地址：http://localhost:8080/ui

# 运行conformance测试
$ ~/dind/dind-cluster.sh e2e

# 重建并重启集群
$ ~/dind/dind-cluster.sh up

# 运行特定e2e测试（基于子字符串匹配）
$ ~/dind/dind-cluster.sh e2e "existing RC"

# 关闭集群
$ ~/dind/dind-cluster.sh down

首次启动因需构建基础镜像和Kubernetes二进制文件可能较慢，后续启动速度显著提升。

IPv6模式（实验性）

通过设置IP_MODE环境变量启用IPv6-only模式，可自定义DNS64前缀、DIND子网和服务CIDR等参数：

shell
export IP_MODE=ipv6
export EMBBEDDED_CONFIG=y
export DNS64_PREFIX=fd00:77:64:ff9b::
export DIND_SUBNET=fd00:77::
export SERVICE_CIDR=fd00:77:30::/110

注意：如需完整IPv6支持，可能需要 cherry-pick 两个Kubernetes PR：

• PR #56245：更新Kubenet CNI模板至v0.3.1
• PR #52748：在e2e测试IP:port端点中为IPv6地址添加括号

配置自定义

可通过编辑config.sh文件覆盖默认设置，关键配置项包括：

• CNI_PLUGIN：指定CNI插件（可选值：bridge、flannel、calico、weave）
• 节点数量、网络参数、镜像仓库等（详见config.sh文件注释）

远程Docker / GCE使用

支持在远程Docker环境（如GCE实例）上构建和运行集群，需配合ssh端口转发：

shell
# 加载GCE环境配置（保留docker-machine shell环境）
. gce-setup.sh

需转发KUBE_RSYNC_PORT和APISERVER_PORT端口，具体配置参考Kubernetes源码中build/README.md的"Really remote Docker engine"部分。

集群状态转储

支持将集群状态导出为文本或压缩格式，便于CI环境中的问题诊断：

• ./dind-cluster.sh dump：导出集群状态为带标记的文本块
• ./dind-cluster.sh dump64：导出集群状态为base64压缩文本块
• ./dind-cluster.sh split-dump：将文本块分割为文件（输出至cluster-dump/目录）
• ./dind-cluster.sh split-dump64：将base64压缩文本块分割为文件

示例：从Travis CI日志中提取并解析集群状态：

shell
travis logs NNN.N | ./dind-cluster.sh split-dump64

转储内容包括：节点系统服务状态与日志、进程/容器/网络信息、Pod容器日志、kubectl资源信息等。

附加说明

• 非串行[Conformance] e2e测试可正常通过
• 串行[Serial]...[Conformance]测试存在部分问题，可尝试运行：

  shell
  $ dind/dind-cluster.sh e2e-serial
  

相关工作

• kubernetes-dind-cluster：kubeadm-dind-cluster的前身，启动速度更快但采用非标准部署方式
• kubeadm-ci-dind/kubeadm-ci-packager/kubeadm-ci-tester：专注于CI环境，包含打包步骤，速度较慢
• nkube：在Kubernetes内部启动Kubernetes集群（Kubernetes-in-Kubernetes）