스토리지 클래스 생성하기

Amazon EKS Auto Mode의 StorageClass는 애플리케이션이 영구 스토리지를 요청할 때 Amazon EBS 볼륨이 자동으로 프로비저닝되는 방식을 정의합니다. 이 페이지는 Amazon EKS Auto Mode와 함께 작동하여 EBS 볼륨을 프로비저닝하는 StorageClass를 생성·구성하는 방법을 설명합니다.

StorageClass를 구성하면 볼륨 유형, 암호화, IOPS 및 기타 스토리지 매개변수를 포함한 EBS 볼륨의 기본 설정을 지정할 수 있어요. 또한 암호화 관리를 위해 AWS KMS 키를 사용하도록 StorageClass를 구성할 수 있습니다.

EKS Auto Mode는 StorageClass를 자동으로 만들지 않습니다. EKS Auto Mode의 스토리지 기능을 사용하려면 ebs.csi.eks.amazonaws.com을 참조하는 StorageClass를 직접 만들어야 해요.

출처: 문서

본문

먼저 storage-class.yaml이라는 파일을 만듭니다.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: auto-ebs-sc
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
allowedTopologies:
- matchLabelExpressions:
  - key: eks.amazonaws.com/compute-type
    values:
    - auto
provisioner: ebs.csi.eks.amazonaws.com
volumeBindingMode: WaitForFirstConsumer
parameters:
  type: gp3
  encrypted: "true"

둘째, 스토리지 클래스를 클러스터에 적용합니다.

kubectl apply -f storage-class.yaml

핵심 구성 요소:

provisioner: ebs.csi.eks.amazonaws.com — EKS Auto Mode를 사용합니다.
allowedTopologies — eks.amazonaws.com/compute-type:auto에 대해 일치하도록 matchLabelExpressions를 지정하면, Pod가 Auto Mode를 사용해 볼륨을 자동 프로비저닝해야 할 때 비 Auto 노드에 스케줄링되지 않도록 보장합니다.
volumeBindingMode: WaitForFirstConsumer — Pod가 필요로 할 때까지 볼륨 생성을 지연합니다.
type: gp3 — EBS 볼륨 유형을 지정합니다.
encrypted: "true" — EBS가 StorageClass를 사용해 만든 모든 볼륨을 암호화합니다. EBS는 기본 aws/ebs 키 별칭을 사용합니다. 자세한 내용은 Amazon EBS User Guide의 How Amazon EBS encryption works를 참고하세요. 이 값은 선택 사항이지만 권장됩니다.
storageclass.kubernetes.io/is-default-class: "true" — 영구 볼륨 클레임에 다른 볼륨 클래스를 지정하지 않는 한 Kubernetes가 기본적으로 이 스토리지 클래스를 사용합니다. 이 값은 선택 사항입니다. 다른 스토리지 컨트롤러에서 마이그레이션하는 경우 이 값을 설정할 때 주의하세요.

자체 관리형 KMS 키로 EBS 볼륨 암호화

EKS Auto Mode가 자동화한 EBS 볼륨을 암호화하는 데 자체 관리형 KMS 키를 사용하려면 다음을 해야 합니다.

자체 관리형 KMS 키를 만듭니다. 자세한 내용은 KMS User Guide의 Create a symmetric encryption KMS key 또는 How Amazon Elastic Block Store (Amazon EBS) uses KMS를 참고하세요.
KMS 키에 대한 접근을 허용하는 새 정책을 만듭니다. 아래 샘플 IAM 정책으로 정책을 만듭니다. 새 자체 관리형 KMS 키의 ARN을 삽입하세요. 자세한 내용은 AWS IAM User Guide의 Creating roles and attaching policies (console)를 참고하세요.
정책을 EKS Cluster Role에 연결합니다. AWS 콘솔을 사용해 EKS Cluster Role의 ARN을 찾으세요. 역할 정보는 Overview 섹션에서 볼 수 있어요. 자세한 내용은 Amazon EKS cluster IAM role를 참고하세요.
StorageClass를 업데이트해 parameters.kmsKeyId 필드에서 KMS Key ID를 참조합니다.

샘플 자체 관리형 KMS IAM 정책 — 정책에서 다음 값을 업데이트하세요.

