AuthBox documentation — Scenarios

Documentation embedded in this build.

A fleet of edge proxies around a central AuthBox

What it is for

One AuthBox in the middle; proxies and read-only replicas at the edges of the network. Each edge holds a signed bundle of the centre's authority and decides from what it holds — there is no call to the middle while a request is in flight, so no request waits on a link across the country, and an outage at the centre is not an outage at the door.

A central AuthBox publishes signed bundles outward to three edge boxes — two proxies and a read-only replica — each of which decides there; thin dotted arrows carry receipts back to the centre

The centre publishes its live store on a cadence, and what happened at the edge comes back: signed receipts, and the door's own sealed audit segments, so a refusal decided at the edge is on the console of the deployment whose policy decided it — stored as the door signed it, shown beside the centre's own record and never merged into it. An edge that goes dark keeps enforcing exactly what it was given until its freshness budget lapses; then it steps out of rotation rather than failing open, and the fleet is short one edge instead of wrong at one edge.

This is not a cache in front of a central decision. The decision is made at the edge.

The topology

A central AuthBox publishes signed bundles outward; each edge decides there, and thin return paths carry receipts back to the centre.

                    +-----------------+
                    |  CENTRAL BOX    |
                    |  publishes on   |
                    |  a cadence      |
                    +--+----+------+--+
             bundle     |    |      |     bundle
        +---------------+    |      +---------------+
        v                    v                      v
   +---------+         +----------+           +-----------+
   | PROXY   |         | PROXY    |           | REPLICA   |
   | decides |         | decides  |           | read-only |
   +----+----+         +-----+----+           +-----+-----+
        |                    |                      |
        +---- receipts, sealed audit segments ------+
                      (back to the centre)

The reference deployment is one writer, three read-only replicas and three proxies.

Stand it up

$ make kind-up                   # the reference fleet on a kind cluster you keep
$ make scenario-kubernetes       # the manifests applied and walked
$ make scenario-replica-fleet    # an edge goes dark and lapses

make kind-up leaves a cluster standing for you to poke at; the two scenarios bring their own topology up, check it and take it down. All three need docker, and the kind ones need kind and kubectl.

What the smoke proves

make scenario-kubernetes runs the Go twin TestKubernetesReferenceDeployment: the checked-in manifests under deploy/kubernetes/ actually applied to a kind node — one writer, three replicas, three proxies, every operator object, across three namespaces. Until this scenario existed the manifests were proven statically and never once applied, which is the gap it closes.

make scenario-replica-fleet runs TestReplicaFleet and is the edge's own story in three checks: a writer signs and publishes a bundle; a replica already running and polling adopts it live, so a record present only in the newer bundle becomes visible without a restart; and an aged replica whose bundle has passed its maximum age reports itself not ready, leaves rotation, and goes on enforcing exactly the data it holds. Leaving rotation rather than failing open is the whole claim, and it is asserted on the wire an operator's load balancer reads.

make kind-up proves the same fleet stands up from the base manifests through the single-node overlay, with fixture PKI, on a cluster you keep.

Read on