Amazon EFS CSI コントローラーを使用して Kubernetes 永続ボリュームオブジェクトを動的に作成する際の問題をトラブルシューティングするにはどうすればよいですか?

解決方法

Amazon Elastic File System (Amazon EFS) CSI ドライバーは、サービスアカウント用の AWS Identity and Access Management (IAM) ロール (IRSA) 機能を使用します。この機能を使用するには、OpenID Connect (OIDC) プロバイダー、IAM ロール、アクセス許可など、さまざまなコンポーネントが正しく設定されている必要があります。これらのコンポーネントは、IAM ロールポリシーと Kubernetes サービスアカウントを使用して設定されます。表示されたエラーに基づいて、次のトラブルシューティングのステップを試します。

注: AWS CLI コマンドの実行時にエラーが発生した場合は、AWS CLI の最新バージョンを使用していることを確認してください。

「storageclass.storage.k8s.io "<STORAGE_CLASS_NAME>" not found」(storageclass.storage.k8s.io「<STORAGE_CLASS_NAME>」が見つかりません)

このエラーは、PersistentVolumeClaim オブジェクト定義のパラメータ storageClassName によって参照されるストレージクラスが存在しないため、作成される必要があることを示しています。

エラーを解決するには、次を実行します。

1.    Kubernetes ストレージクラスオブジェクトを作成します。

2.    Amazon EFS のストレージクラスマニフェストをダウンロードします。

curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-efs-csi-driver/master/examples/kubernetes/dynamic_provisioning/specs/storageclass.yaml

3.    ダウンロードしたファイルを編集します。次のステートメントを見つけて、[fileSystemId] の値を自分のファイルシステム ID に置き換えてください。

fileSystemId: fs-582a03f344f0fc633 # Replace the filesystem id

4.    ストレージクラスをデプロイします。

kubectl apply -f storageclass.yaml

「failed to provision volume with StorageClass "<STORAGE_CLASS_NAME>": rpc error: code = InvalidArgument desc = File System does not exist: Resource was not found」(StorageClass「<STORAGE_CLASS_NAME>」を使用してボリュームをプロビジョニングできませんでした: rpc エラー: コード = InvalidArgument desc = File System が存在しません: リソースが見つかりませんでした)

このエラーは、ストレージクラスオブジェクトによって参照されている fileSystemId がリージョンに存在しないか、正しくないことを示しています。

このエラーをトラブルシューティングするには、ストレージクラスで参照されている Amazon EFS ファイルシステムが正しく、リージョンに存在しているかどうかを確認します。

kubectl get storageclass `kubectl get pvc ${PVC_NAME} -o jsonpath='{.spec.storageClassName}'` -o jsonpath='{.parameters.fileSystemId}'

注: PVC_NAME を PersistentVolumeClaim の名前に置き換えてください。

返された EFS ファイルシステム (fileSystemId) がリージョンに存在しない場合は、Kubernetes ストレージクラスオブジェクトを削除します。その後、[fileSystemId] フィールドに正しいファイルシステム ID を入力して、もう一度作成します。

「failed to provision volume with StorageClass "<STORAGE_CLASS_NAME>": rpc error: code = Internal desc = Failed to fetch File System info: Describe File System failed: WebIdentityErr: failed to retrieve credentials caused by: InvalidIdentityToken: No OpenIDConnect provider found in your account for https://oidc.eks.<REGION-CODE>.amazonaws.com/id/<OIDC ID> status code: 400, request id: <REQUEST ID>」(StorageClass「<STORAGE_CLASS_NAME>」を使用してボリュームをプロビジョニングできませんでした: rpc エラー: コード = 内部 説明 = File System の情報を取得できませんでした: File System の記述に失敗しました: WebIdentityErr: 認証情報を取得できませんでした 原因: InvalidIdentityToken: https://oidc.eks.<REGION-CODE>.amazonaws.com/id/<OIDC ID> のアカウントに OpenIDConnect プロバイダーが見つかりません ステータスコード: 400、リクエスト ID: <REQUEST ID>)

このエラーは、指定された IAM OIDC ID が Amazon EKS クラスターの IAM で作成されていないことを示しています。

1.    クラスターの OIDC プロバイダー ID を取得し、変数に保存します。

oidc_id=$(aws eks describe-cluster --name ${CLUSTER_NAME} --query "cluster.identity.oidc.issuer" --output text | cut -d '/' -f 5); echo $oidc_id

注: CLUSTER_NAME をクラスターの名前に置き換えてください。

