使用启动模板自定义托管式节点
要获得最高级别的自定义,您可以使用自己的启动模板部署托管节点。使用启动模板可以实现以下功能:
-
在部署节点时提供引导参数,例如额外的 kubelet
实际参数。 -
从与分配给节点的 IP 地址不同的 CIDR 块为 Pods 分配 IP 地址。
-
将您自己的自定义 AMI 部署到节点。
-
将您自己的自定义 CNI 部署到节点。
如果您在首次创建托管节点组时提供自己的启动模板,则以后也将具有更大的灵活性。只要使用自己的启动模板部署托管节点组,您就可以使用同一启动模板的不同版本对其进行迭代更新。将节点组更新为启动模板的其他版本时,将回收组中的所有节点,以匹配指定启动模板版本的新配置。
托管节点组始终部署用于 Amazon EC2 Auto Scaling 组的启动模板。当您不提供启动模板时,Amazon EKS API 会在您的账户中自动创建一个具有默认值的模板。但是,我们建议不要修改自动生成的启动模板。而且,无法直接更新不使用自定义启动模板的现有节点组。相反,您必须使用自定义启动模板创建新的节点组才能执行此操作。
启动模板配置基础知识
您可以使用 AWS Management Console、AWS CLI 或 AWS SDK 创建 Amazon EC2 Auto Scaling 启动模板。有关更多信息,请参阅《Amazon EC2 Auto Scaling 用户指南》中的为自动扩缩组创建启动模板。启动模板中的某些设置类似于用于托管节点配置的设置。使用启动模板部署或更新节点组时,必须在节点组配置或启动模板中指定某些设置。不要在两个位置都指定一个设置。如果某个设置出现在错误的位置,则创建或更新节点组之类的操作将失败。
下表列出启动模板中禁止的设置,它还列出托管节点组配置中所需的类似设置(如果有)。列出的设置是显示在控制台中的设置。它们在 AWS CLI 和 SDK 中可能具有相似但不同的名称。
启动模板 - 已禁止 | 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 组。 |
下表列出托管节点组配置中禁止的设置,还列出启动模板中所需的类似设置(如果有)。列出的设置是显示在控制台中的设置。它们在 AWS CLI 和 SDK 中可能有类似的名称。
Amazon EKS 节点组配置 – 已禁止 | 启动模板 |
---|---|
(仅当您在启动模板中指定了自定义 AMI 时)Set compute and scaling configuration(设置计算和扩缩配置)页面上 Node group compute configuration(节点组计算配置)下的 AMI type(AMI 类型)– 控制台显示 Specified in launch template(已在启动模板中指定)和指定的 AMI ID。 如果未在启动模板中指定应用程序和操作系统映像(Amazon 机器映像),则可以在节点组配置中选择 AMI。 |
Launch template contents(启动模板内容)下的 Application and OS Images (Amazon Machine Image)(应用程序和操作系统映像(Amazon 机器映像))– 如果您有以下任一要求,则必须指定 ID: * 使用自定义 AMI。如果您指定的 AMI 不满足 指定 AMI指定 AMI 中列出的要求,节点组部署将失败。* 需要提供用户数据以将实际参数传递给随 Amazon EKS 优化版 AMI 一起提供的 |
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 用户指南》中的实例元数据和用户数据。如果在不使用自定义启动模板的情况下部署托管节点组,则会在默认启动模板中为节点组自动设置此值。
为 Amazon EC2 实例添加标签
您可以使用启动模板的 TagSpecification
参数来指定将哪些标签应用于节点组中的 Amazon EC2 实例。调用 CreateNodegroup
或 UpdateNodegroupVersion
API 的 IAM 实体必须具有 ec2:RunInstances
和 ec2:CreateTags
的权限,并且必须将标签添加到启动模板中。
使用自定义安全组
您可以使用启动模板指定自定义 Amazon EC2 安全组以应用到节点组中的实例。这可以在实例级安全组参数中,也可以作为网络接口配置参数的一部分。但是,您无法创建同时指定实例级安全组和网络接口安全组的启动模板。请考虑以下适用于为托管节点组使用自定义安全组的条件:
-
使用 AWS Management Console时,Amazon EKS 仅允许使用具有单个网络接口规范的启动模板。
-
默认情况下,Amazon EKS 将查看集群的 Amazon EKS 安全组要求集群安全组应用于节点组中的实例,以便于节点和控制面板之间的通信。如果您使用前面提到的任一选项在启动模板中指定自定义安全组,则 Amazon EKS 不会添加集群安全组。因此,您必须确保安全组的入站和出站规则启用了与集群端点的通信。如果您的安全组规则不正确,则 worker 节点无法加入集群。有关安全组规则的更多信息,请参阅 查看集群的 Amazon EKS 安全组要求。
-
如果需要对节点组中的实例进行 SSH 访问,请确保包含允许该访问的安全组。
Amazon EC2 用户数据
启动模板包括自定义用户数据的部分。您可以在此部分为节点组指定配置设置,而无需手动创建单个自定义 AMI。有关 Bottlerocket 可用设置的更多信息,请参阅 GitHub 上的使用用户数据
在启动实例时,您可以使用 cloud-init
在启动模板中提供 Amazon EC2 用户数据。有关更多信息,请参阅 cloud-init 文档
启动模板中用于托管节点组的 Amazon EC2 用户数据必须采用 MIME 分段归档kubelet
的命令。这是作为 Amazon EKS 合并的用户数据的一部分执行的。某些 kubelet
参数(例如节点上的设置标签)可以直接通过托管节点组 API 进行配置。
注意
如果需要高级 kubelet
自定义,包括手动启动或传入自定义配置参数,请参阅 指定 AMI。如果在启动模板中指定自定义 AMI ID,Amazon EKS 不会合并用户数据。
以下详细信息提供有关用户数据部分的更多信息。
- Amazon Linux 2 用户数据
-
您可以将多个用户数据块合并到一个 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 用户数据
-
Amazon Linux 2023(AL2023)引入了使用 YAML 配置架构的新节点初始化流程
nodeadm
。如果您使用的是自行管理的节点组或带有启动模板的 AMI,则在创建新节点组时,现在需要明确提供其它集群元数据。以下是最低必需参数的示例,其中 apiServerEndpoint
、certificateAuthority
和服务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 用户数据
-
Bottlerocket 采用 TOML 格式构建用户数据。您可以提供要与 Amazon EKS 提供的用户数据合并的用户数据。例如,您可以提供额外的
kubelet
设置。[settings.kubernetes.system-reserved] cpu = "10m" memory = "100Mi" ephemeral-storage= "1Gi"
有关支持设置的更多信息,请参阅 GitHub 上的 Bottlerocket 文档
。您可以在用户数据中配置节点标签和防止在特定节点上调度 Pods污点。但是,我们建议在节点组中对其进行配置。在您这样做时,Amazon EKS 应用这些配置。 合并用户数据时,不保留格式,但内容保持不变。您在用户数据中提供的配置将覆盖 Amazon EKS 配置的任何设置。所以,如果设置
settings.kubernetes.max-pods
或settings.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 用户数据
-
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(引导启动)是一个术语,用于描述添加可以在实例启动时运行的命令。例如,引导允许使用额外的 kubeleteksctl
将参数传递给 bootstrap.sh
脚本,无需指定启动模板。或者,您可以在启动模板的用户数据部分中指定信息来实现此目标。
- eksctl 无需指定启动模板
-
创建一个名为
my-nodegroup.yaml
的文件,其中包含以下内容。将所有example value
替换为您自己的值。--apiserver-endpoint
、--b64-cluster-ca
和--dns-cluster-ip
参数是可选的。但是,定义它们可使bootstrap.sh
脚本避免进行describeCluster
调用。在私有集群设置或频繁扩展节点的集群中,这是非常有用的。有关bootstrap.sh
脚本的更多信息,请参阅 GitHub 上的 bootstrap.sh文件。 -
唯一必需的参数是集群名称(
my-cluster
)。 -
检索
ami-
的优化版 AMI ID1234567890abcdef0
, you can use the tables in the following sections:-
检索建议的 Amazon Linux AMI ID检索建议的 Amazon Linux AMI ID
-
检索建议的 Bottlerocket AMI ID检索建议的 Bottlerocket AMI ID
-
检索建议的 Microsoft Windows AMI ID检索建议的 Microsoft Windows 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
-
- 启动模板中的用户数据
-
在启动模板的用户数据部分指定以下信息。将所有
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,您可以使用使用优化型 Windows AMI 创建节点使用优化版 Windows AMI 创建节点中的表。
-
有一些限制和条件。例如,您必须将
eks:kube-proxy-windows
添加到您的 AWS 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>
有关更多信息,请参阅《Amazon EC2 用户指南》中的亚马逊机器映像(AMI)。Amazon EKS AMI 构建规范包含用于构建基于 Amazon Linux 的自定义 Amazon EKS AMI 的资源和配置脚本。有关更多信息,请参阅 GitHub 上的 Amazon EKS AMI 构建规范
重要
指定 AMI 时,Amazon EKS 不会合并任何用户数据。实际上,您要负责提供节点加入集群所需的 bootstrap
命令。如果您的节点无法加入集群,那么 Amazon EKS CreateNodegroup
和 UpdateNodegroupVersion
操作也会失败。
指定 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
添加到您的 AWS IAM 身份验证器配置映射中。需要执行此操作 DNS 才能正常运行。-
打开 AWS IAM 身份验证器配置映射进行编辑。
kubectl edit -n kube-system cm aws-auth
-
将此条目添加到每个与 Windows 节点关联的
rolearn
下的groups
列表中。您的配置图应该看起来像 aws-auth-cm-windows.yaml。 - eks:kube-proxy-windows
-
保存文件并退出文本编辑器。
-