reconciler

Documentation

Overview

Package reconciler contains logic to manage (apply/delete) depenent objects in a target cluster.

Index

• Constants
• type AdoptionPolicy
• type DeletePolicy
• type InventoryItem
  • func (in *InventoryItem) DeepCopy() *InventoryItem
  • func (in *InventoryItem) DeepCopyInto(out *InventoryItem)
  • func (i InventoryItem) GetName() string
  • func (i InventoryItem) GetNamespace() string
  • func (i *InventoryItem) GetObjectKind() schema.ObjectKind
  • func (i InventoryItem) GroupVersionKind() schema.GroupVersionKind
  • func (i InventoryItem) Matches(key types.ObjectKey) bool
  • func (i *InventoryItem) SetGroupVersionKind(gvk schema.GroupVersionKind)
  • func (i InventoryItem) String() string
• type NameInfo
• type Phase
• type ReconcilePolicy
• type Reconciler
  • func NewReconciler(name string, clnt cluster.Client, options ReconcilerOptions) *Reconciler
  • func (r *Reconciler) Apply(ctx context.Context, inventory *[]*InventoryItem, objects []client.Object, ...) (bool, error)
  • func (r *Reconciler) Delete(ctx context.Context, inventory *[]*InventoryItem) (bool, error)
  • func (r *Reconciler) IsDeletionAllowed(ctx context.Context, inventory *[]*InventoryItem) (bool, string, error)
• type ReconcilerMetrics
• type ReconcilerOptions
• type TypeInfo
• type UpdatePolicy

Constants

const (
	PhaseScheduledForApplication = "ScheduledForApplication"
	PhaseScheduledForDeletion    = "ScheduledForDeletion"
	PhaseScheduledForCompletion  = "ScheduledForCompletion"
	PhaseCreating                = "Creating"
	PhaseUpdating                = "Updating"
	PhaseDeleting                = "Deleting"
	PhaseCompleting              = "Completing"
	PhaseReady                   = "Ready"
	PhaseCompleted               = "Completed"
)

Types

type AdoptionPolicy

type AdoptionPolicy string

AdoptionPolicy defines how the reconciler reacts if a dependent object exists but has no or a different owner.

const (
	// Fail if the dependent object exists but has no or a different owner.
	AdoptionPolicyNever AdoptionPolicy = "Never"
	// Adopt existing dependent objects if they have no owner set.
	AdoptionPolicyIfUnowned AdoptionPolicy = "IfUnowned"
	// Adopt existing dependent objects, even if they have a conflicting owner.
	AdoptionPolicyAlways AdoptionPolicy = "Always"
)

type DeletePolicy

type DeletePolicy string

DeletePolicy defines how the reconciler will delete dependent objects.

const (
	// Delete dependent objects.
	DeletePolicyDelete DeletePolicy = "Delete"
	// Orphan dependent objects.
	DeletePolicyOrphan DeletePolicy = "Orphan"
)

type InventoryItem

type InventoryItem struct {
	// Type of the dependent object.
	TypeInfo `json:",inline"`
	// Namespace and name of the dependent object.
	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.
	ManagedTypes []TypeInfo `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"`
}

InventoryItem represents a dependent object managed by this operator.

func (*InventoryItem) DeepCopy

func (in *InventoryItem) DeepCopy() *InventoryItem

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new InventoryItem.

func (*InventoryItem) DeepCopyInto

func (in *InventoryItem) DeepCopyInto(out *InventoryItem)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (InventoryItem) GetName

func (i InventoryItem) GetName() string

Get inventory item's name.

func (InventoryItem) GetNamespace

func (i InventoryItem) GetNamespace() string

Get inventory item's namespace.

func (*InventoryItem) GetObjectKind

func (i *InventoryItem) GetObjectKind() schema.ObjectKind

Get inventory item's ObjectKind accessor.

func (InventoryItem) GroupVersionKind

func (i InventoryItem) GroupVersionKind() schema.GroupVersionKind

Get inventory item's GroupVersionKind.

func (InventoryItem) Matches

func (i InventoryItem) Matches(key types.ObjectKey) bool

