kubeasz 集群个性化参数配置完全指南：hosts 节点清单与 config.yml 组件参数深度解析

kubeasz 集群个性化参数配置完全指南hosts 节点清单与 config.yml 组件参数深度解析【免费下载链接】kubeasz使用Ansible脚本安装K8S集群介绍组件交互原理方便直接不受国内网络环境影响项目地址: https://gitcode.com/GitHub_Trending/ku/kubeaszkubeasz 使用 Ansible 脚本安装 K8S 集群其个性化配置全部集中在每个集群实例的两个文件中clusters/xxxx/hosts节点定义与集群级全局变量与clusters/xxxx/config.yml组件级附加参数。本文以官方配置指南为骨架结合仓库内模板与源码逐项讲解每个参数的含义、默认值、取值范围与生效原理帮助你按需定制一套专属集群同时理解参数从配置到ansible-playbook 执行的完整链路。一、配置总览kubeasz 集群参数的两大入口kubeasz创建集群主要在以下两个地方进行配置假设集群名xxxx| 配置文件 | 模板来源 | 职责 | | :- | :- | :- | |clusters/xxxx/hosts| example/hosts.multi-node | 集群主要节点定义、主要参数配置与全局变量 | |clusters/xxxx/config.yml| example/config.yml | 其他参数配置或部分组件的附加参数 |两个文件分工明确hosts是 Ansible 的 inventory清单文件负责描述集群有哪些节点、节点归属哪个角色组同时以[all:vars]承载影响全集群的顶层变量config.yml则是通过-e clusters/xxxx/config.yml注入的 extra vars负责各组件deploy、etcd、runtime、kube-master、kube-node、network、cluster-addon、harbor的细粒度调优。这两个文件并非手工从零编写。执行ezctl new xxxx后kubeasz 会自动从模板复制生成集群配置目录ezctl 脚本中的new()函数完成这一动作mkdir -p clusters/$1 cp example/hosts.multi-node clusters/$1/hosts sed -i s/_cluster_name_/$1/g clusters/$1/hosts cp example/config.yml clusters/$1/config.yml随后它会读取ezdown中定义的各组件版本变量通过一连串sed将config.yml中的__k8s_ver__、__flannel__、__calico__、__coredns__等占位符替换为实际版本号同时检测部署机/etc/docker/daemon.json中是否配置了 registry-mirrors据此自动设置ENABLE_MIRROR_REGISTRY的值。命令行会明确提示后续两步操作INFO next steps 1: to config /etc/kubeasz/clusters/xxxx/hosts INFO next steps 2: to config /etc/kubeasz/clusters/xxxx/config.yml整个创建与安装流程可参见 集群规划与安装概览 与 ezctl 命令行介绍。在动手修改前理解ezctl setup如何消费这两个文件很有必要从 ezctl 脚本setup()函数可以看到最终执行的命令为ansible-playbook -i clusters/xxxx/hosts -e clusters/xxxx/config.yml playbooks/$PLAY_BOOK即hosts充当 inventory决定 play 跑在哪些节点上config.yml作为全局 extra vars 注入所有 play。这解释了为什么hosts中的[all:vars]和config.yml中的变量都能在任意 role 的模板中被引用。二、clusters/xxxx/hosts节点定义与集群级全局变量如 集群规划与安装概览 中介绍hosts文件主要包含集群节点定义和集群范围的主要参数配置。编辑时应把握两条原则尽量保持配置简单灵活只改必须改的项避免引入不必要的复杂度尽量保持配置项稳定已定稿的参数如 CIDR、端口范围后期变更代价高规划阶段就要定好。2.1 节点组Group定义参考 example/hosts.multi-node 的完整节点组结构# etcd cluster should have odd member(s) (1,3,5,...) [etcd] 192.168.1.1 192.168.1.2 192.168.1.3 # master node(s), set unique k8s_nodename for each node # CAUTION: k8s_nodename must consist of lower case alphanumeric characters, - or ., # and must start and end with an alphanumeric character [kube_master] 192.168.1.1 k8s_nodenamemaster-01 192.168.1.2 k8s_nodenamemaster-02 192.168.1.3 k8s_nodenamemaster-03 # work node(s), set unique k8s_nodename for each node [kube_node] 192.168.1.4 k8s_nodenameworker-01 192.168.1.5 k8s_nodenameworker-02 # [optional] harbor server, a private docker registry # NEW_INSTALL: true to install a harbor server; false to integrate with existed one [harbor] #192.168.1.8 NEW_INSTALLfalse # [optional] loadbalance for accessing k8s from outside [ex_lb] #192.168.1.6 LB_ROLEbackup EX_APISERVER_VIP192.168.1.250 EX_APISERVER_PORT8443 #192.168.1.7 LB_ROLEmaster EX_APISERVER_VIP192.168.1.250 EX_APISERVER_PORT8443 # [optional] ntp server for the cluster [chrony] #192.168.1.1各组语义如下[etcd]etcd 集群成员必须是 1、3、5 等奇数个以保证选主法定人数生产环境一般复用 master 节点[kube_master]Kubernetes 控制平面节点高可用集群至少 2 个[kube_node]承载业务负载的工作节点可按需提升配置或增加数量[harbor]可选私有镜像仓库NEW_INSTALLtrue表示全新安装 Harborfalse表示对接已有仓库[ex_lb]可选集群外部接入的负载均衡通过LB_ROLEmaster/backup、EX_APISERVER_VIP、EX_APISERVER_PORT配置 keepalived 虚拟 IP[chrony]可选集群内 NTP 时间同步服务器若环境已提供 NTP 服务可留空。k8s_nodename 命名约束每个节点可指定唯一的k8s_nodename该值必须由小写字母数字、-或.组成且以字母数字开头和结尾。若某节点未设置如 example/hosts.allinone 中k8s_nodename则在config.yml的K8S_NODENAME逻辑中自动生成k8s-ip 去除点号形式的名称详见下文 3.2 节。2.2 [all:vars] 全局变量详解hosts文件的[all:vars]段放置影响整个集群的顶层参数即原文档中提到的主要参数配置、全局变量[all:vars] # --------- Main Variables --------------- # Secure port for apiservers SECURE_PORT6443 # Cluster container-runtime supported: docker, containerd # if k8s version 1.24, docker is not supported CONTAINER_RUNTIMEcontainerd # Network plugins supported: calico, flannel, kube-router, cilium, kube-ovn CLUSTER_NETWORKcalico # Service proxy mode of kube-proxy: iptables or nftables # Prerequisites: kernal 5.13 and nft 1.0.0 PROXY_MODEnftables # K8S Service CIDR, not overlap with node(host) networking SERVICE_CIDR10.68.0.0/16 # Cluster CIDR (Pod CIDR), not overlap with node(host) networking CLUSTER_CIDR172.20.0.0/16 # NodePort Range NODE_PORT_RANGE30000-32767 # Cluster DNS Domain CLUSTER_DNS_DOMAINcluster.local各变量的作用与约束| 变量 | 默认值 | 说明 | | :- | :- | :- | |SECURE_PORT|6443| apiserver 安全端口 | |CONTAINER_RUNTIME|containerd| 容器运行时支持docker、containerdk8s 版本 ≥ 1.24 时不再支持 docker| |CLUSTER_NETWORK|calico| 网络插件支持calico、flannel、kube-router、cilium、kube-ovn| |PROXY_MODE|nftables| kube-proxy 代理模式iptables或nftablesnftables 要求内核 ≥ 5.13 且 nft ≥ 1.0.0 | |SERVICE_CIDR|10.68.0.0/16| Service 网段不得与节点主机网络重叠| |CLUSTER_CIDR|172.20.0.0/16| Pod 网段Cluster CIDR不得与节点主机网络重叠| |NODE_PORT_RANGE|30000-32767| NodePort 服务端口范围 | |CLUSTER_DNS_DOMAIN|cluster.local| 集群 DNS 域名 |这些 CIDR 参数会向下一级推导出关键地址。从 roles/kube-master/vars/main.yml 可见SERVICE_CIDR网段的第一个地址被自动计算为集群 Service 的虚拟 IPkubernetes.default.svcCLUSTER_KUBERNETES_SVC_IP: {{ SERVICE_CIDR.split(.)[0] }}.{{ SERVICE_CIDR.split(.)[1] }}.{{ SERVICE_CIDR.split(.)[2] }}.{{ SERVICE_CIDR.split(.)[3]|regex_replace(/.*, )|int 1 }}即默认SERVICE_CIDR10.68.0.0/16时CLUSTER_KUBERNETES_SVC_IP10.68.0.1。而 roles/cluster-addon/vars/main.yml 将网段的第二个地址作为 CoreDNS 服务地址CLUSTER_DNS_SVC_IP: {{ SERVICE_CIDR.split(.)[0] }}.{{ SERVICE_CIDR.split(.)[1] }}.{{ SERVICE_CIDR.split(.)[2] }}.{{ SERVICE_CIDR.split(.)[3]|regex_replace(/.*, )|int 2 }}默认即10.68.0.2。这两个推导关系提醒我们修改 SERVICE_CIDR 时无需也不应手工指定 kubernetes Service IP 与 DNS IPkubeasz 会自动按首地址 1/2规则重新计算。[all:vars]末尾还有一组附加变量模板中明确标注dont change the default value right now当前不建议修改默认值# Binaries Directory bin_dir/opt/kube/bin # Deploy Directory (kubeasz workspace) base_dir/etc/kubeasz # Directory for a specific cluster cluster_dir{{ base_dir }}/clusters/_cluster_name_ # CA and other components cert/key Directory ca_dir/etc/kubernetes/ssl # Default k8s_nodename is empty k8s_nodename # Default python interpreter ansible_python_interpreter/usr/bin/python3注意_cluster_name_占位符会在ezctl new时被替换为实际集群名ansible_python_interpreter指定部署机与目标节点的 Python 解释器路径各节点需保证/usr/bin/python3存在安装前会做准备。2.3 常用设置项速查原文档给出的常用设置项即上文变量的典型改法修改容器运行时CONTAINER_RUNTIMEcontainerd修改集群网络插件CLUSTER_NETWORKcalico修改容器网络地址CLUSTER_CIDR192.168.0.0/16需同步检查是否与宿主机网段冲突并考虑SERVICE_CIDR配套调整修改 NodePort 范围NODE_PORT_RANGE30000-32767三、clusters/xxxx/config.yml组件级个性化配置config.yml主要包括集群某个具体组件的个性化配置具体组件的配置项可能会不断增加可以在不做任何配置更改的情况下使用默认值创建集群——这是它的设计目标默认配置即可开箱即用按需增量覆盖。文件按role分段组织下面结合 example/config.yml 与仓库模板逐段解读。3.1 prepare 段安装来源与安全加固# 可选离线安装系统软件包 (offline|online) INSTALL_SOURCE: online # 可选进行系统安全加固 github.com/dev-sec/ansible-collection-hardening # (deprecated) 未更新上游项目未验证最新k8s集群安装不建议启用 OS_HARDEN: falseINSTALL_SOURCE系统软件包安装来源。默认online使用 yum/apt 在线仓库设为offline时使用离线安装需要先执行./ezdown -P下载离线系统软件包适用于无法访问 yum/apt 仓库的内网环境OS_HARDEN是否启用系统安全加固。模板注释明确提示该功能已标记 deprecated上游项目未更新、未验证最新集群安装不建议启用。3.2 deploy 段CA 证书、kubeconfig 与节点命名# default: ca will expire in 100 years # default: certs issued by the ca will expire in 50 years CA_EXPIRY: 876000h CERT_EXPIRY: 438000h # force to recreate CA and other certs, not suggested to set true CHANGE_CA: false # kubeconfig 配置参数 CLUSTER_NAME: cluster1 CONTEXT_NAME: context-{{ CLUSTER_NAME }} # k8s version K8S_VER: __k8s_ver__ # set unique k8s_nodename for each node, if not set(default:) ip add will be used K8S_NODENAME: {%- if k8s_nodename ! -%} \ {{ k8s_nodename|replace(_, -)|lower }} \ {%- else -%} \ k8s-{{ inventory_hostname|replace(., -) }} \ {%- endif -%} # use K8S_NODENAME to set hostname ENABLE_SETTING_HOSTNAME: trueCA_EXPIRYCA 根证书有效期默认 100 年876000hCERT_EXPIRY由 CA 签发的各组件证书有效期默认 50 年438000h。该值直接注入证书签发配置在 roles/deploy/templates/ca-config.json.j2 中default与kubernetesprofile 的expiry均引用{{ CERT_EXPIRY }}kcfgprofile客户端 kubeconfig 证书则使用{{ CUSTOM_EXPIRY }}由ezctl kcfg-adm -e传入默认4800h。因此调短CERT_EXPIRY意味着所有组件证书的滚动有效期缩短建议结合 证书更新与集群维护 类文档统一规划CHANGE_CA是否强制重新生成 CA 与全部证书。模板注释明确不建议设为true仅在admin.conf泄露等极端场景下配合ezctl kca-renew使用CLUSTER_NAME/CONTEXT_NAMEkubeconfig 中的集群名与上下文名CONTEXT_NAME支持引用CLUSTER_NAME的 Jinja2 模板K8S_VERKubernetes 版本__k8s_ver__占位符由ezctl new依据ezdown中的K8S_BIN_VER自动替换K8S_NODENAME节点名解析逻辑——若某节点k8s_nodename非空则将下划线替换为连字符并转小写否则生成k8s-ip 去点如192.168.1.4→k8s-192-168-1-4ENABLE_SETTING_HOSTNAME是否使用解析出的K8S_NODENAME设置节点 hostname默认开启。3.3 etcd 段数据与 WAL 目录# 设置不同的wal目录可以避免磁盘io竞争提高性能 ETCD_DATA_DIR: /var/lib/etcd ETCD_WAL_DIR: ETCD_DATA_DIR为 etcd 数据目录ETCD_WAL_DIR默认留空与数据目录同盘。若机器存在多块磁盘将 WAL 目录单独放置可避免磁盘 I/O 竞争提升写入性能——这也是原文档在 00 集群规划 中提示关注磁盘布局的原因之一。3.4 runtime 段容器运行时参数# [.]启用拉取加速镜像仓库 ENABLE_MIRROR_REGISTRY: true # [.]添加信任的私有仓库 # 必须按照如下示例格式协议头http://和https://不能省略 INSECURE_REG: - http://easzlab.io.local:5000 - https://reg.yourcompany.com # [.]基础容器镜像 SANDBOX_IMAGE: easzlab.io.local:5000/easzlab/pause:__pause__ # [containerd] root 存储目录默认/var/lib/containerd CONTAINERD_ROOT_DIR: /var/lib/containerd # [containerd] state 存储目录默认/run/containerd CONTAINERD_STATE_DIR: /run/containerd # [containerd] config 目录默认/etc/containerd CONTAINERD_CONFIG_DIR: /etc/containerd # [containerd] systemd service 名称默认containerd.service CONTAINERD_SERVICE_NAME: containerd.service # [docker]容器存储目录 DOCKER_STORAGE_DIR: /var/lib/docker # [docker]开启Restful API DOCKER_ENABLE_REMOTE_API: falseENABLE_MIRROR_REGISTRY启用镜像加速仓库。ezctl new时会根据部署机 daemon.json 是否配置 registry-mirrors 自动设定INSECURE_REG信任的私有仓库列表必须带http://或https://协议头不可省略。这些条目会写入 containerd/docker 的仓库配置例如 roles/containerd/templates/config.toml.j2 中config_path {{ CONTAINERD_CONFIG_DIR }}/certs.d指向按仓库名组织的 hosts.toml 配置目录SANDBOX_IMAGEPod 沙箱基础镜像pause版本占位符__pause__由ezctl new替换CONTAINERD_*containerd 的 root/state/config 目录与 systemd 服务名默认值如注释所示。若根分区空间紧张可考虑将CONTAINERD_ROOT_DIR调整到大容量磁盘与KUBELET_ROOT_DIR同理DOCKER_STORAGE_DIRdocker 数据目录DOCKER_ENABLE_REMOTE_API是否开启 docker Restful API默认关闭涉及安全面谨慎开启。3.5 kube-master 段证书 SAN、Pod 网段与审计# k8s 集群 master 节点证书配置可以添加多个ip和域名比如增加公网ip和域名 MASTER_CERT_HOSTS: - 10.1.1.1 - k8s.easzlab.io #- www.test.com # node 节点上 pod 网段掩码长度决定每个节点最多能分配的pod ip地址 # 如果flannel 使用 --kube-subnet-mgr 参数那么它将读取该设置为每个节点分配pod网段 NODE_CIDR_LEN: 24 # 是否启用集群audit功能 ENABLE_CLUSTER_AUDIT: falseMASTER_CERT_HOSTSapiserver 证书附加的 IP 与域名SAN列表。这是原文档强调的配置 apiserver 支持公网域名的关键参数。其生效原理可见 roles/kube-master/templates/kubernetes-csr.json.j2签发 apiserver 证书时hosts数组会依次包含127.0.0.1、ex_lb虚拟 IP若配置了外部负载均衡、所有kube_master节点 IP、CLUSTER_KUBERNETES_SVC_IP、MASTER_CERT_HOSTS中列出的每个 IP/域名以及kubernetes、kubernetes.default、kubernetes.default.svc等内部 DNS 名称。因此当需要通过公网 IP 或自定义域名访问 apiserver 时必须在此处追加否则 kubectl 会因证书 SAN 不匹配而拒绝连接NODE_CIDR_LEN每个节点分配的 Pod 网段掩码长度。默认 24即每个节点最多 256 个 Pod IP减去保留地址约 250 个可用。flannel 使用--kube-subnet-mgr时会读取该值划分节点子网ENABLE_CLUSTER_AUDIT是否启用集群审计功能默认关闭。3.6 kube-node 段kubelet 与资源预留# Kubelet 根目录 KUBELET_ROOT_DIR: /var/lib/kubelet # node节点最大pod 数 MAX_PODS: 110 # 配置为kube组件kubelet,kube-proxy,dockerd等预留的资源量 # 数值设置详见templates/kubelet-config.yaml.j2 KUBE_RESERVED_ENABLED: no # k8s 官方不建议草率开启 system-reserved, 除非你基于长期监控了解系统的资源占用状况 # 并且随着系统运行时间需要适当增加资源预留数值设置详见templates/kubelet-config.yaml.j2 # 系统预留设置基于 4c/8g 虚机最小化安装系统服务如果使用高性能物理机可以适当增加预留 # 另外集群安装时候apiserver等资源占用会短时较大建议至少预留1g内存 SYS_RESERVED_ENABLED: noKUBELET_ROOT_DIRkubelet 根目录。与CONTAINERD_ROOT_DIR/DOCKER_STORAGE_DIR一样若/var分区空间有限应统一规划迁移MAX_PODS单节点最大 Pod 数默认 110KUBE_RESERVED_ENABLED为 kube 组件kubelet、kube-proxy、dockerd 等预留资源默认no具体数值定义在 roles/kube-node/templates/kubelet-config.yaml.j2SYS_RESERVED_ENABLED为系统服务预留资源默认no。模板注释给出明确建议不要草率开启除非基于长期监控了解系统资源占用预留量基于 4c/8g 虚拟机最小化系统服务设定高性能物理机可适当增加同时提示集群安装期间 apiserver 等组件短时资源占用较大建议至少预留 1G 内存。3.7 network 段各网络插件专项参数按所选CLUSTER_NETWORK对应插件的专项参数生效flannelroles/flannel/templates/kube-flannel.yaml.j2# [flannel]设置flannel 后端host-gw,vxlan等 FLANNEL_BACKEND: vxlan DIRECT_ROUTING: false flannel_ver: __flannel__FLANNEL_BACKEND支持host-gw、vxlan等后端DIRECT_ROUTING控制同子网节点间是否走直连路由。calico对应 roles/calico/templates/calico-v3.32.yaml.j2 等按版本区分的模板# 模式可选项有: [Always, CrossSubnet, Never],跨子网可以配置为Always与CrossSubnet # CrossSubnet为隧道BGP路由混合模式可以提升网络性能同子网配置为Never即可. # 公有云建议使用always比较省事其他的话需要修改各自公有云的网络配置 CALICO_ENABLE_OVERLAY: Always # [calico]设置 calico-node使用的host IPbgp邻居通过该地址建立可手工指定也可以自动发现 IP_AUTODETECTION_METHOD: can-reach{{ groups[kube_master][0] }} # [calico]设置calico 网络 backend: bird, vxlan, none # 少数公有云Azure或者私有云不支持IPinIP封包可以使用 vxlan 模式 CALICO_NETWORKING_BACKEND: bird # [calico]设置calico 是否使用route reflectors # 如果集群规模超过50个节点建议启用该特性 CALICO_RR_ENABLED: false # CALICO_RR_NODES 配置route reflectors的节点如果未设置默认使用集群master节点 CALICO_RR_NODES: [] calico_ver: __calico__ calico_ver_main: {{ calico_ver.split(.)[0] }}.{{ calico_ver.split(.)[1] }}CALICO_ENABLE_OVERLAY覆盖网络模式可选Always、CrossSubnet、Never。CrossSubnet为隧道 BGP 路由混合模式同子网走 BGP、跨子网走隧道可提升性能公有云建议AlwaysIP_AUTODETECTION_METHODcalico-node 使用的 host IP 自动发现策略默认can-reach第一个 master 节点也可手工指定网卡/地址CALICO_NETWORKING_BACKEND数据面 backend可选bird、vxlan、none少数不支持 IPinIP 封包的云环境如 Azure应改用vxlanCALICO_RR_ENABLED/CALICO_RR_NODES是否启用 BGP Route Reflector集群规模超过 50 个节点时建议启用不指定CALICO_RR_NODES时默认使用 master 节点充当 RRcalico_ver_main由完整版本号推导的主版本用于选择对应的 calico 模板文件。ciliumroles/cilium/templates/values.yaml.j2cilium_ver: __cilium__ cilium_connectivity_check: false cilium_hubble_enabled: false cilium_hubble_ui_enabled: falsecilium_connectivity_check控制安装后是否运行连通性自检对应 roles/cluster-addon/tasks/cilium_connectivity_check.ymlcilium_hubble_enabled/cilium_hubble_ui_enabled控制 Hubble 可观测性与 Web UI。kube-ovnkube_ovn_ver指定离线镜像 tar 包对应的版本见 roles/kube-ovn/templates/install.sh.j2。kube-routerroles/kube-router/templates/kuberouter.yaml.j2# [kube-router]公有云上存在限制一般需要始终开启 ipinip自有环境可以设置为 subnet OVERLAY_TYPE: full # [kube-router]NetworkPolicy 支持开关 FIREWALL_ENABLE: true kube_router_ver: __kube_router__OVERLAY_TYPE默认full始终开启 ipinip适配公有云限制自有环境可设为subnetFIREWALL_ENABLE控制 NetworkPolicy 支持。3.8 cluster-addon 段组件安装开关原文档列举的配置 cluster-addon 组件安装即此段。所有组件均遵循xxx_install: yes/no的开关模式未开启则对应组件不安装# coredns 自动安装 dns_install: yes corednsVer: __coredns__ ENABLE_LOCAL_DNS_CACHE: true dnsNodeCacheVer: __dns_node_cache__ # 设置 local dns cache 地址 LOCAL_DNS_CACHE: 169.254.20.10 # metric server 自动安装 metricsserver_install: yes metricsVer: __metrics__ # dashboard 自动安装 dashboard_install: no dashboardVer: __dashboard__ # headlamp 自动安装 headlamp_install: no headlampVer: __headlamp__ # local-storage (local-path-provisioner) 自动安装 local_path_provisioner_install: no local_path_provisioner_ver: __local_path_provisioner__ local_path_storage_class: local-path # 设置默认本地存储路径 local_path_provisioner_dir: /opt/local-path-provisioner # nfs-provisioner 自动安装 nfs_provisioner_install: no nfs_provisioner_namespace: kube-system nfs_provisioner_ver: __nfs_provisioner__ nfs_storage_class: managed-nfs-storage nfs_server: 192.168.1.10 nfs_path: /data/nfs # openebs 自动安装 openebs_install: no openebs_ver: __openebs_ver__ openebs_namespace: openebs openebs_hostpath: /var/openebs/local openebs_hostpath_storage_class: openebs-hostpath openebs_lvm_storage_class: openebs-lvmpv openebs_lvm_vg: vg_k8s # prometheus 自动安装 prom_install: no prom_namespace: monitor prom_storage_class: prom_chart_ver: __prom_chart__ # network-check 自动安装 network_check_enabled: false network_check_schedule: */5 * * * * # node-problem-detector 自动安装 node_problem_detector_install: no node_problem_detector_ver: __node_problem_detector__ # kubeblocks 自动安装 kubeblocks_ver: __kubeblocks_ver__ kubeblocks_install: no # higress 自动安装 # higress gateway 只会部署到node with 标签ingress-controller/providerhigress higress_install: no higress_namespace: higress-system higress_ver: __higress__ # ingress-nginx 自动安装 # ingress-nginx 只会部署到node with 标签ingress-controller/provideringress-nginx ingress_nginx_install: no ingress_nginx_namespace: ingress-nginx ingress_nginx_ver: __ingress_nginx_ver__ ingress_nginx_metrics_enabled: false # 需要先部署prometheus # argocd 自动安装 argocd_install: no关键点默认仅安装 CoreDNS 与 metrics-serverdns_install: yes、metricsserver_install: yes其余组件默认关闭按需开启ENABLE_LOCAL_DNS_CACHE与LOCAL_DNS_CACHE配置节点本地 DNS 缓存nodelocaldns见 roles/cluster-addon/templates/dns/nodelocaldns-ipvs.yaml.j2默认地址169.254.20.10存储类组件local-path、nfs、openebs安装前需先规划好存储路径、NFS 服务器地址等参数higress 与 ingress-nginx 的控制器只调度到带特定标签的节点分别要求节点带ingress-controller/providerhigress、ingress-controller/provideringress-nginx标签开启前需先为网关节点打标签ingress_nginx_metrics_enabled依赖 Prometheus 已部署prom_install: yes所有__xxx__占位符均由ezctl new按 ezdown 中的版本变量自动填充无需手工填写。3.9 harbor 段私有仓库参数# harbor version完整版本号 HARBOR_VER: __harbor__ HARBOR_DOMAIN: harbor.easzlab.io.local HARBOR_PATH: /var/data HARBOR_TLS_PORT: 8443 HARBOR_REGISTRY: {{ HARBOR_DOMAIN }}:{{ HARBOR_TLS_PORT }} # if set false, you need to put certs named harbor.pem and harbor-key.pem in directory down HARBOR_SELF_SIGNED_CERT: true # install extra component HARBOR_WITH_TRIVY: falseHARBOR_DOMAIN、HARBOR_PATH、HARBOR_TLS_PORT分别控制仓库域名、数据目录与 TLS 端口HARBOR_REGISTRY由它们拼接而成HARBOR_SELF_SIGNED_CERT为false时需自行将harbor.pem、harbor-key.pem放入down目录HARBOR_WITH_TRIVY控制是否额外安装 Trivy 镜像漏洞扫描组件。对应的安装模板见 roles/harbor/templates/harbor-v2.12.yml.j2 等按版本区分的文件。四、典型配置组合示例下面给出几个贴合实战的组合场景帮助理解两个文件的配合关系。4.1 内网环境 离线安装hosts中规划好节点后在config.yml中INSTALL_SOURCE: offline # 需先执行 ./ezdown -P 下载离线系统软件包 ENABLE_MIRROR_REGISTRY: true INSECURE_REG: - http://harbor.easzlab.io.local:8443并开启所需 addon如dashboard_install: yes。安装时使用ezctl setup xxxx all一键执行playbooks/90.setup.yml或分步执行01~07。4.2 公网访问 apiserverhosts中定义ex_lb虚拟 IP同时在config.yml中MASTER_CERT_HOSTS: - 公网IP - api.example.com二者都会进入 roles/kube-master/templates/kubernetes-csr.json.j2 的证书 SAN 列表保证通过公网地址访问 apiserver 时 TLS 校验通过。4.3 证书有效期收紧CA_EXPIRY: 87600h # 10 年 CERT_EXPIRY: 43800h # 5 年收紧后需在证书到期前规划轮换相关流程可参考 集群证书管理 与 强制更新证书。五、配置生效链路与排障提示理解配置如何生效有助于快速定位改了不生效的问题ezctl new xxxx依据 example/hosts.multi-node 与 example/config.yml 生成clusters/xxxx/下的两个文件并完成版本占位符替换ezctl setup xxxx step组装命令ansible-playbook -i clusters/xxxx/hosts -e clusters/xxxx/config.yml playbooks/step.ymlhosts决定目标主机config.yml注入全局变量各 role 的模板如 roles/deploy/templates/ca-config.json.j2、roles/kube-master/templates/kubernetes-csr.json.j2、roles/containerd/templates/config.toml.j2在渲染时读取这些变量生成实际的系统配置与证书。排障提示修改hosts中的 CIDR、端口等集群级参数必须在首次安装前确定集群创建后再变更成本很高修改config.yml后分步重跑对应的 playbook 步骤即可增量生效如仅改 addon 则重跑ezctl setup xxxx 07无需重建整个集群PROXY_MODEnftables有明确的内核≥ 5.13与 nft≥ 1.0.0版本前提不满足时请回退iptables或先升级内核可参考 内核升级指南各组件开关型参数使用yes/no字符串时需保持引号避免 YAML 将其解析为布尔值导致判断异常。六、小结kubeasz 将集群级参数与组件级参数清晰分层clusters/xxxx/hosts负责节点拓扑与全局网络/运行时选型clusters/xxxx/config.yml负责证书、目录、资源预留与 addon 安装等细粒度调优。二者通过ansible-playbook -i ... -e ...的机制统一生效配合 ezctl 命令集 可实现对多集群的灵活创建、升级与扩容管理。掌握本文列出的参数含义与生效链路后你便可以在默认配置之上按实际环境与业务需求定制出一套稳定、可维护的 Kubernetes 集群。【免费下载链接】kubeasz使用Ansible脚本安装K8S集群介绍组件交互原理方便直接不受国内网络环境影响项目地址: https://gitcode.com/GitHub_Trending/ku/kubeasz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考