使用启动模板自定义托管节点 - Amazon EKS
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

使用启动模板自定义托管节点

要获得最高级别的自定义,您可以使用自己的启动模板部署托管节点。使用启动模板可以实现以下功能:

  • 在部署节点时提供引导参数,例如额外的 kubelet 参数。

  • 从与分配给节点的 IP 地址不同的 CIDR 块为 Pods 分配 IP 地址。

  • 将您自己的自定义 AMI 部署到节点。

  • 将您自己的自定义 CNI 部署到节点。

如果您在首次创建托管节点组时提供自己的启动模板,则以后也将具有更大的灵活性。只要使用自己的启动模板部署托管节点组,您就可以使用同一启动模板的不同版本对其进行迭代更新。将节点组更新为启动模板的其他版本时,将回收组中的所有节点,以匹配指定启动模板版本的新配置。

托管节点组始终部署用于 Amazon EC2 Auto Scaling 组的启动模板。当您不提供启动模板时,Amazon EKS API 会在您的账户中自动创建一个具有默认值的模板。但是,我们建议不要修改自动生成的启动模板。而且,无法直接更新不使用自定义启动模板的现有节点组。相反,您必须使用自定义启动模板创建新的节点组才能执行此操作。

启动模板配置基础知识

您可以使用 Amazon Web Services Management Console、Amazon CLI 或Amazon开发工具包创建 Amazon EC2 Auto Scaling 启动模板。有关更多信息,请参阅《Amazon EC2 Auto Scaling 用户指南》中的为自动扩缩组创建启动模板。启动模板中的某些设置类似于用于托管节点配置的设置。使用启动模板部署或更新节点组时,必须在节点组配置或启动模板中指定某些设置。不要在两个位置都指定一个设置。如果某个设置出现在错误的位置,则创建或更新节点组之类的操作将失败。

下表列出启动模板中禁止的设置,它还列出托管节点组配置中所需的类似设置(如果有)。列出的设置是显示在控制台中的设置。它们在 Amazon CLI 和开发工具包中可能具有相似但不同的名称。

启动模板 - 已禁止 Amazon EKS 节点组配置
Network interfaces(网络接口)Add network interface(添加网络接口))下的Subnet(子网) Specify networking(指定联网)页面上 Node group network configuration(节点组网络配置)下的 Subnets(子网)
Advanced details(高级详细信息)下的 IAM instance profile(IAM 实例配置文件) Configure Node group(配置节点组)页面上 Node group configuration(节点组配置)下的 Node IAM role(节点 IAM 角色)
Advanced details(高级详细信息)下的 Shutdown behavior(关机行为)Stop - Hibernate behavior(停止 - 休眠行为)。在启动模板中,对于两个设置都保留默认的不包含在启动模板设置中 无等效项 Amazon EKS 必须控制实例生命周期,而不是 Auto Scaling 组。

下表列出托管节点组配置中禁止的设置,还列出启动模板中所需的类似设置(如果有)。列出的设置是显示在控制台中的设置。它们在 Amazon CLI 和开发工具包中可能有类似的名称。

Amazon EKS 节点组配置 – 已禁止 启动模板

(仅当您在启动模板中指定了自定义 AMI 时)Set compute and scaling configuration(设置计算和扩缩配置)页面上 Node group compute configuration(节点组计算配置)下的 AMI type(AMI 类型)– 控制台显示 Specified in launch template(已在启动模板中指定)和指定的 AMI ID。

如果未在启动模板中指定 Application and OS Images (Amazon Machine Image)(应用程序和操作系统映像(Amazon 机器映像)),则可以在节点组配置中选择 AMI。

Launch template contents(启动模板内容)下的 Application and OS Images (Amazon Machine Image)(应用程序和操作系统映像(Amazon 机器映像))– 如果您有以下任一要求,则必须指定 ID:

