Amazon EBS로 Kubernetes 볼륨 스토리지 사용하기

Amazon EBS로 Kubernetes 볼륨 스토리지 사용하기 (Use Kubernetes volume storage with Amazon EBS)

참고

새 기능: Amazon EKS Auto Mode는 블록 스토리지의 일상적인 작업을 자동화해요. EKS Auto Mode에 샘플 상태 저장(stateful) 워크로드 배포하기를 참고하세요.

Amazon EBS(Elastic Block Store) CSI(Container Storage Interface) 드라이버는 여러분이 만드는 Kubernetes 볼륨의 스토리지 역할을 하는 Amazon EBS 볼륨의 수명 주기를 관리해요. Amazon EBS CSI 드라이버는 일반 임시 볼륨(generic ephemeral volume)과 영구 볼륨(persistent volume)이라는 두 유형의 Kubernetes 볼륨에 Amazon EBS 볼륨을 제공해요.

출처: 문서

본문

고려 사항 (Considerations)

  • EKS Auto Mode 클러스터에는 Amazon EBS CSI 컨트롤러를 설치할 필요가 없어요.
  • Amazon EBS 볼륨을 Fargate Pod에 마운트할 수 없어요.
  • Amazon EBS CSI 컨트롤러는 Fargate 노드에서 실행할 수 있지만, Amazon EBS CSI 노드 DaemonSet은 Amazon EC2 인스턴스에서만 실행할 수 있어요.
  • Amazon EBS 볼륨과 Amazon EBS CSI 드라이버는 Amazon EKS Hybrid Nodes와 호환되지 않아요.
  • 최신 추가 기능 버전과 이전 버전 하나가 지원돼요. 최신 버전에서 발견된 버그나 취약점에 대한 수정은 새 마이너 버전으로 이전 릴리스에 백포트돼요.
  • EKS Auto Mode는 스토리지 클래스가 provisioner로 ebs.csi.eks.amazonaws.com을 사용해야 해요. 표준 Amazon EBS CSI 드라이버(ebs.csi.aws.com)는 자체 볼륨을 별도로 관리해요. EKS Auto Mode에서 기존 볼륨을 사용하려면 볼륨 스냅샷을 사용해 Auto Mode provisioner를 사용하는 스토리지 클래스로 마이그레이션하세요.

중요

Amazon EBS CSI 드라이버의 스냅샷 기능을 사용하려면 먼저 CSI 스냅샷 컨트롤러를 설치해야 해요. 자세한 내용은 CSI 볼륨에 스냅샷 기능 활성화하기를 참고하세요.

사전 요구 사항 (Prerequisites)

  • 기존 클러스터. 필요한 플랫폼 버전을 보려면 다음 명령을 실행하세요. 
    aws eks describe-addon-versions --addon-name aws-ebs-csi-driver
  • EBS CSI 드라이버는 AWS IAM 권한이 필요해요.
    • AWS는 EKS Pod Identities 사용을 제안해요. 자세한 내용은 EKS Pod Identities 설정 개요를 참고하세요.
    • 서비스 계정용 IAM 역할(Roles for Service Accounts)에 대한 자세한 내용은 클러스터용 IAM OIDC 프로바이더 생성하기를 참고하세요.

1단계: IAM 역할 생성

Amazon EBS CSI 플러그인은 여러분을 대신해 AWS API를 호출하기 위해 IAM 권한이 필요해요. 이 단계를 수행하지 않으면 추가 기능 설치를 시도하고 kubectl describe pvc를 실행할 때 failed to provision volume with StorageClass와 함께 could not create volume in EC2: UnauthorizedOperation 오류가 표시돼요. 자세한 내용은 GitHub의 Set up driver permissions(드라이버 권한 설정)을 참고하세요.

참고

IMDS 접근을 차단하지 않는 한 Pod는 IAM 역할에 할당된 권한에 접근할 수 있어요. 자세한 내용은 모범 사례로 Amazon EKS 클러스터 보안하기를 참고하세요.

