Object Reconciler on Component Operator Runtime

Overview

Mon, 01 Jan 0001 00:00:00 +0000

This page introduces the main type of package pkg/reconciler and the methods used to drive it.

The `Reconciler` type

Reconciler manages a set of specified objects in a given target cluster. It is created with the NewReconciler constructor:

package reconciler

// Create new reconciler.
// The passed name should be fully qualified; by default it will be used as
// field owner and finalizer.
// The passed client's scheme must recognize at least the core group (v1) and
// apiextensions.k8s.io/v1 and apiregistration.k8s.io/v1.
func NewReconciler(name string, clnt cluster.Client, options ReconcilerOptions) *Reconciler

name should be a fully qualified, unique identifier for the operator, typically a DNS-style name such as mycomponent-operator.mydomain.io. It is used, by default, as the field owner and finalizer, and — importantly — as the prefix of all annotations and labels the reconciler reads and writes. Throughout this documentation, annotations are written as mycomponent-operator.mydomain.io/apply-order and similar; the prefix is exactly this name, so it varies from operator to operator.

Drift Detection

Mon, 01 Jan 0001 00:00:00 +0000

The Object Reconciler continuously keeps managed objects in sync with their desired manifests. It detects when an object has drifted from its declared state and reapplies it. This page explains the mechanism.

Object digest

Whenever a dependent object is about to be applied, the reconciler calculates a digest of the object and persists it as an annotation on the object:

metadata:
 annotations:
 mycomponent-operator.mydomain.io/digest: "..."

(The annotation prefix is the reconciler name, so it varies per operator.)

Apply and Delete Waves

Mon, 01 Jan 0001 00:00:00 +0000

Dependent objects are reconciled in waves. Waves let you express dependencies between objects so that prerequisites are fully in place before the objects that rely on them are applied — and, on the way out, so that objects are removed in a safe order.

Apply order and delete order are independent of each other and are configured with separate annotations. Order values are integers in the range -32768 to 32767; objects without an explicit order are treated as order 0.

Completion

Mon, 01 Jan 0001 00:00:00 +0000

Sometimes an object needs to exist only during the reconciliation, not permanently — think of a one-off migration job, a seeding task, or a certificate generator. The Object Reconciler supports this through the purge order, which is comparable to a Helm hook.

Purge order

An object that carries a purge-order annotation is applied normally, waited for until it is ready, and then deleted from the cluster at the end of the specified apply wave. Its inventory record is not removed; instead it is set to the phase Completed. This distinguishes purged objects from redundant objects (which are removed from the inventory entirely).

Policies

Mon, 01 Jan 0001 00:00:00 +0000

The behavior of the Object Reconciler is governed by five policies. Each has a reconciler-wide default (set through ReconcilerOptions), and most can be overridden per object using an annotation whose prefix is the reconciler name.

Adoption policy — and the ownership concept

Before explaining the policy, it helps to understand ownership. When the reconciler manages an object, it stamps it with an owner id (as a label and annotation). This is how the reconciler tells its own objects apart from foreign ones: on every apply and delete it verifies the owner id before touching an object. Ownership is what makes it safe for the reconciler to update and delete resources — it will not clobber objects it does not own, unless told to.

Managed Types

Mon, 01 Jan 0001 00:00:00 +0000

One of the defining features of component-operator-runtime is its careful handling of managed types — the API extension types that a component may bring along.

What is a managed type?

A managed type is a Kubernetes API extension type, namely:

a type defined by a CustomResourceDefinition contained in the object set, or
a type served by an APIService (aggregated API server) contained in the object set.

Instances of such a type are classified as:

Dependent Objects

Mon, 01 Jan 0001 00:00:00 +0000

Dependent objects are the resources managed by the reconciler — in the higher-level model, the objects returned by a generator’s Generate() method. Under normal circumstances the framework manages their lifecycle well: it creates and deletes them in a sensible order and avoids the obvious transient errors.

For finer control, a manifest may carry any of the annotations below. In all cases the annotation prefix is the reconciler name — the value passed to NewReconciler(). Throughout this page it is written as mycomponent-operator.mydomain.io, but it is a variable; your operator will use its own prefix.

Enhanced Status Detection

Mon, 01 Jan 0001 00:00:00 +0000

Before proceeding to the next apply wave — or declaring the whole set reconciled — the reconciler must decide whether each dependent object has reached a ready state. The check is performed by a status.StatusAnalyzer, which you can override via ReconcilerOptions.StatusAnalyzer; when left unset, an optimized kstatus-based analyzer is used. It is built on the kstatus library, but with important enhancements.

How vanilla kstatus works

For most resources (some built-in types have special logic), kstatus applies roughly the following algorithm.

The Inventory

Mon, 01 Jan 0001 00:00:00 +0000

The inventory is the reconciler’s memory. It is what makes the engine level-based: successive Apply() and Delete() calls consult and update it to know what has already been done. It is a slice of *InventoryItem, one entry per managed object, and is typically persisted in the status of a custom resource between reconciliations.

`InventoryItem`

package reconciler

// InventoryItem represents a dependent object managed by this operator.
type InventoryItem struct {
	// Type of the dependent object (Group, Version, Kind), inlined.
	TypeVersionInfo `json:",inline"`
	// Namespace and name of the dependent object, inlined.
	NameInfo `json:",inline"`
	// Adoption policy.
	AdoptionPolicy AdoptionPolicy `json:"adoptionPolicy"`
	// Reconcile policy.
	ReconcilePolicy ReconcilePolicy `json:"reconcilePolicy"`
	// Update policy.
	UpdatePolicy UpdatePolicy `json:"updatePolicy"`
	// Delete policy.
	DeletePolicy DeletePolicy `json:"deletePolicy"`
	// Apply order.
	ApplyOrder int `json:"applyOrder"`
	// Delete order.
	DeleteOrder int `json:"deleteOrder"`
	// Managed types (present for CRDs / APIServices).
	ManagedTypes []TypeVersionInfo `json:"managedTypes,omitempty"`
	// Digest of the descriptor of the dependent object.
	Digest string `json:"digest"`
	// Phase of the dependent object.
	Phase Phase `json:"phase,omitempty"`
	// Observed status of the dependent object.
	Status status.Status `json:"status,omitempty"`
	// Timestamp when this object was last applied.
	LastAppliedAt *metav1.Time `json:"lastAppliedAt,omitempty"`
}

The two embedded structs carry the object’s identity:

Client and Scheme

Mon, 01 Jan 0001 00:00:00 +0000

The Object Reconciler talks to the target cluster through a cluster.Client. This page describes what that client must provide, and what its scheme must recognize.

The `cluster.Client` interface

package cluster

// The Client interface extends the controller-runtime client by discovery and
// event recording capabilities.
type Client interface {
	client.Client
	// Return a discovery client.
	DiscoveryClient() discovery.DiscoveryInterface
	// Return an event recorder.
	EventRecorder() record.EventRecorder
	// Return a rest config for this client.
	Config() *rest.Config
	// Return a http client for this client.
	HttpClient() *http.Client
}

In other words, a cluster.Client is a controller-runtime client.Client augmented with a few extras the reconciler relies on:

Object Reconciler on Component Operator Runtime

Overview

The Reconciler type

Drift Detection

Object digest

Apply and Delete Waves

Completion

Purge order

Policies

Adoption policy — and the ownership concept

Managed Types

What is a managed type?

Dependent Objects

Enhanced Status Detection

How vanilla kstatus works

The Inventory

InventoryItem

Client and Scheme

The cluster.Client interface

The `Reconciler` type

`InventoryItem`

The `cluster.Client` interface