Amazon EFS CSI 드라이버로 Amazon S3 파일 시스템 스토리지 사용하기

Amazon EFS CSI 드라이버로 Amazon S3 파일 시스템 스토리지 사용하기 (Use Amazon S3 file system storage with the Amazon EFS CSI driver)

S3 Files는 모든 AWS 컴퓨팅을 Amazon S3의 데이터와 직접 연결하는 공유 파일 시스템이에요. 데이터가 S3를 떠나지 않고도 전체 파일 시스템 의미론과 낮은 지연 시간 성능을 갖춘 파일로 모든 S3 데이터에 빠르고 직접적으로 접근할 수 있게 해줘요. 즉 파일 기반 애플리케이션, 에이전트, 팀이 이미 의존하는 도구를 사용해 S3 데이터를 파일 시스템으로 접근하고 작업할 수 있다는 뜻이에요. Amazon EFS CSI(Container Storage Interface) 드라이버는 버전 3.0.0부터 AWS에서 실행되는 Kubernetes 클러스터가 Amazon S3 파일 시스템을 영구 볼륨으로 마운트할 수 있게 해줘요. 이 주제는 Amazon EFS CSI 드라이버를 사용해 Amazon EKS 클러스터에서 Amazon S3 파일 시스템을 관리하는 방법을 보여줘요.

출처: 문서

본문

고려 사항 (Considerations)

  • Amazon EFS CSI 드라이버는 Windows 기반 컨테이너 이미지와 호환되지 않아요.
  • EKS Fargate는 S3 Files를 지원하지 않아요.
  • Amazon EFS CSI 드라이버는 Amazon EKS Hybrid Nodes와 호환되지 않아요.
  • Amazon EFS CSI 드라이버의 Amazon S3 Files 지원은 버전 3.0.0부터 시작돼요.

사전 요구 사항 (Prerequisites)

Amazon EFS CSI 드라이버는 AWS IAM(Identity and Access Management) 권한이 필요해요.

  • AWS는 EKS Pod Identities 사용을 제안해요. 자세한 내용은 EKS Pod Identities 설정 개요를 참고하세요.
  • 서비스 계정용 IAM 역할 및 클러스터용 IAM OIDC(OpenID Connect) 프로바이더 설정에 대한 내용은 클러스터용 IAM OIDC 프로바이더 생성하기를 참고하세요.
  • 기기 또는 AWS CloudShell에 AWS CLI(Command Line Interface) 버전 2.12.3 이상 또는 버전 1.27.160 이상이 설치되고 구성되어 있어야 해요. 현재 버전을 확인하려면 aws --version | cut -d / -f2 | cut -d ' ' -f1을 사용하세요. yum, apt-get, macOS용 Homebrew 같은 패키지 관리자는 최신 AWS CLI보다 몇 버전 뒤처진 경우가 많아요. 최신 버전을 설치하려면 AWS Command Line Interface 사용 설명서의 aws configure로 설치 및 빠른 구성하기를 참고하세요. AWS CloudShell에 설치된 AWS CLI 버전도 최신 버전보다 몇 버전 뒤처질 수 있어요. 업데이트하려면 AWS CloudShell 사용 설명서의 홈 디렉터리에 AWS CLI 설치하기를 참고하세요.
  • 기기 또는 AWS CloudShell에 kubectl 명령줄 도구가 설치되어 있어야 해요. 버전은 클러스터의 Kubernetes 버전과 같거나 최대 한 마이너 버전 앞뒤일 수 있어요. 예를 들어 클러스터 버전이 1.29라면 kubectl 버전 1.28, 1.29, 1.30을 사용할 수 있어요. kubectl을 설치하거나 업그레이드하려면 kubectl 및 eksctl 설정하기를 참고하세요.

1단계: IAM 역할 생성

Amazon EFS CSI 드라이버는 파일 시스템과 상호작용하기 위해 IAM 권한이 필요해요. EFS CSI 드라이버는 별도의 IAM 역할이 있는 두 개의 서비스 계정을 사용해요.

  • efs-csi-controller-sa — 컨트롤러가 사용하며 AmazonS3FilesCSIDriverPolicy와 AmazonS3FilesClientFullAccess가 필요해요.
  • efs-csi-node-sa — 노드 daemonset이 사용하며 다음이 필요해요.
    • AmazonS3FilesClientFullAccess — S3 파일 시스템을 마운트하고 쓰기 권한을 부여해요(s3files:ClientMount, s3files:ClientWrite, s3files:ClientRootAccess).
    • AmazonS3ReadOnlyAccess — 더 높은 처리량을 위해 S3 버킷에서 직접 스트리밍 읽기를 활성화해요.
    • AmazonElasticFileSystemsUtils — 마운트 작업에 대한 가시성과 쉬운 문제 해결을 위해 efs-utils 로그를 Amazon CloudWatch에 게시할 수 있게 해줘요.

참고

