Add reconcile details (#2612)

Author: bradtopol

doc/user-guide.md

@@ -249,7 +249,89 @@ return reconcile.Result{RequeueAfter: time.Second*5}, nil
 
 **Note:** Returning `Result` with `RequeueAfter` set is how you can periodically reconcile a CR.
 
-For a guide on Reconcilers, Clients, and interacting with resource Events, see the [Client API doc][doc_client_api].
+#### Reconcile Result Use Cases
+**The following are possible reconcile loop return options.**
+
+#### 1. With the error:
+
+If an error is encountered during processing the appropriate return option is to return an error.
+This results in the reconcile loop being re-triggered to run again.
+
+**Usage**
+```Go
+return reconcile.Result{}, err
+```
+
+**Example:**
+
+In the example below a `reconcile.Result{}, err` is used when there is an error reading the object.
+As a result the request is requeued for another try.
+```Go
+// Fetch the Memcached instance
+memcached := &cachev1alpha1.Memcached{}
+err := r.client.Get(context.TODO(), request.NamespacedName, memcached)
+if err != nil {
+  if errors.IsNotFound(err) {
+		...
+  }
+  // Error reading the object - requeue the request.
+  reqLogger.Error(err, "Failed to get Memcached")
+  return reconcile.Result{}, err
+}
+```
+
+#### 2. Without an error:
+
+There are several situations where although no error occured, the reconcile loop should signify
+during its return that it needs to run again.
+
+**Usage**
+```Go
+return reconcile.Result{Requeue: true}, nil
+```
+
+**Example:**
+
+In the example below a `reconcile.Result{Requeue: true}, nil` is used because a new resource is being created and as such there is the potential that further processing is required. Thus, the reconcile loop needs to trigger a requeue but there is no error associated with this requeue.
+As a result the request is requeued for another try.
+```Go
+// Define a new deployment
+dep := r.deploymentForMemcached(memcached)
+...
+
+// Deployment created successfully - return and requeue
+return reconcile.Result{Requeue: true}, nil
+```
+
+#### 3. Without an error and no need to requeue the request:
+
+In some situations, such as when the primary resource has been deleted, there is no need to
+requeue the request for another attempt
+
+**Usage**
+```Go
+return reconcile.Result{}, nil
+```
+
+**Example:**
+
+In the example below a `reconcile.Result{}, nil` is used because the Memcached resource was not found, and no further processing is required.  
+```Go
+// Fetch the Memcached instance
+memcached := &cachev1alpha1.Memcached{}
+err := r.client.Get(context.TODO(), request.NamespacedName, memcached)
+if err != nil {
+	if errors.IsNotFound(err) {
+		// Request object not found, could have been deleted after reconcile request.
+		// Owned objects are automatically garbage collected. For additional cleanup logic use finalizers.
+		// Return and don't requeue
+		reqLogger.Info("Memcached resource not found. Ignoring since object must be deleted")
+		return reconcile.Result{}, nil
+	}
+...
+```
+
+For a guide on Reconcilers, Clients, and interacting with resource Events, see the [Client API doc][doc_client_api] and the [controller-runtime documentation over reconcile][controller-runtime-reconcile-godoc].
 
 ## Build and run the operator
 
@@ -760,6 +842,7 @@ When the operator is not running in a cluster, the Manager will return an error
 [event_filtering]:./user/event-filtering.md
 [controller_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller#Options
 [controller_godocs]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller
+[controller-runtime-reconcile-godoc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Reconciler
 [operator_scope]:./operator-scope.md
 [install_guide]: ./user/install-operator-sdk.md
 [pod_eviction_timeout]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/#options

website/content/en/docs/golang/quickstart.md

@@ -238,7 +238,89 @@ return reconcile.Result{RequeueAfter: time.Second*5}, nil
 
 **Note:** Returning `Result` with `RequeueAfter` set is how you can periodically reconcile a CR.
 
-For a guide on Reconcilers, Clients, and interacting with resource Events, see the [Client API doc][doc_client_api].
+#### Reconcile Result Use Cases
+**The following are possible reconcile loop return options.**
+
+#### 1. With the error:
+
+If an error is encountered during processing the appropriate return option is to return an error.
+This results in the reconcile loop being re-triggered to run again.
+
+**Usage**
+```Go
+return reconcile.Result{}, err
+```
+
+**Example:**
+
+In the example below a `reconcile.Result{}, err` is used when there is an error reading the object.
+As a result the request is requeued for another try.
+```Go
+// Fetch the Memcached instance
+memcached := &cachev1alpha1.Memcached{}
+err := r.client.Get(context.TODO(), request.NamespacedName, memcached)
+if err != nil {
+  if errors.IsNotFound(err) {
+		...
+  }
+  // Error reading the object - requeue the request.
+  reqLogger.Error(err, "Failed to get Memcached")
+  return reconcile.Result{}, err
+}
+```
+
+#### 2. Without an error:
+
+There are several situations where although no error occured, the reconcile loop should signify
+during its return that it needs to run again.
+
+**Usage**
+```Go
+return reconcile.Result{Requeue: true}, nil
+```
+
+**Example:**
+
+In the example below a `reconcile.Result{Requeue: true}, nil` is used because a new resource is being created and as such there is the potential that further processing is required. Thus, the reconcile loop needs to trigger a requeue but there is no error associated with this requeue.
+As a result the request is requeued for another try.
+```Go
+// Define a new deployment
+dep := r.deploymentForMemcached(memcached)
+...
+
+// Deployment created successfully - return and requeue
+return reconcile.Result{Requeue: true}, nil
+```
+
+#### 3. Without an error and no need to requeue the request:
+
+In some situations, such as when the primary resource has been deleted, there is no need to
+requeue the request for another attempt
+
+**Usage**
+```Go
+return reconcile.Result{}, nil
+```
+
+**Example:**
+
+In the example below a `reconcile.Result{}, nil` is used because the Memcached resource was not found, and no further processing is required.  
+```Go
+// Fetch the Memcached instance
+memcached := &cachev1alpha1.Memcached{}
+err := r.client.Get(context.TODO(), request.NamespacedName, memcached)
+if err != nil {
+	if errors.IsNotFound(err) {
+		// Request object not found, could have been deleted after reconcile request.
+		// Owned objects are automatically garbage collected. For additional cleanup logic use finalizers.
+		// Return and don't requeue
+		reqLogger.Info("Memcached resource not found. Ignoring since object must be deleted")
+		return reconcile.Result{}, nil
+	}
+...
+```
+
+For a guide on Reconcilers, Clients, and interacting with resource Events, see the [Client API doc][doc_client_api] and the [controller-runtime documentation over reconcile][controller-runtime-reconcile-godoc].
 
 ## Build and run the operator
 
@@ -751,6 +833,7 @@ When the operator is not running in a cluster, the Manager will return an error
 [event_filtering]:/docs/golang/references/event-filtering/
 [controller_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller#Options
 [controller_godocs]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/controller
+[controller-runtime-reconcile-godoc]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/reconcile#Reconciler
 [operator_scope]:/docs/operator-scope/
 [pod_eviction_timeout]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/#options
 [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options