reconcile

package
v0.19.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2024 License: Apache-2.0 Imports: 6 Imported by: 6,946

Documentation

Overview

Package reconcile defines the Reconciler interface to implement Kubernetes APIs. Reconciler is provided to Controllers at creation time as the API implementation.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func TerminalError added in v0.15.0

func TerminalError(wrapped error) error

TerminalError is an error that will not be retried but still be logged and recorded in metrics.

Types

type Func

type Func = TypedFunc[Request]

Func is a function that implements the reconcile interface.

Example

This example implements a simple no-op reconcile function that prints the object to be Reconciled.

package main

import (
	"context"
	"fmt"
	"time"

	"k8s.io/apimachinery/pkg/types"
	"sigs.k8s.io/controller-runtime/pkg/reconcile"
)

func main() {
	r := reconcile.Func(func(_ context.Context, o reconcile.Request) (reconcile.Result, error) {
		// Create your business logic to create, update, delete objects here.
		fmt.Printf("Name: %s, Namespace: %s", o.Name, o.Namespace)
		return reconcile.Result{}, nil
	})

	res, err := r.Reconcile(context.Background(), reconcile.Request{NamespacedName: types.NamespacedName{Namespace: "default", Name: "test"}})
	if err != nil || res.Requeue || res.RequeueAfter != time.Duration(0) {
		fmt.Printf("got requeue request: %v, %v\n", err, res)
	}

}
Output:

Name: test, Namespace: default

type ObjectReconciler added in v0.17.0

type ObjectReconciler[object client.Object] interface {
	Reconcile(context.Context, object) (Result, error)
}

ObjectReconciler is a specialized version of Reconciler that acts on instances of client.Object. Each reconciliation event gets the associated object from Kubernetes before passing it to Reconcile. An ObjectReconciler can be used in Builder.Complete by calling AsReconciler. See Reconciler for more details.

type Reconciler

type Reconciler = TypedReconciler[Request]

Reconciler implements a Kubernetes API for a specific Resource by Creating, Updating or Deleting Kubernetes objects, or by making changes to systems external to the cluster (e.g. cloudproviders, github, etc).

reconcile implementations compare the state specified in an object by a user against the actual cluster state, and then perform operations to make the actual cluster state reflect the state specified by the user.

Typically, reconcile is triggered by a Controller in response to cluster Events (e.g. Creating, Updating, Deleting Kubernetes objects) or external Events (GitHub Webhooks, polling external sources, etc).

Example reconcile Logic:

* Read an object and all the Pods it owns. * Observe that the object spec specifies 5 replicas but actual cluster contains only 1 Pod replica. * Create 4 Pods and set their OwnerReferences to the object.

reconcile may be implemented as either a type:

type reconciler struct {}

func (reconciler) Reconcile(ctx context.Context, o reconcile.Request) (reconcile.Result, error) {
	// Implement business logic of reading and writing objects here
	return reconcile.Result{}, nil
}

Or as a function:

reconcile.Func(func(ctx context.Context, o reconcile.Request) (reconcile.Result, error) {
	// Implement business logic of reading and writing objects here
	return reconcile.Result{}, nil
})

Reconciliation is level-based, meaning action isn't driven off changes in individual Events, but instead is driven by actual cluster state read from the apiserver or a local cache. For example if responding to a Pod Delete Event, the Request won't contain that a Pod was deleted, instead the reconcile function observes this when reading the cluster state and seeing the Pod as missing.

func AsReconciler added in v0.17.0

func AsReconciler[object client.Object](client client.Client, rec ObjectReconciler[object]) Reconciler

AsReconciler creates a Reconciler based on the given ObjectReconciler.

type Request

type Request struct {
	// NamespacedName is the name and namespace of the object to reconcile.
	types.NamespacedName
}

Request contains the information necessary to reconcile a Kubernetes object. This includes the information to uniquely identify the object - its Name and Namespace. It does NOT contain information about any specific Event or the object contents itself.

type Result

type Result struct {
	// Requeue tells the Controller to requeue the reconcile key.  Defaults to false.
	Requeue bool

	// RequeueAfter if greater than 0, tells the Controller to requeue the reconcile key after the Duration.
	// Implies that Requeue is true, there is no need to set Requeue to true at the same time as RequeueAfter.
	RequeueAfter time.Duration
}

Result contains the result of a Reconciler invocation.

func (*Result) IsZero added in v0.5.9

func (r *Result) IsZero() bool

IsZero returns true if this result is empty.

type TypedFunc added in v0.19.0

type TypedFunc[request comparable] func(context.Context, request) (Result, error)

TypedFunc is a function that implements the reconcile interface.

func (TypedFunc[request]) Reconcile added in v0.19.0

func (r TypedFunc[request]) Reconcile(ctx context.Context, req request) (Result, error)

Reconcile implements Reconciler.

type TypedReconciler added in v0.19.0

type TypedReconciler[request comparable] interface {
	// Reconcile performs a full reconciliation for the object referred to by the Request.
	//
	// If the returned error is non-nil, the Result is ignored and the request will be
	// requeued using exponential backoff. The only exception is if the error is a
	// TerminalError in which case no requeuing happens.
	//
	// If the error is nil and the returned Result has a non-zero result.RequeueAfter, the request
	// will be requeued after the specified duration.
	//
	// If the error is nil and result.RequeueAfter is zero and result.Requeue is true, the request
	// will be requeued using exponential backoff.
	Reconcile(context.Context, request) (Result, error)
}

TypedReconciler implements an API for a specific Resource by Creating, Updating or Deleting Kubernetes objects, or by making changes to systems external to the cluster (e.g. cloudproviders, github, etc).

The request type is what event handlers put into the workqueue. The workqueue then de-duplicates identical requests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL