Amazon EKS において、Amazon EFS ボリュームのマウントに関する問題をトラブルシューティングする方法を教えてください。

解決策

前提条件:

• Amazon EFS ファイルシステムにおいて、アベイラビリティーゾーンの各ワーカーノードサブネットにマウントターゲットが存在することを確認します。
• Amazon EFS ストレージクラスの定義で efs.csi.aws.com を指定したことを確認します。詳細については、GitHub のウェブサイトで「EFS ストレージクラス」を参照してください。
• PersistentVolumeClaim と PersistentVolume を使用していることを確認します。詳細については、GitHub のウェブサイトで PersistentVolumeClaim と PersistentVolume を確認してください。
  注: 動的プロビジョニングでは、PersistentVolumeClaim と PersistentVolume を使用する必要はありません。詳細については、GitHub のウェブサイトで「動的プロビジョニング」を参照してください。
• EKS クラスターに Amazon EFS CSI ドライバーアドオンがインストールされていることを確認します。

EKS ワーカーノードから Amazon EFS API へのネットワークが正しく構成されていることを確認します。

EFS ワーカーノードと EFS コントローラーポッドから Amazon EFS API にアクセスできることを確認します。

ネットワークが Amazon EFS API に到達できるよう構成されていない場合、次のいずれかのエラーメッセージが表示される可能性があります。

• "failed to provision volume with StorageClass "xxxx": rpc error: code = DeadlineExceeded desc = context deadline exceeded" (ボリュームのプロビジョニング失敗)
• "Could not start amazon-efs-mount-watchdog, unrecognized init system "bash" Mount attempt x/3 failed due to timeout after 15 sec" (マウントの試行時にタイムアウト)
• "Unable to attach or mount volumes: timed out waiting for the condition" (条件の待機中にタイムアウトしたため、ボリュームをアタッチ、マウントできない)

外向きインターネットアクセスのないプライベートクラスターを使用する場合、VPC の 仮想プライベートクラウド (VPC) エンドポイントに com.amazonaws.region.elasticfilesystem を含める必要があります。VPC エンドポイントのセキュリティグループに対し、ワーカーノードとポッドのサブネットからポート 443 へのトラフィックを許可するインバウンドルールを作成します。VPC エンドポイントに関連付けられたポリシーには、必須権限が含まれていることを確認します。

Amazon EFS マウントターゲットが正しく構成されていることを確認する

EKS ノードを実行する各アベイラビリティーゾーンに Amazon EFS マウントターゲットが作成済みであることを確認します。たとえば、ワーカーノードを us-east-1a と us-east-1b に分散させた場合は、マウントする EFS ファイルシステムの両アベイラビリティーゾーンにマウントターゲットを作成する必要があります。

マウントターゲットの構成が正しくない場合、次のエラーメッセージが表示される可能性があります。

"Output: Failed to resolve "fs-xxxxxx.efs.us-east-1.amazonaws.com" - The file system mount target ip address cannot be found"

Amazon EFS ファイルシステムとワーカーノードに関連付けられたセキュリティグループが NFS トラフィックを許可していることを確認する

セキュリティグループがトラフィックを許可していない場合、次のいずれかのエラーメッセージが表示される可能性があります。

• "Could not start amazon-efs-mount-watchdog, unrecognized init system "bash" Mount attempt x/3 failed due to timeout after 15 sec" (マウントの試行時にタイムアウト)
• "failed to provision volume with StorageClass "xxxx": rpc error: code = DeadlineExceeded desc = context deadline exceeded" (ボリュームのプロビジョニング失敗)
• "Unable to attach or mount volumes: timed out waiting for the condition" (条件の待機中にタイムアウトしたため、ボリュームをアタッチ、マウントできない)

Amazon EFS ファイルシステムのセキュリティグループには、クラスターVPC の Classless Inter-Domain Routing (CIDR) から受信するネットワークファイルシステム (NFS) トラフィックを許可するインバウンドルールが必要です。ポート 2049 での内向きトラフィックを許可します。

ポッドが EFS ボリュームをマウントできないワーカーノードに関連付けられたセキュリティグループには、アウトバウンドルールが必要です。アウトバウンドルールは、ポート 2049 での NFS から EFS ファイルシステムへのトラフィックを許可する必要があります。

Amazon EFS ファイルシステムにサブディレクトリのパスを作成したことを確認する

サブディレクトリのパスを永続ボリュームに追加する場合、Amazon EFS CSI ドライバーはファイルシステム内にサブディレクトリのパスを作成しません。マウント操作を正常に実行するには、サブディレクトリをファイルシステムに作成済みである必要があります。サブディレクトリがファイルシステム内に存在しない場合、次のエラーメッセージが表示される可能性があります。

