用途 该技能面向使用 Kubespray 部署 Kubernetes 集群的场景，包括新建集群、为多节点集群编写 inventory、配置集群变量（CNI、版本、插件）以及执行首次集群部署。资料明确说明它不适用于升级（应使用 kubespray-operations）和故障排查（应使用 kubespray-troubleshooting）。
主要能力 Kubespray 使用 Ansible 自动化操作系统准备、容器运行时安装、etcd 集群、控制平面引导和 CNI 部署。其核心原则是内部使用 kubeadm，但处理 kubeadm 不负责的部分：操作系统配置、containerd、CNI 与高可用设置。
关键文件包括：inventory.ini 定义主机与分组成员关系；group_vars/all/.yml 保存全局设置（etcd、containerd、NTP）；group_vars/k8s_cluster/.yml 保存集群设置（CNI、版本、插件）；cluster.yml 为主部署 playbook。
变量优先级从低到高为：角色默认值、角色变量、inventory group_vars、inventory host_vars、playbook 变量、命令行 extra-vars（-e）。资料提醒，若同一变量在角色 vars 中定义，group_vars 中的设置可能静默失效，可用 -e 强制覆盖，例如： ansible-playbook cluster.yml -e kube_version="v1.32.9"
配置要点 inventory 采用双网络设计：ansible_host 为 Ansible SSH 管理 IP，ip 为 Kubernetes 内部通信 IP。多网卡环境需显式设置 ip=，否则可能误检测地址导致 kubeadm join 失败。分组包括 kube_control_plane、etcd、kube_node 和 k8s_cluster；示例使用 [etcd:children] 指向 kube_control_plane 的 stacked etcd 模式，etcd 节点数应为 1、3 或 5。控制平面列表中的第一个节点是 kubeadm init 的初始节点，其不可达会使引导失败。
常用变量涵盖 kube_version、kube_network_plugin（calico、flannel、cilium）、kube_service_addresses、kube_pods_subnet、kube_proxy_mode、container_manager、auto_renew_certificates、enable_nodelocaldns；Flannel 多网卡环境需设置 flannel_interface。Kubespray 的 clusterDNS 默认为 10.233.0.3。插件配置示例包括 helm_enabled、metrics_server_enabled、ingress_nginx_enabled。
使用方式 在 kubespray 根目录运行： ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml -b -v 可附加 -u、--private-key、-e 等参数。部署分为七个阶段：前置条件、容器运行时、下载、etcd 引导、控制平面初始化、工作节点加入、CNI 与插件。
部署后验证包括：复制并修正 kubeconfig；检查 kube-system 各系统 Pod 的状态；用 etcdctl.sh member list 与 endpoint status 检查 etcd 成员、leader 与 RAFT TERM；用 curl 检查各控制平面 API server；检查镜像与二进制；用 kubeadm certs check-expiration 检查证书；用 busybox 测试集群内 DNS；用 kubectl top 验证 metrics-server。
适用场景与限制 适用于实验室或生产环境的初始集群搭建与配置。资料列出的常见错误包括 inventory 解析失败、用目录而非 .ini 文件作为 -i 参数、SSH 不可达、vault 密码缺失、etcd 节点数为偶数、未启用证书自动续期、在错误目录运行、变量优先级冲突、Flannel 选错网卡和 DNS 地址预期错误。其它环境要求、版本兼容性和具体耗时以实际资料为限，未提供的细节暂未提供。