Infisical Agent (Secrets-Management)

Host-nativer Background-Daemon auf dem NUC, der Secrets aus Infisical als env_file-Dateien nach /run/infisical/ rendert. Loest das fruehere infisical run ---Wrapper-Pattern ab: Compose-Stacks starten wieder mit plain docker compose up -d und beziehen Secrets ueber env_file.

Zugriff

Wo laeuft's	NUC (10.10.10.3) als systemd-Service infisical-agent.service
Konfig	/etc/infisical/agent.yaml (lokal, nicht im Repo)
Output	/run/infisical/<stack>.env (tmpfs, root:robin 0640)
Logs	sudo journalctl -u infisical-agent.service
Traefik	Nein (interner Host-Dienst, kein Container)

Architektur

Infisical Cloud (EU)  ◄── HTTPS-Poll (60s) ──  infisical-agent.service (systemd)
                                                  │
                                                  ▼
                                  /run/infisical/<stack>.env (tmpfs, root:robin 0640)
                                                  │
                                                  ▼
                                  Docker-Compose-Stacks (env_file: …)

Der Agent authentifiziert sich per Universal Auth (Machine Identity) gegen die EU-Instanz und pollt alle 60 s. Jeder konfigurierte Stack erhaelt ein eigenes gerendertes .env-File im tmpfs.

Angebundene Stacks

Pro Stack ein Template-Block in agent.yaml (Infisical-Pfad → Ziel-File):

Infisical-Pfad	Ziel-File
/ollama	/run/infisical/ollama.env
/speedtest-tracker	/run/infisical/speedtest-tracker.env
/paperless-ngx	/run/infisical/paperless-ngx.env

Konfigurationsbesonderheiten

• Universal Auth: Machine Identity mit Client-ID/-Secret unter /etc/infisical/client-{id,secret} (root:root 0600).
• Daten-Region: address: https://eu.infisical.com (EU-Instanz). US waere https://app.infisical.com. Falsche Region → Login 401 Invalid credentials trotz korrekter Credentials.
• Polling-Interval: 60 s pro Template. Rotierte Secrets landen in max. 1 min im File; der Container behaelt das alte Secret bis zu einem --force-recreate.
• Boot-Order: Before=docker.service — der Agent startet vor Docker, damit die env_files beim Container-Start vorhanden sind.
• Hardening: systemd-Sandbox mit NoNewPrivileges, ProtectSystem=strict, ProtectHome=true, UMask=0027. RuntimeDirectory=infisical legt /run/infisical als 0750 root:robin an (trotz ProtectSystem=strict beschreibbar).

Anbindung in Compose-Stacks

services:
  <service>:
    image: <pinned>
    env_file:
      - /run/infisical/<stack>.env
    environment:
      # Nicht-geheime Werte bleiben inline
      - TZ=Europe/Berlin

Kein infisical run ---Wrapper mehr — plain docker compose up -d.

Wichtige Pfade

Pfad	Zweck
/etc/infisical/agent.yaml	Agent-Config (root:root 0640)
/etc/infisical/client-id	Universal-Auth Client-ID (root:root 0600)
/etc/infisical/client-secret	Universal-Auth Client-Secret (root:root 0600)
/run/infisical/access-token	Auth-Token-Sink (tmpfs)
/run/infisical/<stack>.env	Gerenderte Secrets pro Stack (tmpfs, root:robin 0640)
/etc/systemd/system/infisical-agent.service	systemd-Unit

Wartung

Neuen Stack anbinden

1. Secrets in der Infisical-UI unter /<stack> anlegen
2. Template-Block in /etc/infisical/agent.yaml ergaenzen
3. sudo systemctl reload infisical-agent.service
4. Pruefen: sudo cat /run/infisical/<stack>.env
5. Im Compose: env_file: - /run/infisical/<stack>.env

Secret rotieren

1. Secret in der Infisical-UI aendern
2. Agent rendert das File innerhalb von max. 60 s neu
3. Container neu erzeugen: docker compose -f <stack>/docker-compose.yaml up -d --force-recreate

Troubleshooting

Symptom	Ursache	Fix
Status failed, "unable to authenticate"	Client-ID/-Secret falsch oder falsche Region	/etc/infisical/client-{id,secret} und address (EU/US) pruefen
.env leer/fehlt	Template-Block falsch oder Permissions	journalctl -u infisical-agent
Container: ENOENT /run/infisical/x.env	Agent laeuft nicht oder Template fehlt	systemctl status infisical-agent.service, agent.yaml pruefen
Rotation propagiert nicht	polling-interval zu gross oder Agent crashed	Logs pruefen

Vollstaendige Bootstrap-Anleitung (Machine Identity anlegen, Credentials ablegen, Unit deployen) im Quell-Repo: infrastructure/infisical-agent/README.md.