**이 페이지 개선에 도움 주기**
이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **GitHub에서 이 페이지 편집** 링크를 선택합니다.
# Amazon EBS와 함께 Kubernetes 볼륨 스토리지 사용
**참고**
**신규:** Amazon EKS Auto Mode는 블록 스토리지에 대한 일상적인 작업을 자동화합니다. [EKS Auto Mode에 샘플 상태 저장 워크로드 배포](sample-storage-workload.md) 방법에 대해 알아봅니다.
[Amazon Elastic Block Store(Amazon EBS) CSI(Container Storage Interface) 드라이버](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/)에서는 Amazon EBS 볼륨의 수명 주기를 사용자가 생성하는 Kubernetes 볼륨의 스토리지로 관리합니다. Amazon EBS CSI 드라이버는 Amazon EBS 볼륨을 Kubernetes 볼륨 유형인 일반 [임시 볼륨](https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/) 및 [영구 볼륨](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)에 사용할 수 있도록 만듭니다.
## 고려 사항
+ Amazon EBS CSI 컨트롤러를 EKS Auto Mode 클러스터에 설치할 필요가 없습니다.
+ Amazon EBS 볼륨을 Fargate 포드에 탑재할 수 없습니다.
+ Amazon EBS CSI 컨트롤러는 Fargate 노드에서 실행할 수 있지만 Amazon EBS CSI 노드 `DaemonSet`은(는) Amazon EC2 인스턴스에서만 실행할 수 있습니다.
+ Amazon EBS 볼륨 및 Amazon EBS CSI 드라이버는 Amazon EKS Hybrid Nodes와 호환되지 않습니다.
+ 최신 추가 기능 버전과 하나의 이전 버전에 대한 지원이 제공됩니다. 최신 버전에서 발견된 버그나 취약성에 대한 수정 사항은 새 마이너 버전의 이전 릴리스로 백포트됩니다.
+ EKS 자동 모드를 사용하려면 스토리지 클래스에서 `ebs.csi.eks.amazonaws.com`을 프로비저너로 사용해야 합니다. 표준 Amazon EBS CSI 드라이버(`ebs.csi.aws.com`)는 자체 볼륨을 별도로 관리합니다. EKS 자동 모드에서 기존 볼륨을 사용하려면 볼륨 스냅샷을 사용하여 자동 모드 프로비저너를 사용하는 스토리지 클래스로 마이그레이션합니다.
**중요**
Amazon EBS CSI 드라이버의 스냅샷 기능을 사용하려면 먼저 CSI 스냅샷 컨트롤러를 설치해야 합니다. 자세한 내용은 [CSI 볼륨의 스냅샷 기능 활성화](csi-snapshot-controller.md) 섹션을 참조하세요.
## 사전 조건
+ 기존 클러스터가 있어야 합니다. 필요한 플랫폼 버전을 확인하려면 다음 명령을 실행합니다.
```
aws eks describe-addon-versions --addon-name aws-ebs-csi-driver
```
+ EBS CSI 드라이버에는 AWS IAM 권한이 필요합니다.
+ AWS는 EKS Pod Identity 사용을 제안합니다. 자세한 내용은 [EKS Pod Identity 설정 개요](pod-identities.md#pod-id-setup-overview) 섹션을 참조하세요.
+ 서비스 계정에 대한 IAM 역할에 대한 자세한 내용은 [클러스터에 대한 IAM OIDC 공급자 생성](enable-iam-roles-for-service-accounts.md) 섹션을 참조하세요.
## 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 permission](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/blob/master/docs/install.md#set-up-driver-permissions)을 참조하세요.
**참고**
IMDS에 대한 액세스 권한을 차단하지 않는 한 포드는 IAM 역할에 할당된 권한에 대한 액세스 권한이 있습니다. 자세한 내용은 [모범 사례로 Amazon EKS 클러스터 보호](security-best-practices.md) 섹션을 참조하세요.
다음 절차에서는 IAM 역할을 생성하고 AWS 관리형 정책을 연결하는 방법을 보여줍니다. 이 절차를 구현하려면 다음 도구 중 하나를 사용할 수 있습니다.
+ [`eksctl`](#eksctl_store_app_data)
+ [AWS Management Console](#console_store_app_data)
+ [AWS CLI](#awscli_store_app_data)
**참고**
범위가 더욱 축소된 권한으로 자체 관리형 정책을 생성할 수 있습니다. [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonEBSCSIDriverPolicyV2.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonEBSCSIDriverPolicyV2.html)를 검토하고 권한이 감소된 사용자 지정 IAM 정책을 생성합니다. `AmazonEBSCSIDriverPolicy`에서 마이그레이션할 경우 [EBS CSI 드라이버 정책 마이그레이션](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/issues/2918)을 참조하세요.
**참고**
이 절차의 특정 단계는 드라이버를 Amazon EKS 추가 기능으로 사용하기 위해 작성되었습니다. 드라이버를 자체 관리형 추가 기능으로 드라이버를 사용하려면 여러 단계가 필요합니다. 자세한 내용은 GitHub의 [Set up driver permissions](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/blob/master/docs/install.md#set-up-driver-permissions)를 참조하세요.
### `eksctl`
1. 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
```
1. 사용자 지정 [KMS 키](https://aws.amazon.com/kms/)를 사용하지 않는 경우 이 단계를 건너뛸 수 있습니다. Amazon EBS 볼륨의 암호화에 사용자 지정 KMS 키를 사용하는 경우 필요에 따라 IAM 역할을 사용자 지정합니다. 예를 들어, 다음을 수행합니다.
1. 다음 코드를 복사하여 새로운 `kms-key-for-encryption-on-ebs.json` 파일에 붙여 넣습니다. *custom-key-arn*을 사용자 지정 [KMS 키 ARN](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awskeymanagementservice.html#awskeymanagementservice-key)으로 바꿉니다.
```
{
"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"]
}
]
}
```
1. 정책을 생성합니다. *KMS\$1Key\$1For\$1Encryption\$1On\$1EBS\$1Policy*를 다른 이름으로 변경할 수 있습니다. 그러나 이렇게 하는 경우 이후 단계에서도 변경해야 합니다.
```
aws iam create-policy \
--policy-name KMS_Key_For_Encryption_On_EBS_Policy \
--policy-document file://kms-key-for-encryption-on-ebs.json
```
1. 다음 명령을 사용하여 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. IAM 콘솔(https://console.aws.amazon.com/iam/)을 엽니다.
1. 왼쪽 탐색 창에서 **역할**을 선택합니다.
1. **역할** 페이지에서 **역할 생성**을 선택합니다.
1. **신뢰할 수 있는 엔터티 선택** 페이지에서 다음을 수행합니다.
1. **신뢰할 수 있는 엔터티 유형** 섹션에서 **웹 자격 증명**을 선택합니다.
1. **아이덴티티 제공업체(Identity provider)**의 경우 클러스터에 대해 **OpenID Connect 공급자 URL(OpenID Connect provider URL)**을 선택합니다(Amazon EKS의 **개요**에 표시된 대로).
1. **대상**에서 `sts.amazonaws.com`을 입력합니다.
1. **다음**을 선택합니다.
1. **권한 추가** 페이지에서 다음을 수행합니다.
1. **필터 정책** 상자에 `AmazonEBSCSIDriverPolicyV2`를 입력합니다.
1. 검색에서 반환된 `AmazonEBSCSIDriverPolicyV2` 왼쪽에 있는 확인란을 선택합니다.
1. **다음**을 선택합니다.
1. **이름, 검토 및 생성** 페이지에서 다음을 수행합니다.
1. **역할 이름**에 역할의 고유한 이름(예: *AmazonEKS\$1EBS\$1CSI\$1DriverRole*)을 입력합니다.
1. **태그 추가(선택사항)**에서 태그를 키-값 페어로 연결하여 메타데이터를 역할에 추가합니다. IAM에서 태그 사용에 대한 자세한 내용을 알아보려면 [IAM 사용 설명서](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)의 *IAM 리소스에 태깅*을 참조하세요.
1. **역할 생성**을 선택합니다.
1. 역할을 생성한 후 편집할 수 있도록 콘솔에서 이 역할을 선택하여 엽니다.
1. **신뢰 관계** 탭을 선택한 후 **신뢰 정책 편집**을 선택합니다.
1. 다음과 비슷한 줄을 찾습니다.
```
"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:ebs-csi-controller-sa"
```
1. **신뢰 정책 업데이트**를 선택하여 종료합니다.
1. Amazon EBS 볼륨의 암호화에 사용자 지정 [KMS 키](https://aws.amazon.com/kms/)를 사용하는 경우 필요에 따라 IAM 역할을 사용자 지정합니다. 예를 들어, 다음을 수행합니다.
1. 왼쪽 탐색 창에서 **정책**을 선택합니다.
1. **정책** 페이지에서 **정책 생성**을 선택합니다.
1. **정책 생성** 페이지에서 **JSON** 탭을 선택합니다.
1. 다음 코드를 복사하여 편집기에 붙여 넣어 *custom-key-arn*을 사용자 지정 [KMS 키 ARN](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awskeymanagementservice.html#awskeymanagementservice-key)으로 바꿉니다.
```
{
"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"]
}
]
}
```
1. **다음: 태그**를 선택합니다.
1. **태그 추가(선택사항)** 페이지에서 **다음: 검토**를 선택합니다.
1. **이름**에 정책의 고유한 이름(예: *KMS\$1Key\$1For\$1Encryption\$1On\$1EBS\$1Policy*)을 입력합니다.
1. **정책 생성**을 선택합니다.
1. 왼쪽 탐색 창에서 **역할**을 선택합니다.
1. 콘솔에서 ** *AmazonEKS\$1EBS\$1CSI\$1DriverRole* **을 선택하여 열고 편집합니다.
1. **권한 추가** 드롭다운 목록에서 **정책 연결**을 선택합니다.
1. **정책 필터링** 상자에 *KMS\$1Key\$1For\$1Encryption\$1On\$1EBS\$1Policy*를 입력합니다.
1. 검색에서 반환된 *KMS\$1Key\$1For\$1Encryption\$1On\$1EBS\$1Policy* 왼쪽의 확인란을 선택합니다.
1. **정책 연결**을 선택합니다.
### AWS CLI
1. 클러스터의 OIDC 공급자 URL을 확인합니다. **을 클러스터 이름으로 바꿉니다. 명령의 출력이 `None`인 경우 **사전 요구 사항**을 검토합니다.
```
aws eks describe-cluster --name my-cluster --query "cluster.identity.oidc.issuer" --output text
```
예제 출력은 다음과 같습니다.
```
https://oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
```
1. IAM 역할을 생성하여 `AssumeRoleWithWebIdentity` 작업을 부여합니다.
1. 다음 콘텐츠를 `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"
}
}
}
]
}
```
1. 역할을 생성합니다. *AmazonEKS \$1EBS\$1CSI\$1DriverRole*을 다른 이름으로 변경할 수 있습니다. 변경하는 경우 이후 단계에서 변경해야 합니다.
```
aws iam create-role \
--role-name AmazonEKS_EBS_CSI_DriverRole \
--assume-role-policy-document file://"aws-ebs-csi-driver-trust-policy.json"
```
1. 정책을 연결합니다. AWS은(는) AWS 관리형 정책을 유지 관리하거나 자체 사용자 지정 정책을 생성할 수 있습니다. 다음 명령으로 AWS 관리형 정책을 역할에 연결합니다.
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicyV2 \
--role-name AmazonEKS_EBS_CSI_DriverRole
```
1. Amazon EBS 볼륨의 암호화에 사용자 지정 [KMS 키](https://aws.amazon.com/kms/)를 사용하는 경우 필요에 따라 IAM 역할을 사용자 지정합니다. 예를 들어, 다음을 수행합니다.
1. 다음 코드를 복사하여 새로운 `kms-key-for-encryption-on-ebs.json` 파일에 붙여 넣습니다. *custom-key-arn*을 사용자 지정 [KMS 키 ARN](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awskeymanagementservice.html#awskeymanagementservice-key)으로 바꿉니다.
```
{
"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"]
}
]
}
```
1. 정책을 생성합니다. *KMS\$1Key\$1For\$1Encryption\$1On\$1EBS\$1Policy*를 다른 이름으로 변경할 수 있습니다. 그러나 이렇게 하는 경우 이후 단계에서도 변경해야 합니다.
```
aws iam create-policy \
--policy-name KMS_Key_For_Encryption_On_EBS_Policy \
--policy-document file://kms-key-for-encryption-on-ebs.json
```
1. 다음 명령을 사용하여 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 권한이 할당된 Kubernetes `clusterrole`에 바인딩되어 있습니다.
## 2단계: Amazon EBS CSI 드라이버 받기
보안을 강화하고 작업량을 줄이려면 Amazon EKS 추가 기능을 통해 Amazon EBS CSI 드라이버를 설치하는 것이 좋습니다. Amazon EKS 추가 기능을 클러스터에 추가하려면 [Amazon EKS 추가 기능 생성](creating-an-add-on.md) 섹션을 참조하세요. Amazon EKS 추가 기능에 대한 자세한 내용은 [Amazon EKS 추가 기능](eks-add-ons.md) 섹션을 참조하세요.
**중요**
Amazon EBS 드라이버를 Amazon EKS 추가 기능으로 추가하기 전에 클러스터에 자체 관리형 버전의 드라이버가 설치되어 있지 않은지 확인하세요. 설치되어 있다면 GitHub의 [Uninstalling a self-managed Amazon EBS CSI driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/blob/master/docs/install.md#uninstalling-the-ebs-csi-driver)를 참조하세요.
**참고**
기본적으로 EBS CSI에서 사용하는 RBAC 역할에는 테인트 제거 기능을 지원하기 위해 노드를 변경할 권한이 있습니다. Kubernetes RBAC의 제한 사항으로 인해 이때 클러스터의 다른 노드도 변경할 수 있습니다. 헬름 차트에는 ebs-csi-node 서비스 계정에 대한 노드 RBAC 권한 변경을 비활성화하는 파라미터(`node.serviceAccount.disableMutation`)가 있습니다. 이를 활성화하면 테인트 제거와 같은 드라이버 기능이 작동하지 않습니다.
대신 Amazon EBS CSI 드라이버의 자체 관리형 설치를 원하는 경우 GitHub의 [Installation](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/blob/master/docs/install.md)을 참조하세요.
## 3단계: 샘플 애플리케이션 배포
다양한 샘플 앱을 배포하고 필요에 따라 수정할 수 있습니다. 자세한 내용은 GitHub의 [Kubernetes Examples](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/tree/master/examples/kubernetes)를 참조하세요.