v1

README

Composite Controller

Composite controller pattern is used to implement controllers that have a parent or main CRD, based on which the child objects are configured and created. The status of the child objects may be reflected on the parent object status. Changes in the parent object results in update of the child objects.

The lifecycle of the child objects are dependent on the parent object. The dependency can be in the form of owner reference or finalizer. In case of owner reference, the child objects have an owner reference metadata with the parent's reference. When the parent is deleted, the child objects are automatically deleted by the garbage collector. In case of finalizer based dependency, the parent object waits for some custom cleanup operations to complete. Once the cleanup operation is completed successfully, the finalizer on the parent object is removed and the parent is deleted.

Finalizer based cleanup strategy

The finalizer based cleanup strategy is relatively complex compared to the owner reference based cleanup. Following diagrams try to explain the sequence of the actions when finalizer based cleanup is used.

Create reconcile

Update reconcile

Delete reconcile

Documentation

Overview

Package v1 contains helpers to build a composite controller reconciler. It defines a Controller interface which provides methods required for reconciling a composite controller. A composite controller manages a set of child objects based on the desired state specified in a parent object. The package also provides an implementation of the Reconcile method that can be embedded in a controller to satisfy the controller-runtime's Reconciler interface.

Index

• Variables
• type CleanupStrategy
• type CompositeReconciler
  • func (c *CompositeReconciler) Init(mgr ctrl.Manager, ctrlr Controller, prototype client.Object, ...) error
  • func (c *CompositeReconciler) Reconcile(ctx context.Context, req ctrl.Request) (result ctrl.Result, reterr error)
• type CompositeReconcilerOption
  • func WithCleanupStrategy(cleanupStrat CleanupStrategy) CompositeReconcilerOption
  • func WithClient(cli client.Client) CompositeReconcilerOption
  • func WithFinalizer(finalizer string) CompositeReconcilerOption
  • func WithInitCondition(cndn metav1.Condition) CompositeReconcilerOption
  • func WithInstrumentation(tp trace.TracerProvider, mp metric.MeterProvider, log logr.Logger) CompositeReconcilerOption
  • func WithName(name string) CompositeReconcilerOption
  • func WithPrototype(obj client.Object) CompositeReconcilerOption
  • func WithScheme(scheme *runtime.Scheme) CompositeReconcilerOption
• type Controller

Variables

var DefaultInitCondition metav1.Condition = metav1.Condition{
	Type:    "Progressing",
	Status:  metav1.ConditionTrue,
	Reason:  "Initializing",
	Message: "Component initializing",
}

DefaultInitCondition is the default init condition used by the composite reconciler to add to the status of a new resource.

Types

type CleanupStrategy

type CleanupStrategy int

CleanupStrategy is the resource cleanup strategy used by the reconciler.

const (

	// OwnerReferenceCleanup depends on k8s garbage collector. All the child
	// objects of a parent are added with a reference of the parent object.
	// When the parent object gets deleted, all the child objects are garbage
	// collected.
	OwnerReferenceCleanup CleanupStrategy = iota
	// FinalizerCleanup allows using custom cleanup logic. When this strategy
	// is set, a finalizer is added to the parent object to avoid accidental
	// deletion of the object. When the object is marked for deletion with a
	// deletion timestamp, the custom cleanup code is executed to delete all
	// the child objects. Once all custom cleanup code finished, the finalizer
	// from the parent object is removed and the parent object is allowed to be
	// deleted.
	FinalizerCleanup
)

type CompositeReconciler

type CompositeReconciler struct {
	// contains filtered or unexported fields
}

CompositeReconciler defines a composite reconciler.

func (*CompositeReconciler) Init

func (c *CompositeReconciler) Init(mgr ctrl.Manager, ctrlr Controller, prototype client.Object, opts ...CompositeReconcilerOption) error

Init initializes the CompositeReconciler for a given Object with the given options.

func (*CompositeReconciler) Reconcile

func (c *CompositeReconciler) Reconcile(ctx context.Context, req ctrl.Request) (result ctrl.Result, reterr error)

Reconcile implements the composite controller reconciliation.

type CompositeReconcilerOption

type CompositeReconcilerOption func(*CompositeReconciler)

CompositeReconcilerOption is used to configure CompositeReconciler.

func WithCleanupStrategy

func WithCleanupStrategy(cleanupStrat CleanupStrategy) CompositeReconcilerOption

WithCleanupStrategy sets the CleanupStrategy of the CompositeReconciler.

func WithClient

func WithClient(cli client.Client) CompositeReconcilerOption

WithClient sets the k8s client in the reconciler.

func WithFinalizer

func WithFinalizer(finalizer string) CompositeReconcilerOption

WithFinalizer sets the name of the finalizer used by the CompositeReconciler.

func WithInitCondition

func WithInitCondition(cndn metav1.Condition) CompositeReconcilerOption

WithInitCondition sets the initial status Condition to be used by the CompositeReconciler on a resource object.

func WithInstrumentation

func WithInstrumentation(tp trace.TracerProvider, mp metric.MeterProvider, log logr.Logger) CompositeReconcilerOption

WithInstrumentation configures the instrumentation of the CompositeReconciler.

func WithName

func WithName(name string) CompositeReconcilerOption

WithName sets the name of the CompositeReconciler.

func WithPrototype

func WithPrototype(obj client.Object) CompositeReconcilerOption

WithPrototype sets a prototype of the object that's reconciled.

func WithScheme

func WithScheme(scheme *runtime.Scheme) CompositeReconcilerOption

WithScheme sets the runtime Scheme of the CompositeReconciler.

type Controller

type Controller interface {
	// Apply default values to the primary object spec. Use this in case a
	// defaulting webhook has not been deployed.
	Default(context.Context, client.Object)

	// Validate validates the primary object spec before it's created. It
	// ensures that all required fields are present and valid. Use this in case
	// a validating webhook has not been deployed.
	Validate(context.Context, client.Object) error

	// Initialize sets the provided initialization condition on the object
	// status. The object status need not be updated using a k8s client, only
	// the status value should be set. The controller handles updating the
	// object status in the API. Any additional status, other than the initial
	// conditions can be set here.
	Initialize(context.Context, client.Object, metav1.Condition) error

	// UpdateStatus queries the status of the child objects and based on them,
	// sets the status of the primary object instance. It need not save the
	// updated object in the API. API update is done by the controller after
	// collecting and comparing the new status with the old status. This is the
	// only place for updating the object. All other updates to the object are
	// discarded.
	UpdateStatus(context.Context, client.Object) error

	// Operate runs the core operation of the controller that ensures that
	// the child objects or the other objects and configurations in the
	// environment are in the desired state. It should be able to update any
	// existing resources or create one, if there's a configuration drift,
	// based on the type of objects.
	// The returned result is the returned reconcile result.
	Operate(context.Context, client.Object) (result ctrl.Result, err error)

	// Cleanup runs the custom cleanup operation to delete or undo the changes
	// made by the controller. This can be empty for controllers that use owner
	// reference based garbage collection for cleanup. For controllers with
	// custom cleanup requirement, the cleanup logic can be defined here.
	Cleanup(context.Context, client.Object) (result ctrl.Result, err error)
}

Controller is the controller interface that must be implemented by a composite controller. It provides methods required for reconciling a composite controller.