`` — AWS 계정 ID, 예: 111122223333
`` — 클러스터의 AWS 리전, 예: us-west-2

{
  "Version":"2012-10-17",
  "Id": "key-auto-policy-3",
  "Statement": [
      {
          "Sid": "Enable IAM User Permissions",
          "Effect": "Allow",
          "Principal": {
              "AWS": "arn:aws:iam::123456789012:root"
          },
          "Action": "kms:*",
          "Resource": "*"
      },
      {
        "Sid": "Allow access through EBS for all principals in the account that are authorized to use EBS",
        "Effect": "Allow",
        "Principal": {
            "AWS": "*"
        },
        "Action": [
            "kms:Encrypt",
            "kms:Decrypt",
            "kms:ReEncrypt*",
            "kms:GenerateDataKey*",
            "kms:CreateGrant",
            "kms:DescribeKey"
        ],
        "Resource": "*",
        "Condition": {
            "StringEquals": {
                "kms:CallerAccount": "123456789012",
                "kms:ViaService": "ec2.us-east-1.amazonaws.com"
            }
        }
    }
  ]
}

샘플 자체 관리형 KMS StorageClass

parameters:
  type: gp3
  encrypted: "true"
  kmsKeyId:

`StorageClass` 매개변수 참조

Kubernetes StorageClass 리소스에 대한 일반 정보는 Kubernetes Documentation의 Storage Classes를 참고하세요.

StorageClass 리소스의 parameters 섹션은 AWS 특화입니다. 다음 표로 사용 가능한 옵션을 검토하세요.

매개변수	값	기본값	설명
"csi.storage.k8s.io/fstype"	xfs, ext2, ext3, ext4	ext4	볼륨 생성 중 포맷될 파일 시스템 유형. 대소문자 구분!
"type"	io1, io2, gp2, gp3, sc1, st1, standard, sbp1, sbg1	gp3	EBS 볼륨 유형
"iopsPerGB"			GiB당 I/O 작업 수. IO1, IO2, GP3 볼륨에 지정할 수 있음
"allowAutoIOPSPerGBIncrease"	true, false	false	`"true"`이면 CSI 드라이버가 `iopsPerGB *`가 AWS가 지원하는 IOPS 범위에 맞지 않을 정도로 낮을 때 볼륨의 IOPS를 증가시킵니다. 사용자가 너무 작은 PVC 용량이나 `iopsPerGB` 값을 지정해도 동적 프로비저닝이 항상 성공하게 합니다. 반면 `iopsPerGB`에 요청된 것보다 높은 IOPS를 가지므로 추가 비용이 발생할 수 있습니다.
"iops"			초당 I/O 작업 수. IO1, IO2, GP3 볼륨에 지정할 수 있음
"throughput"		125	MiB/s 단위 처리량. gp3 볼륨 유형이 지정된 경우에만 유효
"encrypted"	true, false	false	볼륨 암호화 여부. 유효한 값은 "true" 또는 "false"
"blockExpress"	true, false	false	io2 Block Express 볼륨 생성을 활성화
"kmsKeyId"			볼륨 암호화 시 사용할 키의 전체 ARN. 지정하지 않으면 AWS가 볼륨이 있는 리전의 기본 KMS 키를 사용. 변경하지 않으면 `/aws/ebs`라는 자동 생성 키가 됨
"blockSize"			기반 파일 시스템 포맷 시 사용할 블록 크기. Linux 노드와 fstype `ext2`, `ext3`, `ext4`, `xfs`에서만 지원
"inodeSize"			기반 파일 시스템 포맷 시 사용할 inode 크기. Linux 노드와 fstype `ext2`, `ext3`, `ext4`, `xfs`에서만 지원
"bytesPerInode"			기반 파일 시스템 포맷 시 사용할 `bytes-per-inode`. Linux 노드와 fstype `ext2`, `ext3`, `ext4`에서만 지원
"numberOfInodes"			기반 파일 시스템 포맷 시 사용할 `number-of-inodes`. Linux 노드와 fstype `ext2`, `ext3`, `ext4`에서만 지원
"ext4BigAlloc"	true, false	false	`bigalloc` 포맷 옵션을 활성화해 `ext4` 파일 시스템이 클러스터 블록 할당을 사용하도록 변경합니다. 경고: `bigalloc`은 노드의 Linux 커널에서 완전히 지원되지 않을 수 있습니다.
"ext4ClusterSize"			`bigalloc` 기능이 활성화된 경우 `ext4` 파일 시스템 포맷 시 사용할 클러스터 크기. 참고: `ext4BigAlloc` 매개변수를 true로 설정해야 합니다.

