企业官网建设流程全解析

1. 为什么需要深入研究Kubespray的高级配置

Kubespray这个项目在Kubernetes部署领域算是一个绕不开的存在。早期用kubeadm手工搭集群，搭一次还好，多套环境反复折腾就非常痛苦；用云厂商的托管Kubernetes，又容易绑定在一个平台里出不来。Kubespray基于Ansible，把Kubernetes集群的部署、扩容、升级、证书轮换全都编排好了，一份inventory加几个配置文件，就能在裸机、虚拟机、私有云上铺出一套生产可用的集群。

但很多人在Kubespray上栽跟头，往往不是不会用默认配置，而是不知道怎么改高级配置。默认的kubespray部署出来的集群可以用，但离"适合我的业务”还有距离：网络插件选型要不要变？etcd是堆叠模式还是独立部署？apiserver的请求压力怎么控制？私有化环境里镜像拉不下来怎么办？集群升级怎么做到业务无损？这些问题都藏在group_vars和inventory的细节里。标题里的“advanced”不是摆设，Kubespray的高级配置，本质上决定了你这套集群的上限和运维成本。

这篇文章就是要解决这类问题。内容偏向有kubeadm或Kubespray基础、正在准备上生产、或者已经被生产集群折腾过的工程师。我会从配置体系的底层逻辑讲到具体参数怎么改，再结合踩坑经验把常见问题和排查思路拆开讲。看完之后，你应该能自己动手改出一套适合自己业务场景的部署方案，而不是每次部署都靠默认配置碰运气。

2. 理解Kubespray的配置体系，才能谈高级

2.1 配置文件的角色：inventory、group_vars与roles的变量优先级

Kubespray的配置体系，简单说就是：inventory清单决定“服务器归到哪个组”，group_vars下的YAML文件决定“这些组上的角色怎么干活”。

默认安装包解压后，会有一个inventory/sample目录，里面包含：

• hosts.yaml：定义所有节点、IP、分组（kube_control_plane、kube_node、etcd等）。
• group_vars/all/all.yml：全局参数，比如版本号、镜像仓库、证书有效期、NTP等。
• group_vars/k8s_cluster/k8s-cluster.yml：集群层参数，比如Pod网段、Service网段、网络插件、DNS配置等。
• group_vars/k8s_cluster/addons.yml：可选插件，比如ingress-controller、metrics-server、dns-autoscaler等。
• group_vars/etcd.yml：etcd专属参数。
• group_vars/kubernetes/kubernetes.yml：apiserver、kubelet、controller-manager等组件参数。

变量优先级方面，Kubespray底层是Ansible，所以它严格遵循Ansible的变量覆盖规则：-e命令行参数会覆盖所有文件变量；inventory里的host_vars会覆盖group_vars；group_vars中越接近host的组优先级越高。实操中常见的错误是，你已经改了k8s-cluster.yml但觉得没生效，十有八九是inventory里的host_vars悄悄把它覆盖了。

提示：在修改任何高级配置前，建议先用ansible -m debug -a 'var=hostvars[inventory_hostname]' -i inventory/mycluster/hosts.yaml kube_control_plane[0]的方式确认变量最终解析值。这种排查比事后看日志省太多时间。

2.2 自定义group_vars目录，别把样板配置污染了

很多人的习惯是直接修改inventory/sample，这非常糟糕。因为Kubespray每次版本升级，sample目录都可能变化，你本地改的东西会被覆盖或合并，时间长了根本不知道哪些是自定义的。

正确做法是把配置单独复制出来，比如：

cp -r inventory/sample inventory/mycluster

然后在inventory/mycluster/group_vars下维护自己的all.yml、k8s-cluster.yml、etcd.yml。部署时只需要指定：

ansible-playbook -i inventory/mycluster/hosts.yaml cluster.yml

这就把“官方样板”和“我的配置”分开了，升级、回滚、多环境管理都干净很多。

高级配置的第一步，往往就是把这个目录拆分做好。我见过一个团队，把开发、测试、生产三套配置放在三个目录，inventory文件统一用模板生成，group_vars尽量做差异最小化。这样一套代码、多套环境，既保证了环境一致性，也为后面的滚动升级和批量扩容打下了基础。

2.3 理解角色调用链：cluster.yml到底做了什么

Kubespray的cluster.yml主入口，按顺序调用了多套角色：bootstrap、etcd、kubernetes (master/node)、network、addons等。理解了这条调用链，你在排查问题时才不会一头雾水。