Set compute and scaling configuration(设置计算和扩展配置)页面上 Node group compute configuration(节点组计算配置)下的 Disk size(磁盘大小)– 控制台显示 Specified in launch template(已在启动模板中指定)。 Storage (Volumes)(存储(卷))Add new volume(添加新卷))下的 Size(大小)。您必须在启动模板中指定此项。
Specify Networking(指定网络)页面上 Node group configuration(节点组配置)下的 SSH key pair(SSH 密钥对)– 控制台显示在启动模板中指定的密钥或显示 Not specified in launch template(未在启动模板中指定)。 Key pair (login)(密钥对(登录))下的 Key pair name(密钥对名称
在使用启动模板时,您无法指定允许远程访问的源安全组。 实例的 Network settings(网络设置)下的 Security groups(安全组),或者 Network interfaces(网络接口)Add network interface(添加网络接口))下的 Security groups(安全组),但不能同时兼具。有关更多信息,请参阅 使用自定义安全组
注意
  • 如果使用启动模板部署节点组,请在启动模板的 Launch template contents(启动模板内容)下指定 0 或 1 个 Instance type(实例类型)。您也可以为控制台 Set compute and scaling configuration(设置计算和扩缩配置)页面的 Instance types(实例类型)指定 0-20 个实例类型。或者,您可以使用其他使用 Amazon EKS API 的工具来执行此操作。如果您在启动模板中指定实例类型,并使用该启动模板部署节点组,则无法在控制台中或通过使用 Amazon EKS API 的其他工具指定任何实例类型。如果没有在启动模板、控制台中或通过使用 Amazon EKS API 的其他工具指定实例类型,则使用 t3.medium 实例类型。如果您的节点组使用 Spot 容量类型,我们建议您使用控制台指定多个实例类型。有关更多信息,请参阅 托管节点组容量类型

  • 如果部署到节点组的任何容器使用实例元数据服务版本 2,请确保在启动模板中将Metadata response hop limit(元数据响应跃点限制)设置为 2。有关更多信息,请参阅 Amazon EC2 用户指南(适用于 Linux 实例)中的实例元数据和用户数据。如果在不使用自定义启动模板的情况下部署托管节点组,则会在默认启动模板中为节点组自动设置此值。

为 Amazon EC2 实例添加标签

您可以使用启动模板的 TagSpecification 参数来指定将哪些标签应用于节点组中的 Amazon EC2 实例。调用 CreateNodegroupUpdateNodegroupVersion API 的 IAM 实体必须具有 ec2:RunInstancesec2:CreateTags 的权限,并且必须将标签添加到启动模板中。

使用自定义安全组

您可以使用启动模板指定自定义 Amazon EC2 安全组以应用到节点组中的实例。这可以在实例级安全组参数中,也可以作为网络接口配置参数的一部分。但是,您无法创建同时指定实例级安全组和网络接口安全组的启动模板。请考虑以下适用于为托管节点组使用自定义安全组的条件:

  • Amazon EKS 仅允许使用包含单个网络接口规范的启动模板。

  • 预设情况下,Amazon EKS 将集群安全组应用于节点组中的实例,以便于节点和控制层面之间的通信。如果您使用前面提到的任一选项在启动模板中指定自定义安全组,则 Amazon EKS 不会添加集群安全组。因此,您必须确保安全组的入站和出站规则启用了与集群端点的通信。如果您的安全组规则不正确,则 worker 节点无法加入集群。有关安全组规则的更多信息,请参阅 Amazon EKS 安全组要求和注意事项

  • 如果需要对节点组中的实例进行 SSH 访问,请确保包含允许该访问的安全组。

Amazon EC2 用户数据

启动模板包括自定义用户数据的部分。您可以在此部分为节点组指定配置设置,而无需手动创建单个自定义 AMI。有关 Bottlerocket 可用设置的更多信息,请参阅 GitHub 上的使用用户数据

