Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Create a storage class

A StorageClass in Amazon EKS Auto Mode defines how Amazon EBS volumes are automatically provisioned when applications request persistent storage. This page explains how to create and configure a StorageClass that works with the Amazon EKS Auto Mode to provision EBS volumes.

By configuring a StorageClass, you can specify default settings for your EBS volumes including volume type, encryption, IOPS, and other storage parameters. You can also configure the StorageClass to use AWS KMS keys for encryption management.

EKS Auto Mode does not create a StorageClass for you. You must create a StorageClass referencing ebs.csi.eks.amazonaws.com to use the storage capability of EKS Auto Mode.

First, create a file named 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"

Second, apply the storage class to your cluster.

kubectl apply -f storage-class.yaml

Key components:

Use self-managed KMS key to encrypt EBS volumes

To use a self-managed KMS key to encrypt EBS volumes automated by EKS Auto Mode, you need to:

Sample self-managed KMS IAM Policy

Update the following values in the policy below:

{
  "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"
            }
        }
    }
  ]
}

Sample self-managed KMS StorageClass

parameters:
  type: gp3
  encrypted: "true"
  kmsKeyId: <custom-key-arn>

StorageClass Parameters Reference

For general information on the Kubernetes StorageClass resources, see Storage Classes in the Kubernetes Documentation.

The parameters section of the StorageClass resource is specific to AWS. Use the following table to review available options.

For more information, see the AWS EBS CSI Driver on GitHub.

Considerations

The block storage capability of EKS Auto Mode is different from the EBS CSI Driver.

Migrate from volume-modifier-for-k8s to VolumeAttributesClass

For EKS Auto Mode clusters running Kubernetes 1.34 or later, use a VolumeAttributesClass (VAC) to change an EBS volume’s type, IOPS, or throughput.

Existing PVCs can be migrated in place by creating a VAC and setting spec.volumeAttributesClassName on the existing PVC. The PVC and PV are not recreated and there are no interruptions to your workloads during this process.

Optional: Remove the VMK annotations

Removing the old annotations is not required for VAC to work. Once a PVC or PV references a VAC, VMK refuses annotation-based modifications and VAC is the authoritative path.

The annotations may be removed later as configuration cleanup. If they are removed, also update any Helm, GitOps, or other automation that would add them back. VMK status annotations left on the PV are harmless and do not need to be removed.

Changing or Reverting the Settings

VAC parameters are immutable. To change the EBS configuration, create another VAC and assign its name to the PVC.

To cancel a change that has not completed, restore the previously assigned VAC. If the PVC did not previously use one, clear the field:

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

Clearing the field does not undo an EBS modification that already completed. To restore previous volume settings, create a VAC containing those settings and assign it to the PVC. Normal EBS parameter constraints and modification cooldowns apply.

Install CSI Snapshot Controller add-on

EKS Auto Mode is compatible with the CSI Snapshot Controller Amazon EKS add-on.

AWS suggests you configure this add-on to run on the built-in system node pool.

For more information, see:

To install snapshot controller in system node pool