1. 控制端准备

# 任意能 ssh 到所有节点的机器

sudo dnf install -y python3 git

pip3 install ansible==9.0.0          # 2025 年 9 月验证无 bug 版本

ssh-keygen -t ed25519 -N ''          # 一路回车

ssh-copy-id root@<所有节点IP>         # 建议用 root，省去 escalate

2. 目录结构（建议直接 git clone）

k8s-ansible-quickstart/

├── inventory.ini               # 待生成

├── single-host-file.yaml       # 生成 inventory 的 playbook

├── vars.yaml                   # 全局变量

├── k8s.repo                    # 官方 1.31 源

├── single-master-node.yaml     # 真正干活的 playbook

└── README.md

3. 一键生成 inventory（交互式）

ansible-playbook -i inventory.ini single-host-file.yaml

脚本会问你： 

- 集群类型（single / multi） 

- Master IP 

- Worker IP（逗号分隔） 

执行完后自动生成如下结构的 `inventory.ini`：

[k8s_cluster:children]

k8s_master_sing_clus

k8s_worker_sing_clus

[k8s_master_sing_clus]

192.168.56.10

[k8s_worker_sing_clus]

192.168.56.11

192.168.56.12

4. 全局变量（vars.yaml）

docker_version: "26.1.4"

k8s: "1.31.1"

kubernetes_version: "v1.31.1"

# 根据实际网段改

ip_cpe: "192.168.56.10"      # control-plane-endpoint

ip_aaa: "192.168.56.10"      # apiserver-advertise-address

ip_pnc: "10.244.0.0/16"      # Pod CIDR

ip_sc:  "10.96.0.0/16"       # Service CIDR

5. 核心 Playbook 讲解（single-master-node.yaml）

5.1 系统级调优（所有节点）

- 关闭 swap、firewalld、selinux 

- 加载 br_netfilter / overlay 

- 内核参数：ip_forward、bridge-nf-call-iptables、swappiness=0 … 

- 安装 containerd，生成默认配置并重启 

5.2 安装 Docker-CE

- name: 添加 Docker 仓库

  command: yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

- name: 安装指定版本

  yum:

    name:

      - docker-ce-{{ docker_version }}

      - docker-ce-cli-{{ docker_version }}

    state: present

5.3 安装 Kubernetes 组件

- name: 添加 1.31 官方源

  copy:

    src: k8s.repo

    dest: /etc/yum.repos.d/kubernetes.repo

- name: 安装 kubelet kubeadm kubectl

  yum:

    name:

      - kubelet-{{ k8s }}

      - kubeadm-{{ k8s }}

      - kubectl-{{ k8s }}

    state: present

5.4 Master 节点初始化

- name: kubeadm init

  command: |

    kubeadm init \

      --control-plane-endpoint="{{ ip_cpe }}:6443" \

      --upload-certs \

      --apiserver-advertise-address={{ ip_aaa }} \

      --pod-network-cidr={{ ip_pnc }} \

      --service-cidr={{ ip_sc }} \

      --kubernetes-version={{ k8s }} --v=5

  when: inventory_hostname in groups['k8s_master_sing_clus']

随后自动： 

- 创建 `$HOME/.kube/config` 

- 安装 Flannel CNI（`kubectl apply -f kube-flannel.yml`） 

- 生成 `kubeadm join` 命令并保存到 `/opt/ansible/join-command`

5.5 Worker 节点自动加入

- name: 拷贝 join 命令到 worker

  copy:

    src: /opt/ansible/join-command

    dest: /tmp/kubeadm-join.sh

    mode: '0777'

  when: inventory_hostname in groups['k8s_worker_sing_clus']

- name: 执行加入集群

  command: sh /tmp/kubeadm-join.sh

6. 跑起来！

# 1. 生成 inventory

ansible-playbook -i inventory.ini single-host-file.yaml

# 2. 一键部署

ansible-playbook -i inventory.ini single-master-node.yaml

# 3. 在 Master 上看节点

ssh root@192.168.56.10

kubectl get nodes -o wide

预期输出：

NAME             STATUS   ROLES           AGE   VERSION   INTERNAL-IP

192.168.56.10    Ready    control-plane   3m    v1.31.1   192.168.56.10

192.168.56.11    Ready    <none>          1m    v1.31.1   192.168.56.11

192.168.56.12    Ready    <none>          1m    v1.31.1   192.168.56.12

7. 常见问题速查

| 现象 | 最可能原因 | 秒解 |

| `kubeadm init` 卡 `[etcd]` | 节点时间不同步 | `ansible all -m shell -a "chronyc makestep"` |

| `kubectl get nodes` 显示 `NotReady` | CNI 没装好 | `kubectl apply -f kube-flannel.yml` 再观察 |

| worker 加入报 `certificates` | token 过期 | 在 master 重新 `kubeadm token create --print-join-command` |

| containerd 拉镜像失败 | 国内网络 | 提前 `ctr image pull registry.aliyuncs.com/google_containers/pause:3.9` |