다음 절차는 IAM 역할을 만들고 AWS 관리형 정책을 연결하는 방법을 보여줘요. 이 절차를 구현하려면 다음 도구 중 하나를 사용할 수 있어요: eksctl, AWS Management Console, AWS CLI.

참고

더 범위가 좁은 권한으로 자체 관리형 정책을 만들 수 있어요. AmazonEBSCSIDriverPolicyV2를 검토하고 권한을 줄인 커스텀 IAM 정책을 만드세요. AmazonEBSCSIDriverPolicy에서 마이그레이션한다면 EBS CSI 드라이버 정책 마이그레이션을 참고하세요.

참고

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

eksctl

IAM 역할을 만들고 정책을 연결해요. AWS는 AWS 관리형 정책을 유지하거나 여러분이 직접 커스텀 정책을 만들 수 있어요. 다음 명령으로 IAM 역할을 만들고 AWS 관리형 정책을 연결할 수 있어요. my-cluster를 클러스터 이름으로 바꾸세요. 이 명령은 IAM 역할을 만들고 IAM 정책을 연결하는 AWS CloudFormation 스택을 배포해요.

eksctl create iamserviceaccount \
        --name ebs-csi-controller-sa \
        --namespace kube-system \
        --cluster my-cluster \
        --role-name AmazonEKS_EBS_CSI_DriverRole \
        --role-only \
        --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicyV2 \
        --approve

커스텀 KMS 키를 사용하지 않는다면 이 단계를 건너뛸 수 있어요. Amazon EBS 볼륨의 암호화에 커스텀 KMS 키를 사용한다면 필요에 따라 IAM 역할을 커스터마이징하세요. 예를 들어 다음을 수행해요.

  1. 다음 코드를 새 kms-key-for-encryption-on-ebs.json 파일에 복사해 붙여넣으세요. custom-key-arn을 커스텀 KMS 키 ARN으로 바꾸세요. 
    {
      "Version":"2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "kms:CreateGrant",
            "kms:ListGrants",
            "kms:RevokeGrant"
          ],
          "Resource": ["arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"],
          "Condition": {
            "Bool": {
              "kms:GrantIsForAWSResource": "true"
            }
          }
        },
        {
          "Effect": "Allow",
          "Action": [
            "kms:Encrypt",
            "kms:Decrypt",
            "kms:ReEncrypt*",
            "kms:GenerateDataKey*",
            "kms:DescribeKey"
          ],
          "Resource": ["arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"]
        }
      ]
    }
  2. 정책을 만들어요. KMS_Key_For_Encryption_On_EBS_Policy를 다른 이름으로 바꿀 수 있어요. 다만 바꾸면 이후 단계에서도 꼭 바꾸세요. 
    aws iam create-policy \
      --policy-name KMS_Key_For_Encryption_On_EBS_Policy \
      --policy-document file://kms-key-for-encryption-on-ebs.json
  3. 다음 명령으로 IAM 정책을 역할에 연결해요. 111122223333을 계정 ID로 바꾸세요. 
    aws iam attach-role-policy \
      --policy-arn arn:aws:iam::111122223333:policy/KMS_Key_For_Encryption_On_EBS_Policy \
      --role-name AmazonEKS_EBS_CSI_DriverRole

