Zum Inhalt springen
Produkte

// Betrieb

Onboarding a new location

Onboarding gives a location's spoke-agent the credentials it needs to publish metrics to the hub. The agent authenticates once with a registration token, exchanges it for scoped NATS credentials, and then runs on its own. The token is time-limited and works for one agent: after its first use it only lets that agent retry for 5 minutes, so it's safe to hand to an installer.

Prerequisite: the location exists in inventory — see creating a location — and (usually) has at least one resource to collect — see adding a resource.

Connecting a Proxmox homelab? For the full sequence — monitoring-token creation, the exact credential format, self-signed TLS, and the registry to use — follow the end-to-end Connect a Proxmox homelab walkthrough, which threads this page together with the resource and credential steps.

The normal flow (registration token)

  1. Open Locations.
  2. On the location's row, select Onboard. Fleeger mints a one-time registration token (requires the location.create permission) and shows a ready-to-run install command. Pick your platform — Docker, Kubernetes, or Standalone — and the command updates to match (see Run the agent as a container for what each one does). The hub's own meta location has no agent and offers no Onboard: the hub monitors itself, and a token for it is refused.
  3. Run that command where the agent will live (a Pi in the homelab, a pod in the cluster, …). On first boot the agent:
    • calls POST /api/bootstrap with the token (the token is its only credential),
    • receives NATS user credentials scoped to this location,
    • writes them plus a <creds>.meta.json, and discards the token.
  4. The agent connects to NATS and starts publishing. Within ~30s the location flips to reachable on the dashboard (see checking reachability).

On later restarts the agent reuses the persisted credentials — it never needs the token again. That also means a new token is ignored while they are there: to onboard the location again (after offboarding, or to start over), remove them first (see re-onboarding).

Run the agent as a container