"Output: mount.nfs4: mounting fs-18xxxxxx.efs.us-east-1.amazonaws.com:/path-in-dir:/ failed, reason given by server: No such file or directory" (サブディレクトリが存在しない)

EFS ファイルシステム内にサブディレクトリが存在するかどうかを確認するには、EC2 インスタンスにその EFS ファイルシステムをマウントし、コンテンツをリスト表示します。サブディレクトリが存在しない場合は、mkdir コマンドで作成します。

クラスターの VPC が Amazon DNS サーバーを使用していることを確認する

Amazon EFS CSI ドライバーで EFS ボリュームをマウントする際、VPC では Amazon DNS サーバーを使用する必要があります。

注: Amazon Provided DNS 以外は、Amazon EFS サービスのファイルシステム DNS を解決できません。

DNS サーバーを検証するには、ワーカーノードにログインし、次のコマンドを実行します。

nslookup fs-4fxxxxxx.efs.region.amazonaws.com AMAZON_PROVIDED_DNS_IP

注: region を実際の AWS リージョンに置き換えてください。AMAZON_PROVIDED_DNS_IP を DNS の IP アドレスに置き換えてください。

カスタム DNS サーバーがリクエストを転送していない場合、次のエラーメッセージが表示される可能性があります。

"Output: Failed to resolve "fs-xxxxxx.efs.us-west-2.amazonaws.com" - The file system mount target ip address cannot be found" (マウントターゲットの IP アドレスを見つけられない)

クラスター VPC でカスタム DNS サーバーを使用する場合は、この DNS サーバーにおいて、*.amazonaws.com に当てはまるすべてのリクエストを Amazon DNS サーバーに転送する設定を行います。

制限的なファイルシステムポリシーを使用する場合、PersistentVolume 定義に iam マウントオプションが存在することを確認する

制限的なファイルポリシーに iam マウントオプションが追加されていない場合、ポッドで障害が発生し、次のエラーメッセージが表示されます。

"mount.nfs4: access denied by server while mounting 127.0.0.1:/" (サーバーによるアクセス拒否)

Amazon EFS ファイルシステムにおいて、マウント権限を特定の AWS Identity and Access Management (IAM) ロールのみに制限する設定を行った場合は、-o iam マウントオプションを指定します。CSI ドライバーに IAM マウントオプションの追加を許可するために、spec.mountOptions プロパティを含めます。

例:

apiVersion: v1  
kind: PersistentVolume  
metadata:  
  name: efs-pv1  
spec:  
  mountOptions:  
    - iam

必須権限を含む IAM ロールで Amazon EFS CSI ドライバーコントローラーのサービスアカウントにアノテーションが付与されていることを確認する

efs-csi-controller ポッドが使用するサービスアカウントに適切なアノテーションが付与されていることを確認するには、次のコマンドを実行します。

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

出力例:

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

アカウントに適切な AWS Identity and Access Management (IAM) ロールと権限が存在することを確認するには、クラスターの IAM OIDC プロバイダーを検証します。サービスアカウント efs-csi-controller-sa と関連付けられた IAM ロールには、EFS API コールの実行に必要な権限が含まれることを確認します。次に、IAM ロールの信頼ポリシーは、サービスアカウント efs-csi-controller-sa を信頼していることを確認します。

IAM ロールの信頼ポリシー例:

{  
  "Version": "2012-10-17",  
  "Statement": [  
    {  
      "Effect": "Allow",  
      "Principal": {  
        "Federated": "arn:aws:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"  
      },  
      "Action": "sts:AssumeRoleWithWebIdentity",  
      "Condition": {  
        "StringLike": {  
          "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:efs-csi-*",  
          "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"  
        }  
      }  
    }  
  ]  
}

EFS CSI ドライバーポッドが実行中であることを確認する

ポッドがクラスターにおいてアクティブであることを確認するには、次のコマンドを実行します。

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

ポッドがファイルシステムをマウントできない EC2 ワーカーノードから行われる EFS マウント操作を確認する

ポッドの Amazon EKS ワーカーノードにログインします。次に、EFS マウントヘルパーで EFS ワーカーノードに EFS ファイルシステムを手動マウントします。マウント操作をテストするには、次のコマンドを実行します。

sudo mount -t efs -o tls file-system-dns-name efs-mount-point/

ワーカーノードがファイルシステムをマウントできる場合は、CSI コントローラーと CSI ノードポッドの efs-plugin ログを確認します。

EFS CSI ドライバーポットのログを参照し、マウントできない原因を判断する

ボリュームをマウントできない場合は、efs-plugin ログを参照します。efs-plugin コンテナログを取得するには、次のコマンドを実行します。

kubectl logs deployment/efs-csi-controller -n kube-system -c efs-plugin  
kubectl logs daemonset/efs-csi-node -n kube-system -c efs-plugin