Skip to content

Commit 284d4c1

Browse files
nastena1606nastena1606
committed
K8SPS-127 Documented automatic storage resize
 modified: docs/operator.md modified: docs/scaling.md
1 parent 48dc008 commit 284d4c1

2 files changed

Lines changed: 158 additions & 13 deletions

File tree

‎docs/operator.md‎

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,12 +65,67 @@ Pause/resume: setting it to `true` gracefully stops the cluster, and setting it
6565

6666
### `enableVolumeExpansion`
6767

68-
Enables or disables [automatic storage scaling / volume expansion](scaling.md#storage-resizing-with-volume-expansion-capability).
68+
Enables or disables [storage resizing with volume expansion](scaling.md#storage-resizing-with-volume-expansion-capability).
6969

7070
| Value type | Example |
7171
| ----------- | ---------- |
7272
| :material-toggle-switch-outline: boolean | `false` |
7373

74+
This option is deprecated and will be removed in version 1.5.0. Use the [`storageScaling.enableVolumeScaling`](#storagescalingenablevolumescaling) option instead.
75+
76+
## Storage scaling section
77+
78+
The `storageScaling` section in the [deploy/cr.yaml :octicons-link-external-16:](https://github.com/percona/percona-server-mysql-operator/blob/v{{release}}/deploy/cr.yaml) file controls volume expansion and automatic storage resizing for MySQL PVCs. See [Scale storage](scaling.md#scale-storage) for usage details.
79+
80+
### `storageScaling.enableVolumeScaling`
81+
82+
Enables or disables [storage scaling / volume expansion](scaling.md#storage-resizing-with-volume-expansion-capability) with Volume Expansion capability.
83+
84+
| Value type | Example |
85+
| ----------- | ---------- |
86+
| :material-toggle-switch-outline: boolean | `false` |
87+
88+
### `storageScaling.enableExternalAutoscaling`
89+
90+
Enables or disables the use of external volume autoscaler. When disabled, the Operator uses its own expansion logic with Volume Expansion capability.
91+
92+
| Value type | Example |
93+
| ----------- | ---------- |
94+
| :material-toggle-switch-outline: boolean | `false` |
95+
96+
### `storageScaling.autoscaling.enabled`
97+
98+
Enables automatic storage resizing based on user-defined thresholds. Read more about this feature in [Automatic storage resizing](scaling.md#automatic-storage-resizing).
99+
100+
| Value type | Example |
101+
| ----------- | ---------- |
102+
| :material-toggle-switch-outline: boolean | `false` |
103+
104+
### `storageScaling.autoscaling.triggerThresholdPercent`
105+
106+
The percentage of the storage usage that triggers automatic resizing. Valid values are from 50 to 95. Default value is 80.
107+
108+
| Value type | Example |
109+
| ----------- | ---------- |
110+
| :material-numeric-1-box: int | `80` |
111+
112+
### `storageScaling.autoscaling.growthStep`
113+
114+
The amount to increase the storage during automatic resizing. Default value is `2Gi`.
115+
116+
| Value type | Example |
117+
| ----------- | ---------- |
118+
| :material-code-string: string | `2Gi` |
119+
120+
### `storageScaling.autoscaling.maxSize`
121+
122+
The maximum size to which storage can be automatically resized.
123+
Autoscaling stops when storage reaches this limit. Must be at least `1Gi`.
124+
125+
| Value type | Example |
126+
| ----------- | ---------- |
127+
| :material-code-string: string | `10Gi` |
128+
74129
### `initContainer.Image`
75130

76131
An alternative init image for the Operator.

‎docs/scaling.md‎

Lines changed: 102 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -43,21 +43,32 @@ for more details about other components.
4343
4444
### Scale storage
4545
46-
Kubernetes manages storage with a PersistentVolume (PV), a segment of
47-
storage supplied by the administrator, and a PersistentVolumeClaim
48-
(PVC), a request for storage from a user.
46+
Kubernetes manages storage with the following components:
4947
50-
Starting with Kubernetes v1.11, a user can increase the size of an existing
48+
* a PersistentVolume (PV) - a segment of
49+
storage supplied by the Kubernetes administrator,
50+
* a PersistentVolumeClaim
51+
(PVC) - a request for storage from a user.
52+
53+
Starting with Kubernetes v1.11, you can increase the size of an existing
5154
PVC object (considered stable since Kubernetes v1.24).
52-
The user cannot shrink the size of an existing PVC object.
55+
Note that you **cannot shrink** the size of an existing PVC object.
56+
57+
Use storage scaling to keep up with growing data while keeping the cluster online. The Operator supports the following scaling options:
58+
59+
* automatic scaling - Starting with Operator version 1.2.0, the Operator monitors storage usage and scales the storage automatically
60+
* storage resizing with Volume Expansion capability - Starting with the Operator version 0.11.0, you can instruct the Operator to scale the storage by updating the Custom Resource manifest
61+
* manual scaling - scale the storage manually.
5362
54-
Starting from the Operator version 0.11.0, you can scale Percona Server for MySQL storage automatically by configuring the Custom Resource manifest. Alternatively, you can scale the storage manually. For either way, the volume type must support PVCs expansion.
63+
You can also use an external autoscaler with the Operator. Enabling an external autoscaler disables the Operator's internal logic for automatic storage resizing. Choose one method based on your environment and requirements; using both simultaneously is not supported.
64+
65+
For either option, the volume type must support PVCs expansion.
5566
5667
#### Check expansion capability for your volume type
5768
5869
Certain volume types support PVCs expansion by default. You can run the following command to check if your storage supports the expansion capability:
5970
60-
``` {.bash data-prompt="$" }
71+
```
6172
$ kubectl describe sc <storage class name> | grep AllowVolumeExpansion
6273
```
6374

@@ -71,13 +82,92 @@ Find exact details about
7182
PVCs and the supported volume types in [Kubernetes
7283
documentation :octicons-link-external-16:](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#expanding-persistent-volumes-claims).
7384

85+
#### Automatic storage resizing
86+
87+
Starting with version 1.2.0, the Operator can automatically resize Persistent Volume Claims (PVCs) for Percona Server for MySQL Pods based on your configured thresholds. The Operator monitors storage usage of MySQL PVCs. When the usage exceeds the defined threshold, the Operator triggers resizing until the storage size reaches the maximum limit.
88+
89+
This feature gives you:
90+
91+
* fewer outages from full disks because storage grows with demand
92+
* less guesswork on capacity planning and fewer last-minute fixes
93+
* lower operational effort for developers and platform engineers
94+
* cost control by expanding only when needed
95+
* a more predictable environment so teams can focus on delivery
96+
97+
To enable automatic storage resizing, edit the `deploy/cr.yaml` Custom Resource manifest as follows:
98+
{.power-number}
99+
100+
1. Make sure the MySQL component has a storage size set.
101+
102+
Example:
103+
104+
```yaml
105+
spec:
106+
mysql:
107+
volumeSpec:
108+
persistentVolumeClaim:
109+
resources:
110+
requests:
111+
storage: 6Gi
112+
```
113+
114+
2. Configure autoscaling thresholds in the [`storageScaling`](operator.md#operator-storagescaling-section) subsection:
115+
116+
* `enableVolumeScaling` - set to `true`. This replaces the deprecated [`enableVolumeExpansion`](operator.md#enablevolumeexpansion) option and must be enabled for autoscaling to work
117+
* `autoscaling.enabled` - set to `true`
118+
* `autoscaling.triggerThresholdPercent` - specify the usage percentage (50–95, default `80`). When usage exceeds this threshold, autoscaling is triggered
119+
* `autoscaling.growthStep` - specify how much storage to add on each resize (default `2Gi`)
120+
* `autoscaling.maxSize` - specify the upper limit for storage growth (minimum `1Gi`). When this limit is reached, scaling stops
121+
122+
Example configuration:
123+
124+
```yaml
125+
spec:
126+
storageScaling:
127+
enableVolumeScaling: true
128+
autoscaling:
129+
enabled: true
130+
triggerThresholdPercent: 80
131+
growthStep: 2Gi
132+
maxSize: 10Gi
133+
```
134+
135+
3. Apply the configuration:
136+
137+
```bash
138+
kubectl apply -f deploy/cr.yaml -n <namespace>
139+
```
140+
141+
When the Operator changes the storage size, it updates the Custom Resource status as follows:
142+
143+
* adds the `pvc-resize-in-progress` annotation. The annotation contains the timestamp of the resize start and indicates that the resize operation is running. After the resize finishes, the Operator deletes this annotation
144+
* records the new size in the `currentSize` field
145+
* updates the `resizeCount` field
146+
* records any errors in the `lastError` field
147+
148+
Run `kubectl get ps <cluster-name> -o yaml -n <namespace>` to check the current cluster state.
149+
150+
??? example "Sample output"
151+
152+
```{.text .no-copy}
153+
storageAutoscaling:
154+
datadir-ps-cluster1-mysql-0:
155+
currentSize: 4194304Ki
156+
lastResizeTime: "2026-01-23T15:08:59Z"
157+
resizeCount: 2
158+
```
159+
160+
The `storageAutoscaling` section appears under the `.status` in the Custom Resource.
161+
162+
When the storage size reaches the limit, no further resizing is done and this event is recorded in the logs. You can either clean up the data or set a new limit based on your organization's policies and requirements. For help with common issues, see [Operator logs](debug-logs.md).
163+
74164
#### Storage resizing with Volume Expansion capability
75165

76166
In this document we're using the default Percona Server for MySQL cluster name `ps-cluster1`. If you have a different name, replace `ps-cluster1` with it in the commands.
77167

78168
To enable storage resizing via volume expansion, do the following:
79169

80-
1. Set the [enableVolumeExpansion](operator.md#enablevolumeexpansion) Custom Resource option to `true` (it is turned off by default). When enabled, the Operator will automatically expand the storage for you when you define a new size in the Custom Resource
170+
1. Set the [`storageScaling.enableVolumeScaling`](operator.md#storagescalingenablevolumescaling) Custom Resource option to `true` (it is turned off by default). When enabled, the Operator automatically expands storage when you increase the size in the Custom Resource
81171
2. Change the
82172
`mysql.volumeSpec.persistentVolumeClaim.resources.requests.storage` option in the `deploy/cr.yaml` file to the desired storage size.
83173

@@ -86,8 +176,8 @@ To enable storage resizing via volume expansion, do the following:
86176
```yaml
87177
spec:
88178
...
89-
enableVolumeExpansion: true
90-
...
179+
storageScaling:
180+
enableVolumeScaling: true
91181
mysql:
92182
...
93183
volumeSpec:
@@ -100,8 +190,8 @@ To enable storage resizing via volume expansion, do the following:
100190

101191
3. Apply the new configuration:
102192

103-
``` {.bash data-prompt="$" }
104-
$ kubectl apply -f cr.yaml
193+
```
194+
kubectl apply -f cr.yaml
105195
```
106196

107197
The storage size change takes some time. When it starts, the Operator automatically adds the `pvc-resize-in-progress` annotation to the `PerconaServerMySQL` Custom Resource. The annotation contains the timestamp of the resize start and indicates that the resize operation is running. After the resize finishes, the Operator deletes this annotation.

0 commit comments

Comments
 (0)