View a markdown version of this page

Amazon EFS CSI 드라이버와 함께 Amazon S3 파일 시스템 스토리지 사용 EFS - Amazon EKS

이 페이지 개선에 도움 주기

이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 GitHub에서 이 페이지 편집 링크를 선택합니다.

Amazon EFS CSI 드라이버와 함께 Amazon S3 파일 시스템 스토리지 사용 EFS

S3 Files는 모든 AWS 컴퓨팅을 Amazon S3의 데이터와 직접 연결하는 공유 파일 시스템입니다. 데이터가 S3를 벗어나지 않고도 전체 파일 시스템 의미 체계와 지연 시간이 짧은 성능을 갖춘 파일로 모든 S3 데이터에 빠르고 직접 액세스할 수 있습니다. 따라서 파일 기반 애플리케이션, 에이전트, 팀은 기존에 사용 중인 도구를 계속 사용하여 파일 시스템으로서 S3 데이터에 액세스하고 작업할 수 있습니다. 버전 3.0.0부터는 Amazon EFS 컨테이너 스토리지 인터페이스(CSI) 드라이버를 사용하면 AWS에서 실행되는 Kubernetes 클러스터가 Amazon S3 파일 시스템을 영구 볼륨으로 탑재할 수 있습니다. 이 주제에서는 Amazon EFS CSI 드라이버를 사용하여 Amazon EKS 클러스터의 Amazon S3 파일 시스템을 관리하는 방법을 설명합니다.

고려 사항

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

  • EKS Fargate는 S3 Files를 지원하지 않습니다.

  • Amazon EFS CSI 드라이버는 Amazon EKS Hybrid Nodes와 호환되지 않습니다.

  • Amazon EFS CSI 드라이버의 Amazon S3 Files 지원은 버전 3.0.0부터 시작됩니다.

사전 조건

  • Amazon EFS CSI 드라이버에는 AWS Identity and Access Management(IAM) 권한이 필요합니다.

  • 장치에 설치 및 구성된 AWS 명령줄 인터페이스(AWS CLI)의 버전 2.12.3 이상 또는 버전 1.27.160 이상 또는 AWS CloudShell. 현재 버전을 확인하려면 aws --version | cut -d / -f2 | cut -d ' ' -f1을 사용합니다. yum, apt-get 또는 macOS용 Homebrew 같은 패키지 관리자는 최신 버전의 AWS CLI 이전에 나온 버전이 몇 가지 있을 때도 있습니다. 최신 버전을 설치하려면 AWS 명령줄 인터페이스 사용 설명서에서 설치aws config를 사용하여 빠른 구성을 참조하세요. AWS CloudShell에 설치된 AWS CLI 버전도 최신 버전보다 여러 버전 이전일 수도 있습니다. 업데이트하려면 AWS CloudShell 사용 설명서홈 디렉터리에 AWS CLI 설치하기를 참조하세요.

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

1단계 - IAM 역할 생성

Amazon EFS CSI 드라이버가 파일 시스템과 상호 작용하려면 IAM 권한이 필요합니다. EFS CSI 드라이버는 별도의 IAM 역할이 있는 서비스 계정 2개를 사용합니다.

  • efs-csi-controller-sa - 컨트롤러에서 사용하며 AmazonS3FilesCSIDriverPolicy가 필요합니다.

  • efs-csi-node-sa - 노드 daemonset에서 사용하며, 다음이 필요합니다.

    • AmazonS3ReadOnlyAccess - 더 높은 처리량을 위해 S3 버킷에서 직접 읽기 스트리밍을 활성화합니다.

    • AmazonElasticFileSystemsUtils - Amazon CloudWatch에 efs-utils 로그를 게시하여 탑재 작업에 대한 가시성을 확보하고 문제를 더 쉽게 해결할 수 있습니다.

참고

Amazon S3 파일 시스템과 Amazon EFS 스토리지를 둘 다 사용하려면 AmazonS3FilesCSIDriverPolicyAmazonEFSCSIDriverPolicy 관리형 정책을 둘 다 컨트롤러 역할에 연결해야 합니다. Amazon EFS 스토리지에 대한 자세한 내용은 Amazon EFS와 함께 탄력적 파일 시스템 스토리지 사용 섹션을 참조하세요.

