config/v1/types_cluster_operator: ClusterOperatorStatus doc wordsmithing

Leaning heavily on [1].  Autogenerated bumps via:

  $ hack/update-swagger-docs.sh
  $ make update-codegen-crds

[1]: https://github.com/openshift/cluster-version-operator/blob/cd332aa6ceb924fd49f7be7aeffce815dc81d663/docs/dev/clusteroperator.md#what-should-an-operator-report-with-clusteroperator-custom-resource

Author: wking

config/v1/0000_00_cluster-version-operator_01_clusteroperator.crd.yaml

@@ -71,12 +71,12 @@ spec:
           type: object
           properties:
             conditions:
-              description: conditions describes the state of the operator's reconciliation
-                functionality.
+              description: conditions describes the state of the operator's managed
+                and monitored components.
               type: array
               items:
                 description: ClusterOperatorStatusCondition represents the state of
-                  the operator's reconciliation functionality.
+                  the operator's managed and monitored components.
                 type: object
                 required:
                 - lastTransitionTime
@@ -85,23 +85,22 @@ spec:
                 properties:
                   lastTransitionTime:
                     description: lastTransitionTime is the time of the last update
-                      to the current status object.
+                      to the current status property.
                     type: string
                     format: date-time
                   message:
                     description: message provides additional information about the
                       current condition. This is only to be consumed by humans.
                     type: string
                   reason:
-                    description: reason is the reason for the condition's last transition.  Reasons
-                      are CamelCase
+                    description: reason is the CamelCase reason for the condition's
+                      current status.
                     type: string
                   status:
                     description: status of the condition, one of True, False, Unknown.
                     type: string
                   type:
-                    description: type specifies the state of the operator's reconciliation
-                      functionality.
+                    description: type specifies the aspect reported by this condition.
                     type: string
             extension:
               description: extension contains any additional status information specific
@@ -135,10 +134,12 @@ spec:
                     description: resource of the referent.
                     type: string
             versions:
-              description: versions is a slice of operand version tuples.  Operators
-                which manage multiple operands will have multiple entries in the array.  If
-                an operator is Available, it must have at least one entry.  You must
-                report the version of the operator itself with the name "operator".
+              description: versions is a slice of operator and operand version tuples.  Operators
+                which manage multiple operands will have multiple operand entries
+                in the array.  Available operators must report the version of the
+                operator itself with the name "operator". An operator reports a new
+                "operator" version when it has rolled out the new version to all of
+                its operands.
               type: array
               items:
                 type: object
@@ -152,8 +153,8 @@ spec:
                     type: string
                   version:
                     description: version indicates which version of a particular operand
-                      is currently being manage.  It must always match the Available
-                      condition.  If 1.0.0 is Available, then this must indicate 1.0.0
+                      is currently being managed.  It must always match the Available
+                      operand.  If 1.0.0 is Available, then this must indicate 1.0.0
                       even if the operator is trying to rollout 1.1.0
                     type: string
   versions:

config/v1/0000_00_cluster-version-operator_01_clusterversion.crd.yaml

@@ -201,7 +201,7 @@ spec:
               type: array
               items:
                 description: ClusterOperatorStatusCondition represents the state of
-                  the operator's reconciliation functionality.
+                  the operator's managed and monitored components.
                 type: object
                 required:
                 - lastTransitionTime
@@ -210,23 +210,22 @@ spec:
                 properties:
                   lastTransitionTime:
                     description: lastTransitionTime is the time of the last update
-                      to the current status object.
+                      to the current status property.
                     type: string
                     format: date-time
                   message:
                     description: message provides additional information about the
                       current condition. This is only to be consumed by humans.
                     type: string
                   reason:
-                    description: reason is the reason for the condition's last transition.  Reasons
-                      are CamelCase
+                    description: reason is the CamelCase reason for the condition's
+                      current status.
                     type: string
                   status:
                     description: status of the condition, one of True, False, Unknown.
                     type: string
                   type:
-                    description: type specifies the state of the operator's reconciliation
-                      functionality.
+                    description: type specifies the aspect reported by this condition.
                     type: string
             desired:
               description: desired is the version that the cluster is reconciling

config/v1/types_cluster_operator.go

