Component Operator

Cluster Setup

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

Prerequisites

Install the following tools before you begin:

Step 1 – Create a kind cluster

kind create cluster

Step 2 – Install the Flux source controller

Component-operator relies on the Flux source controller to fetch and serve artifact content. Install only the source controller component:

flux install --components source-controller

Step 3 – Install component-operator

helm upgrade --install component-operator \
 oci://ghcr.io/sap/component-operator/charts/component-operator \
 --namespace flux-system

Wait for the operator to become ready:

Command-Line Flags

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

The component-operator controller manager is configured via command-line flags at startup. All flags are optional unless noted otherwise.

Flag	Type	Default	Description
`-metrics-bind-address`	string	`:8080`	Address on which the Prometheus metrics endpoint is served.
`-health-probe-bind-address`	string	`:8081`	Address on which the liveness and readiness probe HTTP endpoints are served.
`-kubeconfig`	string	—	Path to a kubeconfig file. Only required when running out-of-cluster (e.g. for local development). In-cluster deployments use the pod’s service account automatically.
`-leader-elect`	bool	`false`	Enable leader election. When running multiple replicas of the controller manager, enabling this ensures that only one instance is active at any time. Recommended for production deployments.
`-default-service-account`	string	—	Name of the service account to impersonate by default for all components that do not explicitly set `spec.serviceAccountName`. The account is resolved relative to each component’s namespace. See Impersonation and Remote Clusters.
`-events-address`	string	—	HTTP address of a Flux notification-controller events receiver. When set, component-operator streams reconciliation events (successful applies, errors, state transitions) to this endpoint. See Notifications.
`-max-concurrent-reconciles`	int	`5`	Maximum number of component reconciliations that may run in parallel. See Performance and Sizing.

High Availability and Leader Election

For production deployments, run two or more replicas of the controller manager with -leader-elect enabled. Leader election ensures that only one instance actively reconciles at any time; the others remain on standby and take over automatically if the leader fails or is restarted.

Component

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

Overview

The Component custom resource is the primary API for managing Kubernetes components with component-operator. It defines a set of Kubernetes resources (deployments, services, RBAC, etc.) that are managed as a cohesive unit.

API Version

core.cs.sap.com/v1alpha1

Kind

Component

Spec

The ComponentSpec defines the desired state of a Component.

Source Reference

Field	Type	Required	Description
`sourceRef`	SourceReference	Yes	Reference to the source containing the manifest templates
`revision`	string	No	Pin component to a specific source revision
`digest`	string	No	Pin component to a specific source digest
`path`	string	No	Subfolder within the source (default: root)

Placement and Targeting

Field	Type	Required	Description
`namespace`	string	No	Target namespace for deployment (default: component’s namespace)
`name`	string	No	Target name for deployment (default: component’s name)
`serviceAccountName`	string	No	Service account to impersonate during reconciliation
`kubeConfig`	KubeConfigSpec	No	KubeConfig for deploying to remote cluster

Templating and Values

Field	Type	Required	Description
`values`	JSON	No	Inline values for templating
`valuesFrom`	[]SecretKeyReference	No	Secret references containing values
`decryption`	Decryption	No	Decryption settings for encrypted manifests
`postBuild`	PostBuild	No	Post-build variable substitution and patches

Reconciliation Control

Field	Type	Required	Description
`suspend`	boolean	No	Suspend reconciliation (default: false)
`requeueInterval`	duration	No	Period for re-reconciliation after success (default: 10m)
`retryInterval`	duration	No	Period for re-reconciliation after retriable error
`timeout`	duration	No	How long dependent objects have to become ready
`sticky`	boolean	No	Stick to source revision until ready or timeout
`reapplyInterval`	duration	No	Force reapply interval (default: 60m)

Policies

