k8s_PaaS check_tool 实战指南:用 Ansible Playbook 自动化检查 Kubernetes 集群部署环境
k8s_PaaS check_tool 实战指南:用 Ansible Playbook 自动化检查 Kubernetes 集群部署环境
本指南围绕 k8s_PaaS 仓库中的 check_tool 工具展开,它是一套基于 Ansible Playbook 编写的集群环境体检脚本,专门配合《第二章——企业部署实战_K8S》在部署 Kubernetes 集群时使用。读完本文,你将掌握 check_tool 的安装方式、hosts 清单与 ansible.cfg 的配置要点,并逐条理解 pre_check、pre_for_k8s、node_base_service 三个 Playbook 背后检查了哪些部署前置条件,从而在第二章部署脚本报错时快速定位是哪台机器、哪个配置项出了问题。
check_tool 是什么:第二章部署的"体检工具"
第二章《企业部署实战_K8S》需要在一批机器上手动配置 DNS、CA 证书、Docker、Harbor、etcd、kube-apiserver、kubelet 等大量内容,配置项多、容易出错,不少新手会卡在中途。check_tool 正是为此设计的配套检查脚本:它不做部署、只做"体检",通过 Ansible 批量登录各台目标主机,检查第二章要求的关键配置文件是否被正确修改。
正如 README.md 前言所述,"目前仅有第二章的检查,运行脚本报错后,检查报错的对应内容"——也就是说,它的使用场景是:第二章部署脚本执行出错时,先运行 check_tool,让它告诉你具体是哪一项配置没有过关。这个定位在 第二章——企业部署实战_K8S.md 中也有呼应:"由于第二章需要配置的内容较多,不少新同学卡在这里。建议配合使用软件包里的 check_tool 边检查,边部署"。
目录结构与文件角色总览
check_tool 位于 软件包/check_tool 目录,结构如下:
check_tool/
├── README.md # 使用说明
├── ansible.cfg # Ansible 运行配置
├── hosts # 目标主机清单(inventory)
├── maim.yml # 主运行文件(入口)
└── playbooks/
├── pre_check.yml # 机器基础检查
├── pre_for_k8s.yml # K8s 前的准备内容检查
└── node_base_service.yml # 节点部署内容检查
整个工具遵循"入口 + 三个子 Playbook"的结构:maim.yml 负责统计总耗时并按顺序导入三个子 Playbook;三个子 Playbook 分别覆盖"机器本身是否达标"、"K8s 部署前的基础服务是否就绪"、"各节点组件配置文件是否正确"三个递进层次。下面按使用顺序逐一展开。
快速开始:三步完成环境体检
按 README 的说明,使用 check_tool 只需要三个步骤。
第一步:安装 Ansible
在用于执行检查的机器(管理机)上安装 Ansible,CentOS/RHEL 系可直接用 yum:
yum install ansible -y
Ansible 采用"管理机 + 被管节点"的免代理模型,只需管理机安装 Ansible,通过 SSH 即可批量操作清单中的所有目标主机。
第二步:配置 hosts 主机清单
将 hosts 中的 IP、账号、密码改成你自己的机器信息,虚拟 IP 没有可以先不填。具体字段含义见下文"hosts 清单文件详解"。
第三步:运行 ansible-playbook
在 check_tool 目录下执行:
ansible-playbook -i hosts main.yml
注意:README 与命令中的主运行文件名均为
main.yml,而仓库实际文件名为 maim.yml(源码中保留了maim拼写)。如果你克隆仓库后直接运行,请使用ansible-playbook -i hosts maim.yml,或自行将文件名调整为main.yml。
运行完成后,每个检查项会输出明确的 ok(成功)、failed(失败)与 fail_msg/success_msg 中文提示信息,直接指出具体哪个文件、哪个配置项不满足要求,运行效果如下图所示:
hosts 清单文件详解:五台业务机 + 一台虚拟 IP
hosts 是 Ansible 的主机清单(inventory),定义了分组、主机别名、SSH 连接信息与组级变量。仓库自带的示例内容如下:
[all]
k8s_11 ansible_host=172.29.238.188
k8s_12 ansible_host=172.29.238.187
k8s_21 ansible_host=172.29.238.184
k8s_22 ansible_host=172.29.238.186
k8s_200 ansible_host=172.29.238.185
[all:vars]
ansible_ssh_pass=****
ansible_ssh_port=22
ansible_ssh_user=root
[virtual_ip]
k8s_10 ansible_host=172.29.238.10
各字段说明如下:
| 字段/分组 | 含义与配置要点 |
|---|---|
k8s_11 ~ k8s_200 |
主机别名,命名规则为 k8s_<机器尾号>。第二章约定五台业务机分别为 11、12、21、22、200 号机器,别名中的数字会被 playbook 用 awk -F "_" '{print $NF}' 提取出来,用于校验主机名、配置文件中的对应网段 |
ansible_host |
各机器的内网 IP,需要替换为你自己的 IP |
[all:vars] |
组级变量,作用于 [all] 组内所有主机 |
ansible_ssh_pass |
SSH 密码,要求所有机器密码统一,才能用一条命令批量检查 |
ansible_ssh_port |
SSH 端口,默认 22 |
ansible_ssh_user |
SSH 用户,默认 root |
[virtual_ip] |
虚拟 IP 分组,k8s_10 为 keepalived 对外提供的 VIP(如 172.29.238.10)。没有 VIP 可以先不填、不改,相关检查项会直接跳过或不受影响 |
从三个 Playbook 的 hosts 字段可以推断出这套环境的分工:k8s_11 承担 DNS(bind9)与 L4 反代,k8s_12 承担 L4 反代与 etcd,k8s_21/k8s_22 是主控+计算节点(etcd、apiserver、kubelet、kube-proxy 等),k8s_200 是 CA 证书签发机并部署 Harbor 与 Docker。实际部署时请与第二章的机器规划保持一致。
ansible.cfg:关闭主机密钥检查与日志落盘
ansible.cfg 是 Ansible 的运行时配置文件,内容如下:
[defaults]
host_key_checking = False
log_path = ./run_ansible.log
gathering = "implicit"
三个配置项的作用分别是:
host_key_checking = False:关闭 SSH 首次连接的主机密钥确认。如果不关闭,Ansible 首次连接新机器时会停在 "yes/no" 交互上,导致批量检查无法自动化执行。log_path = ./run_ansible.log:将本次运行日志写出到当前目录下的run_ansible.log文件。脚本报错后,可以翻看该日志回溯每个任务的完整输出。gathering = "implicit":设置 facts 收集方式为"隐式"。配合各 playbook 中gather_facts: no/false的声明,只在确实需要 facts(如内存、时间、默认网卡 IP)的任务中按需收集,其余纯文本比对任务不收集,从而加快检查速度。
maim.yml 主运行文件:时间戳统计整体耗时
maim.yml 是整套检查的入口,做了三件事:记录开始时间、按顺序导入三个子 Playbook、计算并打印总耗时。
开头部分通过 command: date +%s 获取开始时间戳并 register 到 start_time,随后连续导入三个子 Playbook:
- import_playbook: playbooks/pre_check.yml
- import_playbook: playbooks/pre_for_k8s.yml
- import_playbook: playbooks/node_base_service.yml
收尾部分再次获取结束时间戳,并用 Jinja2 表达式计算耗时(end_time.stdout | int - start_time.stdout | int),最后通过 debug 打印开始时间、结束时间和"运行耗时 X 分钟 Y 秒"。这个设计让用户在跑完全部检查后立刻得到一个总耗时反馈,方便判断脚本是否卡在某台机器或某个任务上(耗时异常偏长往往意味着某台机器 SSH 连接或某个命令执行超时)。
playbooks/pre_check.yml:机器基础检查
pre_check.yml 是"机器本身是否达标"的检查,在五台业务机(k8s_11,k8s_12,k8s_21,k8s_22,k8s_200)上统一执行。
CPU 与内存最低配置
通过 grep -c '^processor' /proc/cpuinfo 统计 CPU 核数,断言必须 ≥ 2C,否则输出 fail_msg: "CPU必须大于2C";内存则直接使用 Ansible 收集到的 ansible_memory_mb fact,断言必须 ≥ 2048(即 2GB)。这两项是运行 K8s 组件的最低硬件门槛。
主控+计算节点的大内存检查
针对 k8s_21、k8s_22 两个主控+计算节点,额外断言内存大于 15000MB(约 15GB),提示"内存小于 16GB"为警告级别,并设置了 ignore_errors: true,即不达标只告警、不中断检查。
细节提示:源码第 36 行使用的变量名是
ansible_metotal_mb,而 Ansible 官方 fact 名称为ansible_memtotal_mb,二者存在拼写差异。按源码现状该断言可能取不到值,实际运行时建议核对变量名,或将其改为ansible_memtotal_mb后再执行。
时间同步
执行 systemctl is-active ntpd,断言输出为 active,提示"时间可能未同步"(同样 ignore_errors: true 仅告警)。随后打印每台主机当前的 ansible_date_time.date 与 ansible_date_time.time,便于人工比对。K8s 集群对节点间时钟偏差敏感,时间不同步会直接导致证书校验与 etcd 通信异常,因此这一步很关键。
防火墙与 SELinux
- 防火墙:用
systemctl is-active --quiet firewalld && echo 'active' || echo 'inactive'探测并打印状态(仅展示、不判定失败)。 - SELinux:读取
/etc/selinux/config中的SELINUX=行,断言必须为disabled。SELinux 未关闭是 K8s 部署中非常常见的失败原因。
主机名规范
第二章要求主机名修改为 xxx.host.com 的规范格式,此部分分两步断言:
- 主机名必须包含
host.com; - 从主机别名中提取尾号数字(
echo {{ inventory_hostname }} | awk -F "_" '{print $NF}'),断言该数字必须出现在主机名中(例如别名k8s_11对应主机名应包含11)。
这样既保证主机名符合内部域名规范,又保证主机名与机器 IP 尾号一一对应,避免搞混节点。
互联网连通性
ping -c 1 baidu.com 断言返回码为 0,检查机器能否连通外网。K8s 部署过程中需要拉取镜像、解析域名,完全离线或 DNS 异常的环境会在后续步骤大量报错。
playbooks/pre_for_k8s.yml:部署 K8s 前的配置检查
pre_for_k8s.yml 检查"K8s 前置准备"是否就绪,覆盖 DNS、网卡、CA 证书、Docker、Harbor 五大块。
bind9 DNS 配置检查(k8s_11)
第二章要求用 bind9 在 11 号机器搭建内部 DNS(解析 host.com 与 od.com 两个域),本 Playbook 使用 ansible.builtin.slurp 读取远端文件内容(base64 编码后经 b64decode 还原)后逐条断言关键字符串:
/etc/named.conf:必须包含listen-on port 53 { 本机IP; };、allow-query { any; };、forwarders、dnssec-enable no;、dnssec-validation no;,同时必须不包含listen-on-v6 port 53 { ::1; };(IPv6 监听需移除);/etc/named.rfc1912.zones:必须包含zone "host.com" IN {、type master;、file "host.com.zone";、allow-update { 本机IP; };,以及od.com对应的一套同构配置;/var/named/host.com.zone与/var/named/od.com.zone:断言$ORIGIN、$TTL 600、SOA 记录(dns.host.com. dnsadmin.host.com. ( ... 10800 / 900 / 604800 / 86400 ... ))、NS dns.host.com.、以及dns/HDSS7-11等 A 记录指向本机 IP;- 最后运行
named-checkconf,断言其 stdout 与 stderr 均为空,即配置语法无错误。
网卡 DNS1 指向检查(五台机器)
读取 /etc/sysconfig/network-scripts/ifcfg-eth0,断言必须包含 DNS1={{ hostvars['k8s_11']['ansible_host'] }},即所有机器都把 DNS 指向 11 号机器;随后再次 ping -c 1 baidu.com 验证 DNS 解析链路是否生效。
CA 证书签发时效检查(k8s_200)
读取 /opt/certs/ca-csr.json,断言必须包含 1752000。1752000 小时约等于 200 年,第二章要求 CA 根证书授权时长设为 200 年(避免证书过期导致集群不可用),不满足会提示"授权时间较短,请设置为 1752000h"。
Docker daemon 配置检查(k8s_21、k8s_22、k8s_200)
对部署 Docker 的三台机器读取 /etc/docker/daemon.json,断言同时满足:
- 包含
/data/docker(Docker 数据目录迁移到独立数据盘); - 包含
overlay2(存储驱动); - 包含
172.7.{{ 节点尾号 }}.1/24(为每台节点规划的容器网段,例如 21 号机器应为172.7.21.1/24)。
Harbor 仓库与 Nginx 检查(k8s_200)
Harbor 是第二章镜像仓库方案的核心,检查分为两部分:
/opt/harbor/harbor.yml必须包含端口180、数据目录/data/harbor与日志目录/data/harbor/logs;/etc/nginx/conf.d/harbor.od.com.conf必须包含listen 80、server_name harbor.od.com、转发端口180;- 最后断言
systemctl is-enabled nginx输出为enabled,保证 Nginx 开机自启、Harbor 的反代入口在重启后依然可用。
playbooks/node_base_service.yml:各节点部署内容检查
node_base_service.yml 对应第二章中"安装部署主控节点服务 / 运算节点服务"的各个步骤,逐个检查 etcd、apiserver、L4 反代、controller-manager、scheduler、kubelet、kube-proxy 的配置文件是否按第二章要求修改完成。核心手法是 grep 断言目标文件里必须出现/必须出现 N 次某 IP 或某字符串。
etcd 相关检查(k8s_200、k8s_12、k8s_21、k8s_22)
- 在 k8s_200 上:
/opt/certs/ca-config.json必须包含1752000h(证书有效期);/opt/certs/etcd-peer-csr.json必须包含 11、12、21、22 四台机器的 IP; - 在 k8s_12、k8s_21、k8s_22 上:
id etcd命令可正常执行(etcd 用户/用户组已创建); /opt/etcd/etcd-server-startup.sh:本机 IP 必须出现 5 次(对应--name、--initial-advertise-peer-urls、--listen-peer-urls、--advertise-client-urls、--listen-client-urls等 5 处引用);12、21、22 三台机器的 IP 都必须出现;以尾号数字构造的-{{ 尾号 }}字符串必须恰好出现 2 次(--name节点名与相关 peer 参数中的标识);/etc/supervisord.d/etcd-server.ini:必须包含本机尾号数字(supervisor 管理的进程名/配置文件与节点号对应)。
kube-apiserver 相关检查(k8s_200、k8s_21、k8s_22)
- 在 k8s_200 上:
/opt/certs/apiserver-csr.json必须同时包含虚拟 IP(k8s_10的ansible_host)与 21、22 两台机器的 IP(apiserver 证书 SAN 需要覆盖 VIP 和各主控节点); - 在 k8s_21、k8s_22 上:
/opt/kubernetes/server/bin/kube-apiserver.sh必须包含 12、21、22 三台机器的 IP;/etc/supervisord.d/kube-apiserver.ini必须包含本机尾号数字。
L4 反代:nginx + keepalived(k8s_11、k8s_12)
/etc/nginx/nginx.conf(11、12 两台反代机):必须包含 21、22 两台 apiserver 机器的 IP(upstream 后端指向);/etc/keepalived/keepalived.conf(11 号机器):虚拟 IP 必须存在,且 11 号机器 IP 必须出现 2 次;12 号机器同理:虚拟 IP 必须存在,12 号机器 IP 必须出现 2 次。由此推断第二章中 keepalived 的vrrp_instance配置里每台机器自身的 IP 出现在两处(如virtual_ipaddress之外的状态脚本或网卡绑定相关位置)。
controller-manager / scheduler(k8s_21、k8s_22)
/etc/supervisord.d/kube-conntroller-manager.ini与/etc/supervisord.d/kube-scheduler.ini必须包含本机尾号数字。
细节提示:源码中 controller-manager 的 supervisor 配置文件名为
kube-conntroller-manager.ini(多了一个n),与 Kubernetes 官方组件名kube-controller-manager存在拼写差异。部署时请与第二章使用的实际文件名保持一致,此处检查脚本按源码现状工作。
运算节点:kubelet 与 kube-proxy(k8s_200、k8s_21、k8s_22)
- 在 k8s_200 上:
/opt/certs/kubelet-csr.json必须包含虚拟 IP 与 21、22 两台机器的 IP; - 在 k8s_21、k8s_22 上:
/opt/kubernetes/server/bin/conf/kubelet.kubeconfig与kube-proxy.kubeconfig必须包含虚拟 IP(客户端访问 apiserver 走 VIP);/opt/kubernetes/server/bin/kubelet.sh、kube-proxy.sh必须包含{{ 尾号 }}.host.com(组件以规范主机名注册到集群);/etc/supervisord.d/kube-kubelet.ini、kube-proxy.ini必须包含本机尾号数字。
使用建议:如何配合第二章"边检查边部署"
综合 README 说明与三个 Playbook 的检查顺序,推荐的配合方式是:
- 装好 Ansible 并配置好 hosts 后,先整体跑一遍
ansible-playbook -i hosts maim.yml,把机器基础配置(CPU/内存/时间/防火墙/SELinux/主机名/外网)和 K8s 前置准备(DNS/网卡/CA/Docker/Harbor)一次性体检完,确认无failed再进入第二章的组件安装步骤; - 第二章每一步部署脚本报错时,不必逐文件人工核对,直接运行 check_tool,报错信息中的
fail_msg会明确指出"哪个文件缺少哪段内容"(例如SELINUX 未设置为 disabled、etcd-server-startup.sh 文件中没有 5 个地址); - 借助
run_ansible.log回溯:ansible.cfg 已开启日志落盘,某个任务执行异常但提示不够直观时,可翻看该日志获取完整命令输出; - 根据输出分组定位机器:check_tool 的所有输出都带
inventory_hostname(主机别名),打印信息与断言信息均会显示是哪台机器不通过,可直接锁定需要修复的节点。
需要注意的是,check_tool 目前只覆盖第二章的检查内容,且以第二章约定(五台业务机 + 一台 VIP、host.com 域名、统一密码等)为前提;如果你的环境是公有云版或其他拓扑,请先调整 hosts 与各 Playbook 中硬编码的域名、网段、端口后再使用。
小结
check_tool 用不到 500 行的 YAML,把第二章上百个手工配置点沉淀成了可重复执行、带中英文提示、能统计耗时的自动化体检套件。它本身不做任何部署动作,却在实战中极大地降低了第二章的排障成本:把"部署失败后人工逐文件比对"变成"一键运行、按输出精准修复"。本文基于 README.md 及仓库内 maim.yml、hosts、ansible.cfg 与三个 Playbook 的完整源码整理,读者可直接进入 软件包/check_tool 目录按需调整后运行。
