Add docs for RecoverVolumeExpansionFailure feature

content/en/docs/concepts/storage/persistent-volumes.md

@@ -299,6 +299,11 @@ Expanding EBS volumes is a time-consuming operation. Also, there is a per-volume
 
 #### Recovering from Failure when Expanding Volumes
 
+If a user specifies a new size that is too big to be satisfied by underlying storage system, expansion of PVC will be continuously retried until user or cluster administrator takes some action. This can be undesirable and hence Kubernetes provides following methods of recovering from such failures.
+
+{{< tabs name="recovery_methods" >}}
+{{% tab name="Manually with Cluster Administrator access" %}}
+
 If expanding underlying storage fails, the cluster administrator can manually recover the Persistent Volume Claim (PVC) state and cancel the resize requests. Otherwise, the resize requests are continuously retried by the controller without administrator intervention.
 
 1. Mark the PersistentVolume(PV) that is bound to the PersistentVolumeClaim(PVC) with `Retain` reclaim policy.
@@ -307,6 +312,30 @@ If expanding underlying storage fails, the cluster administrator can manually re
 4. Re-create the PVC with smaller size than PV and set `volumeName` field of the PVC to the name of the PV. This should bind new PVC to existing PV.
 5. Don't forget to restore the reclaim policy of the PV.
 
+{{% /tab %}}
+{{% tab name="By requesting expansion to smaller size" %}}
+{{% feature-state for_k8s_version="v1.23" state="alpha" %}}
+
+{{< note >}}
+Recovery from failing PVC expansion by users is available as an alpha feature since Kubernetes 1.23. The `RecoverVolumeExpansionFailure` feature must be enabled for this feature to work. Refer to the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) documentation for more information.
+{{< /note >}}
+
+If the feature gates `ExpandPersistentVolumes` and `RecoverVolumeExpansionFailure` are both
+enabled in your cluster, and expansion has failed for a PVC, you can retry expansion with a
+smaller size than the previously requested value. To request a new expansion attempt with a
+smaller proposed size, edit `.spec.resources` for that PVC and choose a value that is less than the
+value you previously tried.
+This is useful if expansion to a higher value did not succeed because of capacity constraint.
+If that has happened, or you suspect that it might have, you can retry expansion by specifying a
+size that is within the capacity limits of underlying storage provider. You can monitor status of resize operation by watching `.status.resizeStatus` and events on the PVC.
+
+Note that,
+although you can a specify a lower amount of storage than what was requested previously,
+the new value must still be higher than `.status.capacity`.
+Kubernetes does not support shrinking a PVC to less than its current size.
+{{% /tab %}}
+{{% /tabs %}}
+
 
 ## Types of Persistent Volumes
 

content/en/docs/reference/access-authn-authz/admission-controllers.md

@@ -583,7 +583,8 @@ subresource of the referenced *owner* can change it.
 This admission controller implements additional validations for checking incoming `PersistentVolumeClaim` resize requests.
 
 {{< note >}}
-Support for volume resizing is available as an alpha feature. Admins must set the feature gate `ExpandPersistentVolumes`
+Support for volume resizing is available as a beta feature. As a cluster administrator,
+you must ensure that the feature gate `ExpandPersistentVolumes` is set
 to `true` to enable resizing.
 {{< /note >}}
 

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -165,6 +165,7 @@ different Kubernetes components.
 | `ProxyTerminatingEndpoints` | `false` | Alpha | 1.22 | |
 | `QOSReserved` | `false` | Alpha | 1.11 | |
 | `ReadWriteOncePod` | `false` | Alpha | 1.22 | |
+| `RecoverVolumeExpansionFailure` | `false` | Alpha | 1.23 | |
 | `RemainingItemCount` | `false` | Alpha | 1.15 | 1.15 |
 | `RemainingItemCount` | `true` | Beta | 1.16 | |
 | `RemoveSelfLink` | `false` | Alpha | 1.16 | 1.19 |
@@ -889,6 +890,8 @@ Each feature gate is designed for enabling/disabling a specific feature:
   (memory only for now).
 - `ReadWriteOncePod`: Enables the usage of `ReadWriteOncePod` PersistentVolume
   access mode.
+- `RecoverVolumeExpansionFailure`: Enables users to edit their PVCs to smaller sizes so as they can recover from previously issued
+  volume expansion failures. See [enhancement proposal](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/1790-recover-resize-failure/README.md) for more details.
 - `RemainingItemCount`: Allow the API servers to show a count of remaining
   items in the response to a
   [chunking list request](/docs/reference/using-api/api-concepts/#retrieving-large-results-sets-in-chunks).