比如网络插件的配置，实际上是在k8s-cluster.yml里指定kube_network_plugin，后续由network角色去安装对应的CNI。你如果切换了网络插件，Kubespray会执行一次重新安装CNI的流程，但这个流程不会自动删除旧CNI的资源，这就是很多切换后节点状态异常的根源。

再比如etcd角色的执行顺序在所有Kubernetes组件之前，因为控制面组件启动时就要连接etcd。如果etcd配置出问题，后面全是连环失败。

所以高级配置的底层逻辑，不是一个参数一个参数地抠，而是先搞清楚你改的这个变量，影响的是哪条角色执行链、在哪个阶段生效、能不能热更新、需不需要重建节点。这个理解框架一旦建立，后面再看官方文档就不会晕。

3. 关键高级配置项详解：从网络到etcd再到控制面

3.1 网络插件选型与CNI参数调优

Kubespray默认的kube_network_plugin是calico，这也是多数生产环境的主选。但在不同场景下，有人需要切Cilium，有人需要Flannel的极简，还有人因为底层网络特殊必须调整MTU和封装模式。

• kube_network_plugin: calico或cilium或flannel。
• kube_pods_subnet：Pod网段，默认10.233.64.0/18。
• kube_service_addresses：Service网段，默认10.233.0.0/18。
• calico_ip_auto_method：如果节点有多个网卡，需要指定怎么识别内网IP，比如interface=eth.*。
• calico_vxlan_mode：是否使用VXLAN封装，默认Always。
• cilium_enable_hubble：要不要开Hubble观测。

以Calico为例，如果你在云环境里用VPC网络，其实没必要再做一次IPIP或VXLAN封装，直接在underlay网络里跑BGP就行。可以在k8s-cluster.yml里设置：

calico_ipip_mode: Never calico_vxlan_mode: Never

这样每个节点上的Pod IP可以直接通过底层网络路由，转发效率高，丢包率也低。不过前提是你的VPC路由表能动态感知容器网段，或者你的网络设备支持BGP对接，否则Pod跨节点会直接不通。

Cilium这边，高级配置常见的是开启kube_proxy_replacement: strict，这会把kube-proxy的职责接管过来，去掉一层Netfilter的负担。但开启前必须确认节点内核版本支持，并且你接受Cilium对网络策略更激进的默认行为。升级时也要先看清楚Cilium版本与K8s版本的兼容矩阵，否则很可能会出现CrashLoopBackoff。

实操心得：切换网络插件前，一定要先记录每个节点的Pod数量、Service数量、现有策略规则，最好是选维护窗口做。Kubespray虽然能一键切换，但CNI的资源清理、旧节点上的遗留路由、策略规则，经常需要手工兜底。我在一次切Cilium时，就因为旧Calico的cali* veth没有被清干净，导致部分节点上路由混乱，流量到处串。后来写了个清理脚本，把每台节点上ip link里带cali前缀的虚拟网卡都删了才恢复。

MTU这个参数也值得单独说。默认Kubespray会尝试探测节点主网卡的MTU，然后给隧道接口设置相应的值。但如果你用了Docker叠加层网络、或者物理网络本身有额外的封装，就必须手动指定。比如物理网卡MTU是1500，VXLAN要额外扣50字节，那么Pod网络MTU就该设1450。好在Kubespray有mtu相关变量可以全局覆盖，不需要每台机器去改。

3.2 etcd部署模式与资源规划

etcd是整个集群的大脑，配置错了影响的是全局。Kubespray支持两种模式：堆叠模式（stacked）和独立模式（external）。

默认情况下，etcd和控制面节点共用，也就是etcd_deployment_type: docker同时，控制面节点上跑着etcd容器。这种方案节点数少、成本低，适合中小规模。但有一个隐患：当控制面节点压力大时，etcd的磁盘IO和内存可能被kube-apiserver抢资源，二者互相影响，极端情况下会发生集群级抖动。

如果集群规模超过20个节点，或者你有很多写密集型负载，我建议独立部署etcd节点。在inventory里把etcd节点单独拆分：

all: hosts: node1: {ip: 192.168.1.11} node2: {ip: 192.168.1.12} node3: {ip: 192.168.1.13} etcd1: {ip: 192.168.1.21} etcd2: {ip: 192.168.1.22} etcd3: {ip: 192.168.1.23} children: kube_control_plane: hosts: {node1: {}, node2: {}, node3: {}} kube_node: hosts: {node1: {}, node2: {}, node3: {}} etcd: hosts: {etcd1: {}, etcd2: {}, etcd3: {}}

