Skip to content

Gateway agent

Every Gateway node runs a gateway agent. Its job is deliberately narrow: accept the desired state compiled for its Deployment, apply that state to its own runtime domain, and report back what it actually applied.

Controller  -- delivers desired state -->  gateway agent
                                              |
                                              | apply (privileged helper)
                                              v
                                     runtime domain: WireGuard,
                                     routes, nftables, NAT, conntrack
                                              |
                                              | report applied / observed
                                              v
Controller  <---------------------------------+

The agent serves a small authenticated API to the Controller (see API); it never fetches configuration from anywhere else, and it never invents state.

The four state models

Intent and reality are kept strictly apart:

State Meaning How it is established
Desired what the Controller has compiled and published for this (Gateway node, Deployment) the Controller compiled valid configuration and persisted the desired state
Delivered what reached the Gateway and validated there the Gateway accepted the candidate, verified it against its own schema and its binding, and persisted it
Applied what the Gateway actually put into the kernel the privileged apply succeeded and the kernel matches the applied artifact
Observed what is really happening at runtime derived from real runtime signals at the Gateway, such as client handshake state

Two rules follow from this and appear throughout the documentation:

  • Configuration is not activity. An object being enabled is an access state, never an activity state. Whether something is currently connected is a runtime signal, never inferred from desired state.
  • Applied is confirmed, not assumed. The Controller confirms an applied state against the Gateway's own view of the kernel; a Gateway that received state but could not put it into the kernel does not report ready.

Applying state is idempotent

An unchanged effective state is a no-op. The Controller compares effective content, not the global revision, so an unrelated change elsewhere in Git does not cause a re-apply and does not disturb live client tunnels. A repeated delivery of the same state never resets a live WireGuard session.

Last known good

Each runtime domain keeps a durable last-known-good applied state as a local artifact (0600, no secrets).

  • A successful apply replaces it.
  • A failed apply is recorded as a failure and never replaces the last-known-good, so a partial failure cannot be falsely acknowledged and cannot widen reachability.
  • After a restart the Gateway reconstructs the kernel from the last-known-good. A domain that was never applied reconstructs nothing and routes nothing.
  • Removing an object withdraws its reachability: JANUS removes only the objects it owns and leaves everything else untouched.

Controller-side reconciliation

Configuration is turned into desired state by a serial pipeline:

fetch        git fetch --prune
resolve      the exact commit of the tracked branch
materialize  a detached checkout of that exact commit
parse        load all objects
validate     semantic validation (fail closed)
compile      per enabled Gateway
validate     validate each compiled desired state
persist      transactional write of compiled state and runtime state
advance      move last-known-good

All enabled Gateways must compile. A Git revision becomes globally last-known-good only when every enabled Gateway validates and compiles successfully. Disabled Gateways do not block, and a single failing Gateway rejects the revision globally — the previous last-known-good is retained.

Situation Behaviour
Invalid revision marked invalid with the error recorded; previous last-known-good retained; the compiler is not called; no partial apply; the Controller stays alive
Git unavailable last-known-good retained; no empty desired state is invented; failures are logged and retried on the poll interval
First boot, invalid configuration the Controller stays alive but is not ready; no last-known-good exists; the failure is visible
First boot, valid configuration last-known-good is established on the first successful reconciliation
Valid revision after an invalid one last-known-good advances past the invalid revision
Policy reaches its expiry the access it granted stops being compiled without requiring a new commit

Reconciliation runs at startup, on a configurable poll interval, and on demand. The last-known-good survives a Controller restart because it is persisted, not held in memory.

Controller outage

A Controller outage is not an open state. The Gateway keeps the state it already applied, keeps its durable last-known-good, creates no new grant, and continues to enforce the policy it has. Recovery is a normal reconciliation.