@@ -34,15 +34,15 @@ type ClusterOperatorSpec struct {
 // ClusterOperatorStatus provides information about the status of the operator.
 // +k8s:deepcopy-gen=true
 type ClusterOperatorStatus struct {
-	// conditions describes the state of the operator's reconciliation functionality.
+	// conditions describes the state of the operator's managed and monitored components.
 	// +patchMergeKey=type
 	// +patchStrategy=merge
 	// +optional
 	Conditions []ClusterOperatorStatusCondition `json:"conditions,omitempty"  patchStrategy:"merge" patchMergeKey:"type"`
 
-	// versions is a slice of operand version tuples.  Operators which manage multiple operands will have multiple
-	// entries in the array.  If an operator is Available, it must have at least one entry.  You must report the version of
-	// the operator itself with the name "operator".
+	// versions is a slice of operator and operand version tuples.  Operators which manage multiple operands will have multiple
+	// operand entries in the array.  Available operators must report the version of the operator itself with the name "operator".
+	// An operator reports a new "operator" version when it has rolled out the new version to all of its operands.
 	// +optional
 	Versions []OperandVersion `json:"versions,omitempty"`
 
@@ -67,8 +67,8 @@ type OperandVersion struct {
 	// +required
 	Name string `json:"name"`
 
-	// version indicates which version of a particular operand is currently being manage.  It must always match the Available
-	// condition.  If 1.0.0 is Available, then this must indicate 1.0.0 even if the operator is trying to rollout
+	// version indicates which version of a particular operand is currently being managed.  It must always match the Available
+	// operand.  If 1.0.0 is Available, then this must indicate 1.0.0 even if the operator is trying to rollout
 	// 1.1.0
 	// +kubebuilder:validation:Required
 	// +required
@@ -107,10 +107,10 @@ const (
 )
 
 // ClusterOperatorStatusCondition represents the state of the operator's
-// reconciliation functionality.
+// managed and monitored components.
 // +k8s:deepcopy-gen=true
 type ClusterOperatorStatusCondition struct {
-	// type specifies the state of the operator's reconciliation functionality.
+	// type specifies the aspect reported by this condition.
 	// +kubebuilder:validation:Required
 	// +required
 	Type ClusterStatusConditionType `json:"type"`
@@ -120,12 +120,12 @@ type ClusterOperatorStatusCondition struct {
 	// +required
 	Status ConditionStatus `json:"status"`
 
-	// lastTransitionTime is the time of the last update to the current status object.
+	// lastTransitionTime is the time of the last update to the current status property.
 	// +kubebuilder:validation:Required
 	// +required
 	LastTransitionTime metav1.Time `json:"lastTransitionTime"`
 
-	// reason is the reason for the condition's last transition.  Reasons are CamelCase
+	// reason is the CamelCase reason for the condition's current status.
 	// +optional
 	Reason string `json:"reason,omitempty"`
 
@@ -135,21 +135,40 @@ type ClusterOperatorStatusCondition struct {
 	Message string `json:"message,omitempty"`
 }
 
-// ClusterStatusConditionType is the state of the operator's reconciliation functionality.
+// ClusterStatusConditionType is an aspect of operator state.
 type ClusterStatusConditionType string
 
 const (
-	// Available indicates that the binary maintained by the operator (eg: openshift-apiserver for the
+	// Available indicates that the operand (eg: openshift-apiserver for the
 	// openshift-apiserver-operator), is functional and available in the cluster.
 	OperatorAvailable ClusterStatusConditionType = "Available"
 
-	// Progressing indicates that the operator is actively making changes to the binary maintained by the
-	// operator (eg: openshift-apiserver for the openshift-apiserver-operator).
+	// Progressing indicates that the operator is actively rolling out new code,
+	// propagating config changes, or otherwise moving from one steady state to
+	// another.  Operators should not report progressing when they are reconciling
+	// a previously known state.
 	OperatorProgressing ClusterStatusConditionType = "Progressing"
 
 	// Degraded indicates that the operand is not functioning completely. An example of a degraded state
 	// would be if there should be 5 copies of the operand running but only 4 are running. It may still be available,
 	// but it is degraded
+
+	// Degraded indicated that the operator's current state does not match its
+	// desired state over a period of time resulting in a lower quality of service.
+	// The period of time may vary by component, but a Degraded state represents
+	// persistent observation of a condition.  As a result, a component should not
+	// oscillate in and out of Degraded state.  A service may be Available even
+	// if its degraded.  For example, your service may desire 3 running pods, but 1
+	// pod is crash-looping.  The service is Available but Degraded because it
+	// may have a lower quality of service.  A component may be Progressing but
+	// not Degraded because the transition from one state to another does not
+	// persist over a long enough period to report Degraded.  A service should not
+	// report Degraded during the course of a normal upgrade.  A service may report
+	// Degraded in response to a persistent infrastructure failure that requires
+	// administrator intervention.  For example, if a control plane host is unhealthy
+	// and must be replaced.  An operator should report Degraded if unexpected
+	// errors occur over a period, but the expectation is that all unexpected errors
+	// are handled as operators mature.
 	OperatorDegraded ClusterStatusConditionType = "Degraded"
 
 	// Upgradeable indicates whether the operator is in a state that is safe to upgrade. When status is `False`