terraform-aws-eks 用户数据与节点引导User Data Bootstrapping完整指南【免费下载链接】terraform-aws-eksTerraform module to create Amazon Elastic Kubernetes (EKS) resources 项目地址: https://gitcode.com/GitHub_Trending/te/terraform-aws-eks导读本文聚焦 terraform-aws-eks 模块中「节点用户数据user data」的设计与使用围绕 docs/user_data.md 文档深入剖析 EKS Managed Node Group 与 Self Managed Node Group 两大类场景下用户数据如何被注入、渲染、合并与引导节点入集群。读完本文你将掌握pre_bootstrap_user_data、bootstrap_extra_args、post_bootstrap_user_data、enable_bootstrap_user_data、user_data_template_path、cloudinit_pre_nodeadm/cloudinit_post_nodeadm等核心变量的适用条件与使用姿势理解 AL2 / AL2023 / Bottlerocket / Windows 四种 AMI 类型各自的格式约束并能在自定义 AMI 场景下正确选择模块内置模板或自研模板两条路径。一、整体设计用户数据从哪来、由谁渲染在 terraform-aws-eks 中所有节点用户数据的渲染逻辑被收敛在一个内部子模块 modules/_user_data 中它对外只暴露一个输出user_dataBase64 编码后的最终用户数据定义见 modules/_user_data/outputs.tf。该模块被两个消费方以不同的参数调用modules/eks-managed-node-group/main.tf#L17-L37托管节点组场景默认is_eks_managed_node_group truemodules/self-managed-node-group/main.tf#L59-L81自管节点组场景固定传入is_eks_managed_node_group false且enable_bootstrap_user_data true自管节点组必须由用户自己完成引导见下文。渲染的核心逻辑位于 modules/_user_data/main.tf#L16-L80通过ami_type前缀判断 AMI 家族AL2_、AL2023_见 main.tf#L17-L18通过ami_type_to_user_data_path映射表main.tf#L21-L47把 AMI 类型翻译成默认模板路径用templatefile()渲染模板注入cluster_name、cluster_endpoint、cluster_auth_base64、cluster_service_cidr、cluster_ip_family、bootstrap_extra_args、pre_bootstrap_user_data、post_bootstrap_user_data等变量main.tf#L52-L73最终base64encode后输出。需要特别注意的是 main.tf#L1-L14 中的硬性前置校验当create true时cluster_service_cidr必须提供长度大于 6。这与 AWS 引导脚本使用 service CIDR 计算 kube-proxy 等配置相关即使你的 AMI 类型不需要该值也要显式传入否则terraform plan会直接报错cluster_service_cidr is required when create true.二、EKS Managed Node Group 的两条用户数据路径对托管节点组而言AWS 服务本身会向节点注入引导用户数据。因此问题只有两个往前面加什么、是否完全接管。路径 1不指定ami_id—— 使用 AWS 提供的引导数据做前置追加当没有提供ami_id时AWS EKS 托管节点组服务会自动合并引导脚本。用户可以通过变量注入额外内容该内容会被**前置pre-pended**到服务生成的用户数据之前。对于AL2_*、BOTTLEROCKET_*、WINDOWS_*使用pre_bootstrap_user_data ...对于AL2023_*使用cloudinit_pre_nodeadm以 MIME multipart 片段形式提供cloudinit_pre_nodeadm [{ content -EOT --- apiVersion: node.eks.aws/v1alpha1 kind: NodeConfig spec: ... EOT content_type application/node.eks.aws }]在源码层面这个前置追加行为体现在 modules/_user_data/main.tf#L89-L101当满足is_eks_managed_node_group !enable_bootstrap_user_data pre_bootstrap_user_data ! 时模块通过cloudinit_config把用户提供的pre_bootstrap_user_data封装成text/x-shellscript类型的 MIME partbase64_encode true、gzip false随后由 AWS 服务把它拼接到自己的引导数据之前。路径 2指定了ami_id自定义 AMI—— 引导职责转移到用户侧一旦指定ami_idAWS 服务不再向节点注入引导脚本节点如何拿到集群 CA、API Server 地址并注册进集群完全由你的用户数据负责。文档给出两条子路径子路径 AAMI 是 AWS EKS Optimized AMI 的衍生镜像时选用模块内置引导模板enable_bootstrap_user_data true # 启用模块内置引导模板 pre_bootstrap_user_data ... bootstrap_extra_args ... post_bootstrap_user_data ...enable_bootstrap_user_data是总开关默认false见 modules/_user_data/variables.tf#L15-L20。开启后模板渲染出的引导内容会包含完整的节点引导命令详见第三、四节。子路径 BAMI 不是 EKS Optimized 衍生镜像或需要完全掌控时提供自己的模板user_data_template_path ./your/user_data.sh # 用户自供引导模板 pre_bootstrap_user_data ... bootstrap_extra_args ... post_bootstrap_user_data ...注意文档中的重要限制只有被传给templatefile()的变量即 main.tf#L52-L73 中注入的那批enable_bootstrap_user_data、cluster_name、cluster_endpoint、cluster_auth_base64、cluster_service_cidr、cluster_ip_family、cluster_dns_ips、bootstrap_extra_args、pre_bootstrap_user_data、post_bootstrap_user_data才能在自供模板中使用。如果你想在模板里用其他自定义变量就必须先自行预渲染pre-render再把最终模板交给模块。关于 AL2023 的 nodeadm 特殊之处AL2023 采用 nodeadmnode.eks.aws/v1alpha1NodeConfig体系模块在 modules/_user_data/main.tf#L109-L137 中实现了专门的 cloud-init 组装逻辑若enable_bootstrap_user_data true则最终 user data cloudinit_pre_nodeadm片段 模块渲染的 NodeConfig 片段application/node.eks.awscloudinit_post_nodeadm片段若未启用则只保留cloudinit_pre_nodeadm片段多个片段通过cloudinit_config以MIMEBOUNDARY为边界封装成 MIME multipartbase64_encode true、gzip false。测试用例 tests/user-data/main.tf#L147-L216 与渲染结果 tests/user-data/rendered/al2023/eks-mng-custom-ami.txt 展示了这一组合三个 MIME part 依次是用户自定义 NodeConfigshutdownGracePeriod: 30s、featureGates、模块生成的集群接入 NodeConfigcluster name / apiServerEndpoint / certificateAuthority / cidr、以及text/x-shellscript类型的收尾脚本echo All done。Bottlerocket 的合并语义重要提醒文档特别强调Bottlerocket 的用户数据是TOML 格式且系统会把你的 TOML 与 EKS 注入的值合并merge因此pre_bootstrap_user_data与post_bootstrap_user_data不适用Bottlerocket 自行决定各设置何时生效需要追加配置时请通过bootstrap_extra_args提供额外的 TOML 片段对AL2_*bootstrap_extra_args则会被透传给 AWS EKS Optimized AMI 的bootstrap.sh如 kubelet 额外参数等。三、Self Managed Node Group引导完全由你负责自管节点组没有 AWS 服务替你注入引导数据你必须提供能让节点入集群的用户数据。与托管节点组一样也有两条路路线 A使用模块内置模板AMI 为 EKS Optimized 衍生镜像时enable_bootstrap_user_data true pre_bootstrap_user_data ... bootstrap_extra_args ... post_bootstrap_user_data ...路线 B使用自供模板更细粒度控制user_data_template_path ./your/user_data.sh pre_bootstrap_user_data ... bootstrap_extra_args ... post_bootstrap_user_data ...从源码看自管节点组在调用_user_data模块时被强制要求引导见 modules/self-managed-node-group/main.tf#L59-L81其中enable_bootstrap_user_data true被硬编码传入同时is_eks_managed_node_group false。这也解释了为何自管节点组场景下模块渲染出的脚本中会包含完整的bootstrap.sh调用见下节渲染示例。四、四种 AMI 类型的默认模板与渲染产物模块内置模板统一放在 templates 目录由 main.tf#L21-L47 的映射表按ami_type选择AMI 家族AMI 类型示例模板文件用户数据格式AL2AL2_x86_64、AL2_ARM_64、AL2_x86_64_GPUtemplates/al2_user_data.tplbash/shell 脚本AL2023AL2023_x86_64_STANDARD、AL2023_ARM_64_STANDARD、AL2023_x86_64_NEURON、AL2023_x86_64_NVIDIA、AL2023_ARM_64_NVIDIAtemplates/al2023_user_data.tplMIME multipart内含 NodeConfig YAMLBottlerocketBOTTLEROCKET_x86_64、BOTTLEROCKET_ARM_64、BOTTLEROCKET_x86_64_FIPS、BOTTLEROCKET_ARM_64_NVIDIA等templates/bottlerocket_user_data.tplTOMLWindowsWINDOWS_CORE_2019_x86_64、WINDOWS_FULL_2022_x86_64、WINDOWS_CORE_2025_x86_64等templates/windows_user_data.tplPowerShell / PS1powershell标签包裹AL2 模板templates/al2_user_data.tpl 的核心逻辑#!/bin/bash set -e ${pre_bootstrap_user_data} B64_CLUSTER_CA${cluster_auth_base64} API_SERVER_URL${cluster_endpoint} /etc/eks/bootstrap.sh ${cluster_name} ${bootstrap_extra_args} --b64-cluster-ca $B64_CLUSTER_CA --apiserver-endpoint $API_SERVER_URL \ --ip-family ${cluster_ip_family} --service-${cluster_ip_family}-cidr ${cluster_service_cidr} ${post_bootstrap_user_data}注意--service-${cluster_ip_family}-cidr会根据cluster_ip_family自动展开为--service-ipv4-cidr或--service-ipv6-cidr。对应的真实渲染产物可见 tests/user-data/rendered/al2/self-mng-bootstrap.sh自管 AL2 引导场景与 tests/user-data/rendered/al2/eks-mng-custom-ami-ipv6.shIPv6 双栈场景。AL2023 模板templates/al2023_user_data.tpl 生成的是 nodeadm 的 NodeConfig--- apiVersion: node.eks.aws/v1alpha1 kind: NodeConfig spec: cluster: name: ${cluster_name} apiServerEndpoint: ${cluster_endpoint} certificateAuthority: ${cluster_auth_base64} cidr: ${cluster_service_cidr}Bottlerocket 模板templates/bottlerocket_user_data.tpl[settings.kubernetes] cluster-name ${cluster_name} api-server ${cluster_endpoint} cluster-certificate ${cluster_auth_base64} cluster-dns-ip ${cluster_dns_ips} ${bootstrap_extra_args}其中cluster_dns_ips由 main.tf#L50 计算默认取cluster_service_cidr的第 10 个地址cidrhost(cidr, 10)即常见*.0.0.10的 CoreDNS IP再拼接additional_cluster_dns_ips列表。测试 tests/user-data/rendered/bottlerocket/self-mng-bootstrap.toml 显示渲染结果为cluster-dns-ip [192.168.0.10]后面跟着bootstrap_extra_args注入的[settings.kernel] lockdown integrity片段。Windows 模板templates/windows_user_data.tpl 以powershell标签包裹调用 EKS 自带的Start-EKSBootstrap.ps1[string]$EKSBinDir $env:ProgramFiles\Amazon\EKS [string]$EKSBootstrapScriptName Start-EKSBootstrap.ps1 [string]$EKSBootstrapScriptFile $EKSBinDir\$EKSBootstrapScriptName $EKSBootstrapScriptFile -EKSClusterName ${cluster_name} -APIServerEndpoint ${cluster_endpoint} -Base64ClusterCA ${cluster_auth_base64} ${bootstrap_extra_args} 31 41 51 61 $LastError if ($?) { 0 } else { $Error[0].Exception.HResult } ${post_bootstrap_user_data}真实渲染产物见 tests/user-data/rendered/windows/eks-mng-custom-ami.ps1pre_bootstrap_user_data出现在powershell标签之后、引导脚本调用之前post_bootstrap_user_data追加在引导调用之后、/powershell之前。五、逻辑流程图模块如何决策文档提供了一个逻辑示意图user_data.svg概括_user_data模块的决策流。综合源码 modules/_user_data/main.tf#L16-L137 与 variables.tf决策要点如下是否渲染create false时输出空字符串如测试中的eks_mng_al2_disabled选择模板user_data_template_path优先为空则按ami_type从映射表取内置模板AL2 托管节点组非自定义 AMIpre_bootstrap_user_data以 MIME part 前置交给 AWS 服务合并AL2023cloudinit_pre_nodeadm可选模块渲染的 NodeConfig cloudinit_post_nodeadm组装为 MIME multipartBottlerocket模板渲染 bootstrap_extra_argsTOML 追加与 EKS 注入值合并Windows / AL2 自定义 AMI模板按enable_bootstrap_user_data条件渲染pre_/post_内容分别置于引导命令前后。六、通过测试验证理解tests/user-data 实操指南测试用例目录 tests/user-data 是官方用于验证_user_data子模块的完整工作台覆盖了四大 AMI 家族 × 托管/自管 × no-op / additional / custom-ami / custom-template 的矩阵组合例如eks_mng_al2_no_op什么都不做仅满足cluster_service_cidr硬性要求eks_mng_al2_additional仅前置一段 shellexport USE_MAX_PODSfalseeks_mng_al2_custom_ami自定义 AMI 内置模板 三段式注入eks_mng_al2_custom_ami_ipv6IPv6 双栈自定义 AMIeks_mng_al2_custom_template自定义 AMI 自供模板tests/user-data/templates/linux_custom.tpleks_mng_al2023_additionalAL2023 仅提供cloudinit_pre_nodeadm片段eks_mng_bottlerocket_additionalBottlerocket 通过bootstrap_extra_args追加 TOMLeks_mng_windows_custom_amiWindows 自定义 AMI 完整引导self_mng_*全部自管场景。运行方式tests/user-data/README.md#L9-L13terraform init terraform plan terraform apply --auto-approve测试通过local_file资源把渲染结果落盘到 tests/user-data/rendered 目录如al2/、al2023/、bottlerocket/、windows/四个子目录便于直接比对不同配置下的最终用户数据差异——这是理解本模块行为最直观的教材。七、与 compute_resources 文档的衔接真实节点组配置示例在真实节点组配置中上述变量通过 docs/compute_resources.md 中的场景落地。例如自定义 AMI 的托管节点组AL2023 nodeadm 体系eks_managed_node_groups { custom_ami { ami_id ami-0caf35bc73450c396 ami_type AL2023_x86_64_STANDARD # 自定义 AMI 时默认不注入引导脚本开启后使用模块内置模板补回引导 enable_bootstrap_user_data true cloudinit_pre_nodeadm [{ content -EOT --- apiVersion: node.eks.aws/v1alpha1 kind: NodeConfig spec: kubelet: config: shutdownGracePeriod: 30s EOT content_type application/node.eks.aws }] cloudinit_post_nodeadm [{ content -EOT echo All done EOT content_type text/x-shellscript; charset\us-ascii\ }] } }Bottlerocket 自定义 AMI 的托管节点组eks_managed_node_groups { bottlerocket_custom_ami { ami_id ami-0ff61e0bcfc81dc94 ami_type BOTTLEROCKET_x86_64 enable_bootstrap_user_data true bootstrap_extra_args -EOT [settings.kernel] lockdown integrity [settings.kubernetes.node-labels] label1 foo label2 bar [settings.kubernetes.node-taints] dedicated experimental:PreferNoSchedule special true:NoSchedule EOT } }更多组合可参考 examples/eks-managed-node-group 与 examples/self-managed-node-group 示例目录。八、关键结论速查托管节点组未指定ami_idAWS 服务负责引导你只需pre_bootstrap_user_dataAL2/Bottlerocket/Windows或cloudinit_pre_nodeadmAL2023做前置注入。托管节点组指定ami_id引导责任转移到你身上——EKS Optimized 衍生 AMI 用enable_bootstrap_user_data true启用内置模板否则用user_data_template_path提供自研模板。自管节点组必须自行引导模块强制enable_bootstrap_user_data true内置模板/自研模板两条路均可。格式约束Bottlerocket 必须 TOML 且pre_/post_bootstrap_user_data不适用Windows 必须 PowerShell/PS1AL2023 必须走 nodeadm MIME multipartAL2 为 bash 脚本。硬性要求只要create truecluster_service_cidr必须显式提供。模板变量范围自供模板只能使用templatefile()注入的固定变量集额外变量需预先渲染。【免费下载链接】terraform-aws-eksTerraform module to create Amazon Elastic Kubernetes (EKS) resources 项目地址: https://gitcode.com/GitHub_Trending/te/terraform-aws-eks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考