使用kubeasz 3.6.0部署Kubernetes 1.27集群：国内网络零镜像拉取失败实践

本文面向 运维工程师 / 云原生初学者，系统讲解如何使用 kubeasz（基于 Ansible 的国内开源 K8s 部署工具） 快速、稳定地部署一套 Kubernetes 集群，并深入解释核心配置文件（hosts / config.yml）与关键执行命令。

一、为什么选择 kubeasz

在国内网络环境下，直接使用 kubeadm 或 Kubespray 部署 Kubernetes 往往会遇到以下问题：

• 官方镜像源访问慢甚至失败
• 组件版本、参数配置复杂
• 部署失败后排错成本高

kubeasz 的优势非常明确：

• 国内友好：默认使用阿里云 / 华为云镜像源，彻底解决镜像拉取难题。
• 轻量简洁：核心配置文件极少，上手成本低。
• 基于 Ansible：部署过程可控、可审计、可重复。
• 组件齐全：内置 Calico / Flannel / Ingress / Dashboard 等常用组件。
• 支持扩缩容：天然支持 add-node / reset 等运维操作。

项目地址：https://github.com/easzlab/kubeasz

二、集群规划与环境准备

2.1 节点规划示例（3 节点）

角色	主机名	IP 地址	说明
Master	master1	192.168.1.10	控制节点 + etcd
Worker	worker1	192.168.1.11	工作节点
Worker	worker2	192.168.1.12	工作节点

💡 提示：实验环境可将 etcd 与 master 复用；生产环境建议 etcd 使用 3 节点独立部署以保证高可用。

2.2 所有节点基础配置（必须）

在所有节点（master1, worker1, worker2）上执行以下命令，完成基础环境准备。

# 1. 关闭防火墙（CentOS）
systemctl stop firewalld && systemctl disable firewalld
# Ubuntu
ufw disable

# 2. 关闭 SELinux（CentOS）
setenforce 0
sed -i 's/^SELINUX=enforcing$/SELINUX=disabled/' /etc/selinux/config

# 3. 关闭 swap（K8s 强制要求）
swapoff -a
sed -i '/swap/s/^/#/' /etc/fstab

# 4. 主机名解析
cat >> /etc/hosts << EOF
192.168.1.10 master1
192.168.1.11 worker1
192.168.1.12 worker2
EOF

# 5. 内核参数
cat > /etc/sysctl.d/k8s.conf << EOF
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF
sysctl --system

三、Ansible 控制节点准备（master1）

部署工作将在 master1 节点上发起，因此需要将其配置为 Ansible 控制节点。

3.1 安装依赖

# CentOS
yum install -y git python3 python3-pip sshpass

# Ubuntu
apt update && apt install -y git python3 python3-pip sshpass

3.2 安装指定版本 Ansible

kubeasz 对 Ansible 版本有特定要求，安装指定版本以确保兼容性。

pip3 install ansible==2.12.10 jinja2==3.1.2
ansible --version

3.3 配置 SSH 免密登录

这是 Ansible 工作的基础，必须配置成功。

ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
ssh-copy-id root@192.168.1.10
ssh-copy-id root@192.168.1.11
ssh-copy-id root@192.168.1.12

⚠️ 注意：Ansible 强依赖免密登录，若未配置，后续所有 playbook 执行都会直接失败。

四、安装与初始化 kubeasz

4.1 克隆项目

git clone https://github.com/easzlab/kubeasz.git /etc/kubeasz
cd /etc/kubeasz

4.2 下载所需二进制与镜像

这一步会从国内镜像源拉取所有部署所需的二进制文件和容器镜像，是保证后续部署顺畅的关键。

./ezdown -D

作用说明：

• 下载 kubelet / kubeadm / kubectl 等 Kubernetes 二进制文件。
• 下载 containerd / etcd 等运行时与存储组件。
• 自动使用国内镜像源，速度有保障。

五、创建并配置集群

5.1 创建集群配置目录

我们将创建一个名为 my-cluster 的集群配置目录，并复制示例配置文件作为模板。

