Add OLM OperatorConditions docs

_topic_map.yml

@@ -1058,6 +1058,8 @@ Topics:
       File: olm-understanding-dependency-resolution
     - Name: Operator groups
       File: olm-understanding-operatorgroups
+    - Name: Operator conditions
+      File: olm-operatorconditions
     - Name: Metrics
       File: olm-understanding-metrics
     - Name: Webhooks
@@ -1101,6 +1103,9 @@ Topics:
   - Name: Viewing Operator status
     File: olm-status
     Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated
+  - Name: Managing Operator conditions
+    File: olm-managing-operatorconditions
+    Distros: openshift-origin,openshift-enterprise,openshift-webscale
   - Name: Allowing non-cluster administrators to install Operators
     File: olm-creating-policy
     Distros: openshift-origin,openshift-enterprise,openshift-webscale

modules/olm-crds.adoc

@@ -31,4 +31,8 @@ The following custom resource definitions (CRDs) are defined and managed by Oper
 |`OperatorGroup`
 |`og`
 |Configures all Operators deployed in the same namespace as the `OperatorGroup` object to watch for their custom resource (CR) in a list of namespaces or cluster-wide.
+
+|`OperatorConditions`
+|-
+|Creates a communication channel between OLM and an Operator it manages. Operators can write to the `Status.Conditions` array to communicate complex states to OLM.
 |===

modules/olm-operatorconditions-about.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * operators/understanding/olm/olm-understanding-olm.adoc
+// * operators/understanding/olm/olm-operatorconditions.adoc
+
+[id="olm-about-operatorconditions_{context}"]
+ifeval::["{context}" == "olm-understanding-olm"]
+= Operator conditions
+endif::[]
+ifeval::["{context}" != "olm-understanding-olm"]
+= About Operator conditions
+endif::[]
+
+As part of its role in managing the lifecycle of an Operator, Operator Lifecycle Manager (OLM) infers the state of an Operator from the state of Kubernetes resources that define the Operator. While this approach provides some level of assurance that an Operator is in a given state, there are many instances where an Operator might need to communicate information to OLM that could not be inferred otherwise. This information can then be used by OLM to better manage the lifecycle of the Operator.
+
+OLM provides a custom resource definition (CRD) called `OperatorCondition` that allows Operators to communicate conditions to OLM. There are a set of supported conditions that influence management of the Operator by OLM when present in the `Status.Conditions` array of an `OperatorCondition` resource.

modules/olm-overriding-operatorconditions.adoc

@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-managing-operatorconditions.adoc
+
+[id="olm-supported-operatorconditions_{context}"]
+= Overriding Operator conditions
+
+As a cluster administrator, you might want to ignore a supported Operator condition reported by an Operator. When present, Operator conditions in the `Spec.Overrides` array override the conditions in the `Status.Conditions` array, allowing cluster administrators to deal with situations where an Operator is incorrectly reporting a state to Operator Lifecycle Manager (OLM).
+
+For example, consider a known version of an Operator that always communicates that it is not upgradeable. In this instance, you might want to upgrade the Operator despite the Operator communicating that it is not upgradeable. This could be accomplished by overriding the Operator condition by adding the condition `type` and `status` to the `Spec.Overrides` array in the `OperatorCondition` resource.
+
+.Prerequisites
+
+* An Operator with an `OperatorCondition` resource, installed using OLM.
+
+.Procedure
+
+. Edit the `OperatorCondition` resource for the Operator:
++
+[source,terminal]
+----
+$ oc edit operatorcondition <name>
+----
+
+. Add a `Spec.Overrides` array to the object:
++
+.Example Operator condition override
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1
+kind: OperatorCondition
+metadata:
+  name: my-operator
+  namespace: operators
+spec:
+  overrides:
+  - type: Upgradeable <1>
+    status: "True"
+    reason: "upgradeIsSafe"
+    message: "This is a known issue with the Operator where it always reports that it cannot be upgraded."
+status:
+  conditions:
+  - type: Upgradeable
+    status: "False"
+    reason: "migration"
+    message: "The operator is performing a migration."
+    lastTransitionTime: "2020-08-24T23:15:55Z"
+----
+<1> Allows the cluster administrator to change the upgrade readiness to `True`.