Amazon S3 파일 시스템과 Amazon EFS 스토리지를 모두 사용하려면 컨트롤러 역할에 AmazonS3FilesCSIDriverPolicy와 AmazonEFSCSIDriverPolicy 관리형 정책을 모두 연결해야 해요. Amazon EFS 스토리지에 대한 자세한 내용은 Amazon EFS로 탄력적 파일 시스템 스토리지 사용하기를 참고하세요.

이 절차를 구현하려면 다음 도구 중 하나를 사용할 수 있어요: eksctl, AWS Management Console, AWS CLI.

참고

이 절차의 구체적인 단계는 드라이버를 Amazon EKS 추가 기능으로 사용할 때를 위해 작성됐어요. 자체 관리형 설치에 대한 자세한 내용은 GitHub의 Set up driver permission(드라이버 권한 설정)을 참고하세요.

eksctl

Pod Identities 사용 시: 다음 명령으로 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,arn:aws:iam::aws:policy/AmazonS3FilesClientFullAccess

# 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/AmazonS3FilesClientFullAccess,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 \
    --attach-policy-arn arn:aws:iam::aws:policy/AmazonS3FilesClientFullAccess \
    --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/AmazonS3FilesClientFullAccess \
    --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. https://console.aws.amazon.com/iam/ 에서 IAM 콘솔을 엽니다.
  2. 왼쪽 탐색 창에서 Roles를 선택합니다.
  3. Roles 페이지에서 Create role을 선택합니다.
  4. Select trusted entity 페이지에서 다음을 수행합니다.
    • EKS Pod Identities 사용 시:
      • Trusted entity type 섹션에서 AWS service를 선택합니다.
      • Service or use case 드롭다운에서 EKS를 선택합니다.
      • Use case 섹션에서 EKS - Pod Identity를 선택합니다.
      • Next를 선택합니다.
    • 서비스 계정용 IAM 역할 사용 시:
      • Trusted entity type 섹션에서 Web identity를 선택합니다.
      • Identity provider에서 클러스터의 OpenID Connect 프로바이더 URL(Amazon EKS의 Overview 아래에 표시됨)을 선택합니다.
      • Audience에서 sts.amazonaws.com을 선택합니다.
      • Next를 선택합니다.
  5. Add permissions 페이지에서 다음을 수행합니다.
    • Filter policies 상자에 AmazonS3FilesCSIDriverPolicy를 입력합니다. 검색 결과로 반환된 정책 왼쪽의 확인란을 선택합니다. 그런 다음 AmazonS3FilesClientFullAccess를 검색해 선택합니다.
    • Next를 선택합니다.
  6. Name, review, and create 페이지에서 다음을 수행합니다.
    • Role name에 AmazonEKS_EFS_CSI_ControllerRole 같은 역할의 고유 이름을 입력합니다.
    • Add tags (Optional) 아래에서 태그를 키-값 쌍으로 연결해 역할에 메타데이터를 추가합니다. IAM에서 태그 사용에 대한 자세한 내용은 IAM 사용 설명서의 IAM 리소스 태그 지정하기를 참고합니다.
    • Create role을 선택합니다.
  7. 역할이 생성된 후:
    • EKS Pod Identities 사용 시:
      1. Amazon EKS 콘솔을 엽니다.
      2. 왼쪽 탐색 창에서 Clusters를 선택한 다음, EKS Pod Identity 연결을 구성하려는 클러스터 이름을 선택합니다.
      3. Access 탭을 선택합니다.
      4. Pod Identity associations에서 Create를 선택합니다.
      5. IAM role 드롭다운을 선택하고 새로 만든 역할을 선택합니다.
      6. Kubernetes namespace 필드를 선택하고 kube-system을 입력합니다.
      7. Kubernetes service account 필드를 선택하고 efs-csi-controller-sa를 입력합니다.
      8. Create를 선택합니다. Pod Identity 연결 생성에 대한 자세한 내용은 Pod Identity 연결 생성하기(AWS 콘솔)를 참고합니다. 위 단계를 반복해 노드 서비스 계정용 두 번째 역할을 만듭니다. Add permissions 페이지에서 대신 AmazonS3FilesClientFullAccess, AmazonS3ReadOnlyAccess, AmazonElasticFileSystemsUtils를 연결합니다. 그런 다음 Kubernetes service account 필드에 efs-csi-node-sa로 Pod Identity 연결을 만듭니다.
    • 서비스 계정용 IAM 역할 사용 시:
      1. 역할을 선택해 편집을 위해 엽니다.
      2. Trust relationships 탭을 선택한 다음 Edit trust policy를 선택합니다.
      3. 다음 줄과 유사한 줄을 찾습니다. 
        "oidc.eks.region-code.amazonaws.com/id/:aud": "sts.amazonaws.com"
      4. 이전 줄 위에 다음 줄을 추가합니다. 을 클러스터가 있는 AWS 리전으로 바꾸고, 을 클러스터의 OIDC 프로바이더 ID로 바꿉니다. 
        "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount:kube-system:efs-csi-controller-sa",
      5. Update policy를 선택해 마칩니다.
      6. 위 단계를 반복해 노드 서비스 계정용 두 번째 역할을 만듭니다. Add permissions 페이지에서 대신 AmazonS3FilesClientFullAccess, AmazonS3ReadOnlyAccess, AmazonElasticFileSystemsUtils를 연결합니다. 신뢰 정책에서 :sub 조건 값에 efs-csi-node-sa를 사용합니다.