2.    クラスターの IAM OIDC ID プロバイダーを作成します。

eksctl utils associate-iam-oidc-provider --cluster ${CLUSTER_NAME} –-approve

注: eksctl ユーティリティを使用して IAM OIDC プロバイダーを作成できない場合は、AWS マネジメントコンソールを使用してください。

「failed to provision volume with StorageClass "<STORAGE_CLASS_NAME>": rpc error: code = Unauthenticated desc = Access Denied.Please ensure you have the right AWS permissions: Access denied」(StorageClass「<STORAGE_CLASS_NAME>」を使用してボリュームをプロビジョニングできませんでした: rpc エラー: コード = 認証されていません 説明 = アクセスが拒否されました。適切な AWS 許可が確実に付与されているようにしてください: アクセスが拒否されました)

このエラーは、IRSA に必要なアクセス許可がないことを示しています (例: elasticfilesystem:CreateAccessPoint)。

1.    EFS CSI コントローラーのデプロイによって使用されているサービスアカウントを取得します。

kubectl get deploy -n kube-system efs-csi-controller -o=jsonpath={'.spec.template.spec.serviceAccount'}

2.    サービスアカウントによって使用されている IAM ロールを検索します。

kubectl get sa -n kube-system ${SERVICE_ACCOUNT} -oyaml -o=jsonpath={'.metadata.annotations.eks\.amazonaws\.com/role-arn'}

3.    GitHub から IAM ポリシードキュメントをダウンロードします。

curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-efs-csi-driver/master/docs/iam-policy-example.json

4.    IAM ポリシーが存在しない場合は作成します。

aws iam create-policy --policy-name AmazonEKS_EFS_CSI_Driver_Policy --policy-document file://iam-policy-example.json

5.    この IAM ポリシーを、以前に取得した IAM ロールにアタッチします。このロールには、EFS CSI コントローラーのデプロイによって使用されているサービスアカウントの注釈が付いています。

aws iam attach-role-policy --policy-arn arn:aws:iam::${ACCOUNT_ID}:policy/AmazonEKS_EFS_CSI_Driver_Policy --role-name ${IAM_ROLE_NAME}

注:

次のコマンドを実行することによって、アカウント ID を取得できます。

aws sts get-caller-identity --query "Account" --output text

次のコマンドを実行することによって、IAM ロールを取得できます。

echo $IAM_ROLE_ARN | cut -d "/" -f2

「Failed to fetch File System info: Describe File System failed: WebIdentityErr: failed to retrieve credentials caused by: AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity」(File System の情報を取得できませんでした: File System の記述に失敗しました: WebIdentityErr: 認証情報を取得できませんでした 原因: AccessDenied: sts:AssumeRoleWithWebIdentity を実行するための許可がありません)

このエラーは、次のいずれかの理由により発生します。

• IAM 許可 sts:AssumeRoleWithWebIdentity が指定されていない。
• IAM ロールにアタッチされている信頼関係ドキュメントに記載されている IAM OIDC ID プロバイダーが正しくない。
• 前述の Kubernetes サービスアカウント (例: system:serviceaccount:kube-system:efs-csi-controller-sa) が、EFS CSI コントローラーのデプロイによって使用されているアカウントと一致しない。

このエラーをトラブルシューティングするには、次を実行します。

1.    クラスターの OIDC プロバイダー ID を取得し、変数に保存します。

oidc_id=$(aws eks describe-cluster --name ${CLUSTER_NAME} --query "cluster.identity.oidc.issuer" --output text | cut -d '/' -f 5); echo ${oidc_id}

CLUSTER_NAME をクラスターの名前に置き換えてください。

2.    IAM OIDC プロバイダー ID が AWS アカウントに存在することを確認します。

aws iam list-open-id-connect-providers | grep $oidc_id | cut -d "/" -f4

3.    IAM ロールにアタッチされている信頼関係ドキュメントを確認します。

aws iam get-role --role-name ${IAM_ROLE_NAME} --output json --query "Role.AssumeRolePolicyDocument"

アクション sts:AssumeRoleWithWebIdentity が許可されていることを確認します。また、IAM OIDC ID が、前述のコマンドによって返された OIDC ID と一致することを確認します。

注:

次のコマンドを実行することによって、IAM ロールを取得できます。

echo $IAM_ROLE_ARN | cut -d "/" -f2

---

関連情報

サービスアカウントの IAM ロール

Amazon EFS CSI ドライバー