然后把group_vars/etcd.yml里的etcd_data_dir、etcd_memory_limit调大，必要时设置etcd_quota_backend_bytes，防止etcd的数据库无限制膨胀。我的经验是，独立etcd节点给4核8G、SSD盘，跑一个百节点规模的控制面绰有余裕。

etcd性能上的另一个高级参数是etcd_defrag和etcd_compaction相关配置。Kubespray在一些版本里支持周期性的碎片整理任务。如果你的集群频繁大量删除Pod或ConfigMap，etcd存储会产生碎片，KV空间看起来不大，但实际磁盘和内存占用却不小。定期执行defrag能有效降内存。

温馨提示：etcd节点千万别做内存超卖。有些同学在虚拟化平台上一台宿主机开好几个etcd虚机，结果磁盘IO互相竞争。etcd对fsync延迟极其敏感，磁盘抖动轻则写入变慢，重则触发心跳超时导致leader切换。独立部署etcd时，尽量用本地SSD，不要用网络存储做etcd的数据盘。

3.3 控制面组件参数与负载均衡配置

kube-apiserver是Kubernetes的流量入口。Kubespray会帮你生成默认的静态Pod清单，但你可以在group_vars/kubernetes/kubernetes.yml里通过kube_apiserver_extra_args增加参数。

比如应对大量并发请求：

kube_apiserver_extra_args: max-requests-inflight: 3000 max-mutating-requests-inflight: 1000 request-timeout: 60s

比如开启审计日志：

kube_apiserver_extra_args: audit-log-path: /var/log/kubernetes/audit/audit.log audit-log-maxage: 7 audit-log-maxbackup: 10 audit-log-maxsize: 100

比如调整NodePort端口范围：

kube_apiserver_extra_args: service-node-port-range: 30000-32767

这几个参数虽然看着简单，但改完需要重启apiserver。Kubespray在滚动升级时会逐个节点替换apiserver，但在正常环境下你手动改extra_args后，一般不会自动重建静态Pod，需要手动把对应节点上的静态Pod目录里的apiserver.yaml动一下，或者执行kubectl delete pod -n kube-system kube-apiserver-xxx让它重建。很多人改了配置以为生效，结果看apiserver进程还是老参数，就是这个原因。

控制面高可用方面，Kubespray提供了两种负载均衡方案：

• 在loadbalancer角色里启用内置的haproxy + keepalived，适合没有现成LB的裸机场景。
• 使用外部LB（如云负载均衡、F5等），此时只需要在inventory的all节点组里设置：

loadbalancer_apiserver: address: 192.168.100.100 port: 6443

外部方案配置上更简单，但你要自己保证LB的高可用。内置方案多一层运维成本，好处是集群自己能把VIP管起来，不依赖外部设施。两者怎么选，关键看你有没有独立网络团队和现成LB。

3.4 私有镜像仓库、离线包与版本管理

生产环境经常面临一个问题：边缘机房或者内网环境访问不了外网镜像仓库，Kubespray默认从registry.k8s.io等地方拉镜像，这在内网环境基本会卡死。

Kubespray专门为离线环境设计了download模式。思路是：先在能联网的环境里跑一次

ansible-playbook -i inventory/mycluster/hosts.yaml cluster.yml --tags download

把需要的镜像、二进制文件、容器镜像压缩包都拉到本地。然后在目标环境里，用file_server或者直接挂载的静态文件目录来供源。

对应的核心配置：

# all.yml download_run_once: true download_localhost: true download_cache_dir: /opt/kubespray_cache

再配合把镜像仓库指向内网私有仓库：

kube_image_repo: "registry.private.example.com" kube_image_tag: "v1.28.5"

Kubespray支持通过docker_registry变量配置镜像仓库的认证信息。具体来说：

docker_registry_mirrors: - "https://registry.private.example.com"

或者更彻底一点，把container_manager配置成containerd，然后给containerd配置一个内网镜像源。用containerd做容器运行时在生产环境中越来越主流，它比Docker少一层守护进程，也更省内存。

实操心得：离线部署最大的坑不是镜像本身，而是版本管理。Kubespray的版本、Kubernetes的版本、各组件镜像的版本，三者之间有严格的对应关系。强烈建议把kube_version、kube_image_tag、calico版本、cilium版本全部固定下来，最好用Git管理配置目录。不要总是升到最新，生产集群的稳定性靠的是“锁版本”，不是“追新”。

