Skip to content
pilots
Dashboard
All pages

What a machine may do

A machine holds no API key, and that is deliberate. A key baked into a guest is a key in every snapshot of it and in every fork of it, and it outlives the machine it was meant for.

A machine asks instead

Each machine has a credential broker bound inside its own network namespace, on the gateway address it already routes to. Nothing outside that namespace can reach it, and nothing inside it has to present a credential: the request path IS the identity, because there is nothing a guest could present that a copy of that guest could not.

It is deny by default. With no grant, a machine can mint no token and read no secret.

Granting

The verbs live under the object they apply to, because a grant and a local secret are two different mechanisms and one name for both would be the worst outcome.

pilot machine grant set scratch --scope machines
pilot service grant set web --scope machines,deploy
pilot machine grant show scratch
pilot machine grant clear scratch
You want Do
Let a machine call the API grant it the scopes it needs
Let every replica of a service call it grant the SERVICE. Later deploys inherit it.
Give a machine a secret value --secret NAME=value, and read it from the broker
See what is granted grant show, which prints names and scopes and never values
Take it away grant clear

Inside the machine

Variable What it is
PILOT_BROKER_URL Where to ask. The same address in every machine.
PILOT_TOKEN_FILE Where the guest agent keeps a fresh token.
PILOT_MACHINE_ID This machine’s own id.
PILOT_API_URL The fleet’s API.
by hand, from inside a machine 
curl -s "$PILOT_BROKER_URL/identity"
curl -s "$PILOT_BROKER_URL/token"
curl -s "$PILOT_BROKER_URL/secrets"

What a machine’s token may do

  • Reads are organization-wide. A machine can list its siblings, which is how it finds its own service and resolves a peer.
  • Writes are narrowed to that machine and its own service, and a shell or a raw tunnel counts as a write however it is spelled. A compromised replica restarting its peers one by one is an outage it could cause alone, so it cannot.
  • admin is never brokerable.
  • A token lives 15m. It is stopped by its own expiry, by revoking its hash through the key revocation route, or by destroying the machine.

For a value your own application needs at boot rather than at call time, see secrets. The two are different mechanisms on purpose: a secret is sealed and handed to a deploy, and a grant is answered live, per machine.