AWS CLI

다음 명령으로 AWS CLI를 사용해 IAM 역할을 만들어요.

Pod Identities 사용 시:

  1. pods.eks.amazonaws.com 서비스에 AssumeRole 및 TagSession 작업을 부여하는 IAM 역할을 만들어요. 다음 내용을 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. 컨트롤러 역할을 만들어요. my-cluster를 클러스터 이름으로 바꾸세요. 
    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"
  3. 필요한 AWS 관리형 정책을 컨트롤러 역할에 연결해요. 
    aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy \
  --role-name $controller_role_name

aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3FilesClientFullAccess \
  --role-name $controller_role_name
  4. 같은 신뢰 정책을 사용해 노드 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"
  5. 필요한 AWS 관리형 정책을 노드 역할에 연결해요. 
    aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3FilesClientFullAccess \
  --role-name $node_role_name

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
  6. 다음 명령으로 Pod Identity 연결을 만들어요. ``을 계정 ID로 바꾸세요. 
    aws eks create-pod-identity-association --cluster-name $cluster_name --role-arn {arn-aws}iam:::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:::role/$node_role_name --namespace kube-system --service-account efs-csi-node-sa
    Pod Identity 연결 생성에 대한 자세한 내용은 Pod Identity 연결 생성하기(AWS 콘솔)를 참고합니다.

서비스 계정용 IAM 역할 사용 시:

  1. 클러스터의 OIDC 프로바이더 URL을 확인해요. my-cluster를 클러스터 이름으로 바꾸세요. 
    export cluster_name=my-cluster
aws eks describe-cluster --name $cluster_name --query "cluster.identity.oidc.issuer" --output text
    예시 출력은 다음과 같아요. 
    https://oidc.eks..amazonaws.com/id/
    명령 출력이 None이면 사전 요구 사항을 검토하세요.
  2. 컨트롤러 서비스 계정용 IAM 역할을 만들어요. 다음 내용을 controller-trust-policy.json이라는 파일에 복사해요. 을 계정 ID로 바꾸고, 과 ``을 이전 단계에서 반환된 값으로 바꾸세요. 
    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks..amazonaws.com/id/:aud": "sts.amazonaws.com",
                    "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount:kube-system:efs-csi-controller-sa"
                }
            }
        }
    ]
}
  3. 역할을 만들어요. 
    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"
  4. 필요한 AWS 관리형 정책을 컨트롤러 역할에 연결해요. 
    aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy \
  --role-name $controller_role_name

aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3FilesClientFullAccess \
  --role-name $controller_role_name
  5. 노드 서비스 계정용 IAM 역할을 만들어요. 다음 내용을 node-trust-policy.json이라는 파일에 복사해요. 을 계정 ID로 바꾸고, 과 ``을 1단계에서 반환된 값으로 바꾸세요. 
    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam:::oidc-provider/oidc.eks..amazonaws.com/id/"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks..amazonaws.com/id/:sub": "system:serviceaccount:kube-system:efs-csi-node-sa",
                    "oidc.eks..amazonaws.com/id/:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}
  6. 역할을 만들어요. 
    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"
  7. 필요한 AWS 관리형 정책을 노드 역할에 연결해요. 
    aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonS3FilesClientFullAccess \
  --role-name $node_role_name

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 driver IAM policy 문서를 참고하세요.

2단계: Amazon EFS CSI 드라이버 가져오기

Amazon EKS 추가 기능을 통해 Amazon EFS CSI 드라이버를 설치하는 것을 권장해요. 클러스터에 Amazon EKS 추가 기능을 추가하려면 Amazon EKS 추가 기능 생성하기를, 추가 기능에 대한 자세한 내용은 Amazon EKS 추가 기능을 참고하세요. Amazon EKS 추가 기능을 사용할 수 없다면, 그 이유에 대한 issue를 Containers roadmap GitHub 저장소에 제출하는 것을 권장해요.

중요

Amazon EFS 드라이버를 Amazon EKS 추가 기능으로 추가하기 전에 클러스터에 자체 관리형 버전의 드라이버가 설치되어 있지 않은지 확인하세요. 있다면 GitHub의 Amazon EFS CSI 드라이버 제거하기(Uninstalling the Amazon EFS CSI Driver)를 참고하세요.

또는 Amazon EFS CSI 드라이버의 자체 관리형 설치는 GitHub의 Installation(설치)을 참고하세요.

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

Amazon S3 파일 시스템을 만들려면 GitHub의 Amazon EKS용 Amazon S3 파일 시스템 생성하기(Create an Amazon S3 file system for Amazon EKS)를 참고하세요.

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

다양한 샘플 앱을 배포하고 필요에 따라 수정할 수 있어요. 자세한 내용은 GitHub의 Examples(예시)를 참고하세요.

더 알아보기 (Learn more)