KubeSpray helm-apps 角色实战指南：随集群安装声明式部署 Helm Chart

KubeSpray helm-apps 角色实战指南随集群安装声明式部署 Helm Chart【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubesprayKubeSpray 的helm-apps角色允许你在集群安装或升级过程中以纯声明式的方式批量安装 Helm Chart只需在 Playbook 中列出仓库repositories、发布项releases和公共选项release_common_opts角色便会自动完成helm repository add、缓存刷新与helm upgrade --install全链路操作。读完本文你将掌握该角色的完整参数体系、底层任务执行流程以及如何像仓库内置的kubelet-csr-approver与自定义 CNI 插件那样把它挂接到自己的集群编排中。角色定位与运行前提roles/helm-apps/README.md对该角色的定位是在 KubeSpray 集群安装或升级期间拉取并部署 Helm Chart。它有两个硬性前提执行主机必须能够访问 Kubernetes API主机上必须已安装helm二进制文件。这两个前提在仓库中都有对应的实现保障角色依赖声明在 meta/main.yml 中它无条件依赖kubernetes-apps/helm子角色kubernetes-apps/helm/tasks/main.yml 负责下载并部署 helm先通过download_file.yml带校验和地下载helm-{{ helm_version }}-linux-{{ image_arch }}.tar.gz再把二进制拷贝到{{ bin_dir }}/helm权限 0755最后安装 bash 补全脚本到/etc/bash_completion.d/helm.sh。与之配套的默认值分布在 kubespray_defaults/defaults/main/main.yml 与 kubespray_defaults/defaults/main/download.yml 中# kubespray_defaults/defaults/main/main.yml helm_enabled: false # 默认关闭需要在 inventory 中显式开启 bin_dir: /usr/local/bin # helm 二进制的安装目录 # kubespray_defaults/defaults/main/download.ymldownloads 片段 helm: enabled: {{ helm_enabled }} file: true dest: {{ local_release_dir }}/helm-{{ helm_version }}/helm-{{ helm_version }}-linux-{{ image_arch }}.tar.gz checksum: {{ helm_archive_checksum }} url: {{ helm_download_url }} unarchive: true owner: root mode: 0755 groups: - kube_control_plane几个值得注意的细节helm_version由校验和表推导见 kubespray_defaults/defaults/main/download.ymlhelm_version: {{ (helm_archive_checksums[amd64] | dict2items)[0].key }}对应的 SHA256 清单维护在 kubespray_defaults/vars/main/checksums.ymlhelm的下载任务只对kube_control_plane组生效即二进制只会落到控制面节点上helm_enabled是布尔开关inventory 中若给出非布尔值会被 validate_inventory/tasks/main.yml 直接拦截报错当作为kubernetes-apps的一部分运行时helm 子角色受helm_enabled条件与helmtag 控制见 kubernetes-apps/meta/main.yml。因此实际使用 helm-apps 前请先在 group vars 中设置helm_enabled: true。从仓库内置的两个调用方来看角色统一运行在inventory_hostname groups[kube_control_plane][0]也就是第一个控制面节点——这正是“拥有 Kubernetes API 访问能力”这一前提的落地方式控制面节点上已有 kubeconfig 与 API 连通性。参数定义releases / repositories / release_common_optsREADME 提示完整参数见 meta/argument_specs.yml。该文件用 Ansible 的argument_specs机制对三个入参做了严格校验下面是整理后的完整参数表。releases必填列表“List of dictionaries passed as arguments tokubernetes.core.helm”即每一项最终都会展开成一次kubernetes.core.helm模块调用参数类型必填说明namestr是Helm release 名称chart_refpath是Chart 的引用repo/chart或本地路径namespacestr是目标命名空间chart_versionstr否固定 Chart 版本valuesdict否传入 Chart 的 values 字典create_namespacebool否命名空间不存在时自动创建chart_repo_urlstr否指定 chart 所在仓库 URLdisable_hookbool否禁用 Helm hookshistory_maxint否限制 release 历史记录条数purgebool否删除 release 时同时清理历史replacebool否用当前模板替换旧 releaseskip_crdsbool否安装时跳过 CRDwaitbool否等待资源就绪默认trueargument_specs.ymlwait_timeoutstr否等待超时如10matomicbool否失败时自动回滚默认trueargument_specs.ymlrepositories可选列表默认[]“List of dictionaries passed as arguments tokubernetes.core.helm_repository”参数类型必填说明namestr是仓库别名urlstr否仓库地址username/passwordstr否私有仓库认证仓库中的 custom CNI 场景实际用到了这两个字段release_common_opts可选字典默认{}“Common arguments for every helm invocation”——对每一次 helm 调用生效的公共选项字段集合与releases项相同且声明了更完整的默认值argument_specs.yml参数默认值说明create_namespacetrue默认自动创建命名空间waittrue默认等待资源就绪wait_timeout5m默认等待 5 分钟atomictrue默认失败回滚chart_repo_url/disable_hook/history_max/purge/replace/skip_crds—同 releases 项参数合并优先级是理解行为的关键。安装任务tasks/main.yml的调用形式是kubernetes.core.helm: {{ helm_defaults | combine(release_common_opts, item) }}Ansible 的combine按从左到右依次合并、后者覆盖前者因此优先级为releases 中单项 release_common_opts helm_defaultshelm_defaults定义在 vars/main.ymlhelm_update: true # 是否刷新仓库缓存见下文 helm_defaults: atomic: true binary_path: {{ bin_dir }}/helm helm_repository_defaults: binary_path: {{ bin_dir }}/helm force_update: true所以 README 示例中某个 release 写wait_timeout: 10m就是用它覆盖release_common_opts里继承下来的wait_timeout: 5m。执行流程三个任务的逐行解析helm-apps/tasks/main.yml 全部逻辑只有三个任务但每一处都有讲究。所有任务都带着environment: {{ proxy_env }}运行proxy_env由 kubespray_defaults/defaults/main/main.yml 从 inventory 的http_proxy/https_proxy/no_proxy以及可选的https_proxy_cert_file拼装而来保证在企业代理环境下 helm 的仓库访问与下载不中断。任务一添加 Helm 仓库- name: Add Helm repositories environment: {{ proxy_env }} kubernetes.core.helm_repository: {{ helm_repository_defaults | combine(item) }} loop: {{ repositories }}对repositories中每一项循环调用kubernetes.core.helm_repository并与helm_repository_defaults合并——后者注入了binary_path: {{ bin_dir }}/helm和force_update: true等价于每次都以helm repo add --force-update的语义注册仓库保证重复执行时 URL 变更能够生效。任务二刷新仓库缓存- name: Update Helm repositories environment: {{ proxy_env }} kubernetes.core.helm: state: absent binary_path: {{ bin_dir }}/helm release_name: dummy # trick needed to refresh in separate step release_namespace: kube-system update_repo_cache: true when: - repositories ! [] - helm_update这是一个刻意为之的“trick”用一个不存在的 release 名dummy指定kube-system下的卸载操作由于dummy实际不存在卸载是空操作但update_repo_cache: true会触发helm repo update式的索引刷新确保后面安装时解析到的是最新版本索引。它受两个条件门控仅在提供了repositories且helm_updatevars/main.yml 中默认true为真时执行不引用任何仓库时可直接跳过以节省时间。任务三安装应用- name: Install Helm Applications environment: {{ proxy_env }} kubernetes.core.helm: {{ helm_defaults | combine(release_common_opts, item) }} loop: {{ releases }}对releases列表逐项执行kubernetes.core.helm对应helm upgrade --install语义合并规则见上一节。由于wait与atomic默认开启每个 release 会阻塞到资源就绪安装失败则自动回滚——这也意味着长耗时或依赖外部条件的 Chart 应当显式关闭/调整这两个选项。Playbook 使用示例roles/helm-apps/README.md给出的原始示例如下--- - hosts: kube_control_plane[0] gather_facts: no roles: - name: helm-apps releases: - name: app namespace: app chart_ref: simple-app/simple-app - name: app2 namespace: app chart_ref: simple-app/simple-app wait_timeout: 10m # override the same option in release_common_opts repositories: {{ repos }} - name: simple-app url: https://blog.leiwang.info/simple-app release_common_opts: {{ helm_params }} wait_timeout: 5m示例的核心意图是演示三件事把角色跑在第一个控制面节点上、用repositories注册 Chart 仓库、用release_common_opts提供公共选项并允许单个 release 覆盖app2的wait_timeout: 10m覆盖公共的5m。需要注意repositories与release_common_opts处的{{ ... }}写法是 README 中残留的模板占位符实际使用时应直接写 YAML 列表/字典。按 argument_specs.yml 的字段约束一个可直接运行的等价写法是--- - name: Deploy additional apps with kubespray hosts: kube_control_plane[0] gather_facts: no roles: - name: helm-apps repositories: - name: simple-app url: https://blog.leiwang.info/simple-app release_common_opts: wait_timeout: 5m create_namespace: true releases: - name: app namespace: app chart_ref: simple-app/simple-app values: replicas: 2 - name: app2 namespace: app chart_ref: simple-app/simple-app chart_version: 1.2.3 wait_timeout: 10m # 覆盖 release_common_opts 中的同名选项配合 inventory 侧的准备动作# group_vars/all 或 group_vars/k8s_cluster helm_enabled: true # 让 kubernetes-apps/helm 子角色下载并安装 helm 二进制仓库中的真实用例KubeSpray 自己就有两处把helm-apps作为依赖角色内联调用的地方是学习参数组合的最佳参照。用例一kubelet-csr-approverkubernetes-apps/kubelet-csr-approver/meta/main.ymldependencies: - role: helm-apps when: - inventory_hostname groups[kube_control_plane][0] - kubelet_csr_approver_enabled environment: {{ proxy_env }} release_common_opts: {} releases: - name: kubelet-csr-approver namespace: {{ kubelet_csr_approver_namespace }} chart_ref: {{ kubelet_csr_approver_chart_ref }} chart_version: {{ kubelet_csr_approver_chart_version }} wait: {{ kube_network_plugin ! cni }} atomic: {{ kube_network_plugin ! cni }} values: {{ kubelet_csr_approver_values }} repositories: - name: {{ kubelet_csr_approver_repository_name }} url: {{ kubelet_csr_approver_repository_url }}这里展示了 release 级覆盖的典型场景当网络插件是cni尚未就绪的自定义 CNI时通过把wait/atomic置为假值跳过就绪等待与失败回滚避免角色在 Pod 无法就绪的情况下卡死或误回滚。用例二自定义 CNI 插件network_plugin/custom_cni/meta/main.ymldependencies: - role: helm-apps when: - inventory_hostname groups[kube_control_plane][0] - custom_cni_chart_release_name | length 0 environment: {{ proxy_env }} releases: - name: {{ custom_cni_chart_release_name }} namespace: {{ custom_cni_chart_namespace }} chart_ref: {{ custom_cni_chart_ref }} chart_version: {{ custom_cni_chart_version }} wait: true create_namespace: true values: {{ custom_cni_chart_values }} repositories: - name: {{ custom_cni_chart_repository_name }} url: {{ custom_cni_chart_repository_url }} username: {{ custom_cni_chart_repository_username | default(omit) }} password: {{ custom_cni_chart_repository_password | default(omit) }}该用例补齐了前面参数表中较少出现的私有仓库认证字段username/password配合default(omit)避免向模块传入空值并且由 docs/CNI/custom CNI 相关说明 所在的网络插件文档体系提供配置入口。两个用例共同印证了 README 中“在具备 API 访问能力的控制面首节点上执行”这一要求。使用要点小结先开开关再谈部署inventory 中设置helm_enabled: true否则kube_control_plane节点上不会有{{ bin_dir }}/helm默认/usr/local/bin/helm三个任务中的binary_path引用将失败。优先级链单项 release_common_optshelm_defaults公共默认wait: true、atomic: true、create_namespace: true、wait_timeout: 5m长任务或依赖外部条件的 Chart 记得按需覆盖。仓库缓存刷新是条件行为只有repositories非空且helm_update: true默认时才会执行dummyrelease 的update_repo_cache步骤只安装本地路径 Chart 时这一步自动跳过。代理环境所有任务均通过proxy_env注入代理变量离线或受代理限制的环境中正确配置http_proxy/https_proxy/no_proxy是仓库注册与索引刷新成功的前提。失败语义atomic默认开启release 安装失败会自动回滚并让 Playbook 报错这对“随安装部署应用”的场景通常是期望行为但对容错要求高的 Chart如 kubelet-csr-approver 用例应显式关闭。以上参数与流程均可在 roles/helm-apps/README.md、roles/helm-apps/meta/argument_specs.yml、roles/helm-apps/tasks/main.yml 与 roles/helm-apps/vars/main.yml 中逐条对照验证。【免费下载链接】kubesprayDeploy a Production Ready Kubernetes Cluster项目地址: https://gitcode.com/GitHub_Trending/ku/kubespray创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考