Shared State & Locking

Nanokit is designed for collaborative environments where multiple developers or automated systems might attempt to modify infrastructure simultaneously. To prevent conflicts and data corruption, Nanokit implements a distributed locking and state management system.

The State File (state.json)

The state.json file is the “Source of Truth” for your infrastructure. It tracks:

• Resource IDs: The unique identifiers assigned by the provider (e.g., Docker Container IDs, AWS ARN).
• Configuration Hashes: Snapshots of the nanokit.yml used to deploy each resource.
• Dependency Map: The relationships between services at the time of deployment.

Local vs. Remote State

In local development, the state is stored in your project root. In production, Nanokit can synchronize the state with a remote backend (S3, GCS, or HashiCorp Vault) to ensure every team member is looking at the same infrastructure.

Provisioning Locks

When deploying services that share physical or virtual resources (like a shared node_modules volume in Docker), Nanokit prevents race conditions using a two-tier locking mechanism.

1. The Global Lock (.nk-install-lock)

Before running any provisioning.install command, Nanokit attempts to acquire a global lock. If the lock is already held by another container, the current container will wait.

2. The Sentinel File (.nk-installed-*)

Once an installation is successful, Nanokit creates a Sentinel File containing the hash of the manifest (package.json, package-lock.json).

• Sibling containers check for this file.
• If the sentinel exists and matches the current manifest, they skip the installation entirely.
• This allows a single “Heavy” container (with build tools) to initialize the environment for many “Slim” containers.

Infrastructure Locks

For cloud providers like AWS or GCP, Nanokit uses platform-native locking (e.g., DynamoDB tables or Cloud Storage locks) to prevent two nkapp deploy commands from running at the same time.

Handling Drift

Nanokit’s locking system also enables Drift Protection. Because the state file tracks exactly what should be there, the engine can detect if a resource was modified outside of Nanokit and safely restore it during the next reconciliation loop without causing conflicts with other managed services.