4. 高级配置实操：从修改参数到无损滚动升级

4.1 修改配置的正确姿势

无论你改什么参数，我都建议遵循以下流程：

1. 进入inventory/mycluster/group_vars，确认要改的YAML文件。
2. 用Git diff看清改动内容，确认影响范围。
3. 在非生产环境先执行一次完整部署或升级验证。
4. 生产环境选择维护窗口，逐组执行，不要一口气全量跑。
5. 执行完用kubectl检查核心组件Pod状态和节点Ready状态。

以修改etcd内存限制为例，在etcd.yml里加一行：

etcd_memory_limit: 4G

然后执行：

ansible-playbook -i inventory/mycluster/hosts.yaml cluster.yml --limit etcd -e etcd_memory_limit=4G

--limit etcd是只对etcd这个组里的主机生效。这是Kubespray里特别实用的技巧，不一定要每次全量跑。但也要注意，有些变量跨组共享，只limit一个组可能导致变量不一致，所以--limit只适合明确知道影响范围的场景。

再比如修改apiserver的审计日志参数，改了kube_apiserver_extra_args后，如果只对kube_control_plane组跑，Kubespray会逐个重建apiserver静态Pod。你可以观察这个组的滚动过程，确保每个节点上的apiserver能正常重启后再进行下一个节点，这样能把影响降到最低。

4.2 场景化案例：一个常见的生产环境配置合集

假设我们要部署一套内部OA系统的Kubernetes集群，物理机20台，其中3台控制面，3台etcd独立，其余为工作节点。需求是：网络走VXLAN、RBAC放开一部分给研发自服务、开启审计、镜像全走私有仓库。

推荐的配置如下：

inventory/mycluster/group_vars/all/all.yml：

kube_version: v1.28.5 container_manager: containerd download_run_once: true download_localhost: true kube_image_repo: "registry.private.example.com" docker_registry_mirrors: - "https://registry.private.example.com"

group_vars/k8s_cluster/k8s-cluster.yml：

kube_network_plugin: calico calico_ipip_mode: Never calico_vxlan_mode: Always kube_pods_subnet: 10.244.0.0/16 kube_service_addresses: 10.96.0.0/16 kube_proxy_mode: iptables

group_vars/kubernetes/kubernetes.yml：

kube_apiserver_extra_args: audit-log-path: /var/log/kubernetes/audit/audit.log audit-log-maxage: 30 audit-log-maxbackup: 10 audit-log-maxsize: 200 max-requests-inflight: 3000 kubelet_extra_args: max-pods: 120

group_vars/etcd.yml：

etcd_memory_limit: 4G etcd_quota_backend_bytes: 8589934592

这个配置跑完，集群整体会比较稳。要注意的是，kube_pods_subnet和kube_service_addresses尽可能在部署初期就定好，后期改起来非常麻烦，涉及所有节点上的iptables规则和路由表，别指望一键平滑修改。

4.3 滚动升级实操：Kubespray的升级流程

集群一旦跑起来，版本升级是迟早的事。Kubespray的升级思路很简单：把inventory里的kube_version改成目标版本，然后执行upgrade-cluster.yml。这个playbook会依次升级etcd、控制面、工作节点，并且尽量做到每台节点排空后升级再恢复调度。

我在执行升级时的建议是：

1. 先备份etcd快照，这是保命动作。
2. 用--limit kube_control_plane先只升级控制面，观察apiserver和controller-manager是否正常启动。
3. 再升级工作节点，尽量一批一批来，比如用--limit指定前5台。
4. 每批完成后看节点状态、Pod调度情况。如果出现异常，立即暂停。

命令大致长这样：

ansible-playbook -i inventory/mycluster/hosts.yaml upgrade-cluster.yml -e kube_version=v1.29.2 --limit kube_control_plane

随后：

ansible-playbook -i inventory/mycluster/hosts.yaml upgrade-cluster.yml -e kube_version=v1.29.2 --limit kube_node

注意，跨大版本升级时，kube_version变了，很多镜像Tag也会跟着变，你的私有仓库里必须提前把这些镜像准备好。Kubespray不会自动帮你上传新版本的镜像，离线环境尤其要先跑--tags download，把新版本的镜像包拉到本地仓库。

常见错误：直接把kube_version改成新版本，然后跑upgrade，结果拉镜像失败，升级卡到一半。所以离线环境升级的正确顺序是：新版下载 → 推送私有仓库 → 更新inventory版本号 → 备份etcd → 分批升级。

