Document ways to trigger/not trigger exponential backoff

[djzager]

Related to #617

As a user of controller-runtime, it is not immediately clear what returns from a Reconcile() will force a requeue with (or without) an exponential backoff. Some quick examples:

return reconcile.Result{requeue: true}, nil

return reconcile.Result{requeueAfter: time.Duration(60) * time.Second}, nil

// err != nil
return reconcile.Result{}, fmt.Errorf("My custom error string")

[djzager]

/kind documentation

[djzager]

I see mentions of backoff in

controller-runtime/pkg/internal/controller/controller_test.go

Lines 352 to 354 in 40070e2

	// TODO(directxman12): we should ensure that backoff occurrs with error requeue
	It("should not reset backoff until there's a non-error result", func() {

I think the two potential landing spots for documenting the requeue/backoff behavior would be:

1. in the godoc for controller-runtime (either in the controller directly or in workqueue?)
2. in the kubebuilder book (maybe here?). This would require a separate issue against github.com/kubernetes-sigs/kubebuilder

[vincepri]

/priority important-longterm
/help

[k8s-ci-robot]

@vincepri:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/priority important-longterm
/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[vincepri]

/lifecycle frozen

[cflewis]

I care about this. I spent a couple days writing code to do this and then someone on my team said "maybe this is a Kubebuilder feature" which got me to here.

What do I need to do to make an exponential backoff during a reconcile happen?

[vincepri]

@cflewis Today, you only need to return an error to make it go in exponential backoff loop.