在启动实例时,您可以使用 cloud-init 在启动模板中提供 Amazon EC2 用户数据。有关更多信息,请参阅 cloud-init 文档。您的用户数据可用于执行常见配置操作。其中包括以下操作:

启动模板中用于托管节点组的 Amazon EC2 用户数据必须采用 MIME 分段归档格式(用于 Amazon Linux AMI)和 TOML 格式(用于 Bottlerocket AMI)。这是因为您的用户数据与节点加入集群所需的 Amazon EKS 用户数据合并。不要在用户数据中指定任何启动或修改 kubelet 的命令。这是作为 Amazon EKS 合并的用户数据的一部分执行的。某些 kubelet 参数(例如节点上的设置标签)可以直接通过托管节点组 API 进行配置。

注意

如果需要高级 kubelet 自定义,包括手动启动或传入自定义配置参数,请参阅 指定 AMI。如果在启动模板中指定自定义 AMI ID,Amazon EKS 不会合并用户数据。

以下详细信息提供有关用户数据部分的更多信息。

Amazon Linux 2 user data

您可以将多个用户数据块合并到一个 MIME 分段文件中。例如,您可以将配置 Docker 进程守护程序的云 Boothook 与安装自定义软件包的用户数据 Shell 脚本合并。MIME 分段文件包含以下组成部分:

  • 内容类型和段边界声明 - Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="

  • MIME 版本声明 - MIME-Version: 1.0

  • 一个或多个用户数据块,其包含以下组成部分:

    • 开口边界,表示用户数据块的开头 - --==MYBOUNDARY==

    • 数据块的内容类型声明:Content-Type: text/cloud-config; charset="us-ascii"。有关内容类型的更多信息,请参阅 cloud-init 文档。

    • 用户数据的内容(例如 Shell 命令或 cloud-init 指令的列表)。

    • 封闭边界,表示 MIME 分段文件的结尾:--==MYBOUNDARY==--

    以下是 MIME 分段文件的示例,您可以用它来创建您自己的文件。

    MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="==MYBOUNDARY==" --==MYBOUNDARY== Content-Type: text/x-shellscript; charset="us-ascii" #!/bin/bash echo "Running custom user data script" --==MYBOUNDARY==--
Amazon Linux 2023 user data

Amazon Linux 2023(AL2023)引入了使用 YAML 配置架构的新节点初始化流程 nodeadm。如果您使用的是自行管理的节点组或带有启动模板的 AMI,则在创建新节点组时,现在需要明确提供其他集群元数据。以下是最低必需参数的示例,其中 apiServerEndpointcertificateAuthority 和服务 cidr 是必需的:

--- apiVersion: node.eks.aws/v1alpha1 kind: NodeConfig spec: cluster: name: my-cluster apiServerEndpoint: https://example.com certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk= cidr: 10.100.0.0/16

通常,您将在用户数据中设置此配置,无论是按原样设置还是嵌入 MIME 多部分文档中:

MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="BOUNDARY" --BOUNDARY Content-Type: application/node.eks.aws --- apiVersion: node.eks.aws/v1alpha1 kind: NodeConfig spec: [...] --BOUNDARY--

在 AL2 中,来自这些参数的元数据是从 Amazon EKS DescribeCluster API 调用中发现的。使用 AL2023,这种行为发生了变化,因为在大型节点纵向扩展期间,额外的 API 调用有节流风险。如果您使用的是没有启动模板的托管节点组或者正在使用 Karpenter,则此更改不会影响您。有关 certificateAuthority 和服务 cidr 的更多信息,请参阅《Amazon EKS API 参考》中的 DescribeCluster

Bottlerocket user data

Bottlerocket 采用 TOML 格式构建用户数据。您可以提供要与 Amazon EKS 提供的用户数据合并的用户数据。例如,您可以提供额外的 kubelet 设置。