The spoke-agent is published as a container image and configured entirely by environment variables (or a small TOML file). It connects to the hub over a single URL: it bootstraps over HTTPS, then does everything else — metrics and inventory (reading targets, revealing credentials, reporting discovery / hardware) — over the encrypted NATS WebSocket the hub hands it (wss://<hub>/nats). So a remote agent needs only the one public endpoint; nothing else must be exposed. See agent security for the trust model.

If that endpoint is behind an ingress, a load balancer or a tunnel, the edge has to trust it, or it answers both the bootstrap and /nats with a 503. A new agent then exits with a "bootstrap rejected" error naming the 503; one that already bootstrapped fails when it connects to /nats. The response itself says why ("Fleeger is behind a proxy the edge does not trust…"); fetch the hub URL with curl -i to read it. The same setting decides whether offboarding can revoke the agent later.

If nothing answers at all (a firewall dropping the traffic, a proxy that holds the request), the first boot gives up instead of waiting forever: the agent exits with "bootstrap … timed out", after 10s if it could not connect and after 30s if it connected but got no answer.

An agent whose first boot fails (a timeout, a refused token, an unreachable NATS) exits and is started again: the pod on Kubernetes, the container on Docker through --restart unless-stopped in the commands below. A docker run without --restart stays stopped until you start it again. An exchange the hub could not record leaves the token unused, and the retry is a first exchange. Once the hub has recorded the agent's credentials, the token is used up, even if the answer never reaches the agent. For 5 minutes after that the same token still works: a retry gets fresh credentials, and the ones from the lost answer are revoked (up to 4 retries). A retry the hub refuses within those 5 minutes can simply be tried again. If one is refused as an already-used token after that, mint a new one with Onboard. Whoever sees a used token within those 5 minutes could also exchange it, and the agent then loses its credentials; treat the token as secret until the agent is up. On Docker, remove the old container first (docker rm -f fleeger-agent), or the new docker run fails because the name is taken.

What Config Notes
Hub URL FLEEGER_HUB_URL The one endpoint — same origin as the UI. https://, with no credentials, query or fragment; the agent refuses anything else before it sends the token. http:// works but sends the token and the agent's credential in cleartext, so the agent warns unless the host is loopback or a single-label name such as edge.
Token FLEEGER_REGISTRATION_TOKEN The one-time token from Onboard.
Creds path FLEEGER_NATS_CREDS Where bootstrap writes creds (default /var/lib/fleeger/agent.creds). Must persist — the token stops working 5 minutes after its first use.
Poll interval FLEEGER_POLL_INTERVAL_SECS Seconds between collection cycles (default 30; 0 is ignored). Keep it well under 90s: each resource reports once per cycle, and its alerts treat 90s of silence as unreachable (the location's heartbeat is sent at least every 30s regardless).
State dir FLEEGER_STATE_DIR Where the agent keeps the clusters it last read for its Proxmox and Kubernetes registrations, so a restart keeps their series' identity (default: the creds file's directory). Should persist, like the creds.

Image and registry. The Docker Onboard command runs registry.netcode.dev/fleeger/spoke-agent at your hub build's version, and the Kubernetes one pulls the chart and image from registry.netcode.dev/fleeger at that version too. A hub build without a release version (a local build) puts <version> there; fill in the version yourself. If you mirror or push the images to your own registry (see container images), substitute it in either command.

Keeping the token off the command line. Neither the commands below nor the ones the Onboard panel copies pass the token as an argument to docker, kubectl or helm, where any local user could read it with ps while the command runs. It is handed over in a private file (Docker) or a Secret (Kubernetes), written by printf, a shell builtin. The panel's commands carry the token inline, so it lands in your shell history (a file only you can read); the ones below ask for it at a prompt that does not echo it and keep it out of the history too. All of them are for sh, bash or zsh, not fish. The Secret is applied, so running the Kubernetes commands again with a new token replaces the old one.

Docker

printf 'Registration token: '; stty -echo; IFS= read -r FLEEGER_TOKEN; stty echo; echo
(umask 077; rm -f fleeger-agent.env; printf 'FLEEGER_REGISTRATION_TOKEN=%s\n' "$FLEEGER_TOKEN" > fleeger-agent.env)
unset FLEEGER_TOKEN
docker run -d --restart unless-stopped --name fleeger-agent \
  -v fleeger-agent-data:/var/lib/fleeger \
  -e FLEEGER_HUB_URL=https://your-hub.example.com \
  --env-file fleeger-agent.env \
  registry.netcode.dev/fleeger/spoke-agent:X.Y.Z
rm fleeger-agent.env

X.Y.Z is your hub's release version, the one the Onboard panel's command carries. The named volume keeps the bootstrapped credentials across restarts. --restart unless-stopped starts the agent again after a crash, a failed first boot, or a reboot of a host whose Docker daemon starts at boot; docker stop fleeger-agent keeps it stopped. Docker copies the env file into the container's configuration when it creates it, so the file is not needed afterwards. (If docker run fails, create the file again before retrying; if it failed because a fleeger-agent container exists, docker rm -f fleeger-agent first.)

Same host as the hub? localhost inside the container is the container itself, not your host, and the edge only resolves on the hub's Docker network. Attach to it and point at the edge, with fleeger-agent.env created and removed as above:

docker run -d --restart unless-stopped --name fleeger-agent --network fleeger_default \
  -v fleeger-agent-data:/var/lib/fleeger \
  -e FLEEGER_HUB_URL=http://edge \
  --env-file fleeger-agent.env \
  registry.netcode.dev/fleeger/spoke-agent:X.Y.Z

Kubernetes

Use the Helm chart: fleeger-agent chart (a Deployment + a small PVC for the creds), installed from the OCI registry at your hub's release version (the Onboard panel fills --version in from the hub build):

printf 'Registration token: '; stty -echo; IFS= read -r FLEEGER_TOKEN; stty echo; echo
printf '%s' "$FLEEGER_TOKEN" | kubectl create secret generic fleeger-agent-token \
  --from-file=registration-token=/dev/stdin --dry-run=client -o yaml | kubectl apply -f -
unset FLEEGER_TOKEN
helm install fleeger-agent oci://registry.netcode.dev/fleeger/charts/fleeger-agent \
  --version 1.0.0-rc1 \
  --set image.repository=registry.netcode.dev/fleeger/spoke-agent \
  --set hub.url=https://your-hub.example.com \
  --set existingSecret=fleeger-agent-token

Or from a repository checkout, with fleeger-agent-token created as above and the fleeger/spoke-agent:local image built from the checkout and loaded into the nodes:

helm install fleeger-agent charts/fleeger-agent \
  --set image.tag=local \
  --set hub.url=https://your-hub.example.com \
  --set existingSecret=fleeger-agent-token

For an agent monitoring the very cluster it runs in, add --set rbac.create=true for read-only node/pod metrics via its ServiceAccount. See Deploying Fleeger on Kubernetes.

Standalone (binary)

There's no separately-published binary artifact — only the container images are built by CI (container images). Build the spoke-agent binary from the repo:

cargo build -p spoke-agent --release   # → target/release/spoke-agent

Then write a config file and run it directly:

# spoke-agent.toml
hub_url = "https://your-hub.example.com"
registration_token = "<token>"
nats_creds = "/var/lib/fleeger/agent.creds"
spoke-agent --config spoke-agent.toml

Env vars override the file, so the same binary works with either.

Dev / manual alternative

Running an agent by hand on the dev machine (no bootstrap):

  1. Mint credentials for the location:
    CONFIG_PATH=services/auth-svc/config.toml \
      cargo run -p auth-svc -- mint-creds --location <location-id> > deploy/nats/auth/minted-<location-id>.creds
    (deploy/nats/auth/ is gitignored — these are secrets.) <location-id> is the location's record id, not its display name. The command needs the hub database: it records the credential's user key in the revocation ledger before it prints the creds, so offboarding the location can revoke them. If it cannot connect or sign in to the database, or the database refuses the row, it exits non-zero and prints nothing; delete the empty file the redirect left behind. On a deployed hub, run it in the auth-svc container instead (minting by hand).
  2. Point a spoke-agent config at that location and creds file (location, nats_creds, nats_url), then:
    cargo run -p spoke-agent -- --config <that-config>.toml

Verifying

  • Dashboard → Locations: the card shows reachable with a recent "last seen".
  • Any resources under the location start reporting; auto-discovered sub-resources (VMs, k8s nodes) appear as read-only rows.
  • Still unreachable after a minute? Work through checking reachability.

// Zusammenarbeit

Bereit, Ihre digitale Infrastruktur zu bauen?

Ob individuelle Automatisierung für Ihr Unternehmen oder ein durchgeplantes Netzwerk für Ihr Zuhause — lassen Sie uns über das Projekt sprechen.