proposal: Expand the PVC's initial capacity

Signed-off-by: Yuji Ito <[email protected]>

docs/proposals/resize-when-creating-by-group.md

@@ -0,0 +1,127 @@
+## Summary
+
+Expand the PVC's initial capacity based on the largest capacity in specified PVCs.
+
+### Motivation
+
+One use case for pvc-autoresizer is automatically extending a PV/PVC for multiple Pod/PV pairings, such as a MySQL cluster.
+In such a cluster, if a Pod/PV fails and a PV/PVC is rebuilt for the restore process, a PV is created based on the PVC template. Even if a PV of the same size as the others is actually needed, a PV of the template's capacity is created, resulting in a case where the restore process stops due to insufficient capacity.
+
+To solve this problem, we are planning to add a new function to pvc-autoresizer to create a PV/PVC with sufficient capacity at the time of creation, when a PVC of the same group already exists.
+
+### Goals
+
+- Provide the ability to expand the PVC's initial capacity based on the largest capacity in specified PVCs.
+- The PVC for determining capacity should be user-selectable.
+- [moco](https://github.com/cybozu-go/moco) checks the PV capacity at the beginning of the restore process. It should be able to handle such cases.
+
+## Proposal
+
+Rules for grouping & initial sizing
+
+- If creating a PVC has a `resize.topolvm.io/pre-resize-group-by` annotation and the label specified in the annotation exists, existing PVCs with matching values are determined to be in the same group.
+- If no PVCs are determined to be in the same group, or if the capacity of creating PVC is larger than existing any PVC in the same group, the capacity of the original PVC is used as is.
+
+Examples are given below.
+
+```yaml
+### existing PVCs (excerpted)
+kind: PersistentVolumeClaim
+metadata:
+  name: pvc-x-1
+  labels:
+    label-hoge: group-x
+  annotations:
+    resize.topolvm.io/pre-resize-group-by: label-hoge
+spec:
+  resources:
+    requests:
+      storage: 20Gi
+
+kind: PersistentVolumeClaim
+metadata:
+  name: pvc-x-2
+  labels:
+    label-hoge: group-x
+  annotations:
+    resize.topolvm.io/pre-resize-group-by: label-hoge
+spec:
+  resources:
+    requests:
+      storage: 16Gi
+
+kind: PersistentVolumeClaim
+metadata:
+  name: pvc-y-1
+  labels:
+    label-hoge: group-y
+  annotations:
+    resize.topolvm.io/pre-resize-group-by: label-hoge
+spec:
+  resources:
+    requests:
+      storage: 30Gi
+```
+
+When creating the following new PVC, `pvc-x-1` and `pvc-x-2` with `label-hoge: group-x` are determined to be in the same group, and `pvc-y-1` is determined to be in a different group. Therefore, the PVC is created with **20Gi** based on `pvc-x-1`, which has the largest capacity.
+
+```yaml
+kind: PersistentVolumeClaim
+metadata:
+  name: pvc-x-3
+  labels:
+    label-hoge: group-x
+  annotations:
+    resize.topolvm.io/pre-resize-group-by: label-hoge
+spec:
+  resources:
+    requests:
+      storage: 10Gi
+```
+
+When creating the following new PVC, `pvc-y-1` with `label-hoge: group-y` is a candidate, but since the new PVC's size(50Gi) is larger than the existing(30Gi), the PVC will be created with **50Gi**.
+
+```yaml
+kind: PersistentVolumeClaim
+metadata:
+  name: pvc-y-2
+  labels:
+    label-hoge: group-y
+  annotations:
+    resize.topolvm.io/pre-resize-group-by: label-hoge
+spec:
+  resources:
+    requests:
+      storage: 50Gi
+```
+
+### How to use
+
+- Add `resize.topolvm.io/pre-resize-group-by` annotation to the PVC template to which you want to apply the feature.
+- In most cases, annotations and labels are not added to PVCs that have already been created based on a PVC template. In such cases, it is necessary to manually add `resize.topolvm.io/pre-resize-group-by` annotation to existing PVCs in addition to the PVC template.
+
+## Design details
+
+Implementation method.
+
+### Option A) use mutating webhook for PVC
+
+Pros:
+- PVCs are created with the required capacity specified from the beginning, even a restore program that checks the free capacity of the volume will not cause problems.
+- PVCs are created with the required capacity specified from the beginning, so they will not become unscalable later due to insufficient capacity when the capacity per node is had, as is the case of TopoLVM.
+
+Cons:
+- In order to provide webhook features, additional configuration of mutating webhook and svc is required besides the development of the program.
+
+### Option B) use reconcile loop for PVC
+
+Pros:
+- pvc-autoresizer already has a custom controller that monitors PVCs, so the functionality may be achieved with a few modifications.
+
+Cons:
+- A restore program that performs a free space check of the volume when using PVC may cause an error due to insufficient space before expanding PV/PVC.
+- In TopoLVM, there may be cases in which PVs created cannot be expanded due to insufficient node capacity.
+
+### Decision outcome
+
+We adopt Option A. We have already found out that moco restores check the free space of PVCs. Therefore, the restore does not work well with Option B. It is possible that other programs may behave the same way.