mkdir -p /etc/kubeasz/clusters/my-cluster
cp -r example/* clusters/my-cluster/

六、核心配置文件详解（重点）

kubeasz 的配置非常简洁，主要就两个文件：hosts 和 config.yml。理解它们，你就掌握了部署的命脉。

6.1 主机清单：hosts（INI）

路径： /etc/kubeasz/clusters/my-cluster/hosts

这个文件定义了集群中有哪些节点，以及它们分别扮演什么角色。

[all]
master1 ansible_host=192.168.1.10 ip=192.168.1.10
worker1 ansible_host=192.168.1.11 ip=192.168.1.11
worker2 ansible_host=192.168.1.12 ip=192.168.1.12

[kube_master]
master1

[kube_node]
worker1
worker2

[etcd]
master1

[k8s_cluster:children]
kube_master
kube_node

📌 核心：该文件是 kubeasz 的调度核心，所有 Ansible Playbook 都依据此文件识别节点角色并执行任务。

6.2 集群参数：config.yml（YAML）

路径： /etc/kubeasz/clusters/my-cluster/config.yml

这个文件定义了集群的各项关键参数，我们只需修改几处即可。

# K8s 版本
kube_version: 1.27.0

# 容器运行时
container_manager: containerd

# 网络插件
network_plugin: calico

# Pod 网段
kube_pods_subnet: 10.233.64.0/18

# Service 网段
kube_service_subnet: 10.233.0.0/18

# CoreDNS 地址
kube_dns_cluster_ip: 10.233.0.10

# 国内镜像源
repo_type: aliyun
enable_k8s_repo_cache: true

📌 核心：90% 的部署场景只需要修改以上几个参数即可完成个性化配置。例如，你可以将 kube_version 改为 1.26.6，或者将 network_plugin 改为 flannel。

七、执行部署

7.1 环境预检查（强烈推荐）

在正式部署前，强烈建议运行预检查脚本，它能提前发现环境问题，避免部署中途失败。

ansible-playbook -i clusters/my-cluster/hosts 00-prepare.yml

作用：

• 检查 swap 是否已关闭、内核参数是否正确、所需端口是否可用。
• 在所有节点安装部署所需的基础依赖包。

7.2 初始化 Kubernetes 集群

如果预检查全部通过，就可以执行核心部署脚本了。

ansible-playbook -i clusters/my-cluster/hosts 90-init-cluster.yml

⏱ 部署时间：根据网络和节点性能，通常需要 5 到 15 分钟。Ansible 会输出详细的执行日志，你可以清晰地看到每个步骤的进展。

八、部署验证

部署完成后，在 master1 节点上执行以下命令验证集群状态。

kubectl get nodes
kubectl get pods -n kube-system
kubectl cluster-info

如果一切顺利，所有节点状态都应为 Ready，kube-system 命名空间下的核心 Pod（如 calico、coredns、apiserver 等）都应处于 Running 状态。

九、常用运维操作

9.1 扩容 Worker 节点

当需要增加工作节点时，只需在新节点上完成“基础配置”，并在 hosts 文件的 [all] 和 [kube_node] 部分添加新节点信息，然后运行：

ansible-playbook -i clusters/my-cluster/hosts add-node.yml

9.2 卸载集群（危险操作）

此操作会清除所有节点上的 Kubernetes 组件和数据，请谨慎使用。

ansible-playbook -i clusters/my-cluster/hosts 99-reset-cluster.yml

十、总结与后续

通过以上步骤，你应该已经成功在国内网络环境下部署了一套完整的 Kubernetes 集群。回顾一下，kubeasz 的优势在于：

• 定位清晰：专为国内环境优化，是解决镜像拉取问题的最优解之一。
• 配置简单：核心配置只有 hosts + config.yml 两个文件，学习成本低。
• 运维友好：基于 Ansible，整个部署过程可维护、可扩展、可复现，非常适合剧本化、自动化。
• 场景契合：无论是作为运维人员学习 K8s 的第一套实验集群，还是用于内网、离线或私有云环境的生产部署，kubeasz 都是一个可靠的选择。

希望这篇实践指南能帮助你顺利迈出 Kubernetes集群部署 的第一步。如果在实践中遇到问题，或想了解更多云原生和 DevOps 相关的深度内容，欢迎在 云栈社区 交流讨论，那里有更多实战经验和开源工具等你发现。