modules/olm-supported-operatorconditions.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * operators/understanding/olm/olm-operatorconditions.adoc
+
+[id="olm-supported-operatorconditions_{context}"]
+= Supported conditions
+
+Operator Lifecycle Manager (OLM) supports the following Operator conditions.
+
+[id="olm-upgradeable-operatorcondition_{context}"]
+== Upgradeable condition
+
+The `Upgradeable` Operator condition prevents an existing cluster service version (CSV) from being replaced by a newer version of the CSV. This condition is useful when:
+
+* An Operator is about to start a critical process and should not be upgraded until the process is completed.
+* An Operator is performing a migration of custom resources (CRs) that must be completed before the Operator is ready to be upgraded.
+
+.Example `Upgradeable` Operator condition
+[source,yaml]
+----
+apiVersion: operators.coreos.com/v1
+kind: OperatorCondition
+metadata:
+  name: my-operator
+  namespace: operators
+status:
+  conditions:
+  - type: Upgradeable <1>
+    status: "False" <2>
+    reason: "migration"
+    message: "The Operator is performing a migration."
+    lastTransitionTime: "2020-08-24T23:15:55Z"
+----
+<1> Name of the condition.
+<2> A `False` value indicates the Operator is not ready to be upgraded. OLM prevents a CSV that replaces the existing CSV of the Operator from leaving the `Pending` phase.

modules/olm-updating-use-operatorconditions.adoc

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * operators/admin/olm-managing-operatorconditions.adoc
+
+[id="olm-updating-use-operatorconditions_{context}"]
+= Updating your Operator to use Operator conditions
+
+Operator Lifecycle Manager (OLM) automatically creates an `OperatorCondition` resource for each `ClusterServiceVersion` resource that it reconciles. All service accounts in the CSV are granted the RBAC to interact with the `OperatorCondition` owned by the Operator.
+
+An Operator author can develop their Operator to use the `operator-lib` library such that, after the Operator has been deployed by OLM, it can set its own conditions. For more on writing logic to set Operator conditions as an Operator author, see the Operator SDK documentation.
+
+[id="olm-updating-use-operatorconditions-defaults_{context}"]
+== Setting defaults
+
+In an effort to remain backwards compatible, OLM treats the absence of an `OperatorCondition` resource as opting out of the condition. Therefore, an Operator that opts in to using Operator conditions should set default conditions before the ready probe for the pod is set to `true`. This provides the Operator with a grace period to update the condition to the correct state.

operators/admin/olm-managing-operatorconditions.adoc

@@ -0,0 +1,16 @@
+[id="olm-managing-operatorconditions"]
+= Managing Operator conditions
+include::modules/common-attributes.adoc[]
+:context: olm-managing-operatorconditions
+
+toc::[]
+
+As a cluster administrator, you can manage Operator conditions by using Operator Lifecycle Manager (OLM).
+
+include::modules/olm-overriding-operatorconditions.adoc[leveloffset=+1]
+include::modules/olm-updating-use-operatorconditions.adoc[leveloffset=+1]
+
+[id="olm-managing-operatorconditions-addtl-resources"]
+== Additional resources
+
+* xref:../../operators/understanding/olm/olm-operatorconditions.adoc#olm-operatorconditions[Operator conditions]

operators/operator_sdk/osdk-generating-csvs.adoc

@@ -40,7 +40,7 @@ include::modules/osdk-suggested-namespace.adoc[leveloffset=+1]
 include::modules/osdk-operatorconditions.adoc[leveloffset=+1]
 .Additional resources
 
-* xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[OLM concepts -> Operator conditions]
+* xref:../../operators/understanding/olm/olm-operatorconditions.adoc#olm-operatorconditions[Operator conditions]
 
 include::modules/olm-defining-csv-webhooks.adoc[leveloffset=+1]
 .Additional resources

operators/understanding/olm/olm-operatorconditions.adoc

@@ -0,0 +1,17 @@
+[id="olm-operatorconditions"]
+= Operator conditions
+include::modules/common-attributes.adoc[]
+:context: olm-operatorconditions
+
+toc::[]
+
+This guide outlines how Operator Lifecycle Manager (OLM) uses Operator conditions.
+
+include::modules/olm-operatorconditions-about.adoc[leveloffset=+1]
+include::modules/olm-supported-operatorconditions.adoc[leveloffset=+1]
+
+[id="olm-operatorconditions-addtl-resources"]
+== Additional resources
+
+* xref:../../../operators/admin/olm-managing-operatorconditions.adoc#olm-operatorconditions[Managing Operator conditions]
+* xref:../../../operators/operator_sdk/osdk-generating-csvs.adoc#osdk-operatorconditions_osdk-generating-csvs[Enabling Operator conditions]

operators/understanding/olm/olm-understanding-olm.adoc

@@ -15,4 +15,8 @@ include::modules/olm-subscription.adoc[leveloffset=+2]
 include::modules/olm-installplan.adoc[leveloffset=+2]
 include::modules/olm-operatorgroups-about.adoc[leveloffset=+2]
 
-For more information, see the xref:../../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-understanding-operatorgroups[Operator groups] guide.
+For more information, see xref:../../../operators/understanding/olm/olm-understanding-operatorgroups.adoc#olm-understanding-operatorgroups[Operator groups].
+
+include::modules/olm-operatorconditions-about.adoc[leveloffset=+2]
+
+For more information, see xref:../../../operators/understanding/olm/olm-operatorconditions.adoc#olm-operatorconditions[Operator conditions].