Skip to content

📖 Fix docs & comments referring to "Reconciler" instead of "reconcile" #434

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.

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
merged 1 commit into from
May 24, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion examples/builtins/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ func main() {
os.Exit(1)
}

// Setup a new controller to Reconciler ReplicaSets
// Setup a new controller to reconcile ReplicaSets
entryLog.Info("Setting up controller")
c, err := controller.New("foo-controller", mgr, controller.Options{
Reconciler: &reconcileReplicaSet{client: mgr.GetClient(), log: log.WithName("reconciler")},
Expand Down
2 changes: 1 addition & 1 deletion pkg/controller/controller.go
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ type Options struct {
// Work typically is reads and writes Kubernetes objects to make the system state match the state specified
// in the object Spec.
type Controller interface {
// Reconciler is called to Reconciler an object by Namespace/Name
// Reconciler is called to reconcile an object by Namespace/Name
reconcile.Reconciler

// Watch takes events provided by a Source and uses the EventHandler to
Expand Down
26 changes: 13 additions & 13 deletions pkg/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,15 @@ clients, caches, schemes, etc. Controllers should be Started through the Manage
Controller

Controller implements a Kubernetes API by responding to events (object Create, Update, Delete) and ensuring that
the state specified in the Spec of the object matches the state of the system. This is called a Reconciler.
the state specified in the Spec of the object matches the state of the system. This is called a reconcile.
If they do not match, the Controller will create / update / delete objects as needed to make them match.

Controllers are implemented as worker queues that process reconcile.Requests (requests to Reconciler the
Controllers are implemented as worker queues that process reconcile.Requests (requests to reconcile the
state for a specific object).

Unlike http handlers, Controllers DO NOT handle events directly, but enqueue Requests to eventually Reconciler
Unlike http handlers, Controllers DO NOT handle events directly, but enqueue Requests to eventually reconcile
the object. This means the handling of multiple events may be batched together and the full state of the
system must be read for each Reconciler.
system must be read for each reconcile.

* Controllers require a Reconciler to be provided to perform the work pulled from the work queue.

Expand All @@ -65,11 +65,11 @@ Validating webhook is used to validate if an object meets certain requirements.
Reconciler

Reconciler is a function provided to a Controller that may be called at anytime with the Name and Namespace of an object.
When called, Reconciler will ensure that the state of the system matches what is specified in the object at the
time Reconciler is called.
When called, the Reconciler will ensure that the state of the system matches what is specified in the object at the
time the Reconciler is called.

Example: Reconciler invoked for a ReplicaSet object. The ReplicaSet specifies 5 replicas but only
3 Pods exist in the system. Reconciler creates 2 more Pods and sets their OwnerReference to point at the
3 Pods exist in the system. The Reconciler creates 2 more Pods and sets their OwnerReference to point at the
ReplicaSet with controller=true.

* Reconciler contains all of the business logic of a Controller.
Expand All @@ -80,7 +80,7 @@ a mapping (e.g. owner references) that maps the object that triggers the reconci

* Reconciler is provided the Name / Namespace of the object to reconcile.

* Reconciler does not care about the event contents or event type responsible for triggering the Reconciler.
* Reconciler does not care about the event contents or event type responsible for triggering the reconcile.
- e.g. it doesn't matter whether a ReplicaSet was created or updated, Reconciler will always compare the number of
Pods in the system against what is specified in the object at the time it is called.

Expand Down Expand Up @@ -159,7 +159,7 @@ Controller Example
1.2 Pod (created by ReplicaSet) -> handler.EnqueueRequestForOwnerHandler - enqueue a Request with the
Owning ReplicaSet Namespace and Name.

2. Reconciler ReplicaSet in response to an event
2. reconcile ReplicaSet in response to an event

2.1 ReplicaSet object created -> Read ReplicaSet, try to read Pods -> if is missing create Pods.

Expand All @@ -169,7 +169,7 @@ Owning ReplicaSet Namespace and Name.

Watching and EventHandling

Controllers may Watch multiple Kinds of objects (e.g. Pods, ReplicaSets and Deployments), but they Reconciler
Controllers may Watch multiple Kinds of objects (e.g. Pods, ReplicaSets and Deployments), but they reconcile
only a single Type. When one Type of object must be updated in response to changes in another Type of object,
an EnqueueRequestFromMapFunc may be used to map events from one type to another. e.g. Respond to a cluster resize
event (add / delete Node) by re-reconciling all instances of some API.
Expand All @@ -189,10 +189,10 @@ Controller Writing Tips

Reconciler Runtime Complexity:

* It is better to write Controllers to perform an O(1) Reconciler N times (e.g. on N different objects) instead of
performing an O(N) Reconciler 1 time (e.g. on a single object which manages N other objects).
* It is better to write Controllers to perform an O(1) reconcile N times (e.g. on N different objects) instead of
performing an O(N) reconcile 1 time (e.g. on a single object which manages N other objects).

* Example: If you need to update all Services in response to a Node being added - Reconciler Services but Watch
* Example: If you need to update all Services in response to a Node being added - reconcile Services but Watch
Nodes (transformed to Service object name / Namespaces) instead of Reconciling Nodes and updating Services

Event Multiplexing:
Expand Down
2 changes: 1 addition & 1 deletion pkg/handler/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ EnqueueRequestForOwner - Enqueues a reconcile.Request containing the Name and Na
This will cause owner of the object that was the source of the Event (e.g. the owner object that created the object)
to be reconciled.

EnqueueRequestsFromMapFunc - Enqueues Reconciler.Requests resulting from a user provided transformation function run against the
EnqueueRequestsFromMapFunc - Enqueues reconcile.Requests resulting from a user provided transformation function run against the
object in the Event. This will cause an arbitrary collection of objects (defined from a transformation of the
source object) to be reconciled.
*/
Expand Down