이 절차를 구현하려면 다음 도구 중 하나를 사용할 수 있습니다.

참고

이 절차의 특정 단계는 드라이버를 Amazon EKS 추가 기능으로 사용하기 위해 작성되었습니다. 자체 관리형 설치에 대한 자세한 내용은 GitHub의 Set up driver permission을 참조하세요.

eksctl

Pod Identity를 사용하는 경우

다음 명령을 실행하여 eksctl로 IAM 역할과 Pod Identity 연결을 생성할 수 있습니다. my-cluster를 원하는 값으로 바꿉니다.

export cluster_name=my-cluster # Create the controller role eksctl create podidentityassociation \ --service-account-name efs-csi-controller-sa \ --namespace kube-system \ --cluster $cluster_name \ --role-name AmazonEKS_EFS_CSI_ControllerRole \ --permission-policy-arns arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy # Create the node role eksctl create podidentityassociation \ --service-account-name efs-csi-node-sa \ --namespace kube-system \ --cluster $cluster_name \ --role-name AmazonEKS_EFS_CSI_NodeRole \ --permission-policy-arns arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess,arn:aws:iam::aws:policy/AmazonElasticFileSystemsUtils

서비스 계정에 IAM 역할을 사용하는 경우

다음 명령을 실행하여 eksctl로 IAM 역할을 생성할 수 있습니다. my-cluster를 클러스터 이름으로 바꾸고 region-code를 해당 작업자의 AWS 리전 코드로 바꿉니다.

export cluster_name=my-cluster export region_code=region-code # Create the controller role export controller_role_name=AmazonEKS_EFS_CSI_ControllerRole eksctl create iamserviceaccount \ --name efs-csi-controller-sa \ --namespace kube-system \ --cluster $cluster_name \ --role-name $controller_role_name \ --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy \ --approve \ --region $region_code # Create the node role export node_role_name=AmazonEKS_EFS_CSI_NodeRole eksctl create iamserviceaccount \ --name efs-csi-node-sa \ --namespace kube-system \ --cluster $cluster_name \ --role-name $node_role_name \ --attach-policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \ --attach-policy-arn arn:aws:iam::aws:policy/AmazonElasticFileSystemsUtils \ --approve \ --region $region_code

AWS Management Console

다음을 실행하여 AWS Management Console를 사용하여 IAM 역할을 만듭니다.

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

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

  3. 역할 페이지에서 역할 생성을 선택합니다.

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

    1. EKS Pod Identity를 사용하는 경우

      1. 신뢰할 수 있는 엔터티 유형 섹션에서 AWS 서비스를 선택합니다.

      2. 서비스 또는 사용 사례 드롭다운에서 EKS를 선택합니다.

      3. 사용 사례 섹션에서 EKS - Pod Identity를 선택합니다.

      4. 다음을 선택합니다.

    2. 서비스 계정에 IAM 역할을 사용하는 경우

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

      2. 아이덴티티 제공업체(Identity provider)의 경우 클러스터에 대해 OpenID Connect 공급자 URL(OpenID Connect provider URL)을 선택합니다(Amazon EKS의 개요에 표시된 대로).

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

      4. 다음을 선택합니다.

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

    1. 필터 정책 상자에 AmazonS3FilesCSIDriverPolicy를 입력합니다.

    2. 검색에서 반환된 정책의 왼쪽에 있는 확인란을 선택합니다.

    3. 다음을 선택합니다.

  6. 이름, 검토 및 생성 페이지에서 다음을 수행합니다.

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

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

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

  7. 역할이 생성된 후

    1. EKS Pod Identity를 사용하는 경우

      1. Amazon EKS 콘솔을 엽니다.

      2. 왼쪽 탐색 창에서 클러스터를 선택한 다음 EKS Pod Identity 연결을 구성할 클러스터의 이름을 선택합니다.

      3. 액세스 탭을 선택합니다.

      4. Pod Identity 연결에서 생성을 선택합니다.

      5. IAM 역할 드롭다운을 선택하고 새로 생성된 역할을 선택합니다.

      6. Kubernetes 네임스페이스 필드를 선택하고 kube-system을 입력합니다.

      7. Kubernetes 서비스 계정 필드를 선택하고 efs-csi-controller-sa를 입력합니다.

      8. 생성(Create)을 선택합니다.

      9. Pod Identity 연결 생성에 대한 자세한 내용은 pod identity 연결 생성(AWS 콘솔) 섹션을 참조하세요.

      10. 위의 단계를 반복하여 노드 서비스 계정에 대한 두 번째 역할을 생성합니다. 권한 추가 페이지에서 AmazonS3ReadOnlyAccessAmazonElasticFileSystemsUtils를 대신 연결합니다. 그런 다음, Kubernetes 서비스 계정 필드에 대해 efs-csi-node-sa와 Pod Identity 연결을 생성합니다.

    2. 서비스 계정에 IAM 역할을 사용하는 경우

      1. 역할을 선택하여 편집을 위해 엽니다.

      2. 신뢰 관계 탭을 선택한 후 신뢰 정책 편집을 선택합니다.

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

        "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:efs-csi-controller-sa",
      4. 신뢰 정책 업데이트를 선택하여 종료합니다.

      5. 위의 단계를 반복하여 노드 서비스 계정에 대한 두 번째 역할을 생성합니다. 권한 추가 페이지에서 AmazonS3ReadOnlyAccessAmazonElasticFileSystemsUtils를 대신 연결합니다. 신뢰 정책에서 :sub 조건 값에 efs-csi-node-sa를 사용합니다.

