Overview

ConfigBundleOperator is a Kubernetes Operator for managing configuration through a declarative ConfigBundle resource.

A ConfigBundle represents the desired configuration, while the operator is responsible for maintaining a corresponding ConfigMap in the cluster.

What It Manages¶

The operator introduces the ConfigBundle custom resource as the primary interface for defining configuration.

When a ConfigBundle is created, the operator creates the corresponding ConfigMap. Changes to the ConfigBundle are reflected in the managed resource according to its configuration and lifecycle rules.

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

    A -->|"Observed"| B
    B -->|"Creates / Updates"| C

Core Responsibilities¶

The operator is responsible for keeping the managed ConfigMap consistent with its ConfigBundle.

Its core responsibilities include:

• creating the managed ConfigMap
• detecting changes to the desired configuration
• updating or replacing the managed resource when necessary
• preserving the relationship between the ConfigBundle and its ConfigMap
• detecting unexpected changes to the managed resource
• restoring the expected state when the managed resource is missing or modified (Self-heal)

Declarative Management¶

Users interact with the operator through Kubernetes resources rather than directly manipulating the managed ConfigMap.

The desired state is declared through a ConfigBundle:

apiVersion: training.k8s.operators.dev/v1
kind: ConfigBundle
metadata:
  name: example
  labels: 
      faculty: Computer-Engineering
spec:
  message: "Hello, Kubernetes!"
  immutable: false

The operator interprets this resource and determines what the corresponding ConfigMap should look like.

Reconciliation¶

The operator continuously compares the desired configuration with the state of the managed resource.

When the states differ, the operator takes corrective action.

flowchart TD
    A["Desired State"]
    B["ConfigBundle"]
    C["Reconciliation"]
    D["In Sync"]
    E["Drift"]
    F["Wait"]
    G["Correct"]
    H["ConfigMap"]

    A --> B
    B --> C

    C --> D
    C --> E

    D --> F
    E --> G
    G --> H

This reconciliation model allows the operator to recover from changes that occur outside of the operator itself.

Ownership and Self-Healing¶

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

If the managed resource is deleted or its contents no longer match the expected configuration, the operator can recreate or restore it.

This gives the operator self-healing behavior instead of relying on a one-time creation process.

Lifecycle¶

A ConfigBundle goes through a simple lifecycle:

flowchart TD
    A["ConfigBundle Created"] --> B["Observe Desired State"]
    B --> C["Reconcile"]

    C --> D{"ConfigMap exists?"}

    D -->|No| E["Create ConfigMap"]
    D -->|Yes| F{"State matches desired?"}

    F -->|Yes| G["In Sync"]
    F -->|No| H["Correct ConfigMap"]

    E --> G
    H --> G

    G --> I["Managed State"]

    I --> J{"Change detected?"}

    J -->|ConfigBundle updated| B
    J -->|ConfigMap modified| B
    J -->|ConfigMap deleted| B

    J -->|No| I

    B --> K{"ConfigBundle deleted?"}
    K -->|No| C
    K -->|Yes| L["Delete / Release Managed Resources"]
    L --> M["Lifecycle Complete"]

The exact behavior of each lifecycle operation is described in Behaviour.

Next Steps¶

Now that the responsibilities of ConfigBundleOperator are clear, the Architecture section explains how the operator implements reconciliation and self-healing.