Resource Reconciler
The Reconciler is the “brain” of Nanokit. It is responsible for ensuring that your infrastructure always matches the definition in your nanokit.yml.
The Reconciliation Loop
Nanokit follows a deterministic loop to manage resources. Every time you run nkapp up or a change is detected via the Hub, the Reconciler executes the following stages:
1. Discovery (Observation)
The engine queries the active Infrastructure Provider (e.g., Docker, AWS) to list all existing resources associated with the project. This is the “Current State”.
2. Analysis & Diffing
The Reconciler compares the Desired State (your nanokit.yml) with the Current State. It identifies:
- New Services: In the config but not on the provider.
- Modified Services: Mismatch in image, env, or configuration.
- Orphaned Services: On the provider but removed from the config.
3. Plan Generation
Based on the diff, the Reconciler generates a ServicePlan. This is an ordered list of actions (CREATE, UPDATE, DELETE, NO_OP) required to reach the target state.
4. Execution
The ExecutionEngine takes the plan and carries out the actions in layers, respecting the dependency graph (DAG).
Desired vs. Current State
Nanokit treats your configuration as the absolute source of truth. Unlike traditional scripts, Nanokit doesn’t just “run commands”; it “reconciles state”.
| Component | Role |
|---|---|
| Desired State | Defined in nanokit.yml. Includes images, ports, envs, and scaling rules. |
| Current State | The actual resources running on your provider (containers, VMs, load balancers). |
| State File | A local or remote metadata file (state.json) that tracks IDs and versions. |
Reconciliation Logic (DAG)
The Reconciler uses the GraphEngine to ensure that dependencies are respected during execution. If Service B depends_on Service A, the Reconciler will:
- Start Service A.
- Wait for Service A to be healthy.
- Start Service B.
During deletion, the order is reversed to ensure graceful shutdown of dependent resources.
Manual Changes: If you manually modify a resource (e.g., stopping a container via Docker CLI), Nanokit will detect this “Drift” during the next reconciliation and automatically restart the resource to restore the Desired State.