如何解决在 Amazon EKS 中挂载 EBS 卷时出现的问题？

解决方法

在开始故障排除之前，验证是否已满足以下先决条件：

• 您的 ebs-csi-controller-sa 服务账户 IAM 角色所需的 AWS Identity and Access Management（IAM）权限。
  注意：要对您的服务账户问题进行故障排除，请参阅检查 Amazon EBS CSI 驱动程序控制器服务账户的 IAM 角色和该角色的权限部分。
• 与容器组相同的命名空间中的有效 PersistentVolumeClaim（PVC）（来自 GitHub 网站）。
• 使用内置的预调配程序 kubernetes.io/aws-ebs（来自 Kubernetes 网站）的有效 EBS 存储类定义。或者，使用 EBS 容器存储接口（CSI）驱动程序预调配程序 ebs.csi.aws.com（来自 GitHub 网站）的存储类定义。

验证 Amazon EBS CSI 驱动程序控制器和节点容器组是否正在运行

EBS CSI 驱动程序由作为部署运行的控制器容器组和作为进程守护程序集运行的节点容器组组成。要检查您的集群是否运行这些容器组，请运行以下命令：

kubectl get all -l app.kubernetes.io/name=aws-ebs-csi-driver -n kube-system

**注意：**Windows Worker 节点和 AWS Fargate 不支持 EBS CSI 驱动程序。

确保安装的 EBS CSI 驱动程序版本与您集群的 Kubernetes 版本兼容（来自 GitHub 网站）。

检查在绑定到 EBS 持久性卷时 PVC 是否遇到问题

要检查 PVC 是否遇到问题，请运行以下命令来查看事件。在以下示例命令中，将 PVC_NAME 和 NAMESPACE 替换为您环境的正确值：

kubectl describe pvc PVC_NAME -n NAMESPACE

如果您使用动态卷预调配，请查看返回的事件，以确定卷预调配是成功还是失败。您还可以看到 PVC 绑定到的相应持久性卷名称，如以下示例所示：

Name:          ebs-claim
Namespace:     default
StorageClass:  ebs-sc
Status:        Bound
Volume:        pvc-5cbd76de-6f15-41e4-9948-2bba2574e205
Annotations:   pv.kubernetes.io/bind-completed: yes
               pv.kubernetes.io/bound-by-controller: yes
               volume.beta.kubernetes.io/storage-provisioner: ebs.csi.aws.com
               volume.kubernetes.io/selected-node: ip-10-0-2-57.ec2.internal
. . . . .
. . . . .
Events:
  Type    Reason                 Age                    From                                                                                      Message
  ----    ------                 ----                   ----                                                                                      -------
. . . . .
  Normal  Provisioning           5m22s                  ebs.csi.aws.com_ebs-csi-controller-57d4cbb9cc-dr9cd_8f0373e8-4e58-4dd0-b83c-da6f9ad5d5ce  External provisioner is provisioning volume for claim "default/ebs-claim"
  Normal  ProvisioningSucceeded  5m18s                  ebs.csi.aws.com_ebs-csi-controller-57d4cbb9cc-dr9cd_8f0373e8-4e58-4dd0-b83c-da6f9ad5d5ce  Successfully provisioned volume pvc-5cbd76de-6f15-41e4-9948-2bba2574e205

如果预调配失败，则在事件中查找错误消息。

查看 Amazon EBS CSI 控制器容器组的日志

要查看挂载失败的原因，请查看控制器容器组日志。如果卷在创建过程中出现故障，请参阅 ebs-plugin 和 csi-provisioner 日志。要检索 ebs-plugin 容器日志，请运行以下命令：

kubectl logs deployment/ebs-csi-controller -n kube-system -c ebs-plugin

kubectl logs daemonset/ebs-csi-node -n kube-system -c ebs-plugin

要检索 csi-provisioner 容器日志，请运行以下命令：

kubectl logs deployment/ebs-csi-controller -n kube-system -c csi-provisioner

如果 EBS 卷无法附加到容器组，请查看 csi-attacher 日志。要检索 csi-attacher 容器日志，请运行以下命令：