[settings.kubernetes.system-reserved] cpu = "10m" memory = "100Mi" ephemeral-storage= "1Gi"

有关支持设置的更多信息,请参阅 Bottlerocket 文档。您可以在用户数据中配置节点标签和污点。但是,我们建议在节点组中对其进行配置。在您这样做时,Amazon EKS 应用这些配置。

合并用户数据时,不保留格式,但内容保持不变。您在用户数据中提供的配置将覆盖 Amazon EKS 配置的任何设置。所以,如果设置 settings.kubernetes.max-podssettings.kubernetes.cluster-dns-ip,用户数据中的值将应用到节点。

Amazon EKS 不支持所有有效的 TOM。以下是已知不受支持的格式的列表:

  • 引用的键中的引号:'quoted "value"' = "value"

  • 值中的转义引号:str = "I'm a string. \"You can quote me\""

  • 混合浮点数和整数:numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]

  • 数组中的混合类型:contributors = ["foo@example.com", { name = "Baz", email = "baz@example.com" }]

  • 带引用键的括号标题:[foo."bar.baz"]

Windows user data

Windows 用户数据使用 PowerShell 命令。创建托管节点组时,您的自定义用户数据与 Amazon EKS 托管用户数据结合使用。您的 PowerShell 命令排在首位,然后是托管用户数据命令,所有这些命令都在一个 <powershell></powershell> 标签内。

注意

如果在启动模板中未指定 AMI ID,请勿在用户数据中使用 Windows Amazon EKS 引导脚本来配置 Amazon EKS。

用户数据示例如下所示。

<powershell> Write-Host "Running custom user data script" </powershell>

指定 AMI

如果您具有以下任一要求,请在启动模板的 ImageId 字段中指定一个 AMI ID。选择您对其他信息的要求。

Bootstrapping(引导启动)是一个术语,用于描述添加可以在实例启动时运行的命令。例如,引导允许使用额外的 kubelet 参数。您可以使用 eksctl 将参数传递给 bootstrap.sh 脚本,无需指定启动模板。或者,您可以在启动模板的用户数据部分中指定信息来实现此目标。

eksctl without specifying a launch template

使用以下内容创建名为 my-nodegroup.yaml 的文件。将每个 example value 替换为您自己的值。--apiserver-endpoint--b64-cluster-ca--dns-cluster-ip 参数是可选的。但是,定义它们可使 bootstrap.sh 脚本避免进行 describeCluster 调用。在私有集群设置或频繁扩展节点的集群中,这是非常有用的。有关 bootstrap.sh 脚本的更多信息,请参阅 GitHub 上的 bootstrap.sh 文件。

  • 唯一必需的参数是集群名称(my-cluster)。

  • 要检索 ami-1234567890abcdef0 的优化版 AMI ID,您可以使用以下各部分中的表格:

  • 要检索您的集群的 certificate-authority,请运行以下命令。

    aws eks describe-cluster --query "cluster.certificateAuthority.data" --output text --name my-cluster --region region-code
  • 要检索您的集群的 api-server-endpoint,请运行以下命令。

    aws eks describe-cluster --query "cluster.endpoint" --output text --name my-cluster --region region-code
  • --dns-cluster-ip 的值是您的服务 CIDR,末尾为 .10。要检索您的集群的 service-cidr,请运行以下命令。例如,如果返回值为 ipv4 10.100.0.0/16,则您的值为 10.100.0.10

    aws eks describe-cluster --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --output text --name my-cluster --region region-code
  • 此示例使用包含在 Amazon EKS 优化版 AMI 中的 bootstrap.sh 脚本提供一个 kubelet 参数来设置一个自定义 max-pods 值。节点组名称的长度不能超过 63 个字符。它必须以字母或数字开头,但也可以包括其余字符的连字符和下划线。有关选择 my-max-pods-value 的帮助,请参阅 Amazon EKS 建议每种 Amazon EC2 实例类型的最大 Pods 数量