5. 常见问题与排查技巧实录

5.1 配置不生效，问题出在哪

很多人问我：我改了group_vars/k8s_cluster/k8s-cluster.yml，执行了playbook，但节点行为没变化。这通常有三个原因：

第一，变量被覆盖。你改的是group_vars，但inventory里针对host定义的同名变量优先级更高。用ansible -m debug确认变量最终值。

第二，学习到了但没触发服务重启。Kubespray很多变量只在角色任务里消费一次，比如kube_apiserver_extra_args生成的是静态Pod清单。改完需要重启apiserver才能生效，Kubespray不会每次都自动重启所有组件。

第三，跑错了inventory。很多人习惯了直接执行cluster.yml，没带-i，然后应用到默认的sample集群上，自然看不到效果。

5.2 升级时节点处于NotReady怎么办

升级过程中出现NotReady，先别慌，按顺序排查：

1. 查看节点kubelet状态：systemctl status kubelet或crictl ps，确认容器运行时是哪个。
2. 看容器运行时里的镜像版本，是不是升级时被替换，但kubelet启动失败。
3. 检查CNI状态：升级过程中网络插件可能没跟着升上去。如果CNI Pod没起来，节点会一直NotReady。

如果确定是CNI问题，先查看kube-system下CNI DaemonSet的Pod日志。常见是版本不兼容或者RBAC权限缺失，这时手动apply新版CNI的yaml往往就能救回来。

另外一点：Kubespray升级时会重新生成kubelet的systemd unit文件。如果你手工改过kubelet的参数，升级后可能被覆盖回默认值，导致节点行为异常。所以不要手工改节点上的组件配置，所有需求都通过Kubespray变量走。

5.3 etcd证书过期怎么处理

证书过期是Kubernetes集群里比较唬人的问题。Kubespray可以通过重新生成证书并轮换来解决。常见操作：

• 执行ansible-playbook -i inventory/mycluster/hosts.yaml cluster.yml --tags=etcd，尝试让etcd重新生成证书。
• 如果已经到期导致apiserver连不上etcd，那么要先手工恢复etcd和apiserver之间的信任关系，具体做法是用Kubespray的reset.yml，把集群清掉再重新部署。所以在生产环境里，证书有效性监控比证书快到期才处理，要显得重要得多。

Kubespray在较新版本里支持证书轮换，你可以在group_vars/all/all.yml里设置更合理的证书天数，比如：

certificate_min_validity: 90

这样apiserver、kubelet、etcd等组件在证书剩余不足90天时会自动续期。但注意，Kubespray的轮换逻辑并不会覆盖所有场景，比如外部访问kubeconfig的证书，需要额外检查。

5.4 私有仓库镜像拉取失败

这种情况离线环境非常典型。节点上crictl pull一个镜像失败，报错提示找不到或权限失败。排查步骤：

1. 看节点上containerd的配置文件，是否配置了registry mirrors。
2. 看镜像Tag是否真的存在于私有仓库，很多情况是tag没上传全。
3. 看私有仓库的网络策略，节点是否被防火墙隔离。
4. 确认没有在group_vars里遗漏kube_image_repo或kube_image_tag。

我在实际项目中，最常踩的坑是：某个组件镜像的sha256和Kubespray下载缓存里的校验对不上，导致部署过程中直接校验失败。这时候清理掉download_cache_dir里对应镜像的缓存，重新跑一次download就好。

6. 最后的几点经验

写到这里，关于Kubespray高级配置的主要内容已经讲得差不多了。这套工具并不复杂，但它的复杂度和灵活度都在细节里。我的实际体会是，不要把它当成一个“一键部署脚本”，而是当成一套“可编程的集群生命周期管理平台”。你对Ansible越熟悉，对Kubernetes组件之间的关系理解越深，用Kubespray就越顺手。

还有几个习惯，我觉得值得专门提一下。配置目录一定要纳入版本管理，每个环境一套目录，不要复用同一个inventory；每次改动都留变更记录，方便出问题时回滚。对etcd，永远要想着备份，备份，再备份。对网络插件，永远要小心切换，因为所有存量节点上的网络栈都会被影响。对升级，永远要分批，永远要准备回滚方案。

如果你刚开始接触Kubespray，建议先在虚拟机里搭一套最小集群，反复改各种参数、反复升级降级，等你亲手把集群搞挂又救回来，再上生产环境就会踏实很多。我自己也是这么过来的，踩过的坑越多，后面维护集群越有底气。