자세한 내용은 GitHub의 AWS EBS CSI Driver를 참고하세요.

고려 사항

Note: EKS Auto Mode StorageClass에 의존하는 워크로드는 EKS Auto Mode 노드에만 배포할 수 있어요. 혼합 노드 유형의 클러스터가 있다면 워크로드가 EKS Auto Mode 노드에서만 실행되도록 구성해야 합니다. 자세한 내용은 Control if a workload is deployed on EKS Auto Mode nodes를 참고하세요.

EKS Auto Mode의 블록 스토리지 기능은 EBS CSI Driver와 다릅니다.
정적 프로비저닝: 외부에서 생성한 EBS 볼륨을 EKS Auto Mode와 함께 사용하려면 키 eks:eks-cluster-name, 값은 클러스터 이름인 AWS 태그를 수동으로 추가해야 합니다.
노드 시작 taint: 스토리지 기능 준비 전 Pod 스케줄링을 방지하기 위해 노드 시작 taint 기능을 사용할 수 없습니다.
동적으로 프로비저닝된 볼륨의 커스텀 태그: extra-tag CLI 플래그로 동적 프로비저닝된 EBS 볼륨에 커스텀 태그를 구성할 수 없습니다. StorageClass 태깅으로 커스텀 태그를 추가할 수 있어요. EKS Auto Mode가 관련 AWS 리소스에 태그를 추가합니다. 커스텀 태그에 대해 Cluster IAM Role을 업데이트해야 합니다. 자세한 내용은 Custom AWS tags for EKS Auto resources를 참고하세요.
EBS 상세 성능 메트릭: EBS 상세 성능용 Prometheus 메트릭에 접근할 수 없습니다.

어노테이션 기반 EBS 볼륨 수정은 더 이상 사용되지 않음

volume-modifier-for-k8s 프로젝트는 네이티브 Kubernetes VolumeAttributesClass API를 위해 더 이상 사용되지 않습니다(deprecated). 이 프로젝트는 PersistentVolumeClaim에 어노테이션을 설정해 EBS 볼륨을 수정하는 데 사용됐어요. 2026년 10월 31일 이후 Amazon EKS Auto Mode는 더 이상 이러한 어노테이션을 지원하지 않습니다. 그 이후 EBS 볼륨을 수정하려면(예: type, iops, throughput) 대신 Kubernetes VolumeAttributesClass API를 사용하세요. 자세한 내용은 Kubernetes 문서의 Volume Attributes Classes를 참고하세요.

volume-modifier-for-k8s에서 VolumeAttributesClass로 마이그레이션

Kubernetes 1.34 이상을 실행하는 EKS Auto Mode 클러스터에서는 VolumeAttributesClass(VAC)를 사용해 EBS 볼륨의 유형, IOPS, 처리량을 변경합니다.

기존 PVC는 VAC를 만들고 기존 PVC에 spec.volumeAttributesClassName을 설정해 제자리에서 마이그레이션할 수 있습니다. 이 과정에서 PVC와 PV가 다시 생성되지 않으며 워크로드 중단이 없어요.

VAC에서 볼륨 설정 정의 — VMK 어노테이션은 VAC 매개변수에 다음과 같이 매핑됩니다.

기존 VMK 어노테이션	VAC 매개변수
`ebs.csi.eks.amazonaws.com/volumeType`	type
`ebs.csi.eks.amazonaws.com/iops`	iops
`ebs.csi.eks.amazonaws.com/throughput`	throughput

VAC에서 volumeType이 아닌 type을 사용하세요. 값은 문자열이어야 하며, VAC는 원하는 EBS 구성과 관련된 매개변수만 필요합니다. 예:

apiVersion: storage.k8s.io/v1
kind: VolumeAttributesClass
metadata:
  name: ebs-auto-gp3-6000-250
