Kubespray 可配置参数详解Inventory 变量、网络子网规划、双栈网络与 Kubelet 调优的完整实践指南【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubesprayKubespray 通过 Ansible 变量体系暴露了部署生产级 Kubernetes 集群所需的几乎所有可调项从组件版本、网络插件选择到 Service/Pod 子网规划、双栈Dual Stack网络、DNS 配置和 kubelet 深度调优。本文以仓库文档 docs/ansible/vars.md 为骨架结合roles/kubespray_defaults、roles/network_facts等源码逐项解释这些变量的默认值、约束关系与典型用法读完后可独立编写一份可落地的 Kubespray inventory 变量文件。通用 Ansible 变量与 FactsKubespray 建立在标准 Ansible 变量与 facts 之上Ansible 会自动采集主机 facts官方 facts 说明见 Ansible 文档 user_guide/playbooks_vars_facts 章节。其中最常被 Kubespray 逻辑引用的是ansible_userSSH 连接目标主机时使用的用户。ansible_default_ipv4.addressAnsible 自动选择的 IPv4 地址其判定依据是ip -4 route get 8.8.8.8命令的输出——即“访问外部网络时实际使用的出接口地址”。这一点非常重要当主机有多块网卡时该值由路由表决定而非简单的“第一块网卡”。常用组件版本与网络插件变量以下变量用于锁定组件版本与网络行为是定制 inventory 时最常出现的参数calico_version指定 Calico 组件版本calico_cni_version指定 Calico CNI 插件版本。docker_version指定 Docker 版本应使用带引号的字符串。该值必须与 roles/container-engine/docker/vars/*.yml 中docker_versioned_pkg定义的某个 key 完全匹配否则无法找到对应发行版的包名。containerd_version当container_manager设为containerd时指定其版本。docker_containerd_version当container_manager设为docker时指定配套 cri-containerd 的版本。etcd_version指定 etcd 版本。kube_version指定要部署的 Kubernetes 版本。kube_network_plugin选择容器网络插件默认calico。kube_proxy_mode切换 kube-proxy 模式取值为iptables、ipvs、nftables。从源码结构看这些默认值集中在 roles/kubespray_defaults/defaults/main/main.yml# Network plugin 默认值第 214-216 行附近 # Choose network plugin (cilium, calico, kube-ovn or flannel. Use cni for generic cni plugin) kube_network_plugin: calico # Kube Proxy mode One of [ipvs, iptables, nftables] kube_proxy_mode: ipvs值得注意的两点当前仓库默认 kube-proxy 模式是ipvs当网络插件启用了 kube-proxy 替代方案如 Calico eBPF、Cilium kube-proxy replacement或kube_proxy_remove为 true 时kubeadm_init_phases_skip会自动追加addon/kube-proxy跳过阶段见 defaults 第 50-65 行的 Jinja2 计算逻辑。Calico 的三种封装/后端变量当kube_network_plugin: calico时生效变量含义合法取值默认calico_ipip_modeIPIP 隧道封装Never、Always、CrossSubnetNevercalico_vxlan_modeVXLAN 隧道封装Never、Always、CrossSubnetAlwayscalico_network_backend网络后端none、bird、vxlanvxlan寻址变量ip、access_ip 与负载均衡入口Kubespray 对“本节点用什么 IP”与“其他节点从哪里访问本节点”做了显式分离这是理解云环境部署的关键iphost var本机上各服务绑定的 IP通常是公网 IP。access_ip其他节点访问本机时使用的 IP在 OpenStack、GCE 等公网/内网分离的云上通常是私有 IP。ansible_default_ipv4.address当ip和access_ip都未定义时回退使用该 fact。ip6host varIPv6 服务绑定地址。当ipv6_stack旧变量enable_dual_stack_networks已废弃为true且定义了ip6时kubelet 的--node-ip与节点InternalIP将是ip和ip6的组合纯 IPv6 方案同样适用。access_ip6access_ip的 IPv6 对应项未定义ip6/access_ip6时回退ansible_default_ipv6.address。loadbalancer_apiserver定义后kube_control_planes与kube_nodes将统一通过该地址访问 API Server而不再各自指向 localhost 或第一个控制面节点。详见 HA 部署指南。loadbalancer_apiserver_localhost让所有主机通过“节点内建负载均衡”localhost 上的 nginx/haproxy访问 API Server与loadbalancer_apiserver互斥。这些变量的优先级在 roles/network_facts/tasks/main.yaml 中实现vars: fallback_ip: {{ ansible_default_ipv4.address | d(127.0.0.1) }} fallback_ip6: {{ ansible_default_ipv6.address | d(::1) }} # Set 127.0.0.1 as fallback IP if we do not have host facts for host # ansible_default_ipv4 isnt what you think. _ipv4: {{ ip | default(fallback_ip) }} _access_ipv4: {{ access_ip | default(_ipv4) }} _ipv6: {{ ip6 | default(fallback_ip6) }} _access_ipv6: {{ access_ip6 | default(_ipv6) }}可以看出完整回退链ip→ansible_default_ipv4.address→127.0.0.1access_ip未设时则等于ip的取值结果。若主机不可达Ansible 会回退到127.0.0.1这也是离线规划 inventory 时的事实来源。特殊网络变量main_ip / main_access_ip 家族这组变量旨在消除代码中大量与网络栈类型相关的 if/else 分支它们被所有模板引用。默认只启用 ipv4_stack双栈模式下 IPv4 享有优先权。文档明确警告不理解其含义时不要修改它们。main_access_ipipv4_stack 启用时含双栈等于access_ip纯 IPv6 集群等于access_ip6。main_ip同理分别为ip或ip6。main_access_ips双栈时为access_ip与access_ip6的列表单栈时只含对应单项。main_ipsip与ip6的列表规则同上。它们在 roles/network_facts/tasks/main.yaml 中通过set_fact缓存生成set_fact: cacheable: true main_access_ip: {{ _access_ipv4 if ipv4_stack else _access_ipv6 }} main_ip: {{ _ipv4 if ipv4_stack else _ipv6 }} # Mixed IPs - for dualstack main_access_ips: {{ _access_ips | select }} main_ips: {{ _ips | select }}下游模板大量直接消费它们例如 defaults 中kube_apiserver_address: {{ hostvars[inventory_hostname][main_ip] }}、etcd 的etcd_peer_url: https://{{ etcd_access_address }}:2380roles/kubespray_defaults/defaults/main/main.ymlroles/etcd/templates/openssl.conf.j2 中的 etcd 证书 SAN 也使用main_access_ips列表批量生成双栈地址。集群变量子网、DNS 与 Feature GatesKubernetes 部署需要一批集群级参数以下是文档列出的完整清单及默认值默认值定义于 roles/kubespray_defaults/defaults/main/main.ymlcluster_name集群名默认cluster.local。container_manager节点安装的容器运行时默认containerd见 defaults 第 346 行container_manager: containerd。image_command_tool拉取镜像的工具默认随container_manager而定——containerd用nerdctl、crio用crictl、docker用docker对应 roles/kubespray_defaults/defaults/main/download.yml 中的模板计算。image_command_tool_on_localhost控制机上拉取镜像的工具默认等于image_command_tool。dns_domain集群 DNS 域默认cluster.local实际定义为dns_domain: {{ cluster_name }}。kube_network_plugin容器网络插件默认calico。kube_service_addressesClusterIP 子网默认10.233.0.0/18不得与kube_pods_subnet重叠。kube_pods_subnetPod IP 子网默认10.233.64.0/18不得与kube_service_addresses重叠。kube_network_node_prefix分配给每个节点的 Pod 子网前缀长度。kube_pods_subnet剩余位数决定集群最多能有多少个节点。设置大于 25 时若未相应调整kubelet_max_pods会触发 playbook 断言该断言对 Calico 不适用Calico 不以硬上限方式使用它可参考 Calico 官方 IP block sizes 说明。defaults 中的注释给出了典型组合/18子网 前缀24→ 最多 64 节点、每节点最多 254 个 Pod前缀25→ 最多 128 节点、每节点 126 个 Pod。kube_service_addresses_ipv6集群 IPv6 ClusterIP 子网默认fd85:ee78:d8a6:8607::1000/1164096 个 IPv6 地址不得与kube_pods_subnet_ipv6重叠。kube_pods_subnet_ipv6Pod IPv6 子网默认fd85:ee78:d8a6:8607::1:0000/112256 节点 × 254 Pod不得与kube_service_addresses_ipv6重叠。kube_network_node_prefix_ipv6每节点 Pod IPv6 子网前缀默认120。kube_service_subnets逗号分隔的全部 Service 子网默认根据ipv4_stack/ipv6_stack自动混合生成如双栈下为10.233.0.0/18,fd85:ee78:d8a6:8607::1000/116。不推荐直接修改。kube_pods_subnets逗号分隔的全部 Pod 子网规则同上如双栈下10.233.64.0/18,fd85:ee78:d8a6:8607::1:0000/112。不推荐直接修改。skydns_server集群 DNS 的 ClusterIP默认10.233.0.3。skydns_server_secondarycoredns_dual部署时 CoreDNS 使用的第二 ClusterIP默认10.233.0.4。enable_coredns_k8s_external启用后为 CoreDNS Service 配置 k8s_external 插件该插件用于解析集群外的 Kubernetes 域名。coredns_k8s_external_zone启用 k8s_external 插件时使用的 Zone默认k8s_external.local。enable_coredns_k8s_endpoint_pod_names为 kubernetes 插件启用 endpoint_pod_names 选项。cloud_provider云服务提供方默认未设置使用外置云控制器时设为external。kube_feature_gatesKubernetes alpha/实验特性门列表keyvalue对默认[]。此外可针对各组件单独定制语义与kube_feature_gates相同kube_apiserver_feature_gates、kube_controller_feature_gates、kube_scheduler_feature_gates、kube_proxy_feature_gates、kubelet_feature_gates。kubeadm_feature_gatesKubeadm 特性门列表默认[]。authorization_modesAPI Server 授权模式列表默认[Node, RBAC]。Node与RBAC默认启用旧集群可切换到 RBAC但依赖 Kubernetes API 的应用需要 ServiceAccount 与 ClusterRoleBinding。可通过设为[]覆盖该设置。kube_apiserver_admission_control_config_file启用 kube-apiserver 准入插件配置当前支持EventRateLimit插件。配置结构示例kube_apiserver_admission_event_rate_limits: limit_1: type: Namespace qps: 50 burst: 100 cache_size: 2000 limit_2: type: User qps: 50 burst: 100 ...kube_apiserver_service_account_lookup验证 token 前是否校验 service account默认true。子网与云网络冲突如果云提供方的实例私有地址使用了10.233.0.0/16务必将kube_service_addresses和kube_pods_subnet换到其他网段例如172.18.0.0/16。从 defaults 源码看skydns_server并非写死为10.233.0.3而是由kube_service_subnets计算得出service 子网网段第 3 个 IPkube_apiserver_ip同理取第 1 个 IPdefaults 第 156-157、304 行——这意味着你调整子网后这些 ClusterIP 会随之自动移动。启用双栈IPv4IPv6或纯 IPv6 网络ipv4_stack默认true启用 IPv4 栈。ipv6_stack默认false启用 IPv6 栈旧变量enable_dual_stack_networks已废弃ipv6_stack现为其兼容回退值见 defaults 第 281 行ipv6_stack: {{ enable_dual_stack_networks | default(false) }}。未覆盖时Kubespray 使用kubespray_defaultsrole 中的默认子网。默认配置可容纳最多 256 个节点、每节点 126 个 Pod、最多 4096 个 Service。双栈模式需将两个变量都设为true此时 IPv4 享有更高优先级体现在main_ip、main_access_ip等变量的取值上将ipv4_stack设为false则可构建纯 IPv6 集群。DNS 变量默认情况下Kubespray 将 8.8.8.8 配置为宿主机上游 DNS原有/etc/resolv.conf的其余设置将丢失。按你的网络环境设置以下变量upstream_dns_servers在 Kubespray 部署的 DNS 之外配置到宿主机上的上游 DNS 服务器数组同时作为 CoreDNS 的集群外查询上游。nameservers为宿主机配置的 DNS 服务器数组。searchdomains最多 4 个搜索域数组。remove_default_searchdomains布尔值。启用后searchdomains可容纳 6 个搜索域。dns_etchostsCoreDNS 和 NodeLocal DNS 使用的 hosts 文件内容。dns_upstream_forward_extra_optsCoreDNS/NodeLocal DNS forward 段中关于上游 DNS 的附加选项。更多细节可参考仓库中的 DNS Stack 说明。defaults 中相关默认值包括upstream_dns_servers: []、dns_mode: coredns、enable_nodelocaldns: true、ndots: 2defaults 第 121-158 行。其他服务变量docker_options常用于--insecure-registrymyregistry.mydomain:5000。docker_plugins定义要通过docker plugin install安装的 Docker 插件列表。containerd_default_runtime定义后修改 Kubernetes CRI 插件使用的默认 containerd runtime。containerd_additional_runtimes设置 CRI 插件使用的附加 containerd runtimesroles/container-engine/containerd/defaults/main.yml 中的默认配置可在 inventory 变量中覆盖。crio_criu_support_enabled设为true时在 CRI-O 中启用容器 checkpoint/restore宿主机需安装 CRIU建议同时启用ContainerCheckpointfeature gate 以获得更高层的 kubelet API该特性仍处于实验阶段目前仅面向容器分析场景。http_proxy/https_proxy/no_proxy/no_proxy_exclude_workers/additional_no_proxy代理环境下部署的代理变量。no_proxy默认为全部集群内部 IP 与各节点对应主机名——这一默认值正是在 roles/network_facts/tasks/main.yaml 中自动生成的聚合kube_control_plane、kube_node可被no_proxy_exclude_workers排除、etcd、calico_rr各组的main_access_ip、主机名及hostname.dns_domain变体、svc与svc.dns_domain、kube_service_subnets/kube_pods_subnets以及127.0.0.1/localhost。kubelet_cgroup_driver手动覆盖 kubelet 的 cgroup-driver。默认自动探测以匹配容器管理器配置。containerd推荐systemd但若存在 cgroups v1 或 kata-containers 兼容问题可改为cgroupfs。kubelet_rotate_certificateskubelet 客户端证书临近过期时自动向 kube-apiserver 申请新证书。kubelet_rotate_server_certificateskubelet 服务端证书自动轮换启用它同时会激活kubelet_csr_approver自动审批 CSR 的 Helm 应用其行为可通过kubelet_csr_approver_values覆盖 Helm values该组件即 postfinance 社区的 kubelet-csr-approver 项目。kubelet_streaming_connection_idle_timeout流式连接允许空闲的最大时长超时后自动断开。kubelet_image_gc_high_threshold磁盘使用率超过该百分比0-100后总是执行镜像 GC且必须大于imageGCLowThresholdPercent。默认 85。kubelet_image_gc_low_threshold磁盘使用率低于该百分比0-100时从不执行镜像 GC必须小于imageGCHighThresholdPercent。默认 80。kubelet_max_parallel_image_pulls并行拉取镜像的上限默认1串行设为大于 1 的整数可启用并行拉取。kubelet_make_iptables_util_chainstrue时保证宿主机上存在一组 iptables 规则。kubelet_cpu_manager_policy设为static可使具备特定资源特征的 Pod 获得更高的 CPU 亲和性与独占性应配合kube_reserved或system-reserved使用参见 Kubernetes 官方 CPU Management Policies 文档。kubelet_cpu_manager_policy_options启用 cpuManagerPolicyOptions 的字典。注意布尔值必须写成字符串带引号并启用相应 feature gatekubelet_cpu_manager_policy_options: distribute-cpus-across-numa: true full-pcpus-only: truekubelet_topology_manager_policy控制 CPU 与内存在不同 NUMA 节点上的分配行为参见 Kubernetes Topology Manager 官方文档。kubelet_topology_manager_scope拓扑管理器资源对齐的作用域container或pod。kubelet_systemd_hardeningtrue时为 kubelet systemd 服务提供隔离安全特性。前提是使用 cgroup v2可用sudo ls -l /sys/fs/cgroup/*.slice检查目录不存在时需先启用 cgroup v2可参考 rootlesscontaine.rs 的 cgroup v2 启用指南。kubelet_secure_addresses默认kubelet_systemd_hardening将控制面节点的ansible_hostIP 设为kubelet_secure_addresses。当控制面节点有多网卡、且 kube-apiserver 未绑定默认接口时可覆盖。例如控制面节点有eth0:10.0.0.110、eth1:192.168.1.110两个接口Ansible 经eth0连接而希望 kube-apiserver 经eth1访问 kubelet则设置kubelet_secure_addresses: 192.168.1.110。kubelet_systemd_wants_dependencies除容器运行时外 kubelet 服务依赖的列表。例如使用 NFS 动态挂载卷时rpc-statd未随 kubelet 启动可设kubelet_systemd_wants_dependencies: [rpc-statd.service]即在/etc/systemd/system/kubelet.service的[Unit]段加入Wantsrpc-statd.service。node_labels通过kubectl label node应用到节点的标签可定义在 inventory host var 或更宽范围的 group_vars 中只能定义为字典node_labels: label1_name: label1_value label2_name: label2_valuenode_taints通过kubectl taint node应用的污点必须为字符串列表格式keyvalue:effectnode_taints: - node.example.com/externaltrue:NoSchedulekubernetes_audit设为true启用审计。相关参数及默认值audit_log_path:/var/log/audit/kube-apiserver-audit.logaudit_log_maxage:30audit_log_maxbackups:10audit_log_maxsize:100audit_policy_file:{{ kube_config_dir }}/audit-policy/apiserver-audit-policy.yaml默认策略文件包含 roles/kubernetes/control-plane/templates/apiserver-audit-policy.yaml.j2 渲染的默认规则可用audit_policy_custom_rules覆盖。kubernetes_audit_webhook设为true启用 webhook 审计后端参数默认值audit_webhook_config_file:{{ kube_config_dir }}/audit-policy/apiserver-audit-webhook-config.yamlaudit_webhook_server_url:https://audit.appaudit_webhook_server_extra_args:{}audit_webhook_mode:batchaudit_webhook_batch_max_size:100audit_webhook_batch_max_wait:1skubectl_alias为 kubectl 设置 bash 别名简化与集群的交互。remove_anonymous_access设为true时移除 kubeadm 创建的kubeadm:bootstrap-signer-clusterinfoRoleBinding。默认 kubeadm 会在kube-public命名空间创建允许匿名用户的 rolebinding供 join 阶段发现集群信息。该选项在第一个控制面节点 init 完成后移除该 rolebinding并配置 kubeadm 使用 file discovery 完成其他节点 join注意它并不移除 API Server 的匿名认证特性。对应默认值remove_anonymous_access: falsedefaults 第 83 行。为 kube 组件传入自定义参数对于默认部署未覆盖的边缘场景可以为各组件传入额外参数。kubelet 推荐方式是用kubelet_config_extra_args以键值对字典形式插入 kubelet YAML 配置文件kubelet_config_extra_args: evictionHard: memory.available: 100Mi evictionSoftGracePeriod: memory.available: 30s evictionSoft: memory.available: 300Mi历史上也可通过kubelet_custom_flags以命令行参数方式传给 kubeletkubelet_custom_flags: - --eviction-hardmemory.available100Mi - --eviction-soft-grace-periodmemory.available30s - --eviction-softmemory.available300Mi该方式已废弃将保留至 kubelet 完全移除这些 flag 为止。API Server、controller-manager、scheduler的额外参数使用以下变量形式为插入 kubeadm YAML 配置文件的键值对字典kube_kubeadm_apiserver_extra_argskube_kubeadm_controller_extra_argskube_kubeadm_scheduler_extra_argsKubeadm Patches当额外参数仍不够用、需要更深地定制 kubernetes 组件时可以使用 kubeadm patches 机制参见 Kubernetes 官方 control-plane-flags 中 Patches 章节对应变量为kubeadm_patches。从源码看roles/kubernetes/kubeadm_common/tasks/main.yml 会把列表中每一项拷贝到kubeadm_patches_dir默认{{ kube_config_dir }}/patches文件名为targetsuffixtype.yamltype 默认strategic并在 roles/kubernetes/control-plane/templates/kubeadm-config.v1beta4.yaml.j2 中为 init/join/join-control-plane 各阶段注入patches.directory字段从而让 kubeadm 在每个阶段应用这些补丁。应用Apps变量helm_version仅支持 v3.x。存量 v2Tiller安装不会被修改需要手动移除。小结变量生效路径与实操建议结合 defaults 的组织方式Kubespray 变量的覆盖优先级可概括为kubespray_defaultsrole 的 defaultsroles/kubespray_defaults/defaults/main/main.yml、download.yml 等→ inventory 的group_vars/host_vars→ 命令行-e注入。实操上建议版本类变量kube_version、calico_version、containerd_version、docker_version在 inventory 顶部集中声明且docker_version必须与 docker role vars 中的 key 精确匹配多网卡或云上环境务必显式声明ip/access_ip及 IPv6 对应项避免依赖ansible_default_ipv4.address的隐式判定子网规划只改kube_service_addresses、kube_pods_subnet及其 IPv6 对应项kube_service_subnets/kube_pods_subnets交给自动混合生成需要突破默认模板能力的场景优先走kubelet_config_extra_args/kube_kubeadm_*_extra_args/kubeadm_patches这条由浅入深的官方定制通道。【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 3:35:45 · 阅读 1.2k Kubespray 可配置参数详解：Inventory 变量、网络子网规划、双栈网络与 Kubelet 调优的完整实践指南
Kubespray 可配置参数详解Inventory 变量、网络子网规划、双栈网络与 Kubelet 调优的完整实践指南【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubesprayKubespray 通过 Ansible 变量体系暴露了部署生产级 Kubernetes 集群所需的几乎所有可调项从组件版本、网络插件选择到 Service/Pod 子网规划、双栈Dual Stack网络、DNS 配置和 kubelet 深度调优。本文以仓库文档 docs/ansible/vars.md 为骨架结合roles/kubespray_defaults、roles/network_facts等源码逐项解释这些变量的默认值、约束关系与典型用法读完后可独立编写一份可落地的 Kubespray inventory 变量文件。通用 Ansible 变量与 FactsKubespray 建立在标准 Ansible 变量与 facts 之上Ansible 会自动采集主机 facts官方 facts 说明见 Ansible 文档 user_guide/playbooks_vars_facts 章节。其中最常被 Kubespray 逻辑引用的是ansible_userSSH 连接目标主机时使用的用户。ansible_default_ipv4.addressAnsible 自动选择的 IPv4 地址其判定依据是ip -4 route get 8.8.8.8命令的输出——即“访问外部网络时实际使用的出接口地址”。这一点非常重要当主机有多块网卡时该值由路由表决定而非简单的“第一块网卡”。常用组件版本与网络插件变量以下变量用于锁定组件版本与网络行为是定制 inventory 时最常出现的参数calico_version指定 Calico 组件版本calico_cni_version指定 Calico CNI 插件版本。docker_version指定 Docker 版本应使用带引号的字符串。该值必须与 roles/container-engine/docker/vars/*.yml 中docker_versioned_pkg定义的某个 key 完全匹配否则无法找到对应发行版的包名。containerd_version当container_manager设为containerd时指定其版本。docker_containerd_version当container_manager设为docker时指定配套 cri-containerd 的版本。etcd_version指定 etcd 版本。kube_version指定要部署的 Kubernetes 版本。kube_network_plugin选择容器网络插件默认calico。kube_proxy_mode切换 kube-proxy 模式取值为iptables、ipvs、nftables。从源码结构看这些默认值集中在 roles/kubespray_defaults/defaults/main/main.yml# Network plugin 默认值第 214-216 行附近 # Choose network plugin (cilium, calico, kube-ovn or flannel. Use cni for generic cni plugin) kube_network_plugin: calico # Kube Proxy mode One of [ipvs, iptables, nftables] kube_proxy_mode: ipvs值得注意的两点当前仓库默认 kube-proxy 模式是ipvs当网络插件启用了 kube-proxy 替代方案如 Calico eBPF、Cilium kube-proxy replacement或kube_proxy_remove为 true 时kubeadm_init_phases_skip会自动追加addon/kube-proxy跳过阶段见 defaults 第 50-65 行的 Jinja2 计算逻辑。Calico 的三种封装/后端变量当kube_network_plugin: calico时生效变量含义合法取值默认calico_ipip_modeIPIP 隧道封装Never、Always、CrossSubnetNevercalico_vxlan_modeVXLAN 隧道封装Never、Always、CrossSubnetAlwayscalico_network_backend网络后端none、bird、vxlanvxlan寻址变量ip、access_ip 与负载均衡入口Kubespray 对“本节点用什么 IP”与“其他节点从哪里访问本节点”做了显式分离这是理解云环境部署的关键iphost var本机上各服务绑定的 IP通常是公网 IP。access_ip其他节点访问本机时使用的 IP在 OpenStack、GCE 等公网/内网分离的云上通常是私有 IP。ansible_default_ipv4.address当ip和access_ip都未定义时回退使用该 fact。ip6host varIPv6 服务绑定地址。当ipv6_stack旧变量enable_dual_stack_networks已废弃为true且定义了ip6时kubelet 的--node-ip与节点InternalIP将是ip和ip6的组合纯 IPv6 方案同样适用。access_ip6access_ip的 IPv6 对应项未定义ip6/access_ip6时回退ansible_default_ipv6.address。loadbalancer_apiserver定义后kube_control_planes与kube_nodes将统一通过该地址访问 API Server而不再各自指向 localhost 或第一个控制面节点。详见 HA 部署指南。loadbalancer_apiserver_localhost让所有主机通过“节点内建负载均衡”localhost 上的 nginx/haproxy访问 API Server与loadbalancer_apiserver互斥。这些变量的优先级在 roles/network_facts/tasks/main.yaml 中实现vars: fallback_ip: {{ ansible_default_ipv4.address | d(127.0.0.1) }} fallback_ip6: {{ ansible_default_ipv6.address | d(::1) }} # Set 127.0.0.1 as fallback IP if we do not have host facts for host # ansible_default_ipv4 isnt what you think. _ipv4: {{ ip | default(fallback_ip) }} _access_ipv4: {{ access_ip | default(_ipv4) }} _ipv6: {{ ip6 | default(fallback_ip6) }} _access_ipv6: {{ access_ip6 | default(_ipv6) }}可以看出完整回退链ip→ansible_default_ipv4.address→127.0.0.1access_ip未设时则等于ip的取值结果。若主机不可达Ansible 会回退到127.0.0.1这也是离线规划 inventory 时的事实来源。特殊网络变量main_ip / main_access_ip 家族这组变量旨在消除代码中大量与网络栈类型相关的 if/else 分支它们被所有模板引用。默认只启用 ipv4_stack双栈模式下 IPv4 享有优先权。文档明确警告不理解其含义时不要修改它们。main_access_ipipv4_stack 启用时含双栈等于access_ip纯 IPv6 集群等于access_ip6。main_ip同理分别为ip或ip6。main_access_ips双栈时为access_ip与access_ip6的列表单栈时只含对应单项。main_ipsip与ip6的列表规则同上。它们在 roles/network_facts/tasks/main.yaml 中通过set_fact缓存生成set_fact: cacheable: true main_access_ip: {{ _access_ipv4 if ipv4_stack else _access_ipv6 }} main_ip: {{ _ipv4 if ipv4_stack else _ipv6 }} # Mixed IPs - for dualstack main_access_ips: {{ _access_ips | select }} main_ips: {{ _ips | select }}下游模板大量直接消费它们例如 defaults 中kube_apiserver_address: {{ hostvars[inventory_hostname][main_ip] }}、etcd 的etcd_peer_url: https://{{ etcd_access_address }}:2380roles/kubespray_defaults/defaults/main/main.ymlroles/etcd/templates/openssl.conf.j2 中的 etcd 证书 SAN 也使用main_access_ips列表批量生成双栈地址。集群变量子网、DNS 与 Feature GatesKubernetes 部署需要一批集群级参数以下是文档列出的完整清单及默认值默认值定义于 roles/kubespray_defaults/defaults/main/main.ymlcluster_name集群名默认cluster.local。container_manager节点安装的容器运行时默认containerd见 defaults 第 346 行container_manager: containerd。image_command_tool拉取镜像的工具默认随container_manager而定——containerd用nerdctl、crio用crictl、docker用docker对应 roles/kubespray_defaults/defaults/main/download.yml 中的模板计算。image_command_tool_on_localhost控制机上拉取镜像的工具默认等于image_command_tool。dns_domain集群 DNS 域默认cluster.local实际定义为dns_domain: {{ cluster_name }}。kube_network_plugin容器网络插件默认calico。kube_service_addressesClusterIP 子网默认10.233.0.0/18不得与kube_pods_subnet重叠。kube_pods_subnetPod IP 子网默认10.233.64.0/18不得与kube_service_addresses重叠。kube_network_node_prefix分配给每个节点的 Pod 子网前缀长度。kube_pods_subnet剩余位数决定集群最多能有多少个节点。设置大于 25 时若未相应调整kubelet_max_pods会触发 playbook 断言该断言对 Calico 不适用Calico 不以硬上限方式使用它可参考 Calico 官方 IP block sizes 说明。defaults 中的注释给出了典型组合/18子网 前缀24→ 最多 64 节点、每节点最多 254 个 Pod前缀25→ 最多 128 节点、每节点 126 个 Pod。kube_service_addresses_ipv6集群 IPv6 ClusterIP 子网默认fd85:ee78:d8a6:8607::1000/1164096 个 IPv6 地址不得与kube_pods_subnet_ipv6重叠。kube_pods_subnet_ipv6Pod IPv6 子网默认fd85:ee78:d8a6:8607::1:0000/112256 节点 × 254 Pod不得与kube_service_addresses_ipv6重叠。kube_network_node_prefix_ipv6每节点 Pod IPv6 子网前缀默认120。kube_service_subnets逗号分隔的全部 Service 子网默认根据ipv4_stack/ipv6_stack自动混合生成如双栈下为10.233.0.0/18,fd85:ee78:d8a6:8607::1000/116。不推荐直接修改。kube_pods_subnets逗号分隔的全部 Pod 子网规则同上如双栈下10.233.64.0/18,fd85:ee78:d8a6:8607::1:0000/112。不推荐直接修改。skydns_server集群 DNS 的 ClusterIP默认10.233.0.3。skydns_server_secondarycoredns_dual部署时 CoreDNS 使用的第二 ClusterIP默认10.233.0.4。enable_coredns_k8s_external启用后为 CoreDNS Service 配置 k8s_external 插件该插件用于解析集群外的 Kubernetes 域名。coredns_k8s_external_zone启用 k8s_external 插件时使用的 Zone默认k8s_external.local。enable_coredns_k8s_endpoint_pod_names为 kubernetes 插件启用 endpoint_pod_names 选项。cloud_provider云服务提供方默认未设置使用外置云控制器时设为external。kube_feature_gatesKubernetes alpha/实验特性门列表keyvalue对默认[]。此外可针对各组件单独定制语义与kube_feature_gates相同kube_apiserver_feature_gates、kube_controller_feature_gates、kube_scheduler_feature_gates、kube_proxy_feature_gates、kubelet_feature_gates。kubeadm_feature_gatesKubeadm 特性门列表默认[]。authorization_modesAPI Server 授权模式列表默认[Node, RBAC]。Node与RBAC默认启用旧集群可切换到 RBAC但依赖 Kubernetes API 的应用需要 ServiceAccount 与 ClusterRoleBinding。可通过设为[]覆盖该设置。kube_apiserver_admission_control_config_file启用 kube-apiserver 准入插件配置当前支持EventRateLimit插件。配置结构示例kube_apiserver_admission_event_rate_limits: limit_1: type: Namespace qps: 50 burst: 100 cache_size: 2000 limit_2: type: User qps: 50 burst: 100 ...kube_apiserver_service_account_lookup验证 token 前是否校验 service account默认true。子网与云网络冲突如果云提供方的实例私有地址使用了10.233.0.0/16务必将kube_service_addresses和kube_pods_subnet换到其他网段例如172.18.0.0/16。从 defaults 源码看skydns_server并非写死为10.233.0.3而是由kube_service_subnets计算得出service 子网网段第 3 个 IPkube_apiserver_ip同理取第 1 个 IPdefaults 第 156-157、304 行——这意味着你调整子网后这些 ClusterIP 会随之自动移动。启用双栈IPv4IPv6或纯 IPv6 网络ipv4_stack默认true启用 IPv4 栈。ipv6_stack默认false启用 IPv6 栈旧变量enable_dual_stack_networks已废弃ipv6_stack现为其兼容回退值见 defaults 第 281 行ipv6_stack: {{ enable_dual_stack_networks | default(false) }}。未覆盖时Kubespray 使用kubespray_defaultsrole 中的默认子网。默认配置可容纳最多 256 个节点、每节点 126 个 Pod、最多 4096 个 Service。双栈模式需将两个变量都设为true此时 IPv4 享有更高优先级体现在main_ip、main_access_ip等变量的取值上将ipv4_stack设为false则可构建纯 IPv6 集群。DNS 变量默认情况下Kubespray 将 8.8.8.8 配置为宿主机上游 DNS原有/etc/resolv.conf的其余设置将丢失。按你的网络环境设置以下变量upstream_dns_servers在 Kubespray 部署的 DNS 之外配置到宿主机上的上游 DNS 服务器数组同时作为 CoreDNS 的集群外查询上游。nameservers为宿主机配置的 DNS 服务器数组。searchdomains最多 4 个搜索域数组。remove_default_searchdomains布尔值。启用后searchdomains可容纳 6 个搜索域。dns_etchostsCoreDNS 和 NodeLocal DNS 使用的 hosts 文件内容。dns_upstream_forward_extra_optsCoreDNS/NodeLocal DNS forward 段中关于上游 DNS 的附加选项。更多细节可参考仓库中的 DNS Stack 说明。defaults 中相关默认值包括upstream_dns_servers: []、dns_mode: coredns、enable_nodelocaldns: true、ndots: 2defaults 第 121-158 行。其他服务变量docker_options常用于--insecure-registrymyregistry.mydomain:5000。docker_plugins定义要通过docker plugin install安装的 Docker 插件列表。containerd_default_runtime定义后修改 Kubernetes CRI 插件使用的默认 containerd runtime。containerd_additional_runtimes设置 CRI 插件使用的附加 containerd runtimesroles/container-engine/containerd/defaults/main.yml 中的默认配置可在 inventory 变量中覆盖。crio_criu_support_enabled设为true时在 CRI-O 中启用容器 checkpoint/restore宿主机需安装 CRIU建议同时启用ContainerCheckpointfeature gate 以获得更高层的 kubelet API该特性仍处于实验阶段目前仅面向容器分析场景。http_proxy/https_proxy/no_proxy/no_proxy_exclude_workers/additional_no_proxy代理环境下部署的代理变量。no_proxy默认为全部集群内部 IP 与各节点对应主机名——这一默认值正是在 roles/network_facts/tasks/main.yaml 中自动生成的聚合kube_control_plane、kube_node可被no_proxy_exclude_workers排除、etcd、calico_rr各组的main_access_ip、主机名及hostname.dns_domain变体、svc与svc.dns_domain、kube_service_subnets/kube_pods_subnets以及127.0.0.1/localhost。kubelet_cgroup_driver手动覆盖 kubelet 的 cgroup-driver。默认自动探测以匹配容器管理器配置。containerd推荐systemd但若存在 cgroups v1 或 kata-containers 兼容问题可改为cgroupfs。kubelet_rotate_certificateskubelet 客户端证书临近过期时自动向 kube-apiserver 申请新证书。kubelet_rotate_server_certificateskubelet 服务端证书自动轮换启用它同时会激活kubelet_csr_approver自动审批 CSR 的 Helm 应用其行为可通过kubelet_csr_approver_values覆盖 Helm values该组件即 postfinance 社区的 kubelet-csr-approver 项目。kubelet_streaming_connection_idle_timeout流式连接允许空闲的最大时长超时后自动断开。kubelet_image_gc_high_threshold磁盘使用率超过该百分比0-100后总是执行镜像 GC且必须大于imageGCLowThresholdPercent。默认 85。kubelet_image_gc_low_threshold磁盘使用率低于该百分比0-100时从不执行镜像 GC必须小于imageGCHighThresholdPercent。默认 80。kubelet_max_parallel_image_pulls并行拉取镜像的上限默认1串行设为大于 1 的整数可启用并行拉取。kubelet_make_iptables_util_chainstrue时保证宿主机上存在一组 iptables 规则。kubelet_cpu_manager_policy设为static可使具备特定资源特征的 Pod 获得更高的 CPU 亲和性与独占性应配合kube_reserved或system-reserved使用参见 Kubernetes 官方 CPU Management Policies 文档。kubelet_cpu_manager_policy_options启用 cpuManagerPolicyOptions 的字典。注意布尔值必须写成字符串带引号并启用相应 feature gatekubelet_cpu_manager_policy_options: distribute-cpus-across-numa: true full-pcpus-only: truekubelet_topology_manager_policy控制 CPU 与内存在不同 NUMA 节点上的分配行为参见 Kubernetes Topology Manager 官方文档。kubelet_topology_manager_scope拓扑管理器资源对齐的作用域container或pod。kubelet_systemd_hardeningtrue时为 kubelet systemd 服务提供隔离安全特性。前提是使用 cgroup v2可用sudo ls -l /sys/fs/cgroup/*.slice检查目录不存在时需先启用 cgroup v2可参考 rootlesscontaine.rs 的 cgroup v2 启用指南。kubelet_secure_addresses默认kubelet_systemd_hardening将控制面节点的ansible_hostIP 设为kubelet_secure_addresses。当控制面节点有多网卡、且 kube-apiserver 未绑定默认接口时可覆盖。例如控制面节点有eth0:10.0.0.110、eth1:192.168.1.110两个接口Ansible 经eth0连接而希望 kube-apiserver 经eth1访问 kubelet则设置kubelet_secure_addresses: 192.168.1.110。kubelet_systemd_wants_dependencies除容器运行时外 kubelet 服务依赖的列表。例如使用 NFS 动态挂载卷时rpc-statd未随 kubelet 启动可设kubelet_systemd_wants_dependencies: [rpc-statd.service]即在/etc/systemd/system/kubelet.service的[Unit]段加入Wantsrpc-statd.service。node_labels通过kubectl label node应用到节点的标签可定义在 inventory host var 或更宽范围的 group_vars 中只能定义为字典node_labels: label1_name: label1_value label2_name: label2_valuenode_taints通过kubectl taint node应用的污点必须为字符串列表格式keyvalue:effectnode_taints: - node.example.com/externaltrue:NoSchedulekubernetes_audit设为true启用审计。相关参数及默认值audit_log_path:/var/log/audit/kube-apiserver-audit.logaudit_log_maxage:30audit_log_maxbackups:10audit_log_maxsize:100audit_policy_file:{{ kube_config_dir }}/audit-policy/apiserver-audit-policy.yaml默认策略文件包含 roles/kubernetes/control-plane/templates/apiserver-audit-policy.yaml.j2 渲染的默认规则可用audit_policy_custom_rules覆盖。kubernetes_audit_webhook设为true启用 webhook 审计后端参数默认值audit_webhook_config_file:{{ kube_config_dir }}/audit-policy/apiserver-audit-webhook-config.yamlaudit_webhook_server_url:https://audit.appaudit_webhook_server_extra_args:{}audit_webhook_mode:batchaudit_webhook_batch_max_size:100audit_webhook_batch_max_wait:1skubectl_alias为 kubectl 设置 bash 别名简化与集群的交互。remove_anonymous_access设为true时移除 kubeadm 创建的kubeadm:bootstrap-signer-clusterinfoRoleBinding。默认 kubeadm 会在kube-public命名空间创建允许匿名用户的 rolebinding供 join 阶段发现集群信息。该选项在第一个控制面节点 init 完成后移除该 rolebinding并配置 kubeadm 使用 file discovery 完成其他节点 join注意它并不移除 API Server 的匿名认证特性。对应默认值remove_anonymous_access: falsedefaults 第 83 行。为 kube 组件传入自定义参数对于默认部署未覆盖的边缘场景可以为各组件传入额外参数。kubelet 推荐方式是用kubelet_config_extra_args以键值对字典形式插入 kubelet YAML 配置文件kubelet_config_extra_args: evictionHard: memory.available: 100Mi evictionSoftGracePeriod: memory.available: 30s evictionSoft: memory.available: 300Mi历史上也可通过kubelet_custom_flags以命令行参数方式传给 kubeletkubelet_custom_flags: - --eviction-hardmemory.available100Mi - --eviction-soft-grace-periodmemory.available30s - --eviction-softmemory.available300Mi该方式已废弃将保留至 kubelet 完全移除这些 flag 为止。API Server、controller-manager、scheduler的额外参数使用以下变量形式为插入 kubeadm YAML 配置文件的键值对字典kube_kubeadm_apiserver_extra_argskube_kubeadm_controller_extra_argskube_kubeadm_scheduler_extra_argsKubeadm Patches当额外参数仍不够用、需要更深地定制 kubernetes 组件时可以使用 kubeadm patches 机制参见 Kubernetes 官方 control-plane-flags 中 Patches 章节对应变量为kubeadm_patches。从源码看roles/kubernetes/kubeadm_common/tasks/main.yml 会把列表中每一项拷贝到kubeadm_patches_dir默认{{ kube_config_dir }}/patches文件名为targetsuffixtype.yamltype 默认strategic并在 roles/kubernetes/control-plane/templates/kubeadm-config.v1beta4.yaml.j2 中为 init/join/join-control-plane 各阶段注入patches.directory字段从而让 kubeadm 在每个阶段应用这些补丁。应用Apps变量helm_version仅支持 v3.x。存量 v2Tiller安装不会被修改需要手动移除。小结变量生效路径与实操建议结合 defaults 的组织方式Kubespray 变量的覆盖优先级可概括为kubespray_defaultsrole 的 defaultsroles/kubespray_defaults/defaults/main/main.yml、download.yml 等→ inventory 的group_vars/host_vars→ 命令行-e注入。实操上建议版本类变量kube_version、calico_version、containerd_version、docker_version在 inventory 顶部集中声明且docker_version必须与 docker role vars 中的 key 精确匹配多网卡或云上环境务必显式声明ip/access_ip及 IPv6 对应项避免依赖ansible_default_ipv4.address的隐式判定子网规划只改kube_service_addresses、kube_pods_subnet及其 IPv6 对应项kube_service_subnets/kube_pods_subnets交给自动混合生成需要突破默认模板能力的场景优先走kubelet_config_extra_args/kube_kubeadm_*_extra_args/kubeadm_patches这条由浅入深的官方定制通道。【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考