Field	Type	Required	Description
`adoptionPolicy`	string	No	How to handle existing objects (`IfUnowned`, `Never`, `Always`; default: `IfUnowned`)
`updatePolicy`	string	No	How to update objects (`Replace`, `Recreate`, `SsaMerge`, `SsaOverride`; default: `SsaOverride`)
`deletePolicy`	string	No	What happens on deletion (`Delete`, `Orphan`; default: `Delete`)
`missingNamespacesPolicy`	string	No	Auto-create missing namespaces (`Create`, `DoNotCreate`; default: `Create`)

Advanced Configuration

Field	Type	Required	Description
`dependencies`	[]Dependency	No	Dependencies to other components
`additionalManagedTypes`	[]TypeInfo	No	Additional CRD types managed by this component

SourceReference

Defines the source of manifest templates. Exactly one source type must be provided.

CRD Deletion Safeguarding

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

This tutorial installs cert-manager using component-operator. Along the way you will see how the HelmGenerator translates Helm hook annotations into component-operator lifecycle annotations, and observe how component-operator protects against premature deletion when foreign instances of managed CRDs still exist in the cluster.

Prerequisites

You need a Kubernetes cluster with Flux source-controller and component-operator installed. If you don’t have one yet, the Cluster Setup guide walks you through creating a local kind cluster with everything in place.

Prerequisites

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

Component-operator requires the Flux source controller to be installed in the cluster. It relies on Flux’s GitRepository, OCIRepository, Bucket, and HelmChart source types to fetch manifest artifacts. You can install just the source controller without the full Flux stack:

flux install --components source-controller

Alternatively, install the complete Flux toolkit if you plan to use other Flux features alongside component-operator:

flux install

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.

Apply, Delete and Purge Orders

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

This tutorial shows how component-operator’s ordering annotations let you sequence the creation, deletion, and one-shot execution of dependent objects within a single component. You will use a Blueprint as the manifest source so no external Git repository or Helm repository is needed.

Prerequisites

Blueprint

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

Overview

The Blueprint custom resource provides an in-cluster mechanism for storing manifest templates. Blueprints serve as reusable component templates that can be referenced by Component resources, eliminating the need for external source repositories.

API Version

core.cs.sap.com/v1alpha1

Kind

Blueprint

Spec

The BlueprintSpec defines the desired state of a Blueprint.

Field	Type	Required	Description
`files`	map[string]string	No	Map of file paths to file contents

Files Field

The files field contains a map where:

Container Images

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

OCI images for component-operator are published to the GitHub Container Registry alongside each release. You can browse all available images and versions on the GitHub Packages page.

The image reference is:

ghcr.io/sap/component-operator:<version>

Custom Resource Definitions can be downloaded separately as:

ghcr.io/sap/component-operator/crds:<version>

Replace <version> with the desired release tag (e.g. v0.12.0). Using latest is not recommended for production deployments.

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:

Performance and Sizing

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

Concurrency

The -max-concurrent-reconciles flag controls how many Component objects can be reconciled simultaneously. Each reconciliation worker handles one component at a time: fetching the source artifact, rendering the manifests, applying or deleting dependent objects, and updating the component’s status.

The default of 5 concurrent workers is suitable for small to medium clusters with up to a few hundred components. For larger deployments, consider increasing this value.

Factors that influence the right setting:

Scenario 1: Helm

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

Deploy podinfo using its OCI-hosted Helm chart. The equivalent plain Helm command would be:

helm upgrade -i podinfo oci://ghcr.io/stefanprodan/charts/podinfo

With component-operator, a Flux HelmRepository and HelmChart object serve the chart artifact, and a Component drives the deployment lifecycle.

1. Create the Flux source objects

# podinfo-helm-source.yaml
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
 name: podinfo
 namespace: default
spec:
 type: oci
 url: oci://ghcr.io/stefanprodan/charts
 interval: 5m
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmChart
metadata:
 name: podinfo
 namespace: default
spec:
 chart: podinfo
 sourceRef:
 kind: HelmRepository
 name: podinfo
 interval: 5m

kubectl apply -f podinfo-helm-source.yaml

2. Create the Component

# podinfo-helm.yaml
---
apiVersion: core.cs.sap.com/v1alpha1
kind: Component
metadata:
 name: podinfo
 namespace: default
