Documentation menu

Desired state

Hostwright separates the state you declare from the state that is actually running; Phase 2 models the declared side only.

Hostwright is being built as a desired-state system. Today it models and validates the declared side of that system. Runtime observation, convergence, and drift reporting are planned after the RuntimeAdapter and state store are ready.

Desired state and observed runtime state compared by a comparator to produce a drift report.
Drift is the difference between what you declared and what is actually running.

Two kinds of state

  • Desired state — what you declared in hostwright.yaml. Durable persistence is planned for the SQLite phase.
  • Observed state — what is actually running, read back from the runtime through the RuntimeAdapter at a point in time. This is not implemented yet.

The planned job of the reconciler is to compare the two, compute the difference, and converge observed state toward desired state.

Why declare instead of command

Imperative commands describe how; a manifest describes what. A declarative model gives you properties that are hard to get from a pile of shell commands:

  • Idempotency — future apply behavior must converge to the same result when run more than once.
  • Drift detection — once desired and observed state are both recorded, Hostwright can notice when reality has diverged from it.
  • Reviewable change — the difference between current and desired state can be shown as a plan before anything mutates.
  • Recovery — once SQLite state exists, desired state and operation records should survive daemon restarts.

The unit of declaration

A manifest declares a project that contains one or more services. A service references an image and the runtime details needed to run it — ports, environment, health checks, and restart policy.

project: api-local

services:
  api:
    image: ghcr.io/example/api:latest
    ports:
      - "8080:8080"

Open questions

  • Rollback. Future apply behavior still needs a final rollback policy. The current stance is conservative: automatic rollback only when every affected resource is owned by Hostwright and the rollback is deterministic. See the safety model.
  • Replicas. Running more than one instance of a service interacts with Apple container’s VM-per-container model. The scheduling and naming details for replicas are still under design.