如何在我的 Amazon EKS 集群上安装 Amazon S3 CSI 驱动程序？

解决方案

**注意：**如果您在运行 AWS 命令行界面 (AWS CLI) 命令时收到错误，请参阅 AWS CLI 错误故障排除。此外，请确保您使用的是最新版本的 AWS CLI。

先决条件：

• 安装 kubectl and eksctl 命令行工具。
• 为您的集群创建 AWS Identity and Access Management( IAM) OpenID Connect (OIDC) 提供商。
• 对服务账户 (IRSA) 使用 IAM 角色，因为您无法将 EKS 容器组身份与 Amazon S3 CSI 驱动程序一起使用。

要获取 OIDC 发行者 ID，请运行以下 describe-cluster AWS CLI 命令：

aws eks describe-cluster --name your_cluster_name --query "cluster.identity.oidc.issuer" --output text | cut -d '/' -f 5

**注意：**将 your_cluster_name 替换为您的 Amazon EKS 集群名称。

要检查您是否配置了 IAM OIDC 提供商，请运行以下 list-open-id-connect-providers 命令：

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

**注意：**将 YOUR_OIDC_ID 替换为您的 OIDC ID。如果输出为空，则必须创建 IAM OIDC 提供商。

要创建 IAM OIDC 提供商，请运行以下命令：

eksctl utils associate-iam-oidc-provider --cluster your_cluster_name --approve

**注意：**将 your_cluster_name 替换为您的集群名称。

部署 Amazon S3 CSI 驱动程序

完成以下步骤：

1. 根据您的要求创建 IAM 策略。
   通用存储桶策略：

   cat <<EOF > iam-policy.json
   {
      "Version": "2012-10-17",
      "Statement": [
           {
               "Sid": "MountpointFullBucketAccess",
               "Effect": "Allow",
               "Action": [
                   "s3:ListBucket"
               ],
               "Resource": [
                   "arn:aws:s3:::your_bucket_name"
               ]
           },
           {
               "Sid": "MountpointFullObjectAccess",
               "Effect": "Allow",
               "Action": [
                   "s3:GetObject",
                   "s3:PutObject",
                   "s3:AbortMultipartUpload",
                   "s3:DeleteObject"
               ],
               "Resource": [
                   "arn:aws:s3:::your_bucket_name/*"
               ]
           }
      ]
   }
   EOF

   **注意：**将 your_bucket_name 替换为您的存储桶名称。
   目录存储桶策略：

   cat <<EOF > iam-policy.json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "s3express:CreateSession",
               "Resource": "arn:aws:s3express:YOUR_AWS_REGION:YOUR_AWS_ACCOUNT_ID:bucket/your_bucket_name--az_id--x-s3"
           }
       ]
   }
   EOF

   **注意：**将 YOUR_AWS_REGION 替换为您的 AWS 区域，将 YOUR_AWS_ACCOUNT_ID 替换为您的 AWS 账户，将 your_bucket_name 替换为您的存储桶名称，将 az_id 替换为您的可用区。
2. 运行以下 create-policy 命令创建名为 AmazonS3CSIDriverPolicy 的 IAM 策略：

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

   **注意：**将 iam-policy.json 替换为您的 IAM 策略 JSON 文件。
3. 创建以下 IAM 信任策略：

   cat <<EOF > trust-policy.json
   {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Effect": "Allow",
           "Principal": {
             "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/your_OIDC_ID"
           },
           "Action": "sts:AssumeRoleWithWebIdentity",
           "Condition": {
             "StringLike": {
               "oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/your_OIDC_ID:sub": "system:serviceaccount:kube-system:s3-csi-*",
               "oidc.eks.YOUR_AWS_REGION.amazonaws.com/id/your_OIDC_ID:aud": "sts.amazonaws.com"
             }
           }
         }
       ]
   }
   EOF

   **注意：**将 YOUR_AWS_ACCOUNT_ID 替换为您的账户，将 YOUR_AWS_REGION 替换为您的区域，将 YOUR_OIDC_ID 替换为您的 OIDC ID。
4. 运行以下 create-role 命令创建名为 AmazonEKS_S3_CSI_DriverRole 的 IAM 角色：

   aws iam create-role --role-name AmazonEKS_S3_CSI_DriverRole  --assume-role-policy-document file://"trust-policy.json"

   **注意：**将 trust-policy.json 替换为您的 IAM 信任策略 JSON 文件。
5. 运行以下 attach-role-policy 命令将策略附加到 IAM 角色：

   aws iam attach-role-policy  --policy-arn arn:aws:iam::YOUR_AWS_ACCOUNT_ID:policy/AmazonS3CSIDriverPolicy --role-name AmazonEKS_S3_CSI_DriverRole

   **注意：**将 YOUR_AWS_ACCOUNT_ID 替换为您的 AWS 账户 ID。
