Usage on Component Operator

Sources

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

The mandatory field spec.sourceRef defines where component-operator retrieves the manifests used to generate the component’s dependent objects. Exactly one source type must be specified.

Source Types

Flux GitRepository

References a Flux GitRepository object. The source controller fetches and serves the Git repository content as a tarball artifact.

spec:
 sourceRef:
 fluxGitRepository:
 name: my-gitrepo
 # namespace: source-ns # optional; defaults to component's namespace

Flux OCIRepository

References a Flux OCIRepository object, backed by an OCI-compatible container registry.

Manifests

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

The files making up a component’s manifests are provided by the configured source. The field spec.path defines the subfolder within the source artifact to use as the entry point (default: the root of the artifact).

Component-operator automatically determines how to render the manifests based on the contents of that directory:

If a Chart.yaml file exists in spec.path, the content is rendered as a Helm chart using the HelmGenerator.
Otherwise, the KustomizeGenerator logic is applied, which also supports plain YAML manifests without a kustomization.yaml.

Values and ValuesFrom

Parameters for the manifests can be provided inline via spec.values or loaded from Kubernetes Secrets via spec.valuesFrom:

Drift Detection

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

Object Digest

Whenever a dependent object is to be applied to the cluster, a digest is calculated for the object. This digest value is persisted as annotation component-operator.cs.sap.com/digest. The object is considered as synced if the new digest value equals the currently persisted one, and as out of sync otherwise.

If the object is out of sync, component-operator reapplies it to the Kubernetes API, including the new digest value. If the object is in sync, it will normally not be reapplied, with one exception: after the effective reapply interval, the object is force-reapplied. This ensures that manual out-of-band changes are reverted, and other glitches get fixed.

Status Detection

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

Component-operator needs to determine whether each dependent object has reached a ready state before proceeding to the next apply wave or completing the component reconciliation. The readiness check is based on the kstatus library, with additional tuning capabilities.

How kstatus Works

For most resources, vanilla kstatus uses the following algorithm to determine if a Kubernetes object is ready (a special logic applies for some builtin types):

Step 1 — observedGeneration check:

Does the object have status.observedGeneration?
 → Yes: Does status.observedGeneration equal metadata.generation?
 → Yes: proceed to readyCondition check
 → No: object is NOT ready (generation mismatch)
 → No: proceed to readyCondition check

Step 2 — readyCondition check:

Target Namespace and Name

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

The optional fields spec.namespace and spec.name customize the deployment namespace and name of the component, as defined by component-operator-runtime.

Defaulting

If spec.namespace is not set, the target namespace defaults to metadata.namespace — that is, the same namespace in which the Component object itself resides.

If spec.name is not set, the target name defaults to metadata.name — the name of the Component object.

Effect on Dependent Objects

The target namespace is passed to the manifest generator. Any namespaced dependent objects whose manifest does not specify an explicit namespace will be placed in this target namespace. This allows a single set of manifests to be deployed into different namespaces simply by varying spec.namespace across Component instances.

Dependents Lifecycle

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

Reconciliation in Waves

Component-operator supports ordered reconciliation of dependent objects using the concept of waves. Objects are grouped into waves and processed wave by wave, in ascending order of wave number. Wave numbers can be negative, zero (the default), or positive integers in the range -32768 to 32767.

Apply Waves

During apply (creation or update), objects are reconciled wave by wave. The next wave only begins once all objects of the previous wave are fully ready — not just created or updated, but actually ready according to their status. Simply initiating creation or an update is not enough.

Dependents Annotations

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

The following annotations can be added to any rendered manifest to control how component-operator handles that specific dependent object. Where a component-level default exists, it is noted in the Component-level default column.

Annotation	Values	Component-level default	Description
`component-operator.cs.sap.com/adoption-policy`	`if-unowned` (default), `never`, `always`	`spec.adoptionPolicy` (`IfUnowned`)	How to handle an object that already exists in the cluster. See Ownership and Adoption.
`component-operator.cs.sap.com/reconcile-policy`	`on-object-change` (default), `on-object-or-component-change`, `once`	—	When the object is reconciled. See Reconcile Modes.
`component-operator.cs.sap.com/update-policy`	`ssa-override` (default), `ssa-merge`, `replace`, `recreate`	`spec.updatePolicy` (`SsaOverride`)	How the object is updated in the Kubernetes API. See Dependents Lifecycle.
`component-operator.cs.sap.com/delete-policy`	`delete` (default), `orphan`, `orphan-on-apply`, `orphan-on-delete`	`spec.deletePolicy` (`Delete`)	What happens to the object when it becomes redundant or the component is deleted. See Dependents Lifecycle.
`component-operator.cs.sap.com/apply-order`	integer (default: `0`)	—	The wave in which the object is applied. Lower numbers are applied first. See Dependents Lifecycle.
`component-operator.cs.sap.com/delete-order`	integer (default: `0`)	—	The wave in which the object is deleted. Lower numbers are deleted first. Independent of `apply-order`. See Dependents Lifecycle.
`component-operator.cs.sap.com/purge-order`	integer	—	The apply wave at the end of which the object is deleted (purged) from the cluster, while its inventory record is set to `Completed`. See Dependents Lifecycle.
`component-operator.cs.sap.com/reapply-interval`	duration (e.g. `30m`)	`spec.reapplyInterval` (`60m`)	How often the object is force-reapplied even when in sync. See Drift Detection.
`component-operator.cs.sap.com/status-hint`	comma-separated hints (see below)	—	Tuning hints for the kstatus-based readiness check. See Status Detection.

