Mountpoint for Amazon S3 CSI 드라이버를 통해 Amazon S3 객체에 액세스 - Amazon EKS
고려 사항사전 조건IAM 정책 생성IAM 역할 생성Amazon S3 CSI 드라이버용 Mountpoint 설치Amazon S3용 Mountpoint 구성샘플 애플리케이션 배포Amazon S3 CSI 드라이버용 Mountpoint 제거

Mountpoint for Amazon S3 CSI 드라이버를 통해 Amazon S3 객체에 액세스

Amazon S3 CSI(컨테이너 스토리지 인터페이스)용 Mountpoint 드라이버를 사용하면 Kubernetes 애플리케이션이 파일 시스템 인터페이스를 통해 Amazon S3 개체에 액세스하여 애플리케이션 코드를 변경하지 않고도 높은 총 처리량을 달성할 수 있습니다. Amazon S3용 Mountpoint를 기반으로 구축된 CSI 드라이버는 Amazon EKS 및 자체 관리형 Kubernetes 클러스터의 컨테이너가 액세스할 수 있는 볼륨으로 Amazon S3 버킷을 제공합니다. 이 주제에서는 Mountpoint for Amazon S3 CSI 드라이버를 Amazon EKS 클러스터에 배포하는 방법을 설명합니다.

고려 사항

  • Amazon S3 CSI 드라이버용 Mountpoint는 현재 Windows 기반 컨테이너 이미지와 호환되지 않습니다.

  • Amazon S3 CSI용 Mountpoint 드라이버는 AWS Fargate를 지원하지 않습니다. 하지만 Amazon EC2에서 실행되는 컨테이너(Amazon EKS 또는 사용자 지정 Kubernetes 설치)는 지원됩니다.

  • Mountpoint for Amazon S3 CSI 드라이버는 정적 프로비저닝만 지원합니다. 동적 프로비저닝 또는 새 버킷의 생성은 지원되지 않습니다.

    참고

    정적 프로비저닝이란 PersistentVolume 객체의 volumeAttributes에서 bucketName으로 지정된 기존 Amazon S3 버킷을 사용하는 것을 말합니다. 자세한 내용은 GitHub의 정적 프로비저닝을 참조하세요.

  • Amazon S3 CSI 드라이버용 Mountpoint가 탑재된 볼륨은 모든 POSIX 파일 시스템 기능을 지원하지는 않습니다. 파일 시스템 동작에 대한 자세한 내용은 GitHub에서 Amazon S3 파일 시스템 동작에 대한 Mountpoint를 참조하세요.

사전 조건

  • 클러스터의 기존 AWS ID 및 액세스 관리(IAM)OpenID Connect (OIDC) 공급자입니다. 이미 있는지 아니면 생성해야 하는지 확인하려면 클러스터에 대한 IAM OIDC 공급자 생성 부분을 참조하세요.

  • 디바이스 또는 AWS CloudShell에 AWS CLI 버전 2.12.3 이후 버전이 설치 및 구성됩니다.

  • kubectl 명령줄 도구는 장치 또는 AWS CloudShell에 설치됩니다. 버전은 클러스터의 Kubernetes 버전과 동일하거나 최대 하나 이전 또는 이후의 마이너 버전일 수 있습니다. 예를 들어 클러스터 버전이 1.29인 경우 kubectl 버전 1.28, 1.29 또는 1.30를 함께 사용할 수 있습니다. kubectl을 설치하거나 업그레이드하려면 kubectl 및 eksctl 설정 부분을 참조하세요.

IAM 정책 생성

Mountpoint for Amazon S3 CSI 드라이버가 파일 시스템과 상호 작용하려면 Amazon S3 권한이 필요합니다. 이 섹션에서는 필요한 권한을 부여하는 IAM 정책을 생성하는 방법을 소개합니다.

다음 정책 예시는 Mountpoint에 대한 IAM 권한 권장 사항을 따릅니다. 또는 AWS 관리형 정책 AmazonS3FullAccess를 사용할 수 있지만 이 관리형 정책은 Mountpoint에 필요한 것보다 더 많은 권한을 부여합니다.

