Skip to content

Commit 3cd752a

Browse files
balaharish7balaharish7
authored
Diskpool Expansion Documentation (#541)
* docs: Create Documentation for Diskpool Expansion Signed-off-by: Bala Harish <[email protected]> * docs: Create Documentation for Diskpool Expansion Signed-off-by: Bala Harish <[email protected]> * docs: Create Documentation for Diskpool Expansion Signed-off-by: Bala Harish <[email protected]> * docs: Create Documentation for Diskpool Expansion Signed-off-by: Bala Harish <[email protected]> * docs: Create Documentation for Diskpool Expansion Signed-off-by: Bala Harish <[email protected]> --------- Signed-off-by: Bala Harish <[email protected]>
1 parent fe3c4b9 commit 3cd752a

File tree

3 files changed

+102
-3
lines changed

3 files changed

+102
-3
lines changed

‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/additional-information/spdk-blobstore.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ You can configure the Storage Performance Development Kit (SPDK) blobstore clust
2121
Before modifying the default setting, carefully evaluate application I/O patterns and device size. For example: Smaller cluster size provides better storage efficiency and less internal fragmentation, but more metadata overhead. Larger cluster size will provide better performance for large sequential IOs, and low metadata overhead.
2222
:::
2323

24-
### Configuration
24+
## Configuration
2525

2626
1. Per-Pool Configuration (DiskPool CR)
2727

@@ -52,15 +52,15 @@ Set a global cluster size for all new pools that do not specify it in their cust
5252

5353
A new storageclass parameter named `poolClusterSize` is provided. With this option, only the pools that match requested blobstore cluster size will be used for that volume’s replicas. If enough such pools are not found, to satisfy the volume’s replication factor, the provisioning will fail or in case of an existing volume the rebuilds might not be able to start.
5454

55-
### Recommendations
55+
## Recommendations
5656

5757
- This is an advanced user configuration. Proceed with caution and ensure that you fully understand the implications before modifying the default value of `4 MiB`.
5858

5959
- Typically, this configuration has been tested at `32 MiB` for device sizes upto `20 TiB`, where the pool import takes about three minutes on a performant cloud disk.
6060

6161
- For simpler management and more predictable replica scheduling, we recommend minimizing the number of different cluster sizes used in deployment environment. As a general guideline for node clusters utilizing large storage devices, configuring a global blobstore cluster size of `16 MiB` or `32 MiB` provides a strong balance of performance and efficiency.
6262

63-
### Benefits
63+
## Benefits
6464

6565
Choosing a larger cluster size (Example: `16 MiB` or `32 MiB)` significantly reduces the amount of metadata that SPDK needs to manage.
6666

‎docs/main/user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/diskpool-expansion.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
id: diskpool-expansion
3+
title: DiskPool Expansion
4+
keywords:
5+
- DiskPool Expansion
6+
- Mayastor DiskPool
7+
description: This guide explains how to configure, monitor, and perform DiskPool expansion.
8+
---
9+
10+
# DiskPool Expansion
11+
12+
## Overview
13+
14+
The DiskPool Expansion feature in Replicated PV Mayastor helps prevent storage outages when a pool allocation approaches capacity. By allowing controlled growth of an existing DiskPool, you can avoid replica failures caused by “no space” (ENOSPC) conditions and maintain uninterrupted application operations.
15+
16+
This document describes how to configure, and perform a DiskPool expansion, including the required CR settings, status fields, and supported expansion methods.
17+
18+
:::note
19+
DiskPools cannot be expanded indefinitely. Each pool has a maximum expansion limit that is defined during creation. Pools created before this feature was introduced may have limited ability to grow.
20+
:::
21+
22+
## Configuring Maximum Expansion
23+
24+
You can configure the maximum pool size using the `maxExpansion` field in the DiskPool CR.
25+
26+
- **Absolute Size:** Specify a fixed value in MiB, GiB, or TiB (for example: `800GiB`, `3.5TiB`, or `1073741824B`). Binary units must be used to avoid ambiguity.
27+
28+
- **Factor:** Specify a multiplier of the initial capacity (for example: `1x`, `5x`, `20x`). A value of `5x` allows the pool to grow up to five times its initial size. If not specified, the default is `1x`.
29+
30+
**Example: Factor-Based Expansion**
31+
32+
```
33+
apiVersion: "openebs.io/v1beta3"
34+
kind: DiskPool
35+
metadata:
36+
name: <pool-name>
37+
namespace: <namespace>
38+
spec:
39+
node: <node-name>
40+
disks: ["/dev/disk/by-id/<id>"]
41+
maxExpansion: "20x"
42+
```
43+
44+
**Example: Absolute Size Expansion**
45+
46+
```
47+
apiVersion: "openebs.io/v1beta3"
48+
kind: DiskPool
49+
metadata:
50+
name: <pool-name>
51+
namespace: <namespace>
52+
spec:
53+
node: <node-name>
54+
disks: ["/dev/disk/by-id/<id>"]
55+
maxExpansion: "6TiB"
56+
```
57+
58+
Two new fields are available in the DiskPool CR state to track pool expansion:
59+
60+
- `maxExpandableSize` - The absolute maximum size to which the pool can grow. Expansion beyond this limit fails. This does not affect existing volumes or data but makes any extra capacity unusable.
61+
62+
- `diskCapacity` – The size of the underlying disk. Note that `capacity` represents usable space after metadata reservation.
63+
64+
:::important
65+
For any pool, the underlying disk can only be expanded up to (`maxExpandableSize - diskCapacity`). If the disk is grown beyond this value, the expansion request fails.
66+
:::
67+
68+
## Expanding the DiskPool
69+
70+
To expand a pool:
71+
72+
1. Expand the backing disk (must not exceed `maxExpandableSize`).
73+
74+
2. Trigger the Replicated PV Mayastor pool expansion using one of the following methods:
75+
76+
- Annotate the DSP CR
77+
78+
Add the annotation `openebs.io/expand: true` to the CR to trigger reconciliation.
79+
80+
```
81+
kubectl annotate dsp <name> openebs.io/expand=true -n <ns>
82+
```
83+
84+
The Operator removes the annotation once expansion succeeds or when it encounters an unrecoverable error.
85+
86+
- Use the OpenEBS plugin
87+
88+
Run the command `kubectl openebs mayastor expand pool <pool-id> -n openebs` to invoke the pool expansion API.
89+
90+
3. Once successful, both `capacity` and `diskCapacity` values in the CR will reflect the updated size.
91+
92+
:::Important
93+
We recommend using multiple DiskPools instead of over-expanding a single DiskPool (for example, setting `maxExpansion` of 100 GiB to grow up to 50-60 TiB). Increasing the `maxExpansion` value reserves more metadata pages in the pool, which can lengthen pool creation and import times. However, larger pools may be appropriate if the volumes are relatively large.
94+
:::

‎docs/sidebars.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -522,6 +522,11 @@ module.exports = {
522522
type: "doc",
523523
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/encryption",
524524
label: "Encryption"
525+
},
526+
{
527+
type: "doc",
528+
id: "user-guides/replicated-storage-user-guide/replicated-pv-mayastor/advanced-operations/diskpool-expansion",
529+
label: "DiskPool Expansion"
525530
}
526531
]
527532
},

0 commit comments

Comments
 (0)