Configure AWS EBS Storage for Kubernetes

Estimated reading time: 4 minutes

This topic applies to Docker Enterprise.

The Docker Enterprise platform business, including products, customers, and employees, has been acquired by Mirantis, inc., effective 13-November-2019. For more information on the acquisition and how it may affect you and your business, refer to the Docker Enterprise Customer FAQ.

AWS Elastic Block Store (EBS) can be deployed with Kubernetes in Docker Enterprise 2.1 to use AWS volumes as peristent storage for applications. Before using EBS volumes, configure UCP and the AWS infrastructure for storage orchestration to function.

Configure AWS Infrastructure for Kubernetes

Kubernetes Cloud Providers provide a method of provisioning cloud resources through Kubernetes via the --cloud-provider option. In AWS, this flag allows the provisioning of EBS volumes and cloud load balancers.

Configuring a cluster for AWS requires several specific configuration parameters in the infrastructure before installing UCP.

AWS IAM Permissions

Instances must have the following AWS Identity and Access Management permissions configured to provision EBS volumes through Kubernetes PVCs.

Master Worker
ec2:DescribeInstances ec2:DescribeInstances
ec2:AttachVolume ec2:AttachVolume
ec2:DetachVolume ec2:DetachVolume
ec2:DescribeVolumes ec2:DescribeVolumes
ec2:CreateVolume ec2:DescribeSecurityGroups

Infrastructure Configuration

  • Apply the roles and policies to Kubernetes masters and workers as indicated in the above chart.
  • Set the hostname of the EC2 instances to the private DNS hostname of the instance. See DNS Hostnames and To change the system hostname without a public DNS name for more details.
  • Label the EC2 instances with the key KubernetesCluster and assign the same value across all nodes, for example, UCPKubenertesCluster.

Cluster Configuration

  • In addition to your existing install flags, the cloud provider flag --cloud-provider=aws is required at install time.
  • The cloud provider can also be enabled post-install through the UCP config. The ucp-agent needs to be updated to propogate the new config, as described in UCP configuration file.


  cloud_provider = "aws"

Deploy AWS EBS Volumes

After configuring UCP for the AWS cloud provider, you can create persistent volumes that deploy EBS volumes attached to hosts and mounted inside pods. The EBS volumes are provisioned dynamically such they are created, attached, destroyed along with the lifecycle of the persistent volumes. This does not require users to directly access to the AWS as you request these resources directly through Kubernetes primitives.

We recommend you use the StorageClass and PersistentVolumeClaim resources as these abstraction layers provide more portability as well as control over the storage layer across environments.

To learn more about storage concepts in Kubernetes, see Storage - Kubernetes.

Creating a Storage Class

A StorageClass lets administrators describe “classes” of storage available in which classes map to quality-of-service levels, or backup policies, or any policies required by cluster administrators. The following StorageClass maps a “standard” class of storage to the gp2 type of storage in AWS EBS.

kind: StorageClass
  name: standard
  type: gp2
reclaimPolicy: Retain
  - debug

For descriptions of AWS EBS parameters, see Storage Classes.

Creating a Persistent Volume Claim

A PersistentVolumeClaim (PVC) is a claim for storage resources that are bound to a PersistentVolume (PV) when storage resources are granted. The following PVC makes a request for 1Gi of storage from the standard storage class.

kind: PersistentVolumeClaim
apiVersion: v1
  name: task-pv-claim
  storageClassName: standard
    - ReadWriteOnce
      storage: 1Gi

Deploying a Persistent Volume

The following Pod spec references the PVC task-pv-claim from above which references the standard storage class in this cluster.

kind: Pod
apiVersion: v1
  name: task-pv-pod
    - name: task-pv-storage
       claimName: task-pv-claim
    - name: task-pv-container
      image: nginx
        - containerPort: 80
          name: "http-server"
        - mountPath: "/usr/share/nginx/html"
          name: task-pv-storage

Inspecting and Using PVs

Once the pod is deployed, run the following kubectl command to verify the PV was created and bound to the PVC.

kubectl get pv
NAME                                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS    CLAIM                   STORAGECLASS   REASON    AGE
pvc-751c006e-a00b-11e8-8007-0242ac110012   1Gi        RWO            Retain           Bound     default/task-pv-claim   standard                 3h

The AWS console shows a volume has been provisioned having a matching name with type gp2 and a 1GiB size.

Where to go next

UCP, Docker Enterprise, Kubernetes, storage, AWS, ELB