Skip to content

Commit 47a0d9e

Browse files
dkoshkindkoshkin
committed
docs: add AWS and EKS volumes docs
1 parent 7aa470d commit 47a0d9e

File tree

1 file changed

+284
-0
lines changed

1 file changed

+284
-0
lines changed

‎docs/content/customization/aws/volumes.md‎

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
+++
2+
title = "AWS Volumes Configuration"
3+
+++
4+
5+
The AWS volumes customization allows the user to specify configuration for both root and non-root storage volumes for AWS machines.
6+
The volumes customization can be applied to both control plane and worker machines.
7+
This customization will be available when the
8+
[provider-specific cluster configuration patch]({{< ref "..">}}) is included in the `ClusterClass`.
9+
10+
## Configuration Options
11+
12+
The volumes configuration supports two types of volumes:
13+
14+
- **Root Volume**: The primary storage volume for the instance (typically `/dev/sda1`)
15+
- **Non-Root Volumes**: Additional storage volumes that can be attached to the instance
16+
17+
### Volume Configuration Fields
18+
19+
Each volume can be configured with the following fields:
20+
21+
| Field | Type | Required | Description | Default |
22+
|-------|------|----------|-------------|---------|
23+
| `deviceName` | string | No | Device name for the volume (e.g., `/dev/sda1`, `/dev/sdf`) | - |
24+
| `size` | int64 | No | Size in GiB (minimum 8) | Based on AMI, usually 20GiB |
25+
| `type` | string | No | EBS volume type (`gp2`, `gp3`, `io1`, `io2`) | - |
26+
| `iops` | int64 | No | IOPS for provisioned volumes (io1, io2, gp3) | - |
27+
| `throughput` | int64 | No | Throughput in MiB/s (gp3 only) | - |
28+
| `encrypted` | bool | No | Whether the volume should be encrypted | false |
29+
| `encryptionKey` | string | No | KMS key ID or ARN for encryption | AWS default key |
30+
31+
### Supported Volume Types
32+
33+
- **gp2**: General Purpose SSD (up to 16,000 IOPS)
34+
- **gp3**: General Purpose SSD with configurable IOPS and throughput
35+
- **io1**: Provisioned IOPS SSD (up to 64,000 IOPS)
36+
- **io2**: Provisioned IOPS SSD with higher durability (up to 64,000 IOPS)
37+
38+
## Examples
39+
40+
### Root Volume Only
41+
42+
To specify only a root volume configuration:
43+
44+
```yaml
45+
apiVersion: cluster.x-k8s.io/v1beta1
46+
kind: Cluster
47+
metadata:
48+
name: <NAME>
49+
spec:
50+
topology:
51+
variables:
52+
- name: clusterConfig
53+
value:
54+
controlPlane:
55+
aws:
56+
volumes:
57+
root:
58+
deviceName: "/dev/sda1"
59+
size: 100
60+
type: "gp3"
61+
iops: 3000
62+
throughput: 125
63+
encrypted: true
64+
encryptionKey: "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012"
65+
- name: workerConfig
66+
value:
67+
aws:
68+
volumes:
69+
root:
70+
size: 200
71+
type: "gp3"
72+
iops: 4000
73+
throughput: 250
74+
encrypted: true
75+
```
76+
77+
### Non-Root Volumes Only
78+
79+
To specify only additional non-root volumes:
80+
81+
```yaml
82+
apiVersion: cluster.x-k8s.io/v1beta1
83+
kind: Cluster
84+
metadata:
85+
name: <NAME>
86+
spec:
87+
topology:
88+
variables:
89+
- name: clusterConfig
90+
value:
91+
controlPlane:
92+
aws:
93+
volumes:
94+
nonroot:
95+
- deviceName: "/dev/sdf"
96+
size: 500
97+
type: "gp3"
98+
iops: 4000
99+
throughput: 250
100+
encrypted: true
101+
- deviceName: "/dev/sdg"
102+
size: 1000
103+
type: "gp2"
104+
encrypted: false
105+
- name: workerConfig
106+
value:
107+
aws:
108+
volumes:
109+
nonroot:
110+
- deviceName: "/dev/sdf"
111+
size: 200
112+
type: "io1"
113+
iops: 10000
114+
encrypted: true
115+
```
116+
117+
### Both Root and Non-Root Volumes
118+
119+
To specify both root and non-root volumes:
120+
121+
```yaml
122+
apiVersion: cluster.x-k8s.io/v1beta1
123+
kind: Cluster
124+
metadata:
125+
name: <NAME>
126+
spec:
127+
topology:
128+
variables:
129+
- name: clusterConfig
130+
value:
131+
controlPlane:
132+
aws:
133+
volumes:
134+
root:
135+
size: 100
136+
type: "gp3"
137+
iops: 3000
138+
throughput: 125
139+
encrypted: true
140+
nonroot:
141+
- deviceName: "/dev/sdf"
142+
size: 500
143+
type: "gp3"
144+
iops: 4000
145+
throughput: 250
146+
encrypted: true
147+
- deviceName: "/dev/sdg"
148+
size: 1000
149+
type: "gp2"
150+
encrypted: false
151+
- name: workerConfig
152+
value:
153+
aws:
154+
volumes:
155+
root:
156+
size: 200
157+
type: "gp3"
158+
iops: 4000
159+
throughput: 250
160+
encrypted: true
161+
nonroot:
162+
- deviceName: "/dev/sdf"
163+
size: 100
164+
type: "io1"
165+
iops: 10000
166+
encrypted: true
167+
```
168+
169+
### MachineDeployment Overrides
170+
171+
You can customize individual MachineDeployments by using the overrides field:
172+
173+
```yaml
174+
spec:
175+
topology:
176+
# ...
177+
workers:
178+
machineDeployments:
179+
- class: default-worker
180+
name: md-0
181+
variables:
182+
overrides:
183+
- name: workerConfig
184+
value:
185+
aws:
186+
volumes:
187+
root:
188+
size: 500
189+
type: "gp3"
190+
iops: 10000
191+
throughput: 500
192+
encrypted: true
193+
nonroot:
194+
- deviceName: "/dev/sdf"
195+
size: 1000
196+
type: "io2"
197+
iops: 20000
198+
encrypted: true
199+
```
200+
201+
## Resulting CAPA Configuration
202+
203+
Applying the volumes configuration will result in the following values being set in the `AWSMachineTemplate`:
204+
205+
### Root Volume Configuration
206+
207+
When a root volume is specified, it will be set in the `rootVolume` field:
208+
209+
```yaml
210+
spec:
211+
template:
212+
spec:
213+
rootVolume:
214+
deviceName: "/dev/sda1"
215+
size: 100
216+
type: "gp3"
217+
iops: 3000
218+
throughput: 125
219+
encrypted: true
220+
encryptionKey: "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012"
221+
```
222+
223+
### Non-Root Volumes Configuration
224+
225+
When non-root volumes are specified, they will be set in the `nonRootVolumes` field:
226+
227+
```yaml
228+
spec:
229+
template:
230+
spec:
231+
nonRootVolumes:
232+
- deviceName: "/dev/sdf"
233+
size: 500
234+
type: "gp3"
235+
iops: 4000
236+
throughput: 250
237+
encrypted: true
238+
- deviceName: "/dev/sdg"
239+
size: 1000
240+
type: "gp2"
241+
encrypted: false
242+
```
243+
244+
## EKS Configuration
245+
246+
For EKS clusters, the volumes configuration follows the same structure but is specified under the EKS worker configuration:
247+
248+
```yaml
249+
apiVersion: cluster.x-k8s.io/v1beta1
250+
kind: Cluster
251+
metadata:
252+
name: <NAME>
253+
spec:
254+
topology:
255+
variables:
256+
- name: workerConfig
257+
value:
258+
eks:
259+
volumes:
260+
root:
261+
size: 200
262+
type: "gp3"
263+
iops: 4000
264+
throughput: 250
265+
encrypted: true
266+
nonroot:
267+
- deviceName: "/dev/sdf"
268+
size: 500
269+
type: "gp3"
270+
iops: 4000
271+
throughput: 250
272+
encrypted: true
273+
```
274+
275+
## Best Practices
276+
277+
1. **Root Volume**: Always specify a root volume for consistent boot disk configuration
278+
2. **Encryption**: Enable encryption for sensitive workloads using either AWS default keys or customer-managed KMS keys
279+
3. **IOPS and Throughput**: Use gp3 volumes for better price/performance ratio with configurable IOPS and throughput
280+
4. **Device Names**: Use standard device naming conventions (`/dev/sda1` for root, `/dev/sdf` onwards for additional volumes)
281+
5. **Size Planning**: Consider future growth when sizing volumes, as resizing EBS volumes requires downtime
282+
6. **Volume Types**: Choose appropriate volume types based on workload requirements:
283+
- **gp2/gp3**: General purpose workloads
284+
- **io1/io2**: High-performance database workloads requiring consistent IOPS

0 commit comments

Comments
 (0)