update KEP for PersistentVolume last phase transition time

keps/sig-storage/3762-persistent-volume-last-phase-transition-time/README.md

@@ -230,9 +230,9 @@ The "Design Details" section below is for the real
 nitty-gritty.
 -->
 
-We need to update API server to support the newly proposed field and update PV controller to set a value of the new
-timestamp field when a volume transitions to a different phase. Also, if the feature gate is disabled the value must be
-re-set to `nil` when updating or creating a volume.
+We need to update API server to support the newly proposed field and update REST strategy for updating PersistentVolume
+status to set a value of the new timestamp field when a volume transitions to a different phase. Also, if the feature
+gate is disabled and the value has not been yet initialized it must be re-set to `nil` when updating or creating a volume.
 
 The value of the field is not intended for use by any other Kubernetes components at this point and should be used only
 as a convenience feature for cluster admins. Cluster admins should be able to list and sort PersistentVolumes based on
@@ -309,14 +309,10 @@ Changes required for this KEP:
     }
     ```
 
-  * validation should check timestamp format 
   * validation should allow update from `nil`
-  * validation should allow timestamp update if the previous timestamp is older
-  * validation should not allow updating to a point in time before the current timestamp
-
-* kube-controller-manager / PV controller
-  * update the timestamp whenever PV controller transitions PV to a different phase (`pv.Status.Phase`)
-  * remove the timestamp in `LastPhaseTransitionTime` field during volume status update when feature gate is disabled
+  * validation should allow timestamp update from any other previous value (might be required if system time is adjusted later)
+  * update the timestamp whenever PV transitions phase (`pv.Status.Phase`)
+  * remove the timestamp in `LastPhaseTransitionTime` field during any volume status update when feature gate is disabled and value was not yet initialized
 
 <!--
 This section should contain enough information that the specifics of your
@@ -515,9 +511,9 @@ No change in cluster upgrade / downgrade process.
 When upgrading the new `LastPhaseTransitionTime` field and its value will be added to a PV when it transitions phase.
 
 When downgrading from a version that added the new timestamp field PVs we need to make sure that after downgrade the
-values of the disabled field are removed. We intend to use create and update persistent volume REST strategy to remove
-the values. More specifically each time the strategy invokes `PrepareForCreate` or `PrepareForUpdate` method we set the
-value to `nil` if feature gate is disabled.
+values of the disabled field are reset to `nil` if not already initialized. We intend to use update persistent volume
+REST strategy to remove the values. More specifically each time the strategy invokes `PrepareForUpdate` method we set
+the value to `nil` if the field is uninitialized (zero time) and feature gate is disabled.
 
 This means that enabling and disabling feature gate might not have an immediate effect. See "Notes/Constraints/Caveats"
 section for more details.
@@ -618,21 +614,17 @@ feature.
 NOTE: Also set `disable-supported` to `true` or `false` in `kep.yaml`.
 -->
 
-Yes. This will result in the timestamp value being eventually set to `nil`. More details in
-"Upgrade / Downgrade Strategy" section.
+Yes - partially. The value will be reset to `nil` unless PV already had the timestamp field updated on phase transition
+with feature gate enabled. More details in "Upgrade / Downgrade Strategy" section.
 
 ###### What happens if we reenable the feature if it was previously rolled back?
 
 No issues expected. There are three cases that can occur for a PV:
 
   1. PV did not transition its phase when feature gate was enabled - the `LastPhaseTransitionTime` field was not added 
      to the PV object so this is the same case as enabling the feature gate for the first time.
-  2. PV did transition its phase but the `LastPhaseTransitionTime` *was not* reset to `nil` because the PV was not 
-     validated when the feature was enabled - the timestamp value will be updated on next phase change as if the feature
-     gate was never disabled.
-  2. PV did transition its phase but the `LastPhaseTransitionTime` *was* reset to `nil` because the PV was validated at
-     least once already while feature was enabled - the timestamp value will be updated on next phase change because
-     updates from `nil` are allowed.
+  2. PV did transition its phase and the `LastPhaseTransitionTime` is already reset - the timestamp value will be 
+     updated on next phase change as if the feature gate was never disabled.
 
 See "Upgrade / Downgrade Strategy" and "Notes/Constraints/Caveats" sections for more details.