eksctl创建自管理节点时CONFIG_MAP认证模式的问题分析

在AWS EKS集群管理工具eksctl的使用过程中，当尝试创建自管理节点组(self-managed node)并将认证模式(authenticationMode)设置为仅CONFIG_MAP时，可能会遇到节点组创建失败的问题。本文将深入分析这一问题的成因、影响范围以及解决方案。

问题现象

当用户使用eksctl创建EKS集群并指定authenticationMode为CONFIG_MAP时，如果节点组配置中没有显式指定IAM角色ARN，节点组的CloudFormation堆栈会尝试创建Access Entry，但由于集群认证模式限制，操作会失败并返回错误信息："The cluster's authentication mode must be set to one of [API, API_AND_CONFIG_MAP] to perform this operation."

问题根源

该问题源于eksctl 0.166.0版本之后的一个变更。在此版本中，当节点组未显式指定IAM角色时，eksctl会自动将NodeGroupUsesAccessEntry标志设置为true。这一设计假设集群支持Access Entry功能，但在以下两种情况下会导致问题：

1. 集群认证模式被显式设置为仅CONFIG_MAP
2. 在AWS Outposts等特殊环境中，Access Entry功能尚未被支持

影响版本

该问题影响eksctl 0.166.0及之后的版本，包括最新的0.175.0版本。0.166.0之前的版本不受此问题影响。

解决方案

目前有三种可行的解决方案：

方案一：分步创建集群和节点组

首先创建集群，然后在创建节点组时添加--update-auth-configmap参数：

eksctl create cluster -f cluster.yaml
eksctl create nodegroup -f cluster.yaml --update-auth-configmap

方案二：显式指定节点IAM角色

在节点组配置中明确指定预先创建的IAM角色ARN：

nodeGroups:
  - name: ng-1
    instanceType: m5.large
    iam:
      instanceRoleARN: "arn:aws:iam::XXXXXXXX:role/AmazonEKSNodeRole"

方案三：回退到旧版本

使用eksctl 0.166.0之前的版本可以避免此问题，但不推荐作为长期解决方案。

技术背景

在EKS中，节点与集群的认证方式有三种配置：

1. CONFIG_MAP：传统的基于aws-auth ConfigMap的认证方式
2. API：基于Access Entry的新认证方式
3. API_AND_CONFIG_MAP：混合模式

当集群被配置为仅使用CONFIG_MAP认证时，任何尝试创建Access Entry的操作都会失败。eksctl的最新版本默认尝试使用更现代的Access Entry方式，但没有充分考虑所有使用场景的兼容性。

最佳实践建议

对于需要使用CONFIG_MAP认证模式的场景，建议：

1. 始终在节点组配置中显式指定IAM角色
2. 如果使用动态角色创建，确保使用--update-auth-configmap参数
3. 关注eksctl的更新，官方将在后续版本中修复此问题

对于AWS Outposts用户，由于平台限制，目前必须使用CONFIG_MAP认证模式，因此需要特别注意此问题。