Check whether inventory item matches given ObjectKey, in the sense that Group, Kind, Namespace and Name are the same. Note that this does not compare the group's Version.

func (*InventoryItem) SetGroupVersionKind

func (i *InventoryItem) SetGroupVersionKind(gvk schema.GroupVersionKind)

Set inventory item's GroupVersionKind.

func (InventoryItem) String

func (i InventoryItem) String() string

Return a string representation of the inventory item; makes InventoryItem implement the Stringer interface.

type NameInfo

type NameInfo struct {
	// Namespace of the referenced object; empty for non-namespaced objects
	Namespace string `json:"namespace,omitempty"`
	// Name of the referenced object.
	Name string `json:"name"`
}

NameInfo represents an object's namespace and name.

type Phase

type Phase string

type ReconcilePolicy

type ReconcilePolicy string

ReconcilePolicy defines when the reconciler will reconcile the dependent object.

const (
	// Reconcile the dependent object if its manifest, as produced by the generator, changes.
	ReconcilePolicyOnObjectChange ReconcilePolicy = "OnObjectChange"
	// Reconcile the dependent object if its manifest, as produced by the generator, changes, or if the owning
	// component changes (identified by a change of its metadata.generation).
	ReconcilePolicyOnObjectOrComponentChange ReconcilePolicy = "OnObjectOrComponentChange"
	// Reconcile the dependent object only once; afterwards it will never be touched again by the reconciler.
	ReconcilePolicyOnce ReconcilePolicy = "Once"
)

type Reconciler

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

Reconciler manages specified objects in the given target cluster.

func NewReconciler

func NewReconciler(name string, clnt cluster.Client, options ReconcilerOptions) *Reconciler

Create new reconciler. The passed name should be fully qualified; 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 (*Reconciler) Apply

func (r *Reconciler) Apply(ctx context.Context, inventory *[]*InventoryItem, objects []client.Object, namespace string, ownerId string, componentRevision int64) (bool, error)

Apply given object manifests to the target cluster and maintain inventory. That means:

• non-existent objects will be created
• existing objects will be updated if there is a drift (see below)
• redundant objects will be removed.

Existing objects will only be updated or deleted if the owner id check is successful; that means:

• the object's owner id matches the specified ownerId or
• the object's owner id does not match the specified ownerId, and the effective adoption policy is AdoptionPolicyAlways or
• the object has no or empty owner id set, and the effective adoption policy is AdoptionPolicyAlways or AdoptionPolicyIfUnowned.

Objects which are instances of namespaced types will be placed into the namespace passed to Apply(), if they have no namespace defined in their manifest. An update of an existing object will be performed if it is considered to be out of sync; that means:

• the object's manifest has changed, and the effective reconcile policy is ReconcilePolicyOnObjectChange or ReconcilePolicyOnObjectOrComponentChange or
• the specified component revision has changed and the effective reconcile policy is ReconcilePolicyOnObjectOrComponentChange.

The update itself will be done as follows:

• if the effective update policy is UpdatePolicyReplace, a http PUT request will be sent to the Kubernetes API
• if the effective update policy is UpdatePolicySsaMerge or UpdatePolicySsaOverride, a server-side-apply http PATCH request will be sent; while UpdatePolicySsaMerge just implements the Kubernetes standard behavior (leaving foreign non-conflicting fields untouched), UpdatePolicySsaOverride will re-claim (and therefore potentially drop) fields owned by certain field managers, such as kubectl and helm
• if the effective update policy is UpdatePolicyRecreate, the object will be deleted and recreated.

Redundant objects will be removed; that means, in the regular case, a http DELETE request will be sent to the Kubernetes API; if the object specifies its delete policy as DeletePolicyOrphan, no physcial deletion will be performed, and the object will be left around in the cluster; however it will be no longer be part of the inventory.

Objects will be applied and deleted in waves, according to their apply/delete order. Objects which specify a purge order will be deleted from the cluster at the end of the wave specified as purge order; other than redundant objects, a purged object will remain as Completed in the inventory; and it might be re-applied/re-purged in case it runs out of sync. Within a wave, objects are processed following a certain internal order; in particular, instances of types which are part of the wave are processed only if all other objects in that wave have a ready state.

