EKS Auto Mode: Migrate EBS Volume Modifications to VolumeAttributesClass

Amazon EKS Auto Mode is ending support for annotation-based EBS volume modifications after October 31, 2026. If your automation changes volume type, IOPS, or throughput through volume-modifier-for-k8s annotations, migrate to Kubernetes VolumeAttributesClass before that date.

This is specifically about modifying EBS volumes managed by the EKS Auto Mode provisioner, ebs.csi.eks.amazonaws.com. Do not confuse it with migrating volumes from the standard Amazon EBS CSI driver, ebs.csi.aws.com, which is a separate workflow.

What is changing

The old annotations map to VolumeAttributesClass parameters:

For EKS Auto Mode clusters on Kubernetes 1.34 or later, AWS documents an in-place migration: create a VolumeAttributesClass and set spec.volumeAttributesClassName on the existing PVC. The PVC and PV are not recreated, and the workload does not need to be interrupted for this field change.

Normal EBS modification constraints and cooldowns still apply.

Inventory affected PVCs

Find PVCs that still carry the old annotations:

kubectl get pvc -A -o json | jq -r '
  .items[]
  | select(.metadata.annotations // {} | keys[]? | startswith("ebs.csi.eks.amazonaws.com/"))
  | [
      .metadata.namespace,
      .metadata.name,
      (.metadata.annotations["ebs.csi.eks.amazonaws.com/volumeType"] // ""),
      (.metadata.annotations["ebs.csi.eks.amazonaws.com/iops"] // ""),
      (.metadata.annotations["ebs.csi.eks.amazonaws.com/throughput"] // "")
    ]
  | @tsv
'

Confirm the bound PV uses the Auto Mode driver:

PV=$(kubectl get pvc app-data -n production -o jsonpath='{.spec.volumeName}')
kubectl get pv "$PV" -o jsonpath='{.spec.csi.driver}{"\n"}'

Proceed only when the result matches ebs.csi.eks.amazonaws.com.

Create a VolumeAttributesClass

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"

Use type, not volumeType, and quote parameter values as strings. VolumeAttributesClass objects are cluster-scoped, so they do not have a namespace.

kubectl apply -f ebs-auto-gp3-6000-250.yaml
kubectl get volumeattributesclass ebs-auto-gp3-6000-250

The parameters of an existing class are immutable. Create another class when you need a different performance tier. Stable names such as gp3-standard and gp3-high-throughput are usually easier to operate than embedding an application name.

Assign the class to an existing PVC

VAC_NAME=ebs-auto-gp3-6000-250
 
kubectl patch pvc app-data -n production --type=merge \
  -p "{\"spec\":{\"volumeAttributesClassName\":\"${VAC_NAME}\"}}"

Watch the requested and current values:

kubectl get pvc app-data -n production \
  -o custom-columns='NAME:.metadata.name,REQUESTED:.spec.volumeAttributesClassName,CURRENT:.status.currentVolumeAttributesClassName,STATUS:.status.modifyVolumeStatus.status'

The migration has completed when REQUESTED and CURRENT match and STATUS is empty.

If it does not complete:

kubectl describe pvc app-data -n production

Pending commonly means the requested class is unavailable. Infeasible means the CSI driver rejected the parameters. Create a valid class and assign that class instead of editing the immutable parameters.

Remove legacy automation

After validating the new path:

1. update Helm values, Kustomize patches, Terraform, and GitOps repositories that add VMK annotations;
2. stop controllers or jobs that continuously restore those annotations;
3. remove old annotations as configuration cleanup;
4. alert when a PVC has a requested class that does not converge to its current class.

AWS says old status annotations on the PV are harmless. Once a PVC or PV references a VolumeAttributesClass, that becomes the authoritative modification path.

Rollback is not the same as undo

To cancel a modification that has not completed, restore the previous class. If the PVC did not previously use one, clear the field:

kubectl patch pvc app-data -n production --type=merge \
  -p '{"spec":{"volumeAttributesClassName":null}}'

Clearing the field does not undo an EBS change that already completed. To restore previous settings, create a new class with those settings and assign it, subject to EBS limits and cooldowns.

Migration checklist

• Confirm Kubernetes 1.34 or later for the documented EKS Auto Mode path.
• Inventory legacy annotations and owning GitOps sources.
• Confirm the PV uses ebs.csi.eks.amazonaws.com.
• Create reviewed VolumeAttributesClass tiers.
• Migrate one non-production PVC first.
• Wait for requested and current class names to converge.
• Validate application latency and volume performance.
• Migrate production claims in controlled batches.
• Remove annotation-producing automation before October 31, 2026.

Building deeper AWS delivery and operations skills? Explore this AWS DevOps Engineer Professional preparation course on Udemy. Affiliate link: DevOpsBoys may earn a commission at no extra cost to you.

Sources

• Amazon EKS: Create a storage class and migrate to VolumeAttributesClass
• Amazon EKS Auto Mode release notes
• Kubernetes: Volume Attributes Classes
• Kubernetes API: VolumeAttributesClass