Zum Inhalt springen
Produkte

// Deployment

Installing Fleeger from scratch

An end-to-end guide for a new operator standing up Fleeger on Kubernetes from the published charts and images — no repo checkout, no maintainer tooling. By the end you'll have the hub running, a first admin, the UI reachable, and one location (or a remote agent) reporting.

If you're the maintainer working from a git checkout, or you want the full reference for every value and Secret, see Deploying on Kubernetes instead — this guide is the short, opinionated path.

What you'll end up with

The fleeger-hub chart brings up, in one namespace: the dependencies (SurrealDB, NATS/JetStream, VictoriaMetrics), the backend services (auth-svc, inventory-svc, gateway-svc, ingestion-svc, alerting-svc, control-svc), and the frontend SPA behind an edge that serves it and proxies /api to the gateway. Service names are fixed, so install one hub release per namespace.

1. Prerequisites

  • A Kubernetes cluster and a working kubectl context.
  • Helm 3.14+ (3.8 for OCI chart support; 3.14 for the --reset-then-reuse-values flag an upgrade that changes a value needs).
  • Pull access to the registry the release was published to (registry.example.com/fleeger in the examples below — substitute your host). If it's private, have an imagePullSecret ready in the namespace.
  • docker on your workstation for the one-time NATS auth generation in Step 3 (it runs nsc inside a container — you don't install nsc yourself).

Create the namespace you'll install into:

kubectl create namespace fleeger

2. Create the credential master key Secret

Fleeger encrypts stored secrets (infra credentials, alert-channel configs) with a 32-byte master key. Generate one and store it as a Secret. Back it up — losing it makes every stored secret unrecoverable.

head -c 32 /dev/urandom | base64 | tr -d '\n' | \
  kubectl -n fleeger create secret generic fleeger-credential-key --from-file=credential-key=/dev/stdin

3. Generate and load the NATS auth material

Agents and services authenticate to NATS with decentralized (nsc) credentials. This material can't be generated by the chart, so you produce it once and ship it as a Secret. The generator is a small script; the easiest way to get it without a full checkout is to grab it (and its siblings push-accounts.sh and push-spokes.sh) from the release, or clone just enough to run it:

# From a checkout of the release tag (only deploy/nats/ is needed):
deploy/nats/gen-auth.sh

This writes gitignored material under deploy/nats/auth/. Regenerating rotates all NATS credentials (every agent must re-onboard), so do it once and keep the output safe. See agent credentials for the trust model.

Ship it as the Secret the chart expects (fleeger-nats-auth):

kubectl -n fleeger create secret generic fleeger-nats-auth \
  --from-file=ingestion.creds=deploy/nats/auth/ingestion.creds \
  --from-file=gateway.creds=deploy/nats/auth/gateway.creds \
  --from-file=alerting.creds=deploy/nats/auth/alerting.creds \
  --from-file=inventory.creds=deploy/nats/auth/inventory.creds \
  --from-file=control.creds=deploy/nats/auth/control.creds \
  --from-file=core-agent.creds=deploy/nats/auth/core-agent.creds \
  --from-file=sys.creds=deploy/nats/auth/sys.creds \
  --from-file=operator.nk=deploy/nats/auth/operator.nk \
  --from-file=spokes-account.nk=deploy/nats/auth/spokes-account.nk \
  --from-file=resolver.conf=deploy/nats/auth/resolver.conf \
  --from-file=SPOKES.jwt=deploy/nats/auth/nsc-data/nats/nsc/stores/fleeger/accounts/SPOKES/SPOKES.jwt

Include every key above. Each is referenced by name in a pod's volume projection, so a missing one doesn't degrade — that pod crash-loops (or, for core-agent.creds, hangs in ContainerCreating with nothing in the logs). core-agent.creds is only read when coreAgent.enabled=true, but including it now is free and saves a broken install later. The chart preflights the Secret on helm install/upgrade and fails with the missing key names.

Optional Secrets

The chart generates strong values for the SurrealDB root password and the internal service token on install and keeps them across upgrades, so you don't have to (with helm install/upgrade; under Argo CD or helm template the chart cannot read the cluster, refuses, and names the existingSecret values to set, see the Helm chart reference, section GitOps). To pin your own instead, create Secrets with db-password / internal-token keys and pass --set surrealdb.existingSecret=… / --set internal.existingSecret=…. If you enable scheduled backups you'll also provide an S3 credential Secret — see backup & restore.

4. Install the hub from the OCI registry

helm install fleeger oci://registry.example.com/fleeger/charts/fleeger-hub \
  --version 1.0.0-rc1 \
  --namespace fleeger \
  --set image.registry=registry.example.com/fleeger \
  --set 'imagePullSecrets[0].name=<your-pull-secret>' \
  --set credential.existingSecret=fleeger-credential-key

Drop the imagePullSecrets line if the registry is public. Leave image.tag unset: the chart runs the images its own release published (its appVersion), so upgrading the chart later upgrades the images with it. A tag set here would be stored in the release and carried into every upgrade. Watch it settle:

kubectl -n fleeger get pods -w

The DB-owning services run migrations in an init container (retried until SurrealDB is up) and a one-off Job pushes the SPOKES account into the NATS resolver; the services go Ready shortly after.

Bringing your own identity provider? Disable the bundled auth-svc with --set services.auth-svc.enabled=false and front the gateway with your OIDC provider. Any core service can be toggled the same way when you supply that capability yourself.

5. Bootstrap the first admin

There's no self-registration; an operator creates the first admin with the auth-svc admin CLI, run inside its pod:

kubectl -n fleeger exec -it deploy/auth-svc -- /usr/local/bin/service \
  user add -u admin -e admin@example.com -r admin   # prompts for the password

It prompts for the password without echoing it, so the password never appears in a process list (-p would put it in the kubectl and container command lines, which any local user can read). The command is journalled in the audit log before the user is created, so run it once inventory-svc is up (its init container migrates the audit database); before that it refuses and creates nothing. Additional users can be added the same way with -r operator or -r viewer, or from the UI later.

6. Reach the UI

Expose the edge and open it, then sign in with the admin you just created (see logging in).

The flags below go on the helm install in step 4. The hub is already installed by now, so to add them to it, put them on helm upgrade fleeger oci://registry.example.com/fleeger/charts/fleeger-hub --namespace fleeger --reset-then-reuse-values (with --version set to the chart version you are running) instead: an upgrade that passes values without that flag resets everything else you set at install, including the image and credential settings above.

  • Ingress (needs a controller): add these flags to the helm install in step 4 (ending its last line with \), then open the host.

      --set ingress.enabled=true \
      --set ingress.host=fleeger.example.com \
      --set 'edge.trustedProxies[0]=<ingress-controller-pod-CIDR>'

    Replace <ingress-controller-pod-CIDR> with the address range of the one hop directly in front of the edge, usually your ingress controller's pod CIDR. An unreplaced placeholder, or any entry that is not an IPv4/IPv6 address or CIDR, stops the install before anything is applied, with an error naming the entry. Without the flag at all the install stops the same way, with an error saying edge.trustedProxies is empty. The Kubernetes deployment guide explains how to find the right range and why only that hop may be trusted.

  • NodePort: --set edge.service.type=NodePort --set edge.service.nodePort=30080 → http://<node-ip>:30080.

  • Quick check: kubectl -n fleeger port-forward svc/edge 8080:80 → open http://localhost:8080.

Enable TLS before exposing it past a trusted LAN — the login sends credentials and agents connect over WebSocket. The Kubernetes deployment guide has the cert-manager values block.

7. Onboard the first location (or a remote agent)

With the hub up you can start collecting:

  • A location reachable from the hub — create it in inventory, add a resource, then onboard its agent. Follow onboarding a location end to end.

  • A remote agent at another site — install the published fleeger-agent chart there, pointed at your hub with a one-time registration token. Paste the token at the prompt; it is not echoed and stays off every command line:

    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
    unset FLEEGER_TOKEN
    helm install fleeger-agent oci://registry.example.com/fleeger/charts/fleeger-agent \
      --version 1.0.0-rc1 \
      --set image.repository=registry.example.com/fleeger/spoke-agent \
      --set hub.url=https://fleeger.example.com \
      --set existingSecret=fleeger-agent-token

    The token comes from Onboard in the UI; the agent bootstraps once with it, receives location-scoped NATS credentials, and starts reporting. See onboarding a location.

Within ~30s the location flips to reachable on the dashboard.

Next steps

// 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.