This method will change the passed inventory (add or remove elements, change elements). If Apply() returns true, then all objects are successfully reconciled; otherwise, if it returns false, the caller should recall it timely, until it returns true. In any case, the passed inventory should match the state of the inventory after the previous invocation of Apply(); usually, the caller saves the inventory after calling Apply(), and loads it before calling Apply(). The namespace and ownerId arguments should not be changed across subsequent invocations of Apply(); the componentRevision should be incremented only.

func (*Reconciler) Delete

func (r *Reconciler) Delete(ctx context.Context, inventory *[]*InventoryItem) (bool, error)

Delete objects stored in the inventory from the target cluster and maintain inventory. Objects will be deleted in waves, according to their delete order (as stored in the inventory); that means, the deletion of objects having a certain delete order will only start if all objects with lower delete order are gone. Within a wave, objects are deleted following a certain internal ordering; in particular, if there are instances of types which are part of the wave, then these instances will be deleted first; only if all such instances are gone, the remaining objects of the wave will be deleted.

This method will change the passed inventory (remove elements, change elements). If Delete() returns true, then all objects are gone; otherwise, if it returns false, the caller should recall it timely, until it returns true. In any case, the passed inventory should match the state of the inventory after the previous invocation of Delete(); usually, the caller saves the inventory after calling Delete(), and loads it before calling Delete().

func (*Reconciler) IsDeletionAllowed

func (r *Reconciler) IsDeletionAllowed(ctx context.Context, inventory *[]*InventoryItem) (bool, string, error)

Check if the object set defined by inventory is ready for deletion; that means: check if the inventory contains types (as custom resource definition or from an api service), while there exist instances of these types in the cluster, which are not contained in the inventory.

type ReconcilerMetrics

type ReconcilerMetrics struct {
	ReadCounter   prometheus.Counter
	CreateCounter prometheus.Counter
	UpdateCounter prometheus.Counter
	DeleteCounter prometheus.Counter
}

ReconcilerMetrics defines metrics that the reconciler can populate. Metrics specified as nil will be ignored.

type ReconcilerOptions

type ReconcilerOptions struct {
	// Whether namespaces are auto-created if missing.
	// If unspecified, true is assumed.
	CreateMissingNamespaces *bool
	// How to react if a dependent object exists but has no or a different owner.
	// If unspecified, AdoptionPolicyIfUnowned is assumed.
	// Can be overridden by annotation on object level.
	AdoptionPolicy *AdoptionPolicy
	// How to perform updates to dependent objects.
	// If unspecified, UpdatePolicyReplace is assumed.
	// Can be overridden by annotation on object level.
	UpdatePolicy *UpdatePolicy
	// How to analyze the state of the dependent objects.
	// If unspecified, an optimized kstatus based implementation is used.
	StatusAnalyzer status.StatusAnalyzer
	// Prometheus metrics to be populated by the reconciler.
	Metrics ReconcilerMetrics
}

ReconcilerOptions are creation options for a Reconciler.

type TypeInfo

type TypeInfo struct {
	// API group.
	Group string `json:"group"`
	// API group version.
	Version string `json:"version"`
	// API kind.
	Kind string `json:"kind"`
}

TypeInfo represents a Kubernetes type.

type UpdatePolicy

type UpdatePolicy string

UpdatePolicy defines how the reconciler will update dependent objects.

const (
	// Recreate (that is: delete and create) existing dependent objects.
	UpdatePolicyRecreate UpdatePolicy = "Recreate"
	// Replace existing dependent objects.
	UpdatePolicyReplace UpdatePolicy = "Replace"
	// Use server side apply to update existing dependents.
	UpdatePolicySsaMerge UpdatePolicy = "SsaMerge"
	// Use server side apply to update existing dependents and, in addition, reclaim fields owned by certain
	// field owners, such as kubectl or helm.
	UpdatePolicySsaOverride UpdatePolicy = "SsaOverride"
)