kubectl logs deployment/ebs-csi-controller -n kube-system -c csi-attacher

检查 Amazon EBS CSI 驱动程序控制器服务账户的 IAM 角色和该角色的权限

**注意：**要提高 EBS CSI 驱动程序的调试效率，请设置调试日志选项（来自 GitHub 网站）。

确保使用正确的 IAM 角色为 EBS CSI 驱动程序控制器服务账户添加注释。此外，确保 IAM 角色具有所需的权限。

以下问题会导致您的 PVC 事件或 ebs-csi-controller 日志中出现未授权错误：

• IAM 角色中缺少权限。
• 与服务账户关联的 IAM 角色不正确。

1.   要确定 ebs-csi-controller 容器组服务账户的注释是否正确，请运行以下命令：

kubectl describe sa ebs-csi-controller-sa -n kube-system

2.    验证是否存在以下注释：

eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/AmazonEKS_EBS_CSI_DriverRole

3.    验证是否为集群创建了 IAM OpenID Connect（OIDC）提供商。此外，验证 IAM 角色是否具有执行 EBS API 调用所需的权限。确保 IAM 角色的信任策略信任服务账户 ebs-csi-controller-sa。

3.    验证 AWS CloudTrail 是否进行了 CreateVolume、AttachVolume 和 DetachVolume 调用。为此，请查看 CloudTrail 日志。此外，请查看日志以确定进行了调用的主体。这可帮助您确定控制器或 Worker 节点 IAM 角色是否使用服务账户 IAM 角色。

验证持久性卷的节点关联性

每个持久性卷都有节点关联性，该关联性会限制将持久性卷附加到单个可用区内的节点。这是因为您只能将 EBS 卷附加到在创建它们的同一可用区中运行的容器组或节点。如果一个可用区内节点的预定容器组使用另一个可用区中的 EBS 持久性卷，则您会收到以下错误：

“FailedScheduling： 1 个节点存在卷节点关联性冲突”

为了避免出现这种情况，请使用 StatefulSets（来自 Kubernetes 网站）而不是部署。这将在与容器组相同的可用区中，为 StatefulSets 的每个容器组创建一个唯一的 EBS 卷。

要验证持久性卷的节点关联性，请运行以下命令。将 PERSISTENT_VOLUME_NAME 替换为您的卷的名称：

kubectl describe pv PERSISTENT_VOLUME_NAME

**注意：**您无法将 EBS 卷挂载到在两个不同 Worker 节点上运行的两个不同容器组。您可以将 EBS 卷附加到在一个节点上运行的容器组，但不能同时将其附加到另一个节点。如果您尝试将 EBS 卷附加到不同 Worker 节点上的两个容器组，则该容器组会出现故障，并且您会收到以下错误：

“警告 FailedAttachVolume 2m38s attachdetach-controller 多重附加错误，因为卷‘pvc-1cccsdfdc8-fsdf6-43d6-a1a9-ea837hf7h57fa’已独占地附加到一个节点，因此无法附加到另一个节点”

确保您的 EBS 控制器容器组可以连接到 Amazon Elastic Compute Cloud（Amazon EC2）API

如果您在 ebs-csi-controller 日志中看到连接超时错误，则可能是 EBS CSI 控制器未连接到 Amazon EC2 API。如果在创建 PVC 时控制器容器组出现连接问题，则会看到以下错误：

“警告 ProvisioningFailed persistentvolumeclaim/storage-volume-1 无法使用 StorageClass "ebs-sc" 预调配卷：rpc 错误：代码 = DeadlineExceeded desc = 已超过上下文截止日期”

要解决此错误，请检查 EBS 控制器容器组的子网是否已连接到 EC2 API。如果您使用 HTTP/HTTPS 代理运行私有集群，请验证您的 EBS CSI 控制器容器组是否可以使用 HTTP/HTTPS 代理。EBS CSI 驱动程序的 Helm 安装支持设置 HTTP/HTTPS 代理（来自 Kubernetes 网站）。

此消息还可能与 OIDC 问题有关。要解决 OIDC 问题，请参阅如何对 Amazon EKS 中的 OIDC 提供商和 IRSA 进行故障排除？