k8s_PaaS check_tool 实战指南:用 Ansible Playbook 自动化检查 Kubernetes 集群部署环境

原创2026-10-14 07:19:192,218 阅读
文章标签:教程云原生容器编排DevOps

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 中文提示信息,直接指出具体哪个文件、哪个配置项不满足要求,运行效果如下图所示:

check_tool 运行结果截图,展示 Ansible 各检查任务的输出状态

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 的规范格式,此部分分两步断言:

  1. 主机名必须包含 host.com;
  2. 从主机别名中提取尾号数字(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 的检查顺序,推荐的配合方式是:

  1. 装好 Ansible 并配置好 hosts 后,先整体跑一遍 ansible-playbook -i hosts maim.yml,把机器基础配置(CPU/内存/时间/防火墙/SELinux/主机名/外网)和 K8s 前置准备(DNS/网卡/CA/Docker/Harbor)一次性体检完,确认无 failed 再进入第二章的组件安装步骤;
  2. 第二章每一步部署脚本报错时,不必逐文件人工核对,直接运行 check_tool,报错信息中的 fail_msg 会明确指出"哪个文件缺少哪段内容"(例如 SELINUX 未设置为 disabled、etcd-server-startup.sh 文件中没有 5 个地址);
  3. 借助 run_ansible.log 回溯:ansible.cfg 已开启日志落盘,某个任务执行异常但提示不够直观时,可翻看该日志获取完整命令输出;
  4. 根据输出分组定位机器: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 目录按需调整后运行。

登录后查看全文
k8s_PaaS