AWS CLI

다음 명령을 실행하여 AWS CLI로 IAM 역할을 생성할 수 있습니다.

Pod Identity를 사용하는 경우

  1. pods.eks.amazonaws.com 서비스에 AssumeRoleTagSession 작업을 부여하는 IAM 역할을 생성합니다.

    1. 다음 콘텐츠를 aws-efs-csi-driver-trust-policy-pod-identity.json라는 파일에 복사합니다.

      { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowEksAuthToAssumeRoleForPodIdentity", "Effect": "Allow", "Principal": { "Service": "pods.eks.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession" ] } ] }
    2. 역할을 생성합니다. <cluster-name>을 클러스터 이름으로 바꿉니다.

      export cluster_name=my-cluster export controller_role_name=AmazonEKS_EFS_CSI_ControllerRole aws iam create-role \ --role-name $controller_role_name \ --assume-role-policy-document file://"aws-efs-csi-driver-trust-policy-pod-identity.json"
  2. 필요한 AWS 관리형 정책을 컨트롤러 역할에 연결합니다.

    aws iam attach-role-policy \ --policy-arn arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy \ --role-name $controller_role_name
  3. 동일한 신뢰 정책을 사용하여 노드 IAM 역할을 생성합니다.

    export node_role_name=AmazonEKS_EFS_CSI_NodeRole aws iam create-role \ --role-name $node_role_name \ --assume-role-policy-document file://"aws-efs-csi-driver-trust-policy-pod-identity.json"
  4. 필요한 AWS 관리형 정책을 노드 역할에 연결합니다.

    aws iam attach-role-policy \ --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \ --role-name $node_role_name aws iam attach-role-policy \ --policy-arn arn:aws:iam::aws:policy/AmazonElasticFileSystemsUtils \ --role-name $node_role_name
  5. 다음 명령을 실행하여 Pod Identity 연결을 생성합니다. <111122223333>을 계정 ID로 바꿉니다.

    aws eks create-pod-identity-association --cluster-name $cluster_name --role-arn {arn-aws}iam::<111122223333>:role/$controller_role_name --namespace kube-system --service-account efs-csi-controller-sa
    aws eks create-pod-identity-association --cluster-name $cluster_name --role-arn {arn-aws}iam::<111122223333>:role/$node_role_name --namespace kube-system --service-account efs-csi-node-sa
  6. Pod Identity 연결 생성에 대한 자세한 내용은 pod identity 연결 생성(AWS 콘솔) 섹션을 참조하세요.

서비스 계정에 IAM 역할을 사용하는 경우

  1. 클러스터의 OIDC 공급자 URL을 확인합니다. <cluster-name>을 클러스터 이름으로 바꿉니다.

    export cluster_name=my-cluster aws eks describe-cluster --name $cluster_name --query "cluster.identity.oidc.issuer" --output text

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

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

    명령의 출력이 None인 경우 사전 요구 사항을 검토합니다.

  2. 컨트롤러 서비스 계정에 대한 IAM 역할을 생성합니다.

    1. 다음 콘텐츠를 controller-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": { "StringEquals": { "oidc.eks.<region-code>.amazonaws.com/id/<EXAMPLED539D4633E53DE1B71EXAMPLE>:aud": "sts.amazonaws.com", "oidc.eks.<region-code>.amazonaws.com/id/<EXAMPLED539D4633E53DE1B71EXAMPLE>:sub": "system:serviceaccount:kube-system:efs-csi-controller-sa" } } } ] }
    2. 역할을 생성합니다.

      export controller_role_name=AmazonEKS_EFS_CSI_ControllerRole aws iam create-role \ --role-name $controller_role_name \ --assume-role-policy-document file://"controller-trust-policy.json"
  3. 필요한 AWS 관리형 정책을 컨트롤러 역할에 연결합니다.

    aws iam attach-role-policy \ --policy-arn arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy \ --role-name $controller_role_name
  4. 노드 서비스 계정에 대한 IAM 역할을 생성합니다.

    1. 다음 콘텐츠를 node-trust-policy.json라는 파일에 복사합니다. <111122223333>을 계정 ID로 바꿉니다. <EXAMPLED539D4633E53DE1B71EXAMPLE><region-code>를 1단계에서 반환된 값으로 바꿉니다.

      { "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": { "StringEquals": { "oidc.eks.<region-code>.amazonaws.com/id/<EXAMPLED539D4633E53DE1B71EXAMPLE>:sub": "system:serviceaccount:kube-system:efs-csi-node-sa", "oidc.eks.<region-code>.amazonaws.com/id/<EXAMPLED539D4633E53DE1B71EXAMPLE>:aud": "sts.amazonaws.com" } } } ] }
    2. 역할을 생성합니다.

      export node_role_name=AmazonEKS_EFS_CSI_NodeRole aws iam create-role \ --role-name $node_role_name \ --assume-role-policy-document file://"node-trust-policy.json"
  5. 필요한 AWS 관리형 정책을 노드 역할에 연결합니다.

    aws iam attach-role-policy \ --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \ --role-name $node_role_name aws iam attach-role-policy \ --policy-arn arn:aws:iam::aws:policy/AmazonElasticFileSystemsUtils \ --role-name $node_role_name
