1.基础系统配置
- 准备一台虚机配置内存4G/硬盘30G以上
- 最小化安装
Ubuntu 22.04 server - 配置基础网络、更新源、SSH登录等
支持系统 （截止2025年12月17日）
- Alibaba Linux 2.1903, 3.2104(notes)
- Alma Linux 8, 9
- Anolis OS 8.x RHCK, 8.x ANCK
- CentOS/RHEL 7, 8, 9
- Debian 10, 11(notes)
- Fedora 34, 35, 36, 37
- Kylin Linux Advanced Server V10 麒麟V10 Tercel, Lance
- openEuler 22.03 LTS, 24.03 LTS(notes)
- openSUSE Leap 15.x(notes)
- Rocky Linux 8, 9
- Ubuntu 16.04, 18.04, 20.04, 22.04, 24.04
注意: 确保在干净的系统上开始安装，不能使用曾经装过kubeadm或其他k8s发行版的环境
2.下载kubeasz代码、二进制、默认容器镜像
- 下载工具脚本ezdown，举例使用kubeasz版本3.6.8
bash
#下载工具脚本ezdown
export release=3.6.8
wget https://github.com/easzlab/kubeasz/releases/download/${release}/ezdown
#下载如果失败，使用代理下载
wget
https://mirror.ghproxy.com/https://github.com/easzlab/kubeasz/releases/download/${release}/ezdown
chmod +x ./ezdown- 使用工具脚本下载（更多关于ezdown的参数，运行./ezdown 查看）
下载kubeasz代码、二进制、默认容器镜像
# 国内环境
./ezdown -D
# 海外环境
#./ezdown -D -m standard【可选】下载额外容器镜像（cilium,flannel,prometheus等）
# 按需下载
./ezdown -X dashboard
./ezdown -X prometheus
...【可选】下载离线系统包 (适用于无法使用yum/apt仓库情形)
./ezdown -P上述脚本运行成功后，所有文件（kubeasz代码、二进制、离线镜像）均已整理好放入目录/etc/kubeasz
/etc/kubeasz包含 kubeasz 版本为 ${release} 的发布代码/etc/kubeasz/bin包含 k8s/etcd/docker/cni 等二进制文件/etc/kubeasz/down包含集群安装时需要的离线容器镜像/etc/kubeasz/down/packages包含集群安装时需要的系统基础软件
如果报错：
bash
./ezdown -D
2025-12-17 17:00:54 [ezdown:786] INFO Action begin: download_all
2025-12-17 17:00:54 [ezdown:173] INFO downloading docker binaries, arch:x86_64, version:28.0.4
--2025-12-17 17:00:54-- https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/static/stable/x86_64/docker-28.0.4.tgz
Resolving mirrors.tuna.tsinghua.edu.cn (mirrors.tuna.tsinghua.edu.cn)... 101.6.15.130, 2402:f000:1:400::2
Connecting to mirrors.tuna.tsinghua.edu.cn (mirrors.tuna.tsinghua.edu.cn)|101.6.15.130|:443... connected.
HTTP request sent, awaiting response... 403 Forbidden
2025-12-17 17:00:54 ERROR 403: Forbidden.
2025-12-17 17:00:54 [ezdown:175] ERROR downloading docker failed默认调用的国内清华源。更改为其他国内源例如阿里源
bash
sed -i 's/mirrors.tuna.tsinghua.edu.cn/mirrors.aliyun.com/' ./ezdown如果再次报错：
bash
./ezdown -D
2025-12-17 17:09:55 [ezdown:786] INFO Action begin: download_all
2025-12-17 17:09:55 [ezdown:173] INFO downloading docker binaries, arch:x86_64, version:28.0.4
--2025-12-17 17:09:55-- https://mirrors.aliyun.com/docker-ce/linux/static/stable/x86_64/docker-28.0.4.tgz
Resolving mirrors.aliyun.com (mirrors.aliyun.com)... 47.123.18.240
Connecting to mirrors.aliyun.com (mirrors.aliyun.com)|47.123.18.240|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 78805317 (75M) [application/x-compressed-tar]
Saving to: 'docker-28.0.4.tgz'
docker-28.0.4.tgz 100%[=================================================>] 75.15M 4.09MB/s in 19s
2025-12-17 17:10:17 (4.02 MB/s) - 'docker-28.0.4.tgz' saved [78805317/78805317]
2025-12-17 17:10:18 [ezdown:192] WARN docker is already running.
2025-12-17 17:10:18 [ezdown:279] INFO downloading kubeasz: 3.6.8
Error response from daemon: Get "https://registry-1.docker.io/v2/": context deadline exceeded (Client.Timeout exceeded while awaiting headers)
2025-12-17 17:10:33 [ezdown:282] ERROR download failed!
2025-12-17 17:10:33 [ezdown:787] ERROR Action failed: download_allDocker 无法连接到 Docker Hub（registry-1.docker.io） ，导致拉取
kubeasz镜像超时失败。
虽然前面成功从 阿里云镜像站 下载了 Docker 二进制包（docker-28.0.4.tgz），但 Docker 引擎本身在拉取镜像时默认仍走官方 Docker Hub，而 Docker Hub 在国内访问极不稳定，经常超时或被墙。
单独手动配置 Docker 镜像加速器（Registry Mirror）
bash
tee << EOF >> /etc/docker/daemon.json
{ "registry-mirrors":
[ "https://docker.1panel.live",
"https://do.nark.eu.org",
"https://dc.j8.work",
"https://pilvpemn.mirror.aliyuncs.com",
"https://docker.m.daocloud.io",
"https://dockerproxy.com",
"https://docker.mirrors.ustc.edu.cn",
"https://docker.nju.edu.cn",
"https://mirror.ccs.tencentyun.com" ]
}
EOF
bash
systemctl restart docker在执行ok
bash
./ezdown -D
2025-12-17 17:52:53 [ezdown:786] INFO Action begin: download_all
2025-12-17 17:52:53 [ezdown:171] WARN docker binaries already existed
2025-12-17 17:52:54 [ezdown:192] WARN docker is already running.
2025-12-17 17:52:54 [ezdown:279] INFO downloading kubeasz: 3.6.8
3.6.8: Pulling from easzlab/kubeasz
f56be85fc22e: Pull complete
ea5757f4b3f8: Pull complete
bd0557c686d8: Pull complete
37d4153ce1d0: Pull complete
b39eb9b4269d: Pull complete
a3cff94972c7: Pull complete
6b32640e894a: Pull complete
Digest: sha256:dbd989bea272280c4d3b22d1d0b469ce310f7fbbd65566d1cdcfaef6e2d7638b
Status: Downloaded newer image for easzlab/kubeasz:3.6.8
docker.io/easzlab/kubeasz:3.6.8
2025-12-17 17:54:31 [ezdown:288] DEBUG run a temporary container
3bd002a989fe9869ebba1b5bc681cc312526687c42f1e0aff8d478fe967f063e
2025-12-17 17:54:31 [ezdown:295] DEBUG cp kubeasz code from the temporary container
Successfully copied 15.4MB to /etc/kubeasz
2025-12-17 17:54:31 [ezdown:297] DEBUG stop&remove temporary container
temp_easz
2025-12-17 17:54:32 [ezdown:309] INFO downloading kubernetes: v1.34.2 binaries
v1.34.2: Pulling from easzlab/kubeasz-k8s-bin
1b7ca6aea1dd: Pull complete
86afb3d277cf: Pull complete
b66ae37c5414: Pull complete
Digest: sha256:1235371ef995800b45158b59b569c4a9c25eafc2e8f81b7596b6c0fefaafc605
Status: Downloaded newer image for easzlab/kubeasz-k8s-bin:v1.34.2
docker.io/easzlab/kubeasz-k8s-bin:v1.34.2
2025-12-17 17:57:04 [ezdown:313] DEBUG run a temporary container
e67dd6af21ce6ab9cd2896bd7a47700a678f1f7d711e6576ecd26fd2d2f5b521
2025-12-17 17:57:04 [ezdown:315] DEBUG cp k8s binaries
Successfully copied 368MB to /etc/kubeasz/k8s_bin_tmp
2025-12-17 17:57:05 [ezdown:318] DEBUG stop&remove temporary container
temp_k8s_bin
2025-12-17 17:57:05 [ezdown:326] INFO downloading extral binaries kubeasz-ext-bin:1.13.0
1.13.0: Pulling from easzlab/kubeasz-ext-bin
a88dc8b54e91: Pull complete
6184b75f4087: Pull complete
a6213fefeeee: Pull complete
78713b053946: Pull complete
bf6544ef2403: Pull complete
e7b92baaefa0: Pull complete
a4c3d25e2eec: Pull complete
Digest: sha256:767f44b870ba7be6448433a88499234d0f47a04f9a27f1fa6cda35c2b446c9e7
Status: Downloaded newer image for easzlab/kubeasz-ext-bin:1.13.0
docker.io/easzlab/kubeasz-ext-bin:1.13.0
2025-12-17 17:59:21 [ezdown:330] DEBUG run a temporary container
d5ec54b2c4de8e02d47a90c884e6e70c37910d2b0a9fd53f5241809576d70bcb
2025-12-17 17:59:21 [ezdown:332] DEBUG cp extral binaries
Successfully copied 756MB to /etc/kubeasz/extra_bin_tmp
2025-12-17 17:59:23 [ezdown:335] DEBUG stop&remove temporary container
temp_ext_bin
2: Pulling from library/registry
44cf07d57ee4: Pull complete
bbbdd6c6894b: Pull complete
8e82f80af0de: Pull complete
3493bf46cdec: Pull complete
6d464ea18732: Pull complete
Digest: sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373
Status: Downloaded newer image for registry:2
docker.io/library/registry:2
2025-12-17 17:59:42 [ezdown:656] INFO start local registry ...
f873c0e90d2caf14d65f3af0c6e4bb7bac3eab966f88d016ab42f6bd8fdc81ae
2025-12-17 17:59:43 [ezdown:369] INFO download default images, then upload to the local registry
v3.28.4: Pulling from calico/cni
2772ed331197: Pull complete
385e82df3dbc: Pull complete
Digest: sha256:77f4e494343f41763bb7438e1ab61d07094abe07584b56c01ab5c3fb0b9bb4de 36.38MB/140.9MB
Status: Downloaded newer image for calico/node:v3.28.43fda8b4fdd5346b46643ec6ce
docker.io/calico/node:v3.28.4e for calico/cni:v3.28.4
The push refers to repository [easzlab.io.local:5000/easzlab/node]
c679b3382fdd: Pushed
v3.28.4: digest: sha256:cec640f3131eb91fece8b7dc14f5241b5192fe7faa107f91e2497c09332b96c8 size: 530
1.12.4: Pulling from coredns/coredns3cc769c69646e043790a7ee920c8c0edfe9987d0772 6.198MB/34.03MB
b77b57d31f7f: Downloading [============> ] 2.83MB/11.53MB
2e4cf50eeb92: Pull complete
56ce5a7a0a8c: Pull complete
e1089d61b200: Pull complete
0f8b424aa0b9: Pull complete
d557676654e5: Pull complete
d82bc7a76a83: Pull complete
b77b57d31f7f: Pull complete
d6accb83dc23: Pull complete
Digest: sha256:7d60df155cde82d04c93009ac97fa3e8c02e05d3fc6283a0832765b181537393
Status: Downloaded newer image for easzlab/k8s-dns-node-cache:1.26.4
docker.io/easzlab/k8s-dns-node-cache:1.26.4
The push refers to repository [easzlab.io.local:5000/easzlab/k8s-dns-node-cache]
bcbd50e29d07: Pushed
d23ed4180a23: Pushed
1.26.4: digest: sha256:422a07a940516af2363400de76d910c829d6319e9070cf7f48de10bcd51b784c size: 741
docker.io/coredns/coredns:1.12.4
The push refers to repository [easzlab.io.local:5000/easzlab/coredns]
44925e5e2cc9: Pushed
54559abf8a8c: Pushed
bfe9137a1b04: Pushed
f4aee9e53c42: Pushed
1a73b54f556b: Pushed
2a92d6ac9e4f: Pushed
bbb6cacb8c82: Pushed
6f1cdceb6a31: Pushed
af5aa97ebe6c: Pushed
4d049f83d9cf: Pushed
114dde0fefeb: Pushed
4840c7c54023: Pushed
8fa10c0194df: Pushed
bff7f7a9d443: Pushed
1.12.4: digest: sha256:5fe4ce2f40fba78ebd7941f205d5ba21058e6aebff00878325f3f2645d9d465c size: 3233
1.26.4: Pulling from easzlab/k8s-dns-node-cache
b77b57d31f7f: Downloading [===========> ] 2.699MB/11.53MB
d6accb83dc23: Download complete
35d697fe2738: Pull complete
bfb59b82a9b6: Pull complete
4eff9a62d888: Pull complete
a62778643d56: Pull complete
7c12895b777b: Pull complete
3214acf345c0: Pull complete
5664b15f108b: Pull complete
0bab15eea81d: Pull complete
4aa0ea1413d3: Pull complete
da7816fa955e: Pull complete
ddf74a63f7d8: Pull complete
6b6c881bc207: Pull complete
Digest: sha256:803cdfa3bcafcf988d5419669da336321977ad7a2371cb5a93316947486f3c58
Status: Downloaded newer image for easzlab/metrics-server:v0.8.0
docker.io/easzlab/metrics-server:v0.8.0
The push refers to repository [easzlab.io.local:5000/easzlab/metrics-server]
90c3da41cc55: Pushed
bfe9137a1b04: Mounted from easzlab/coredns
f4aee9e53c42: Mounted from easzlab/coredns
1a73b54f556b: Mounted from easzlab/coredns
2a92d6ac9e4f: Mounted from easzlab/coredns
bbb6cacb8c82: Mounted from easzlab/coredns
6f1cdceb6a31: Mounted from easzlab/coredns
af5aa97ebe6c: Mounted from easzlab/coredns
4d049f83d9cf: Mounted from easzlab/coredns
48c0fb67386e: Pushed
8fa10c0194df: Mounted from easzlab/coredns
f464af4b9b25: Pushed
v0.8.0: digest: sha256:d1a527deee93f23ffac97a2be308bf0bd5df3e686427ee447b9699e73049df72 size: 2814
3.10: Pulling from easzlab/pause
61d9e957431b: Pull complete
Digest: sha256:c7e33e8cea1c259324e8b20c62819b6a3703087088a8172d408d50e7c73099f4
Status: Downloaded newer image for easzlab/pause:3.10
docker.io/easzlab/pause:3.10
The push refers to repository [easzlab.io.local:5000/easzlab/pause]
d8bdedd33a4e: Pushed
3.10: digest: sha256:7faf0ab837630eb90a8e919f1ef2ba350609983bb001c4d76a27972c664a0dd9 size: 527
2025-12-17 18:15:41 [ezdown:788] INFO Action successed: download_all或者执行./ezdown -D报错：
bash
./ezdown -D
2025-12-21 11:16:53 [ezdown:786] INFO Action begin: download_all
2025-12-21 11:16:53 [ezdown:173] INFO downloading docker binaries, arch:x86_64, version:28.0.4
--2025-12-21 11:16:53-- https://mirrors.aliyun.com/docker-ce/linux/static/stable/x86_64/docker-28.0.4.tgz
Resolving mirrors.aliyun.com (mirrors.aliyun.com)... 36.147.34.23, 36.147.34.27, 36.147.34.26, ...
Connecting to mirrors.aliyun.com (mirrors.aliyun.com)|36.147.34.23|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 78805317 (75M) [application/x-compressed-tar]
Saving to: 'docker-28.0.4.tgz'
docker-28.0.4.tgz 100%[=======================================>] 75.15M 23.3MB/s in 3.3s
2025-12-21 11:16:57 (22.7 MB/s) - 'docker-28.0.4.tgz' saved [78805317/78805317]
Unit docker.service could not be found.
2025-12-21 11:16:59 [ezdown:194] DEBUG generate docker service file
2025-12-21 11:16:59 [ezdown:220] DEBUG generate docker config: /etc/docker/daemon.json
2025-12-21 11:16:59 [ezdown:222] DEBUG prepare register mirror for CN
2025-12-21 11:16:59 [ezdown:269] DEBUG enable and start docker
Created symlink /etc/systemd/system/multi-user.target.wants/docker.service → /etc/systemd/system/docker.service.
Job for docker.service failed because the control process exited with error code.
See "systemctl status docker.service" and "journalctl -xeu docker.service" for details.
2025-12-21 11:16:59 [ezdown:787] ERROR Action failed: download_all
root@ubuntu11:~# systemctl status docker.service
● docker.service - Docker Application Container Engine
Loaded: loaded (]8;;file://ubuntu11/etc/systemd/system/docker.service/etc/systemd/system/docker.service]8;;; enabled; preset: enabled)
Active: activating (auto-restart) (Result: exit-code) since Sun 2025-12-21 11:17:46 UTC; 4s ago
Docs: ]8;;http://docs.docker.iohttp://docs.docker.io]8;;
Process: 1599 ExecStart=/opt/kube/bin/dockerd (code=killed, signal=TERM)
Process: 1603 ExecStartPost=/sbin/iptables -I FORWARD -s 0.0.0.0/0 -j ACCEPT (code=exited, status=203/>
Main PID: 1599 (code=killed, signal=TERM)
CPU: 5ms说明问题出在
bash
ExecStartPost=/sbin/iptables -I FORWARD -s 0.0.0.0/0 -j ACCEPT (code=exited, status=203/>这条命令可见是iptables 的命令，那么检查iptables是否没有安装，或者是其他问题。
安装iptables
bash
sudo apt install iptables # Ubuntu/Debian
# 或
sudo yum install iptables # CentOS/RHEL或者 service文件里面删除这一条启动命令也行。
在执行即可成功。
3.安装集群
-
容器化运行 kubeasz
./ezdown -S
bash
./ezdown -S
2025-12-21 11:32:07 [ezdown:786] INFO Action begin: start_kubeasz_docker
Loaded image: easzlab/kubeasz:3.6.8
2025-12-21 11:32:07 [ezdown:688] INFO try to run kubeasz in a container
2025-12-21 11:32:07 [ezdown:692] DEBUG get host IP: 10.0.0.11
2025-12-21 11:32:07 [ezdown:696] DEBUG generate ssh key pair
06f250df6568ee4d74115b6f6a15eccf0ab03022a0e77fd6317395ec102761fa
2025-12-21 11:32:07 [ezdown:788] INFO Action successed: start_kubeasz_docker
bash
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
06f250df6568 easzlab/kubeasz:3.6.8 "tail -f /dev/null" 33 seconds ago Up 33 seconds kubeasz
f36c310a2d34 registry:2 "/entrypoint.sh /etc..." 8 minutes ago Up 8 minutes local_registry-
使用默认配置安装 aio 集群
docker exec -it kubeasz ezctl start-aio
如果安装失败，查看日志排除后，使用如下命令重新安装aio集群
docker exec -it kubeasz ezctl setup default all
bash
docker exec -it kubeasz ezctl start-aio
2025-12-21 19:33:27 [ezctl:451] INFO get local host ipadd: 10.0.0.11
2025-12-21 19:33:27 [ezctl:145] DEBUG generate custom cluster files in /etc/kubeasz/clusters/default
2025-12-21 19:33:27 [ezctl:151] DEBUG set versions
2025-12-21 19:33:27 [ezctl:182] DEBUG cluster default: files successfully created.
2025-12-21 19:33:27 [ezctl:183] INFO next steps 1: to config '/etc/kubeasz/clusters/default/hosts'
2025-12-21 19:33:27 [ezctl:184] INFO next steps 2: to config '/etc/kubeasz/clusters/default/config.yml'
ansible-playbook -i clusters/default/hosts -e @clusters/default/config.yml playbooks/90.setup.yml
*** Component Version *********************
*******************************************
* kubernetes: v1.34.1
* etcd: v3.6.4
* calico: v3.28.4
*******************************************
2025-12-21 19:33:27 [ezctl:249] INFO cluster:default setup step:all begins in 5s, press any key to abort:
PLAY [kube_master,kube_node,etcd,ex_lb,chrony] *********************************
TASK [Gathering Facts] *********************************************************
fatal: [10.0.0.11]: UNREACHABLE! => {"changed": false, "msg": "Data could not be sent to remote host \"10.0.0.11\". Make sure this host can be reached over ssh: ssh: connect to host 10.0.0.11 port 22: Connection refused\r\n", "unreachable": true}
PLAY RECAP *********************************************************************
10.0.0.11 : ok=0 changed=0 unreachable=1 failed=0 skipped=0 rescued=0 ignored=0 由以上提示可知，该脚本采用ansible进行部署。出错的地方在
ssh的
4.验证安装
$ source ~/.bashrc
$ kubectl version # 验证集群版本
$ kubectl get node # 验证节点就绪 (Ready) 状态
$ kubectl get pod -A # 验证集群pod状态，默认已安装网络插件、coredns、metrics-server等
$ kubectl get svc -A # 验证集群服务状态- 登录
dashboard可以查看和管理集群，更多内容请查阅dashboard文档
5.清理
以上步骤创建的K8S开发测试环境请尽情折腾，碰到错误尽量通过查看日志、上网搜索、提交issues等方式解决；当然你也可以清理集群后重新创建。
在宿主机上，按照如下步骤清理
- 清理集群
docker exec -it kubeasz ezctl destroy default - 重启节点，以确保清理残留的虚拟网卡、路由等信息