📚 课程目录第1章 EKS集群创建与kubeconfig配置

1. EKS集群创建与kubeconfig配置

创建前的关键决策与准备

EKS 集群创建的核心不是“点一下按钮”，而是先确定三组参数：集群身份（名称、Region、Kubernetes 版本）、网络位置（VPC 与子网）、访问入口（API Server 端点与认证方式）。使用 eksctl 时，这些参数集中在一个 ClusterConfig YAML 中；使用 AWS CLI 时，则需要按顺序创建集群 IAM 角色、VPC 资源、集群本体，再手动配置 kubeconfig。

下面给出一个可直接使用的 eksctl 最小集群配置。它不创建托管节点组，只创建控制平面，便于先验证 kubeconfig 与 kubectl 连通性；节点组留到后续案例处理。

# cluster-basic.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: demo-eks
  region: ap-southeast-1
  version: "1.29"

iam:
  withOIDC: true

vpc:
  cidr: 10.42.0.0/16
  nat:
    gateway: Single

managedNodeGroups: []   # 本案例先不创建节点组

执行创建命令：

eksctl create cluster -f cluster-basic.yaml

创建过程通常需要 12–18 分钟。eksctl 会自动完成：创建集群 IAM 角色、创建 VPC/子网/路由/NAT、调用 EKS CreateCluster、等待 ACTIVE、写入 kubeconfig。完成后可用以下命令确认上下文已写入：

kubectl config get-contexts
kubectl config current-context

若使用 AWS CLI，则需先准备集群角色信任策略，再创建集群，最后手动更新 kubeconfig：

aws eks update-kubeconfig \
  --region ap-southeast-1 \
  --name demo-eks \
  --alias demo-eks

kubeconfig 的生成位置与认证链路

EKS 的 kubeconfig 不是静态证书文件，而是一段“调用 AWS CLI 换取临时 token”的配置。其 users 段通常包含 exec 插件：aws eks get-token --cluster-name demo-eks --region ap-southeast-1。kubectl 每次请求 API Server 时，都会执行该命令获取短期 bearer token，再由 EKS 的 aws-iam-authenticator 映射到 Kubernetes 用户/组。

因此，kubeconfig 能否工作取决于三件事同时成立：本地 AWS 凭证有效、IAM 身份被 EKS 认证映射、API Server 端点网络可达。下图展示这条认证与访问链路，以及常见断点位置。

验证 kubectl 连通性

集群创建完成后，按以下顺序验证，每一步都能定位不同层面的问题：

kubectl config current-context：确认当前上下文指向 demo-eks，若不对则用 kubectl config use-context demo-eks 切换。
kubectl cluster-info：确认 API Server 地址可访问，返回 Kubernetes control plane 的 URL。
kubectl get nodes：本案例未创建节点组，预期返回 No resources found，这恰好证明认证与授权已通过，只是没有节点。
kubectl auth can-i get pods：返回 yes 表示当前 IAM 身份已映射到有权限的 Kubernetes 用户。

若 kubectl get nodes 返回 error: You must be logged in to the server (Unauthorized)，说明 token 已获取但 IAM 身份未被 EKS 认证映射。此时应检查创建集群的 IAM 身份是否与当前凭证一致，或是否被显式加入 aws-auth ConfigMap。

常见失败点与判断依据

现象	可能原因	判断命令
Unable to connect to the server	API Server 端点不可达或 kubeconfig 未写入	`kubectl config view --minify`
Unauthorized	IAM 身份未映射到 K8s 用户	`aws sts get-caller-identity`
Forbidden	已认证但 RBAC 无权限	`kubectl auth can-i --list`
exec plugin 报错	AWS CLI 未安装或凭证过期	`aws eks get-token --cluster-name demo-eks --region ap-southeast-1`

清理与后续衔接

验证完成后，若不再需要该集群，可执行 eksctl delete cluster -f cluster-basic.yaml 删除全部关联资源。若继续后续案例，保留集群即可，下一步是在该集群中创建托管节点组，使 kubectl get nodes 能返回真实节点。