AWS re:Post Knowledge Center Feedback Survey

Help us improve the AWS re:Post Knowledge Center by sharing your feedback in a brief survey. Your input can influence how we create and update our content to better support your AWS journey.

Amazon EKS 클러스터에 Amazon S3 CSI 드라이버를 설치하려면 어떻게 해야 합니까?

5분 분량

Amazon Elastic Kubernetes Service(Amazon EKS) 클러스터에서 Amazon Simple Storage Service(Amazon S3) 컨테이너 스토리지 인터페이스(CSI) 드라이버를 사용하고 싶습니다.

해결 방법

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하면 AWS CLI의 오류 해결을 참조하십시오. 또한 최신 AWS CLI 버전을 사용하고 있는지 확인하십시오.

전제 조건:

kubectl 및 eksctl 명령줄 도구를 설치합니다.
클러스터용 AWS Identity and Access Management(IAM) OpenID Connect(OIDC) 공급자를 생성합니다.
EKS Pod Identity를 Amazon S3 CSI 드라이버와 함께 사용할 수 없으므로 서비스 계정의 IAM 역할(IRSA)을 사용합니다.

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 드라이버 배포

다음 단계를 완료하십시오.

요구 사항에 따라 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를 가용 영역으로 바꾸십시오.

다음 create-policy 명령을 실행하여 AmazonS3CSIDriverPolicy라는 이름의 IAM 정책을 생성합니다.

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

참고: iam-policy.json을 IAM 정책 JSON 파일로 바꾸십시오.

다음과 같은 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로 바꾸십시오.

다음 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 파일로 바꾸십시오.

다음 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로 바꾸십시오.

다음 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 웹 사이트에서 설치를 참조하십시오.

사용자가 기존 파일을 덮어쓸 수 있도록 하려면 영구 볼륨에 --allow-overwrite 플래그를 추가합니다. 모든 쓰기는 파일 시작 부분부터 순차적으로 추가해야 합니다. 파일을 추가할 수는 없습니다. 대신 기존 콘텐츠를 새 콘텐츠로 바꿔야 합니다. 그러나 Amazon S3 Express One Zone 스토리지 클래스의 디렉터리 버킷의 경우 기존 파일을 추가할 수 있습니다. 이렇게 하려면 영구 볼륨에 --incremental-upload 플래그를 추가하십시오. 또한 파일 끝 부분부터 모든 쓰기를 순차적으로 추가합니다. 자세한 내용은 GitHub 웹 사이트에서 파일 읽기 및 쓰기와 구성을 참조하십시오.

Amazon S3 CSI 드라이버 마운트 지점은 정적 프로비저닝만 사용합니다. 동적 프로비저닝을 사용하거나 새 버킷을 생성할 수 없습니다. 마운트 지점에 마운트하는 볼륨은 일부 POSIX 파일 시스템 기능을 사용할 수 없습니다. 자세한 내용은 GitHub 웹 사이트에서 Mountpoint for Amazon S3 파일 시스템 동작을 참조하십시오. 애플리케이션에 완전한 파일 시스템이 필요한 경우 Amazon Elastic File System(Amazon EFS) 또는 Amazon FSx를 사용하는 것이 가장 좋습니다.

Amazon S3 CSI 드라이버 테스트

Amazon S3 CSI 드라이버를 테스트하려면 포드에 정적 프로비저닝을 사용하는 샘플 애플리케이션을 배포하십시오. 단계와 예제는 GitHub 웹 사이트의 정적 프로비저닝 예제를 참조하십시오.

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 Amazon Machine Image(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 릴리스를 참조하십시오.

컨테이너의 사용자는 Amazon S3 버킷에 액세스할 수 없음

기본적으로 S3 버킷을 마운트한 사용자만 마운트된 디렉터리에 액세스할 수 있습니다. 이는 컨테이너의 다른 사용자가 버킷에 액세스할 수 있도록 권한 및 소유권 설정을 구성한 경우에도 발생합니다.

루트가 아닌 다른 사용자가 마운트된 디렉터리에 액세스할 수 있도록 하려면 --allow-other 옵션을 포함하도록 mountOptions를 업데이트하십시오. 루트 사용자가 다른 사용자로 마운트된 디렉터리에 액세스할 수 있게 하려면 --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 액세스 모드만 사용할 수 있습니다.

주제: Containers
태그: Amazon Elastic Kubernetes Service
언어: 한국어

AWS 공식업데이트됨 일 년 전

댓글 없음

Amazon EKS 클러스터에 Amazon S3 CSI 드라이버를 설치하려면 어떻게 해야 합니까?

해결 방법

Amazon S3 CSI 드라이버 배포

Amazon S3 CSI 드라이버 테스트

Amazon S3 CSI 드라이버 관련 문제 해결

관련 콘텐츠