--- apiVersion: eksctl.io/v1alpha5 kind: ClusterConfig metadata: name: my-cluster region: region-code managedNodeGroups: - name: my-nodegroup ami: ami-1234567890abcdef0 instanceType: m5.large privateNetworking: true disableIMDSv1: true labels: { x86-al2-specified-mng } overrideBootstrapCommand: | #!/bin/bash /etc/eks/bootstrap.sh my-cluster \ --b64-cluster-ca certificate-authority \ --apiserver-endpoint api-server-endpoint \ --dns-cluster-ip service-cidr.10 \ --kubelet-extra-args '--max-pods=my-max-pods-value' \ --use-max-pods false

对于每一个可用的 eksctl config 文件选项,请参阅 eksctl 文档中的配置文件架构eksctl 实用程序仍会为您创建启动模板,并使用您在 config 文件中提供的数据填充其用户数据。

使用以下命令创建节点组。

eksctl create nodegroup --config-file=my-nodegroup.yaml
User data in a launch template

在启动模板的用户数据部分指定以下信息。将每个 example value 替换为您自己的值。--apiserver-endpoint--b64-cluster-ca--dns-cluster-ip 参数是可选的。但是,定义它们可使 bootstrap.sh 脚本避免进行 describeCluster 调用。在私有集群设置或频繁扩展节点的集群中,这是非常有用的。有关 bootstrap.sh 脚本的更多信息,请参阅 GitHub 上的 bootstrap.sh 文件。

  • 唯一必需的参数是集群名称(my-cluster)。

  • 要检索您的集群的 certificate-authority,请运行以下命令。

    aws eks describe-cluster --query "cluster.certificateAuthority.data" --output text --name my-cluster --region region-code
  • 要检索您的集群的 api-server-endpoint,请运行以下命令。

    aws eks describe-cluster --query "cluster.endpoint" --output text --name my-cluster --region region-code
  • --dns-cluster-ip 的值是您的服务 CIDR,末尾为 .10。要检索您的集群的 service-cidr,请运行以下命令。例如,如果返回值为 ipv4 10.100.0.0/16,则您的值为 10.100.0.10

    aws eks describe-cluster --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --output text --name my-cluster --region region-code
  • 此示例使用包含在 Amazon EKS 优化版 AMI 中的 bootstrap.sh 脚本提供一个 kubelet 参数来设置一个自定义 max-pods 值。有关选择 my-max-pods-value 的帮助,请参阅 Amazon EKS 建议每种 Amazon EC2 实例类型的最大 Pods 数量

MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="==MYBOUNDARY==" --==MYBOUNDARY== Content-Type: text/x-shellscript; charset="us-ascii" #!/bin/bash set -ex /etc/eks/bootstrap.sh my-cluster \ --b64-cluster-ca certificate-authority \ --apiserver-endpoint api-server-endpoint \ --dns-cluster-ip service-cidr.10 \ --kubelet-extra-args '--max-pods=my-max-pods-value' \ --use-max-pods false --==MYBOUNDARY==--

Bootstrapping(引导启动)是一个术语,用于描述添加可以在实例启动时运行的命令。您可以使用 eksctl 将参数传递给 Start-EKSBootstrap.ps1 脚本,无需指定启动模板。或者,您可以在启动模板的用户数据部分中指定信息来实现此目标。

如果您想指定自定义 Windows AMI ID,请记住以下注意事项:

  • 您必须使用启动模板并在用户数据部分提供所需的引导命令。要检索所需的 Windows ID,您可以使用 Amazon EKS 优化版 Windows AMI 中的表。

  • 有一些限制和条件。例如,您必须将 eks:kube-proxy-windows 添加到您的 Amazon IAM 身份验证器配置映射中。有关更多信息,请参阅 指定 AMI ID 时的限制和条件