Mountpoint에 대해 권장되는 권한에 대한 자세한 내용은 GitHub의 Mountpoint IAM 권한을 참조하세요.

  1. https://console.aws.amazon.com/iam/에서 IAM 콘솔을 엽니다.

  2. 왼쪽 탐색 창에서 정책을 선택합니다.

  3. 정책 페이지에서 정책 생성을 선택합니다.

  4. 정책 편집기에서 JSON을 선택합니다.

  5. 정책 편집기에서 다음을 복사하고 붙여 넣습니다.

    중요

    amzn-s3-demo-bucket1을 사용자의 Amazon S3 버킷 이름으로 대체합니다.

    {
   "Version": "2012-10-17",
   "Statement": [
        {
            "Sid": "MountpointFullBucketAccess",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket1"
            ]
        },
        {
            "Sid": "MountpointFullObjectAccess",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::amzn-s3-demo-bucket1/*"
            ]
        }
   ]
}

    Amazon S3 Express One Zone 스토리지 클래스에 도입된 디렉터리 버킷은 범용 버킷과 다른 인증 메커니즘을 사용합니다. s3:* 작업을 사용하는 대신 s3express:CreateSession 작업을 사용해야 합니다. 디렉터리 버킷에 대한 자세한 내용은 Amazon S3 사용 설명서의 디렉터리 버킷을 참조하세요.

    다음은 디렉터리 버킷에 사용할 최소 권한 정책의 예입니다.

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3express:CreateSession",
            "Resource": "arn:aws:s3express:us-west-2:111122223333:bucket/amzn-s3-demo-bucket1--usw2-az1--x-s3"
        }
    ]
}

  6. Next(다음)를 선택합니다.

  7. 검토 및 생성 페이지에서 정책의 이름을 지정합니다. 이 예시 연습에서는 AmazonS3CSIDriverPolicy라는 이름을 사용합니다.

  8. 정책 생성을 선택합니다.

IAM 역할 생성

Mountpoint for Amazon S3 CSI 드라이버가 파일 시스템과 상호 작용하려면 Amazon S3 권한이 필요합니다. 이 섹션에서는 IAM 역할을 생성하여 이러한 권한을 위임하는 방법을 설명합니다. 이 역할을 생성하려면 다음 도구 중 하나를 사용할 수 있습니다.

참고

IAM 정책 AmazonS3CSIDriverPolicy는 이전 섹션에서 생성되었습니다.

eksctl

Mountpoint를 사용하여 Amazon S3 CSI 드라이버용 eksctl IAM 역할 생성

IAM 역할 및 Kubernetes 서비스 계정을 생성하려면 다음 명령을 실행합니다. 또한 이러한 명령은 AmazonS3CSIDriverPolicy IAM 정책을 역할에 연결하고, Kubernetes 서비스 계정(s3-csi-controller-sa)에 IAM 역할 Amazon 리소스 이름(ARN)을 주석으로 추가하고, Kubernetes 서비스 계정 이름을 IAM 역할에 대한 신뢰 정책에 추가합니다.

CLUSTER_NAME=my-cluster
REGION=region-code
ROLE_NAME=AmazonEKS_S3_CSI_DriverRole
POLICY_ARN=AmazonEKS_S3_CSI_DriverRole_ARN
eksctl create iamserviceaccount \
    --name s3-csi-driver-sa \
    --namespace kube-system \
    --cluster $CLUSTER_NAME \
    --attach-policy-arn $POLICY_ARN \
    --approve \
    --role-name $ROLE_NAME \
    --region $REGION \
    --role-only

AWS Management Console

  1. https://console.aws.amazon.com/iam/에서 IAM 콘솔을 엽니다.

  2. 왼쪽 탐색 창에서 역할을 선택합니다.

  3. 역할(Roles) 페이지에서 역할 생성(Create role)을 선택합니다.

  4. 신뢰할 수 있는 엔터티 선택(Select trusted entity) 페이지에서 다음을 수행합니다.

    1. 신뢰할 수 있는 엔터티 유형(Trusted entity type) 섹션에서 웹 자격 증명(Web identity)을 선택합니다.

    2. 보안 인증 공급자의 경우 클러스터에 대해 OpenID Connect공급자 URL을 선택합니다(Amazon EKS의 개요에 표시된 대로).

      URL이 표시되지 않으면 필수 요건을 검토하세요.

    3. 대상(Audience)에서 sts.amazonaws.com을 입력합니다.

    4. Next(다음)를 선택합니다.

  5. 권한 추가(Add permissions) 페이지에서 다음을 수행합니다.

    1. 필터 정책(Filter policies) 상자에 AmazonS3CSIDriverPolicy를 입력합니다.

      참고

      이 정책은 이전 섹션에서 생성되었습니다.

    2. 검색에서 반환된 AmazonS3CSIDriverPolicy 결과 왼쪽에 있는 확인란을 선택합니다.

    3. Next(다음)를 선택합니다.

  6. 이름, 검토 및 생성(Name, review, and create) 페이지에서 다음을 수행합니다.

    1. 역할 이름(Role name)에 역할의 고유한 이름(예: AmazonEKS_S3_CSI_DriverRole)을 입력합니다.

    2. 태그 추가(선택 사항)에서 태그를 키-값 페어로 연결하여 메타데이터를 역할에 추가합니다. IAM에서 태그 사용에 대한 자세한 내용을 알아보려면 IAM 사용 설명서의 IAM 리소스에 태그 지정을 참조하세요.

    3. 역할 생성을 선택합니다.

  7. 역할을 생성한 후 편집할 수 있도록 콘솔에서 이 역할을 선택하여 엽니다.

  8. 신뢰 관계(Trust relationships) 탭을 선택한 후 신뢰 정책 편집(Edit trust policy)을 선택합니다.

  9. 다음과 비슷한 줄을 찾습니다.

    "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"

    이전 줄의 끝에 쉼표를 추가한 다음 이전 줄 뒤에 다음 줄을 추가합니다. region-code를 클러스터가 있는 AWS 리전으로 바꿉니다. EXAMPLED539D4633E53DE1B71EXAMPLE을 클러스터의 OIDC 공급자 ID로 바꿉니다.

    "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:s3-csi-*"

  10. Condition 운영자를 "StringEquals"에서 "StringLike"로 변경합니다.

  11. 신뢰 정책 업데이트(Update Trust Policy)를 선택하여 종료합니다.

AWS CLI

  1. 클러스터의 OIDC 공급자 URL을 확인합니다. my-cluster를 해당 클러스터의 이름으로 바꿉니다. 명령의 출력이 None인 경우 사전 요구 사항을 검토합니다.

    aws eks describe-cluster --name my-cluster --query "cluster.identity.oidc.issuer" --output text

    예제 출력은 다음과 같습니다.

    https://oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE

  2. IAM 역할을 생성하여 Kubernetes 서비스 계정에 AssumeRoleWithWebIdentity 작업 권한을 부여합니다.

    1. 다음 콘텐츠를 aws-s3-csi-driver-trust-policy.json라는 파일에 복사합니다. 111122223333을 계정 ID로 바꿉니다. EXAMPLED539D4633E53DE1B71EXAMPLE 및 region-code를 이전 단계에서 반환된 값으로 바꿉니다.

      {
  "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:s3-csi-*",
          "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
        }
      }
    }
  ]
}

    2. 역할을 생성합니다. AmazonEKS_S3_CSI_DriverRole를 다른 이름으로 변경할 수 있지만, 그렇게 할 경우 이후 단계에서도 변경해야 합니다.

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

  3. 다음 명령을 사용하여 이전에 생성한 IAM 정책을 역할에 연결합니다.

    aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3CSIDriverPolicy \
  --role-name AmazonEKS_S3_CSI_DriverRole
    참고

    IAM 정책 AmazonS3CSIDriverPolicy는 이전 섹션에서 생성되었습니다.

  4. 드라이버를 Amazon EKS 추가 기능으로 설치하는 경우에는 이 단계를 생략합니다. 자체 관리형 드라이버 설치의 경우 생성한 IAM 역할의 ARN으로 주석이 달린 Kubernetes 서비스 계정을 생성합니다.

    1. 다음 콘텐츠를 mountpoint-s3-service-account.yaml이라는 파일에 저장합니다. 111122223333을 계정 ID로 바꿉니다.

      ---
apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/name: aws-mountpoint-s3-csi-driver
  name: mountpoint-s3-csi-controller-sa
  namespace: kube-system
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/AmazonEKS_S3_CSI_DriverRole

    2. 클러스터에 Kubernetes 서비스 계정을 생성합니다. Kubernetes 서비스 계정(mountpoint-s3-csi-controller-sa)에는 AmazonEKS_S3_CSI_DriverRole 이름으로 생성된 IAM 역할을 사용하여 주석을 추가합니다.

      kubectl apply -f mountpoint-s3-service-account.yaml
      참고

      해당 절차에서 플러그인이 배포되면 s3-csi-driver-sa라는 서비스 계정을 생성하고 해당 계정을 사용하도록 구성됩니다.

Amazon S3 CSI 드라이버용 Mountpoint 설치

Amazon EKS 추가 기능을 통해 Mountpoint for Amazon S3 CSI 드라이버를 설치할 수 있습니다. 다음 도구를 사용하여 클러스터에 애드온을 추가할 수 있습니다.

또는 Mountpoint for Amazon S3 CSI 드라이버를 자체 관리형 설치로 설치할 수 있습니다. 자체 관리형 설치 방법에 대한 지침은 GitHub의 설치를 참조하세요.

v1.8.0부터 CSI 드라이버의 Pods에 대해 허용하도록 테인트를 구성할 수 있습니다. 이렇게 하려면 node.tolerations를 사용하여 사용자 지정 테인트 세트를 지정하거나 node.tolerateAllTaints를 사용하여 모든 테인트를 허용하도록 지정하세요. 테인트와 허용 오차에 대한 자세한 내용을 알아보려면 Kubernetes설명서를 참조하세요.

eksctl

eksctl을 사용하여 Amazon S3 CSI 추가 기능 추가

다음 명령을 실행합니다. my-cluster를 클러스터 이름으로, 111122223333을 계정 ID로, AmazonEKS_S3_CSI_DriverRole을 앞서 만든 IAM 역할의 이름으로 바꿉니다.

eksctl create addon --name aws-mountpoint-s3-csi-driver --cluster my-cluster \
  --service-account-role-arn arn:aws:iam::111122223333:role/AmazonEKS_S3_CSI_DriverRole --force

기존 설정과 충돌하는 –-force 옵션과 Amazon EKS 추가 기능 설정을 제거할 경우, Amazon EKS 추가 기능의 업데이트 작업이 실패하고 충돌을 해결하는 데 도움이 되는 오류 메시지가 표시됩니다. 이 옵션을 사용하여 이러한 설정을 덮어쓰기 때문에 이 옵션을 지정하기 전에 Amazon EKS 추가 기능이 관리해야 하는 설정을 관리하지 않는지 확인합니다. 이 설정의 기타 옵션에 대한 자세한 내용은 eksctl 설명서의 추가 기능을 참조하세요. Amazon EKS Kubernetes 필드 관리에 대한 자세한 내용은 Amazon EKS 추가 기능에 대해 사용자 지정할 수 있는 필드 확인 섹션을 참조하세요.

구성 파일을 통해 eksctl을 사용자 지정할 수 있습니다. 자세한 내용은 eksctl 설명서의 구성 값으로 작업하기를 참조하세요. 다음 예제에서는 모든 테인트를 허용하는 방법을 보여줍니다.

# config.yaml
...

addons:
- name: aws-mountpoint-s3-csi-driver
  serviceAccountRoleARN: arn:aws:iam::111122223333:role/AmazonEKS_S3_CSI_DriverRole
  configurationValues: |-
    node:
      tolerateAllTaints: true

AWS Management Console

  1. Amazon EKS 콘솔을 엽니다.

  2. 좌측 탐색 창에서 클러스터를 선택합니다.

  3. Amazon S3 CSI 추가 기능에 대한 Mountpoint를 구성하려는 클러스터의 이름을 선택합니다.

  4. 추가 기능(Add-ons) 탭을 선택합니다.

  5. 추가 기능 더 가져오기를 선택합니다.

  6. 추가 기능 선택 페이지에서 다음을 수행합니다.

    1. Amazon EKS 애드온 섹션에서 Amazon S3 CSI 드라이버용 Mountpoint 확인란을 선택합니다.

    2. Next(다음)를 선택합니다.

  7. 선택한 추가 기능 설정 구성 페이지에서 다음을 수행합니다.

    1. 사용할 버전을 선택합니다.

    2. IAM 역할 선택에서 Mountpoint for Amazon S3 CSI 드라이버 IAM 정책을 연결한 IAM 역할의 이름을 선택합니다.

    3. (선택 사항) 선택적 구성 설정을 확장한 후 충돌 해결 방법을 업데이트하세요. 재정의를 선택한 경우 기존 추가 기능에 대한 하나 이상의 설정을 Amazon EKS 추가 기능의 설정으로 덮어쓸 수 있습니다. 이 옵션을 사용 설정하지 않고 기존 설정과 충돌이 있는 경우 작업이 실패합니다. 결과 오류 메시지를 사용하여 충돌을 해결할 수 있습니다. 이 옵션을 선택하기 전에 Amazon EKS 추가 기능이 사용자가 자체 관리해야 하는 설정을 관리하지 않는지 확인하세요.

    4. (선택 사항) 선택적 구성 설정을 확장한 후 구성 값 필드에서 톨러레이션을 구성합니다.

    5. Next(다음)를 선택합니다.

  8. 검토 및 추가 페이지에서 생성을 선택합니다. 추가 기능 설치가 완료되면 설치한 추가 기능이 표시됩니다.

AWS CLI

AWS을 사용하여 Amazon S3 CSI 추가 기능에 대한 Mountpoint 추가

다음 명령을 실행합니다. my-cluster를 클러스터 이름으로, 111122223333을 계정 ID로, AmazonEKS_S3_CSI_DriverRole을 앞서 만든 역할의 이름으로 바꿉니다.

aws eks create-addon --cluster-name my-cluster --addon-name aws-mountpoint-s3-csi-driver \
  --service-account-role-arn arn:aws:iam::111122223333:role/AmazonEKS_S3_CSI_DriverRole

--configuration-values 플래그와 함께 명령을 사용자 지정할 수 있습니다. 다음 대체 예제는 모든 테인트를 허용하는 방법을 보여줍니다.

aws eks create-addon --cluster-name my-cluster --addon-name aws-mountpoint-s3-csi-driver \
  --service-account-role-arn arn:aws:iam::111122223333:role/AmazonEKS_S3_CSI_DriverRole \
  --configuration-values '{"node":{"tolerateAllTaints":true}}'

Amazon S3용 Mountpoint 구성

대부분의 경우 버킷 이름만 사용하여 Mountpoint for Amazon S3를 구성할 수 있습니다. Amazon S3용 Mountpoint 구성에 대한 지침은 GitHub에서 Amazon S3용 마운트포인트 구성을 참조하세요.

샘플 애플리케이션 배포

기존 Amazon S3 버킷의 드라이버에 정적 프로비저닝을 배포할 수 있습니다. 자세한 내용은 GitHub의 정적 프로비저닝을 참조하세요.

Amazon S3 CSI 드라이버용 Mountpoint 제거

Amazon EKS 추가 기능을 제거하는 경우 다음 두 가지 옵션이 있습니다.

  • 클러스터에 추가 기능 소프트웨어 보존 – 이 옵션은 모든 설정에 대한 Amazon EKS 관리를 제거합니다. 또한 업데이트를 시작한 후 Amazon EKS가 업데이트를 알리고 Amazon EKS 추가 기능을 자동으로 업데이트하는 기능을 제거합니다. 그러나 클러스터에 추가 기능 소프트웨어는 유지됩니다. 이 옵션을 사용하면 추가 기능을 Amazon EKS 추가 기능이 아닌 자체 관리형 설치 기능으로 만들 수 있습니다. 이 옵션을 사용하면 추가 기능에 대한 가동 중지 시간이 없습니다. 이 절차의 명령은 이 옵션을 사용합니다.

  • 클러스터에서 추가 기능 소프트웨어 완전히 제거(Remove the add-on software entirely from your cluster) - 클러스터에 종속된 리소스가 없는 경우에만 클러스터에서 Amazon EKS 추가 기능을 제거하는 것이 좋습니다. 이 옵션을 수행하려면 이 절차에서 사용하는 명령에서 --preserve를 삭제합니다.

추가 기능에 연결된 IAM 계정이 있는 경우 IAM 계정은 제거되지 않습니다.

다음 도구를 사용하여 Amazon S3 CSI 애드온을 제거할 수 있습니다:

eksctl

eksctl을 사용하여 Amazon S3 CSI 추가 기능 제거

my-cluster를 클러스터 이름으로 바꾸고 다음 명령을 실행합니다.

eksctl delete addon --cluster my-cluster --name aws-mountpoint-s3-csi-driver --preserve

AWS Management Console

  1. Amazon EKS 콘솔을 엽니다.

  2. 좌측 탐색 창에서 클러스터를 선택합니다.

  3. Amazon EBS CSI 추가 기능을 제거할 클러스터의 이름을 선택합니다.

  4. 추가 기능(Add-ons) 탭을 선택합니다.

  5. Amazon S3 CSI 드라이버용 Mountpoint를 선택합니다.

  6. 제거를 선택합니다.

  7. 제거: aws-mountpoint-s3-csi-driver 확인 대화 상자에서 다음을 수행합니다.

    1. 추가 기능에 대한 Amazon EKS의 설정 관리를 중지하려면 클러스터에 보존을 선택합니다. 클러스터에 추가 소프트웨어를 유지하려면 이렇게 합니다. 이는 추가 기능의 모든 설정을 스스로 관리할 수 있도록 하기 위한 것입니다.

    2. aws-mountpoint-s3-csi-driver을 입력합니다.

    3. 제거를 선택합니다.

AWS CLI

AWS CLI을 사용하여 Amazon S3 CSI 추가 기능 제거

my-cluster를 클러스터 이름으로 바꾸고 다음 명령을 실행합니다.

aws eks delete-addon --cluster-name my-cluster --addon-name aws-mountpoint-s3-csi-driver --preserve