Amazon EKS での EBS ボリュームのマウントに関する問題をトラブルシューティングするにはどうすればよいですか?

所要時間3分

Amazon Elastic Block Store (Amazon EBS) ボリュームを Amazon Elastic Kubernetes Service (Amazon EKS) クラスターにマウントしたいと考えています。しかし、「imeout expired waiting for volumes to attach or mount for pod」というエラーが表示されます。

解決方法

トラブルシューティング手順を開始する前に、以下の前提条件を満たしていることを確認してください:

ebs-csi-controller-sa サービスアカウントの IAM ロールに必要な AWS ID およびアクセス管理 (IAM) 権限。
注: サービスアカウントの問題をトラブルシューティングするには、「Creating the Amazon EBS CSI driver IAM role」セクションを参照してください。
ポッドと同じ名前空間にある有効な PersistentVolumeClaim (PVC) (GitHub ウェブサイトにあり)。
ツリー内プロビジョナー kubernetes.io/aws-ebs を使用する有効な EBS ストレージクラス定義 (Kubernetes ウェブサイトにあり)。または、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 ワーカーノードと 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 ウェブサイトにあり)。

EBS CSI ドライバーコントローラーサービスアカウントに正しい IAM ロールが付けられていることを確認してください。また、IAM ロールに必要なアクセス許可があることを確認してください。

次の問題により、PVC イベントまたは ebs-csi-controller ログに不正なエラーが発生します。

IAM ロールに権限がありません。
サービスアカウントに関連付けられた IAM ロールが正しくありません。

ebs-csi-controller ポッドのサービスアカウントに正しいロールが注釈として付いているかどうかを確認するには、次のコマンドを実行します。

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

次の注釈が付いていることを確認します。

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

クラスターの IAM OpenID Connect (OIDC) プロバイダーを作成したことを確認します。また、IAM ロールに EBS API 呼び出しを実行するのに必要な権限があることを確認してください。IAM ロールの信頼ポリシーがサービスアカウント ebs-csi-controller-sa を信頼していることを確認してください。
AWS CloudTrail が CreateVolume、AttachVolume、DetachVolume の呼び出しを行っていることを確認します。そのためには、CloudTrail のログを確認してください。また、ログを確認して、どのプリンシパルが呼び出しを行っているかを特定してください。これにより、コントローラーまたはワーカーノードの IAM ロールがサービスアカウントの IAM ロールを使用しているかどうかを判断できます。

永続ボリュームのノードアフィニティを確認する

各永続ボリュームにはノードアフィニティがあり、1 つのアベイラビリティーゾーン内のノードへの永続ボリュームのアタッチメントを制限します。これは、EBS ボリュームを作成したのと同じアベイラビリティーゾーンで実行されるポッドまたはノードにのみ、EBS ボリュームをアタッチできるためです。あるアベイラビリティーゾーンのノードのスケジュールされたポッドが別のアベイラビリティーゾーンの EBS 永続ボリュームを使用する場合、次のエラーが表示されます。

「FailedScheduling: 1 node(s) had volume node affinity conflict」

このエラーを回避するには、デプロイの代わりにStatefulSets (Kubernetes ウェブサイトにあり) を使用してください。これにより、ポッドと同じアベイラビリティーゾーンに、StatefulSets のポッドごとに固有の EBS ボリュームが作成されます。

永続ボリュームのノードアフィニティを確認するには、次のコマンドを実行します。PERSISTENT_VOLUME_NAME を自分のボリュームの名前に置き換えてください。

kubectl describe pv PERSISTENT_VOLUME_NAME

**注:**2 つの異なるワーカーノードで動作する 2 つの異なるポッドに EBS ボリュームをマウントすることはできません。EBS ボリュームは 1 つのノードで動作するポッドにアタッチできますが、同時に別のノードにアタッチすることはできません。EBS ボリュームを異なるワーカーノード上の 2 つのポッドにアタッチしようとすると、ポッドに障害が発生し、次のエラーが表示されます。

「FailedAttachVolume 2m38s attachdetach-controller Multi-Attach error for volume "pvc-1cccsdfdc8-fsdf6-43d6-a1a9-ea837hf7h57fa" Volume is already exclusively attached to one node and can't be attached to another」

EBS コントローラーポッドが Amazon Elastic Compute Cloud (Amazon EC2) API に接続されていることを確認してください

ebs-csi-controller ログに接続タイムアウトのエラーが表示される場合は、EBS CSI コントローラーが Amazon EC2 API に接続されていない可能性があります。PVC の作成時にコントローラーポッドの接続に問題がある場合は、次のエラーが表示されます。

「Warninh: ProvisioningFailed persistentvolumeclaim/storage-volume-1 failed to provision volume with StorageClass "ebs-sc": rpc error: code = DeadlineExceeded desc = context deadline exceeded」

このエラーを解決するには、EBS コントローラーポッドのサブネットが EC2 API に接続されていることを確認します。HTTP/HTTPS プロキシを使用してプライベートクラスターを実行する場合は、EBS CSI コントローラーポッドが HTTP/HTTPS プロキシを使用できることを確認してください。EBS CSI ドライバーの Helm のインストールでは、HTTP/HTTPS プロキシ (Kubernetes のウェブサイトにあり) のセットアップがサポートされます。

このメッセージは OIDC の問題に関連している可能性もあります。OIDC の問題をトラブルシューティングするには、「Amazon EKS で OIDC プロバイダーと IRSA をトラブルシューティングするにはどうすればいいですか?」を参照してください。

トピック

コンテナ

タグ

Amazon Elastic Kubernetes Service

言語

日本語