spec:
 sourceRef:
 fluxHelmChart:
 name: podinfo
 path: podinfo

kubectl apply -f podinfo-helm.yaml

3. Verify

kubectl get component podinfo
kubectl get pods -l app.kubernetes.io/name=podinfo

4. Cleanup

kubectl delete component podinfo
kubectl delete helmchart podinfo
kubectl delete helmrepository podinfo

Continue with Scenario 2: Kustomize to deploy the same application from a Git repository.

Deploying to a Remote Cluster

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

This tutorial deploys a resource to a second, remote Kubernetes cluster. It demonstrates spec.kubeConfig for targeting a remote cluster, and the mustLocalLookup template function, which reads objects from the local cluster even when the component is deploying to a remote one.

Prerequisites

You need two clusters.

Local cluster (kind) — hosts Flux source-controller and component-operator. If you don’t have one yet, the Cluster Setup guide walks you through creating it.

Remote cluster (kind-target) — the deployment target. No Flux or component-operator installation is needed here. Create it now:

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.

Helm Chart

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

The recommended way to install component-operator is via the official Helm chart. The chart source is hosted at github.com/SAP/component-operator/tree/main/chart and published to the GitHub OCI registry.

Installation

helm upgrade --install component-operator \
 oci://ghcr.io/sap/component-operator/charts/component-operator \
 --namespace flux-system

To pin to a specific version:

helm upgrade --install component-operator \
 oci://ghcr.io/sap/component-operator/charts/component-operator \
 --version <version> \
 --namespace flux-system

Refer to the chart documentation for the full list of available Helm values.

Note: if you want to deploy component-operator into a different namespace (instead of flux-system), then you have to allow the component-operator pod to access the source-controller running flux-system.

Scenario 2: Kustomize

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

Deploy podinfo using the Kustomization at github.com/stefanprodan/podinfo//kustomize. A Flux GitRepository serves the repository content, and the Component selects the kustomize subdirectory as its source path.

1. Create the Flux GitRepository

# podinfo-git-source.yaml
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
 name: podinfo
spec:
 interval: 5m
 url: https://github.com/stefanprodan/podinfo
 ref:
 branch: master

kubectl apply -f podinfo-git-source.yaml

2. Create the Component

# podinfo-kustomize.yaml
---
apiVersion: core.cs.sap.com/v1alpha1
kind: Component
metadata:
 name: podinfo
 namespace: default
spec:
 sourceRef:
 fluxGitRepository:
 name: podinfo
 path: kustomize

kubectl apply -f podinfo-kustomize.yaml

3. Verify

kubectl get component podinfo
kubectl get pods -l app=podinfo

4. Cleanup

kubectl delete component podinfo
kubectl delete gitrepository podinfo

Continue to Next Steps to explore what component-operator has to offer beyond the basics.

Nesting Components

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

This tutorial demonstrates nested components referencing the same source: a pattern where one Component (the outer) creates and manages another Component (the inner) as one of its dependent objects. Combining this with source pinning ensures both components consistently reconcile against the same state of the referenced source.

Prerequisites

You need a Kubernetes cluster with Flux source-controller and component-operator installed. If you don’t have one yet, follow the Cluster Setup guide.

What you will build

A single Blueprint (nesting) contains two subdirectories:

Next Steps

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

You’ve deployed podinfo with component-operator — here are the recommended next steps.

Learn more about usage

The Usage section covers all the concepts you’ll need for real-world deployments:

Sources — GitRepository, OCIRepository, Bucket, HelmChart, and Blueprint source types
Manifests — Helm and Kustomize rendering, values, template functions
Drift Detection — how component-operator detects and corrects configuration drift
Dependent Objects — apply/delete ordering, update and delete policies

Explore the API reference

Component — full field reference for the Component custom resource
Blueprint — in-cluster manifest template source

Configure the operator

Command-line Flags — runtime flags including concurrency and service account defaults
Performance — sizing guidance for larger clusters

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.