Status Hint Values

The component-operator.cs.sap.com/status-hint annotation accepts a comma-separated list of the following values:

Component Deletion

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

When a Component object is deleted, component-operator reconciles the deletion by removing all dependent objects it manages. The process is more nuanced than a simple bulk delete, particularly around extension types.

Basic Deletion Flow

Upon receiving a delete request, the component enters a Deleting state. Dependent objects are then deleted according to their delete order, wave by wave. Each wave only starts once all objects of the previous wave have fully disappeared from the cluster.

Intervals and Timing

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

Reconciliation timing is about

how often a component is reconciled in success state
how often a component is reconciled in various error states
how often a component or single dependent object is force-reapplied to the Kubernetes cluster
temporarily disabling (suspending) reconciliation of a component.

Reconciliation Intervals

Requeue Interval

spec.requeueInterval defines how often a component is re-reconciled after a successful reconciliation.

Requeues are not particularly expensive, but depending on the number of components in a cluster it might be necessary to increase the requeue interval.

Ownership and Adoption

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

Component-operator tracks ownership of dependent objects using a dedicated label: component-operator.cs.sap.com/owner-id. This label is set on every object managed by a component and contains a globally unique identifier for the owning component (incorporating a unique ID of the component’s Kubernetes cluster). It serves as the basis for all ownership and adoption decisions.

Adoption Policy

It can happen that a dependent object already exists in the cluster when a component is applied — either because it was created manually, by another tool, or by a different component. The spec.adoptionPolicy field on the component (and the per-object annotation component-operator.cs.sap.com/adoption-policy) controls how component-operator handles this situation.

Reconcile Modes

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

By default, component-operator reconciles a dependent object whenever its generated manifest changes.

More details about drift detection can be found here.

Reconcile Policy Values

This behavior can be customized per object using the annotation component-operator.cs.sap.com/reconcile-policy.

Value	Description
`on-object-change` (default)	The object is reconciled whenever its generated manifest changes.
`on-object-or-component-change`	The object is reconciled whenever its manifest changes, or whenever the component itself changes (as identified by a change in the component’s generation).
`once`	The object is reconciled exactly once (on creation). It is never updated again by component-operator, regardless of changes to the manifest or the component.

In the on-object-or-component-change case the object digest additionally incorporates a deep digest of the component. In the once case, the object digest is set to __once__. Note that, when changing the effective reconcile policy to once, then one last reconcile happens, caused by the change of the policy.

Impersonation and Remote Clusters

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

By default, component-operator uses its own controller kubeconfig to interact with the Kubernetes API when reconciling a Component. Both impersonation and remote cluster deployment allow you to override this default.

Service Account Impersonation

If spec.serviceAccountName is set, the controller impersonates that service account (relative to the component’s namespace) when applying and deleting dependent objects. This allows fine-grained access control: the service account determines what the component is permitted to create, modify, and delete.

Timeout and Stickiness

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

Timeout

The field spec.timeout defines how long dependent objects are expected to take to reach a ready state after being applied. If not all dependents are ready within this period, the component’s state transitions from Processing to Error.

spec:
 timeout: 10m

If spec.timeout is not set, it defaults to the effective requeue interval.

Important: reaching the timeout does not stop reconciliation. Component-operator continues to attempt reconciliation at the normal requeue interval. The timeout only affects the reported state. Whenever the component itself or any of its referenced objects (e.g., referenced secrets) change, the timeout countdown resets.

Dependencies

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

Component-operator supports declaring dependencies between Component objects via spec.dependencies. This allows you to express that a component must not be applied or deleted until other components have reached a certain state.

Declaring Dependencies

spec:
 dependencies:
 - name: database # same namespace as this component
 - namespace: infra
 name: cert-manager # cross-namespace reference

If namespace is omitted, the dependency is assumed to reside in the same namespace as the declaring component.

Notifications

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

Component-operator can emit events to the Flux notification controller, enabling integration with Flux’s alerting and notification infrastructure.

Enabling Event Streaming

Start the component-operator controller with the --events-address flag pointing to the address of the Flux notification controller:

--events-address=http://notification-controller.flux-system.svc.cluster.local/

When set, component-operator will stream reconciliation events (such as successful applies, errors, and state transitions) to the notification controller, which can then forward them to configured alert providers (Slack, PagerDuty, etc.).

Patching the Flux Alert CRD

To fully leverage Flux notifications — including the ability to create Alert objects that reference Component as an event source — the alerts.notification.toolkit.fluxcd.io CRD shipped with Flux must be patched to add Component as an allowed event source kind.