Merge pull request #28624 from adellape/osdk_operatorconditions

Author: adellape

modules/osdk-operatorconditions.adoc

@@ -0,0 +1,78 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/osdk-generating-csvs.adoc
+
+[id="osdk-operatorconditions_{context}"]
+= Enabling Operator conditions
+
+Operator Lifecycle Manager (OLM) provides Operators with a channel to communicate complex states that influence OLM behavior while managing the Operator. By default, OLM creates an `OperatorCondition` custom resource definition (CRD) when it installs an Operator. Based on the conditions set in the `OperatorCondition` custom resource (CR), the behavior of OLM changes accordingly.
+
+To support Operator conditions, an Operator must be able to read the `OperatorCondition` CR created by OLM and have the ability to:
+
+* Get the specific condition.
+* Set the status of a specific condition.
+
+This can be accomplished by using the link:https://github.com/operator-framework/operator-lib/tree/v0.3.0[`operator-lib`] library. An Operator author can provide a link:https://github.com/kubernetes-sigs/controller-runtime/tree/master/pkg/client[`controller-runtime` client] in their Operator for the library to access the `OperatorCondition` CR owned by the Operator in the cluster.
+
+The library provides a generic `Conditions` interface, which has the following methods to `Get` and `Set` a `conditionType` in the `OperatorCondition` CR:
+
+`Get`:: To get the specific condition, the library uses the `client.Get` function from `controller-runtime`, which requires an `ObjectKey` of type `types.NamespacedName` present in `conditionAccessor`.
+
+`Set`:: To update the status of the specific condition, the library uses the `client.Update` function from `controller-runtime`. An error occurs if the `conditionType` is not present in the CRD.
+
+The Operator is allowed to modify only the `status` subresource of the CR. Operators can either delete or update the `status.conditions` array to include the condition. For more details on the format and description of the fields present in the conditions, see the upstream link:https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Condition[Condition GoDocs].
+
+[NOTE]
+====
+Operator SDK v1.3.0 supports `operator-lib` v0.3.0.
+====
+
+.Prerequisites
+
+* An Operator project generated using the Operator SDK.
+
+.Procedure
+
+To enable Operator conditions in your Operator project:
+
+. In the `go.mod` file of your Operator project, add `operator-framework/operator-lib` as a required library:
++
+[source,go]
+----
+module github.com/example-inc/memcached-operator
+
+go 1.15
+
+require (
+  k8s.io/apimachinery v0.19.2
+  k8s.io/client-go v0.19.2
+  sigs.k8s.io/controller-runtime v0.7.0
+  operator-framework/operator-lib v0.3.0
+)
+----
+
+. Write your own constructor in your Operator logic that:
++
+--
+* Accepts a `controller-runtime` client.
+* Accepts a `conditionType`.
+* Returns a `Condition` interface to update or add conditions.
+--
++
+Because OLM currently supports the `Upgradeable` condition, you can create an interface that has methods to access the `Upgradeable` condition. For example:
++
+[source,go]
+----
+import (
+  ...
+  apiv1 "github.com/operator-framework/api/pkg/operators/v1"
+)
+
+func NewUpgradeable(cl client.Client) (Condition, error) {
+  return NewCondition(cl, "apiv1.OperatorUpgradeable")
+}
+
+cond, err := NewUpgradeable(cl);
+----
++
+In this example, the `NewUpgradeable` constructor is further used to create a variable `cond` of type `Condition`. The `cond` variable would in turn have `Get` and `Set` methods, which can be used for handling the OLM `Upgradeable` condition.

operators/operator_sdk/osdk-generating-csvs.adoc

@@ -37,6 +37,11 @@ include::modules/olm-enabling-operator-for-multi-arch.adoc[leveloffset=+1]
 include::modules/olm-arch-os-support.adoc[leveloffset=+2]
 
 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]
+
 include::modules/olm-defining-csv-webhooks.adoc[leveloffset=+1]
 .Additional resources