AWS Management Console

  1. https://console.aws.amazon.com/iam/ 에서 IAM 콘솔을 엽니다.
  2. 왼쪽 탐색 창에서 Roles를 선택합니다.
  3. Roles 페이지에서 Create role을 선택합니다.
  4. Select trusted entity 페이지에서 다음을 수행합니다.
    • Trusted entity type 섹션에서 Web identity를 선택합니다.
    • Identity provider에서 클러스터의 OpenID Connect 프로바이더 URL(Amazon EKS의 Overview 아래에 표시됨)을 선택합니다.
    • Audience에서 sts.amazonaws.com을 선택합니다.
    • Next를 선택합니다.
  5. Add permissions 페이지에서 다음을 수행합니다.
    • Filter policies 상자에 AmazonEBSCSIDriverPolicyV2를 입력합니다.
    • 검색 결과로 반환된 AmazonEBSCSIDriverPolicyV2 왼쪽의 확인란을 선택합니다.
    • Next를 선택합니다.
  6. Name, review, and create 페이지에서 다음을 수행합니다.
    • Role name에 AmazonEKS_EBS_CSI_DriverRole 같은 역할의 고유 이름을 입력합니다.
    • Add tags (Optional) 아래에서 태그를 키-값 쌍으로 연결해 역할에 메타데이터를 추가합니다. IAM에서 태그 사용에 대한 자세한 내용은 IAM 사용 설명서의 IAM 리소스 태그 지정하기를 참고합니다.
    • Create role을 선택합니다.
  7. 역할이 생성된 후 콘솔에서 역할을 선택해 편집을 위해 엽니다.
  8. Trust relationships 탭을 선택한 다음 Edit trust policy를 선택합니다.
  9. 다음 줄과 유사한 줄을 찾습니다. 
    "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
  10. 이전 줄 끝에 쉼표를 추가한 다음, 이전 줄 뒤에 다음 줄을 추가합니다. region-code를 클러스터가 있는 AWS 리전으로 바꾸고, EXAMPLED539D4633E53DE1B71EXAMPLE을 클러스터의 OIDC 프로바이더 ID로 바꿉니다. 
    "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa"
  11. Update policy를 선택해 마칩니다.

