diff --git a/config/v1/0000_00_cluster-version-operator_01_clusteroperator.crd.yaml b/config/v1/0000_00_cluster-version-operator_01_clusteroperator.crd.yaml index 294e4ee2271..1f938901061 100644 --- a/config/v1/0000_00_cluster-version-operator_01_clusteroperator.crd.yaml +++ b/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,7 +85,7 @@ 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: @@ -93,15 +93,14 @@ spec: 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: diff --git a/config/v1/0000_00_cluster-version-operator_01_clusterversion.crd.yaml b/config/v1/0000_00_cluster-version-operator_01_clusterversion.crd.yaml index 37d6516e871..ccde0db23bb 100644 --- a/config/v1/0000_00_cluster-version-operator_01_clusterversion.crd.yaml +++ b/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,7 +210,7 @@ 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: @@ -218,15 +218,14 @@ spec: 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 diff --git a/config/v1/types_cluster_operator.go b/config/v1/types_cluster_operator.go index 8be68e0ddc2..46783f9733e 100644 --- a/config/v1/types_cluster_operator.go +++ b/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` diff --git a/config/v1/zz_generated.swagger_doc_generated.go b/config/v1/zz_generated.swagger_doc_generated.go index fb64b94e675..03393511887 100644 --- a/config/v1/zz_generated.swagger_doc_generated.go +++ b/config/v1/zz_generated.swagger_doc_generated.go @@ -404,8 +404,8 @@ func (ClusterOperatorSpec) SwaggerDoc() map[string]string { var map_ClusterOperatorStatus = map[string]string{ "": "ClusterOperatorStatus provides information about the status of the operator.", - "conditions": "conditions describes the state of the operator's reconciliation functionality.", - "versions": "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\".", + "conditions": "conditions describes the state of the operator's managed and monitored components.", + "versions": "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.", "relatedObjects": "relatedObjects is a list of objects that are \"interesting\" or related to this operator. Common uses are: 1. the detailed resource driving the operator 2. operator namespaces 3. operand namespaces", "extension": "extension contains any additional status information specific to the operator which owns this status object.", } @@ -415,11 +415,11 @@ func (ClusterOperatorStatus) SwaggerDoc() map[string]string { } var map_ClusterOperatorStatusCondition = map[string]string{ - "": "ClusterOperatorStatusCondition represents the state of the operator's reconciliation functionality.", - "type": "type specifies the state of the operator's reconciliation functionality.", + "": "ClusterOperatorStatusCondition represents the state of the operator's managed and monitored components.", + "type": "type specifies the aspect reported by this condition.", "status": "status of the condition, one of True, False, Unknown.", - "lastTransitionTime": "lastTransitionTime is the time of the last update to the current status object.", - "reason": "reason is the reason for the condition's last transition. Reasons are CamelCase", + "lastTransitionTime": "lastTransitionTime is the time of the last update to the current status property.", + "reason": "reason is the CamelCase reason for the condition's current status.", "message": "message provides additional information about the current condition. This is only to be consumed by humans.", } @@ -441,7 +441,7 @@ func (ObjectReference) SwaggerDoc() map[string]string { var map_OperandVersion = map[string]string{ "name": "name is the name of the particular operand this version is for. It usually matches container images, not operators.", - "version": "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 1.1.0", + "version": "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", } func (OperandVersion) SwaggerDoc() map[string]string {