KubernetesHow-ToBeginner · 4 min read

How to Use AWS EBS Volume in Kubernetes: Step-by-Step Guide

To use an AWS EBS volume in Kubernetes, create a PersistentVolume that references the EBS volume ID, then create a PersistentVolumeClaim to request storage. Finally, mount the claim in your pod's volumeMounts to use the EBS storage inside your container.

📐

Syntax

Using AWS EBS in Kubernetes involves three main parts:

PersistentVolume (PV): Defines the actual EBS volume details like volume ID, filesystem type, and access mode.
PersistentVolumeClaim (PVC): Requests storage from the PV with size and access mode.
Pod volumeMount: Mounts the PVC inside the container to use the storage.

yaml

apiVersion: v1
kind: PersistentVolume
metadata:
  name: ebs-pv
spec:
  capacity:
    storage: 10Gi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  awsElasticBlockStore:
    volumeID: <EBS_VOLUME_ID>
    fsType: ext4
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ebs-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: manual
  resources:
    requests:
      storage: 10Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: ebs-pod
spec:
  containers:
  - name: app
    image: nginx
    volumeMounts:
    - mountPath: "/mnt/data"
      name: ebs-volume
  volumes:
  - name: ebs-volume
    persistentVolumeClaim:
      claimName: ebs-pvc

💻

Example

This example shows how to use an existing AWS EBS volume in Kubernetes by creating a PersistentVolume, PersistentVolumeClaim, and a Pod that mounts the volume at /mnt/data.

yaml

apiVersion: v1
kind: PersistentVolume
metadata:
  name: ebs-pv
spec:
  capacity:
    storage: 5Gi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  awsElasticBlockStore:
    volumeID: vol-0abcd1234efgh5678
    fsType: ext4
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ebs-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: manual
  resources:
    requests:
      storage: 5Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: ebs-example-pod
spec:
  containers:
  - name: nginx-container
    image: nginx
    volumeMounts:
    - mountPath: "/mnt/data"
      name: ebs-storage
  volumes:
  - name: ebs-storage
    persistentVolumeClaim:
      claimName: ebs-pvc

Output

pod/ebs-example-pod created persistentvolumeclaim/ebs-pvc created persistentvolume/ebs-pv created

⚠️

Common Pitfalls

Common mistakes when using AWS EBS volumes in Kubernetes include:

Using the wrong volumeID format or a volume that is not in the same availability zone as the Kubernetes node.
Not matching storageClassName between PV and PVC, causing binding failure.
Trying to mount the same EBS volume to multiple pods simultaneously with ReadWriteOnce access mode, which only allows single node attachment.
Forgetting to set the correct fsType matching the EBS volume filesystem.

Example of a wrong and right storageClassName:

yaml

apiVersion: v1
kind: PersistentVolume
metadata:
  name: ebs-pv
spec:
  storageClassName: manual
  awsElasticBlockStore:
    volumeID: vol-0abcd1234efgh5678
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ebs-pvc
spec:
  storageClassName: wrong-class  # This causes binding failure
---
# Correct PVC
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ebs-pvc
spec:
  storageClassName: manual  # Must match PV's storageClassName

📊

Quick Reference

Tips for using AWS EBS volumes in Kubernetes:

Ensure EBS volume is in the same availability zone as your Kubernetes nodes.
Use ReadWriteOnce access mode because EBS supports single node attachment.
Set persistentVolumeReclaimPolicy to Retain to keep data after PV deletion.
Match storageClassName exactly between PV and PVC.
Format EBS volume with a supported filesystem like ext4.

✅

Key Takeaways

Create a PersistentVolume referencing the AWS EBS volume ID with correct fsType and access mode.

Create a PersistentVolumeClaim matching the PersistentVolume's storageClassName and size.

Mount the PersistentVolumeClaim in your pod to use the EBS volume storage inside containers.

Ensure the EBS volume and Kubernetes nodes are in the same availability zone.

Use ReadWriteOnce access mode because EBS volumes can only be attached to one node at a time.