在启动模板的用户数据部分指定以下信息。将每个 example value 替换为您自己的值。-APIServerEndpoint-Base64ClusterCA-DNSClusterIP 参数是可选的。但是,定义它们可使 Start-EKSBootstrap.ps1 脚本避免进行 describeCluster 调用。

  • 唯一必需的参数是集群名称(my-cluster)。

  • 要检索您的集群的 certificate-authority,请运行以下命令。

    aws eks describe-cluster --query "cluster.certificateAuthority.data" --output text --name my-cluster --region region-code
  • 要检索您的集群的 api-server-endpoint,请运行以下命令。

    aws eks describe-cluster --query "cluster.endpoint" --output text --name my-cluster --region region-code
  • --dns-cluster-ip 的值是您的服务 CIDR,末尾为 .10。要检索您的集群的 service-cidr,请运行以下命令。例如,如果返回值为 ipv4 10.100.0.0/16,则您的值为 10.100.0.10

    aws eks describe-cluster --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --output text --name my-cluster --region region-code
  • 有关更多参数,请参阅 引导脚本配置参数

    注意

    如果您使用自定义服务 CIDR,则需要使用 -ServiceCIDR 参数进行指定。否则,集群 Pods 中的 DNS 解析将失败。

<powershell> [string]$EKSBootstrapScriptFile = "$env:ProgramFiles\Amazon\EKS\Start-EKSBootstrap.ps1" & $EKSBootstrapScriptFile -EKSClusterName my-cluster ` -Base64ClusterCA certificate-authority ` -APIServerEndpoint api-server-endpoint ` -DNSClusterIP service-cidr.10 </powershell>

有关更多信息,请参阅适用于 Linux 实例的 Amazon EC2 用户指南中的 Amazon Machine Images (AMI)。Amazon EKS AMI 构建规范包含用于构建基于 Amazon Linux 的自定义 Amazon EKS AMI 的资源和配置脚本。有关更多信息,请参阅 GitHub 上的 Amazon EKS AMI 构建规范。要构建与其他操作系统一起安装的自定义 AMI,请参阅 GitHub 上的 Amazon EKS 示例自定义 AMI

重要

指定 AMI 时,Amazon EKS 不会合并任何用户数据。实际上,您要负责提供节点加入集群所需的 bootstrap 命令。如果您的节点无法加入集群,那么 Amazon EKS CreateNodegroupUpdateNodegroupVersion 操作也会失败。

指定 AMI ID 时的限制和条件

使用托管节点组指定 AMI ID 所涉及的限制和条件如下:

  • 您必须创建一个新的节点组,以便在在启动模板中指定 AMI ID 和不指定 AMI ID 之间进行切换。

  • 当有较新的 AMI 版本可用时,控制台中不会通知您。要将节点组更新为更新的 AMI 版本,需要使用更新的 AMI ID 创建新版本的启动模板。然后需要使用新的启动模板版本更新节点组。

  • 如果您指定 AMI ID,则无法在 API 中设置以下字段:

    • amiType

    • releaseVersion

    • version

  • 如果您指定 AMI ID,则会异步应用 API 中的任何 taints 设置。要在节点加入集群之前应用污点,必须使用 --register-with-taints 命令行标志将污点传递到用户数据中的 kubelet。有关更多信息,请参阅 Kubernetes文档中的 kubelet

  • 为 Windows 托管节点组指定自定义 AMI ID 时,请将 eks:kube-proxy-windows 添加到您的 Amazon IAM 身份验证器配置映射中。需要执行此操作 DNS 才能正常运行。

    1. 打开 Amazon IAM 身份验证器配置映射进行编辑。

      kubectl edit -n kube-system cm aws-auth
    2. 将此条目添加到每个与 Windows 节点关联的 rolearn 下的 groups 列表中。您的配置映射应类似于 aws-auth-cm-windows.yaml

      - eks:kube-proxy-windows
    3. 保存文件并退出文本编辑器。