AWS Volumes Configuration

The AWS volumes customization allows the user to specify configuration for both root and non-root storage volumes for AWS machines. The volumes customization can be applied to both control plane and worker machines. This customization will be available when the provider-specific cluster configuration patch is included in the ClusterClass.

Configuration Options

The volumes configuration supports two types of volumes:

Root Volume: The primary storage volume for the instance (typically /dev/sda1)
Non-Root Volumes: Additional storage volumes that can be attached to the instance

Volume Configuration Fields

Each volume can be configured with the following fields:

Field	Type	Required	Description	Default
`deviceName`	string	No	Device name for the volume (e.g., `/dev/sda1`, `/dev/sdf`)	-
`size`	int64	No	Size in GiB (minimum 8)	Based on AMI, usually 20GiB
`type`	string	No	EBS volume type (`gp2`, `gp3`, `io1`, `io2`)	-
`iops`	int64	No	IOPS for provisioned volumes (io1, io2, gp3)	-
`throughput`	int64	No	Throughput in MiB/s (gp3 only)	-
`encrypted`	bool	No	Whether the volume should be encrypted	false
`encryptionKey`	string	No	KMS key ID or ARN for encryption	AWS default key

Supported Volume Types

gp2: General Purpose SSD (up to 16,000 IOPS)
gp3: General Purpose SSD with configurable IOPS and throughput
io1: Provisioned IOPS SSD (up to 64,000 IOPS)
io2: Provisioned IOPS SSD with higher durability (up to 64,000 IOPS)

Examples

Root Volume Only

To specify only a root volume configuration:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <NAME>
spec:
  topology:
    variables:
      - name: clusterConfig
        value:
          controlPlane:
            aws:
              volumes:
                root:
                  deviceName: "/dev/sda1"
                  size: 100
                  type: "gp3"
                  iops: 3000
                  throughput: 125
                  encrypted: true
                  encryptionKey: "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012"
      - name: workerConfig
        value:
          aws:
            volumes:
              root:
                size: 200
                type: "gp3"
                iops: 4000
                throughput: 250
                encrypted: true

Non-Root Volumes Only

To specify only additional non-root volumes:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <NAME>
spec:
  topology:
    variables:
      - name: clusterConfig
        value:
          controlPlane:
            aws:
              volumes:
                nonroot:
                  - deviceName: "/dev/sdf"
                    size: 500
                    type: "gp3"
                    iops: 4000
                    throughput: 250
                    encrypted: true
                  - deviceName: "/dev/sdg"
                    size: 1000
                    type: "gp2"
                    encrypted: false
      - name: workerConfig
        value:
          aws:
            volumes:
              nonroot:
                - deviceName: "/dev/sdf"
                  size: 200
                  type: "io1"
                  iops: 10000
                  encrypted: true

Both Root and Non-Root Volumes

To specify both root and non-root volumes:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <NAME>
spec:
  topology:
    variables:
      - name: clusterConfig
        value:
          controlPlane:
            aws:
              volumes:
                root:
                  size: 100
                  type: "gp3"
                  iops: 3000
                  throughput: 125
                  encrypted: true
                nonroot:
                  - deviceName: "/dev/sdf"
                    size: 500
                    type: "gp3"
                    iops: 4000
                    throughput: 250
                    encrypted: true
                  - deviceName: "/dev/sdg"
                    size: 1000
                    type: "gp2"
                    encrypted: false
      - name: workerConfig
        value:
          aws:
            volumes:
              root:
                size: 200
                type: "gp3"
                iops: 4000
                throughput: 250
                encrypted: true
              nonroot:
                - deviceName: "/dev/sdf"
                  size: 100
                  type: "io1"
                  iops: 10000
                  encrypted: true

MachineDeployment Overrides

You can customize individual MachineDeployments by using the overrides field:

spec:
  topology:
    # ...
    workers:
      machineDeployments:
        - class: default-worker
          name: md-0
          variables:
            overrides:
              - name: workerConfig
                value:
                  aws:
                    volumes:
                      root:
                        size: 500
                        type: "gp3"
                        iops: 10000
                        throughput: 500
                        encrypted: true
                      nonroot:
                        - deviceName: "/dev/sdf"
                          size: 1000
                          type: "io2"
                          iops: 20000
                          encrypted: true

Resulting CAPA Configuration

Applying the volumes configuration will result in the following values being set in the AWSMachineTemplate:

Root Volume Configuration

When a root volume is specified, it will be set in the rootVolume field:

spec:
  template:
    spec:
      rootVolume:
        deviceName: "/dev/sda1"
        size: 100
        type: "gp3"
        iops: 3000
        throughput: 125
        encrypted: true
        encryptionKey: "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012"

Non-Root Volumes Configuration

When non-root volumes are specified, they will be set in the nonRootVolumes field:

spec:
  template:
    spec:
      nonRootVolumes:
        - deviceName: "/dev/sdf"
          size: 500
          type: "gp3"
          iops: 4000
          throughput: 250
          encrypted: true
        - deviceName: "/dev/sdg"
          size: 1000
          type: "gp2"
          encrypted: false

EKS Configuration

For EKS clusters, the volumes configuration follows the same structure but is specified under the EKS worker configuration:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <NAME>
spec:
  topology:
    variables:
      - name: workerConfig
        value:
          eks:
            volumes:
              root:
                size: 200
                type: "gp3"
                iops: 4000
                throughput: 250
                encrypted: true
              nonroot:
                - deviceName: "/dev/sdf"
                  size: 500
                  type: "gp3"
                  iops: 4000
                  throughput: 250
                  encrypted: true

Best Practices

Root Volume: Always specify a root volume for consistent boot disk configuration
Encryption: Enable encryption for sensitive workloads using either AWS default keys or customer-managed KMS keys
IOPS and Throughput: Use gp3 volumes for better price/performance ratio with configurable IOPS and throughput
Device Names: Use standard device naming conventions (/dev/sda1 for root, /dev/sdf onwards for additional volumes)
Size Planning: Consider future growth when sizing volumes, as resizing EBS volumes requires downtime
Volume Types: Choose appropriate volume types based on workload requirements:
- gp2/gp3: General purpose workloads
- io1/io2: High-performance database workloads requiring consistent IOPS

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified October 29, 2025: release(main): v0.36.0 (#1368) (525d099)