6. 运行以下 create-addon 命令在您的集群上部署 Amazon S3 CSI 驱动程序：

   aws eks  create-addon --cluster-name your_cluster_name --addon-name aws-mountpoint-s3-csi-driver --service-account-role-arn arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/AmazonEKS_S3_CSI_DriverRole

   **注意：**将 your_cluster_name 替换为您的集群名称，将 YOUR_AWS_ACCOUNT_ID 替换为您的账户 ID。要使用 Kustomize 或 Helm 安装 Amazon S3 CSI 驱动程序，请参阅 GitHub 网站上的 Installation。

要允许用户覆盖现有文件，请在永久卷中添加 --allow-overwrite 标志。必须从文件开头按顺序添加所有写入内容。您无法追加文件。相反，您必须用新内容替换现有内容。但是，对于 Amazon S3 Express One Zone 存储类中的目录存储桶，您可以附加现有文件。为此，请在永久卷中添加 --incremental-upload 标志。此外，从文件末尾开始，按顺序添加所有写入内容。有关详细信息，请参阅 GitHub 网站上的 Reading and writing files 和 Configure。

Amazon S3 CSI 驱动程序挂载点仅使用静态配置。您不能使用动态配置，也不能创建新的存储桶。您在挂载点上挂载的卷不能使用所有 POSIX 文件系统功能。有关详细信息，请参阅 GitHub 网站上的 Mountpoint for Amazon S3 file system behavior。如果您的应用程序需要完整的文件系统，则最佳做法是使用 Amazon Elastic File System (Amazon EFS) 或 Amazon FSx。

测试 Amazon S3 CSI 驱动程序

要测试 Amazon S3 CSI 驱动程序，请为容器组部署使用静态配置的示例应用程序。有关步骤和示例，请参阅 GitHub 网站上的 Static provisioning example。

对 Amazon S3 CSI 驱动程序的问题进行故障排除

您的 Amazon S3 CSI 驱动程序无法按预期运行

要验证 Amazon S3 CSI 驱动程序节点容器组是否正在运行，请运行以下命令：

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

要查看来自 Amazon S3 CSI 驱动程序容器组的日志，请运行以下命令：

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

确保 Amazon S3 存储桶与 Amazon EKS 集群位于同一区域。如果存储桶和集群位于不同的区域，请更新 mountOptions 以包括该区域。

配置示例：

apiVersion: v1
kind: PersistentVolume
metadata:
  name: s3-pv-1
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 10Gi
  csi:
    driver: s3.csi.aws.com
    volumeAttributes:
      bucketName: bucket name
    volumeHandle: s3-csi-driver-volume
  mountOptions:
  - region us-west-2
  - allow-other     
  persistentVolumeReclaimPolicy: Retain
  volumeMode: Filesystem

如果 Amazon S3 CSI 驱动程序在 Bottlerocket 亚马逊机器映像 (AMI) 上不起作用，请运行以下命令来检查容器映像版本：

kubectl get ds s3-csi-node -n kube-system -ojsonpath="{range .spec.template.spec.containers[*]}{.image}{'\n'}{end}"

在命令的输出中，确保容器映像版本大于或等于 v1.4.0。最佳做法是使用最新的 Amazon S3 CSI 驱动程序版本。有关最新版本，请参阅 GitHub 网站上的 mountpoint-s3-csi-driver Releases。

您的容器中的用户无法访问 Amazon S3 存储桶

默认情况下，只有挂载 S3 存储桶的用户才能访问您的挂载目录。即使您配置权限和所有权设置以允许容器中的其他用户访问存储桶，也会发生这种情况。

要允许其他非根用户访问您的挂载目录，请更新 mountOptions 以包括 --allow-other 选项。要允许根用户以其他用户身份访问您的挂载目录，请使用 --allow-root。

策略示例：

apiVersion: v1
kind: PersistentVolume
metadata:
  name: s3-pv-1
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 10Gi
  csi:
    driver: s3.csi.aws.com
    volumeAttributes:
      bucketName: bucket name
    volumeHandle: s3-csi-driver-volume
  mountOptions:
  - region us-west-2
  - allow-other                        
  persistentVolumeReclaimPolicy: Retain
  volumeMode: Filesystem

您收到“Volume capability not supported”（不支持卷功能）错误

当您使用 Amazon S3 CSI 驱动程序时，您可能会收到与以下示例类似的错误消息：

“Warning FailedMount 39s (x8 over 104s) kubelet MountVolume.SetUp failed for volume "s3-pv-1" : rpc error: code = InvalidArgument desc = Volume capability not supported”

当使用 Amazon S3 CSI 驱动程序不支持的访问模式（例如 ReadWriteOncePod 或 ReadWriteOnce）时，您会收到上述错误。只能使用 ReadWriteMany 或 ReadOnlyMany 访问模式。