Skip to content

config/v1/types_cluster_operator: ClusterOperatorStatus doc wordsmithing #501

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
openshift-merge-robot merged 1 commit into from
Nov 5, 2019
Merged

config/v1/types_cluster_operator: ClusterOperatorStatus doc wordsmithing #501

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 15 additions & 14 deletions config/v1/0000_00_cluster-version-operator_01_clusteroperator.crd.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down
11 changes: 5 additions & 6 deletions config/v1/0000_00_cluster-version-operator_01_clusterversion.crd.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
47 changes: 33 additions & 14 deletions config/v1/types_cluster_operator.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"`

Expand All @@ -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
Expand Down Expand Up @@ -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"`
Expand All @@ -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"`

Expand All @@ -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`
Expand Down
14 changes: 7 additions & 7 deletions config/v1/zz_generated.swagger_doc_generated.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.