driverName: ebs.csi.eks.amazonaws.com
parameters:
  type: gp3
  iops: "6000"
  throughput: "250"

VAC는 클러스터 범위이므로 매니페스트에 네임스페이스가 없습니다. 정상적으로 적용합니다.

kubectl apply -f vac.yaml

PVC에 VAC 할당

VAC_NAME=ebs-auto-gp3-6000-250

kubectl patch pvc <PVC_NAME> \
 -n <NAMESPACE> --type=merge \
  -p "{\"spec\":{\"volumeAttributesClassName\":\"${VAC_NAME}\"}}"

변경 완료 확인

kubectl get pvc <PVC_NAME> \
 -n <NAMESPACE> \
  -o custom-columns='NAME:.metadata.name,REQUESTED:.spec.volumeAttributesClassName,CURRENT:.status.currentVolumeAttributesClassName,STATUS:.status.modifyVolumeStatus.status'

REQUESTED와 CURRENT에 같은 VAC 이름이 포함되고 STATUS가 비어 있으면 마이그레이션이 완료된 것입니다.

완료되지 않으면 PVC 이벤트를 검사하세요.

kubectl describe pvc <PVC_NAME> \
 -n <NAMESPACE>

Pending은 보통 참조된 VAC를 사용할 수 없음을 의미합니다. Infeasible은 드라이버가 요청된 EBS 매개변수를 거부했음을 의미합니다. 유효한 VAC를 만들어 대신 할당하세요.

(선택) VMK 어노테이션 제거 — VAC가 작동하는 데 이전 어노테이션 제거는 필요하지 않습니다. PVC나 PV가 VAC를 참조하면 VMK는 어노테이션 기반 수정을 거부하고 VAC가 권위 있는 경로가 됩니다. 어노테이션은 나중에 구성 정리로 제거할 수 있어요. 제거한다면 다시 추가할 Helm, GitOps 또는 기타 자동화도 업데이트해야 합니다. PV에 남은 VMK 상태 어노테이션은 무해하며 제거할 필요가 없습니다.

설정 변경 또는 되돌리기 — VAC 매개변수는 불변입니다. EBS 구성을 변경하려면 다른 VAC를 만들고 그 이름을 PVC에 할당하세요.

완료되지 않은 변경을 취소하려면 이전에 할당된 VAC를 복원합니다. PVC가 이전에 VAC를 사용하지 않았다면 필드를 지웁니다.

kubectl patch pvc <PVC_NAME> \
 -n <NAMESPACE> --type=merge \
  -p '{"spec":{"volumeAttributesClassName":null}}'

필드를 지워도 이미 완료된 EBS 수정은 되돌리지 않습니다. 이전 볼륨 설정을 복원하려면 그 설정이 포함된 VAC를 만들어 PVC에 할당하세요. 정상적인 EBS 매개변수 제약과 수정 쿨다운이 적용됩니다.

CSI Snapshot Controller 애드온 설치

EKS Auto Mode는 CSI Snapshot Controller Amazon EKS 애드온과 호환됩니다. AWS는 이 애드온이 내장 system 노드 풀에서 실행되도록 구성할 것을 권장합니다. 자세한 내용은 다음을 참고하세요.

Run critical add-ons on dedicated instances
Enable or Disable Built-in NodePools
Enable snapshot functionality for CSI volumes

시스템 노드 풀에 snapshot controller 설치:

AWS 콘솔에서 EKS 클러스터를 엽니다.
Add-ons 탭에서 Get more add-ons를 선택합니다.
CSI Snapshot Controller를 선택하고 Next를 선택합니다.
Configure selected add-ons settings 페이지에서 Optional configuration settings를 선택해 Add-on 구성 스키마를 봅니다.
snapshot controller를 system 노드 풀과 연결하려면 다음 yaml을 삽입합니다. snapshot controller는 CriticalAddonsOnly taint에 대한 toleration을 포함합니다.

{
        "nodeSelector": {
            "karpenter.sh/nodepool": "system"
        }
}

Next를 선택합니다.
애드온 구성을 검토하고 Create를 선택합니다.

더 알아보기 (Learn more)

공식 문서

스토리지 클래스 생성하기