Architecture¶

ConfigBundleOperator follows the Kubernetes controller pattern: it continuously observes the desired and actual state of the cluster and reconciles differences between them.

The operator is intentionally simple. A ConfigBundle describes the desired configuration, while a managed ConfigMap represents the resulting state in the cluster.

Reconciliation & Self-Healing¶

The core of ConfigBundleOperator is its reconciliation loop.

The operator observes both the ConfigBundle and its managed ConfigMap, compares the desired configuration with the current state, and takes corrective action when they differ.

flowchart LR
    A["ConfigBundle<br/>Desired State"]
    B["Operator<br/>Reconciliation"]
    C["ConfigMap<br/>Actual State"]

    A -->|"Observe"| B
    C -->|"Observe"| B
    B -->|"Create / Replace"| C

    C -. "Drift" .-> B

The reconciliation process can be summarized as:

Observe → Compare → Act

When the desired and actual states are already consistent, the operator does nothing.

When they differ, the operator takes the necessary action to restore the expected state.

This makes the operator self-healing: changes made outside the operator do not necessarily persist if they cause the managed resource to diverge from its desired configuration.

Components¶

ConfigBundleOperator consists of a small number of logical components that work together through the Kubernetes API.

flowchart TB
    A["Kubernetes API Server"]

    B["ConfigBundle<br/>Desired State"]
    C["ConfigBundle Operator"]
    D["Reconciliation"]
    E["ConfigMap<br/>Actual State"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> A

ConfigBundle¶

ConfigBundle is the custom resource through which users declare the desired configuration.

It is the source of truth for what the managed ConfigMap should contain.

Operator¶

The ConfigBundleOperator observes resources in the cluster and coordinates the reconciliation process.

Its responsibility is not to simply create a ConfigMap once, but to continuously maintain the expected state.

Reconciliation¶

Reconciliation is the decision-making process between the desired state and the actual state.

The reconciliation logic determines whether the managed resource should be created, left unchanged, or corrected.

ConfigMap¶

The managed ConfigMap represents the actual configuration maintained by the operator.

It is derived from the desired configuration declared through the ConfigBundle.

Reconciliation Flow¶

A reconciliation cycle follows a small number of steps.

flowchart TD
    A["Start Reconciliation"]
    B["Read ConfigBundle"]
    C["Build Desired Configuration"]
    D["Read ConfigMap"]
    E{"ConfigMap exists?"}

    F["Create ConfigMap"]
    G{"Configuration matches?"}
    H["No Action"]
    I["Replace ConfigMap"]
    J["Reconciliation Complete"]

    A --> B
    B --> C
    C --> D
    D --> E

    E -->|No| F
    E -->|Yes| G

    G -->|Yes| H
    G -->|No| I

    F --> J
    H --> J
    I --> J

The operator first determines the desired configuration from the ConfigBundle.

It then reads the current ConfigMap and checks whether the resource exists and whether its configuration matches the desired state.

The possible outcomes are:

• Missing resource — create the ConfigMap.
• Matching resource — leave the resource unchanged.
• Different resource — replace the resource with the expected configuration.

Resource Ownership¶

The managed ConfigMap is associated with its ConfigBundle, allowing the operator to establish which resources it is responsible for.

flowchart LR
    A["ConfigBundle"]
    B["Owner Reference"]
    C["ConfigMap"]

    A -->|"owns"| B
    B --> C

This ownership relationship gives the operator a clear connection between the custom resource and the resource it manages.

It also allows Kubernetes to understand the relationship between the two resources and provides the foundation for lifecycle management.

The detailed ownership and deletion behavior is covered in Behaviour.

Summary¶

The architecture can be reduced to a simple control loop:

flowchart LR
    A["Desired State<br/>ConfigBundle"]
    B["Observe"]
    C["Compare"]
    D["Act"]
    E["Actual State<br/>ConfigMap"]

    A --> B
    E --> B
    B --> C
    C --> D
    D --> E
    E -. "Drift" .-> B

The operator does not treat resource creation as a one-time operation. Instead, it continuously works toward a consistent state between the ConfigBundle and its managed ConfigMap.

This reconciliation model is the foundation on which the more advanced operators in the K8s Operators project will build.