참고

AmazonS3ReadOnlyAccess 정책은 모든 S3 버킷에 대한 읽기 액세스 권한을 부여합니다. 특정 버킷에 대한 액세스를 제한하려면 버킷을 분리한 후 이를 태그 기반 인라인 정책으로 바꿀 수 있습니다. 자세한 내용은 GitHub의 Amazon EFS CSI 드라이버 IAM 정책 설명서를 참조하세요.

2단계: Amazon EFS CSI 드라이버 받기

Amazon EKS 추가 기능을 통해 Amazon EFS CSI 드라이버를 설치하는 것이 좋습니다. Amazon EKS 추가 기능을 클러스터에 추가하려면 Amazon EKS 추가 기능 생성 섹션을 참조하세요. Amazon EKS 추가 기능에 대한 자세한 내용은 Amazon EKS 추가 기능 섹션을 참조하세요. Amazon EKS 추가 기능을 사용할 수 없는 경우, 사용할 수 없는 이유에 대한 문제를 컨테이너 로드맵 GitHub 리포지토리에 제출하는 것이 좋습니다.

중요

Amazon EFS 드라이버를 Amazon EKS 추가 기능으로 추가하기 전에 클러스터에 자체 관리형 버전의 드라이버가 설치되어 있지 않은지 확인하세요. 그러한 경우 GitHub에서 Amazon EFS CSI 드라이버 제거를 참조하세요.

대신 Amazon EFS CSI 드라이버의 자체 관리형 설치를 원하는 경우 GitHub의 Installation을 참조하세요.

3단계: Amazon S3 파일 시스템 생성

Amazon S3 파일 시스템을 생성하려면 GitHub의 Create an Amazon S3 file system for Amazon EKS를 참조하세요.

4단계: 샘플 애플리케이션 배포

다양한 샘플 앱을 배포하고 필요에 따라 수정할 수 있습니다. 자세한 내용은 GitHub의 Examples를 참조하세요.