Amazon EBS 볼륨의 암호화에 커스텀 KMS 키를 사용한다면 필요에 따라 IAM 역할을 커스터마이징하세요. 예를 들어 다음을 수행해요.

  1. 왼쪽 탐색 창에서 Policies를 선택합니다.
  2. Policies 페이지에서 Create Policy를 선택합니다.
  3. Create policy 페이지에서 JSON 탭을 선택합니다.
  4. 다음 코드를 편집기에 복사해 붙여넣고, custom-key-arn을 커스텀 KMS 키 ARN으로 바꿉니다. 
    {
      "Version":"2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "kms:CreateGrant",
            "kms:ListGrants",
            "kms:RevokeGrant"
          ],
          "Resource": ["arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"],
          "Condition": {
            "Bool": {
              "kms:GrantIsForAWSResource": "true"
            }
          }
        },
        {
          "Effect": "Allow",
          "Action": [
            "kms:Encrypt",
            "kms:Decrypt",
            "kms:ReEncrypt*",
            "kms:GenerateDataKey*",
            "kms:DescribeKey"
          ],
          "Resource": ["arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"]
        }
      ]
    }
  5. Next: Tags를 선택합니다.
  6. Add tags (Optional) 페이지에서 Next: Review를 선택합니다.
  7. Name에 정책의 고유 이름(예: KMS_Key_For_Encryption_On_EBS_Policy)을 입력합니다.
  8. Create policy를 선택합니다.
  9. 왼쪽 탐색 창에서 Roles를 선택합니다.
  10. 콘솔에서 AmazonEKS_EBS_CSI_DriverRole을 선택해 편집을 위해 엽니다.
  11. Add permissions 드롭다운 목록에서 Attach policies를 선택합니다.
  12. Filter policies 상자에 KMS_Key_For_Encryption_On_EBS_Policy를 입력합니다.
  13. 검색 결과로 반환된 KMS_Key_For_Encryption_On_EBS_Policy 왼쪽의 확인란을 선택합니다.
  14. Attach policies를 선택합니다.

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. AssumeRoleWithWebIdentity 작업을 부여하는 IAM 역할을 만들어요. 다음 내용을 aws-ebs-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.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
          },
          "Action": "sts:AssumeRoleWithWebIdentity",
          "Condition": {
            "StringEquals": {
              "oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com",
              "oidc.eks.us-east-1.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa"
            }
          }
        }
      ]
    }
  3. 역할을 만들어요. AmazonEKS_EBS_CSI_DriverRole을 다른 이름으로 바꿀 수 있어요. 바꾸면 이후 단계에서도 꼭 바꾸세요. 
    aws iam create-role \
      --role-name AmazonEKS_EBS_CSI_DriverRole \
      --assume-role-policy-document file://"aws-ebs-csi-driver-trust-policy.json"
  4. 정책을 연결해요. AWS는 AWS 관리형 정책을 유지하거나 여러분이 직접 커스텀 정책을 만들 수 있어요. 다음 명령으로 AWS 관리형 정책을 역할에 연결하세요. 
    aws iam attach-role-policy \
      --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicyV2 \
      --role-name AmazonEKS_EBS_CSI_DriverRole
  5. Amazon EBS 볼륨의 암호화에 커스텀 KMS 키를 사용한다면 필요에 따라 IAM 역할을 커스터마이징하세요. 예를 들어 다음을 수행해요.
    1. 다음 코드를 새 kms-key-for-encryption-on-ebs.json 파일에 복사해 붙여넣으세요. custom-key-arn을 커스텀 KMS 키 ARN으로 바꾸세요. 
      {
      "Version":"2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "kms:CreateGrant",
            "kms:ListGrants",
            "kms:RevokeGrant"
          ],
          "Resource": ["arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"],
          "Condition": {
            "Bool": {
              "kms:GrantIsForAWSResource": "true"
            }
          }
        },
        {
          "Effect": "Allow",
          "Action": [
            "kms:Encrypt",
            "kms:Decrypt",
            "kms:ReEncrypt*",
            "kms:GenerateDataKey*",
            "kms:DescribeKey"
          ],
          "Resource": ["arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"]
        }
      ]
    }
    2. 정책을 만들어요. KMS_Key_For_Encryption_On_EBS_Policy를 다른 이름으로 바꿀 수 있어요. 다만 바꾸면 이후 단계에서도 꼭 바꾸세요. 
      aws iam create-policy \
      --policy-name KMS_Key_For_Encryption_On_EBS_Policy \
      --policy-document file://kms-key-for-encryption-on-ebs.json
    3. 다음 명령으로 IAM 정책을 역할에 연결해요. 111122223333을 계정 ID로 바꾸세요. 
      aws iam attach-role-policy \
      --policy-arn arn:aws:iam::111122223333:policy/KMS_Key_For_Encryption_On_EBS_Policy \
      --role-name AmazonEKS_EBS_CSI_DriverRole

이제 Amazon EBS CSI 드라이버 IAM 역할을 만들었으므로 다음 섹션으로 진행할 수 있어요. 이 IAM 역할로 추가 기능을 배포하면 ebs-csi-controller-sa라는 서비스 계정을 만들고 이를 사용하도록 구성돼요. 이 서비스 계정은 필요한 Kubernetes 권한이 할당된 clusterrole에 바인딩돼요.

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

보안을 개선하고 작업량을 줄이려면 Amazon EKS 추가 기능을 통해 Amazon EBS CSI 드라이버를 설치하는 것을 권장해요. 클러스터에 Amazon EKS 추가 기능을 추가하려면 Amazon EKS 추가 기능 생성하기를, 추가 기능에 대한 자세한 내용은 Amazon EKS 추가 기능을 참고하세요.

중요

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

참고

기본적으로 EBS CSI가 사용하는 RBAC 역할은 taint 제거 기능을 지원하기 위해 노드를 변경할 수 있는 권한을 가져요. Kubernetes RBAC의 제한으로 인해 이는 클러스터의 다른 노드를 변경할 수 있는 권한도 허용해요. Helm 차트에는 ebs-csi-node 서비스 계정에 대한 노드 RBAC 변경 권한을 비활성화하는 매개변수(node.serviceAccount.disableMutation)가 있어요. 활성화하면 taint 제거 같은 드라이버 기능이 작동하지 않아요.

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

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

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

더 알아보기 (Learn more)