Přeskočit obsah

Průvodce nasazením agenta

Instalace, konfigurace a provoz agentů MazeVault

Verze dokumentu: 1.0.0
Poslední aktualizace: 2026-04-03

1. Přehled

MazeVault Agent je lehký Go binární soubor nasazený na infrastrukturních uzlech. Poskytuje:

  • Synchronizace tajemství — Automatické doručování tajemství do lokálních aplikací
  • Objevování certifikátů — Skenování infrastruktury pro certifikáty (souborový systém, JKS, Windows cert store)
  • Životní cyklus certifikátů — Automatizovaná obnova a nasazení spravovaných certifikátů
  • Real-time aktualizace — WebSocket připojení pro okamžitá push oznámení
  • Lokální proxy — Bezpečný proxy pro přístup aplikací k tajemstvím bez přímých API volání
  • Odolnost při výpadku — Lokální cache zajišťuje provoz během výpadků sítě

2. Podporované platformy

Platforma Architektura Poznámky
Linux x86_64, ARM64 Ubuntu, RHEL, Rocky Linux, Debian, Alpine
Windows x86_64 Windows Server 2019+
Kubernetes Libovolná Sidecar kontejner nebo DaemonSet

3. Instalace

3.1 Linux — Instalace binárního souboru

# Stažení agenta
curl -sL https://vault.example.com/api/v1/agents/download/linux-amd64 -o mazevault-agent
chmod +x mazevault-agent
sudo mv mazevault-agent /usr/local/bin/

# Vytvoření konfiguračního adresáře
sudo mkdir -p /etc/mazevault
sudo mkdir -p /var/lib/mazevault/certs

3.2 Linux — systemd služba

Vytvořte /etc/systemd/system/mazevault-agent.service:

[Unit]
Description=MazeVault Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/mazevault/agent.env
ExecStart=/usr/local/bin/mazevault-agent
Restart=always
RestartSec=10
User=mazevault
Group=mazevault

[Install]
WantedBy=multi-user.target

# Vytvoření servisního uživatele
sudo useradd -r -s /sbin/nologin mazevault

# Povolení a spuštění
sudo systemctl daemon-reload
sudo systemctl enable mazevault-agent
sudo systemctl start mazevault-agent

3.3 Kubernetes — Sidecar kontejner

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: my-app:latest
          volumeMounts:
            - name: secrets
              mountPath: /var/run/secrets/mazevault
        - name: mazevault-agent
          image: ghcr.io/mazevault/agent:latest
          env:
            - name: MAZEVAULT_SERVER_URL
              value: "https://vault.example.com"
            - name: MAZEVAULT_BOOTSTRAP_TOKEN
              valueFrom:
                secretKeyRef:
                  name: mazevault-bootstrap
                  key: token
          volumeMounts:
            - name: secrets
              mountPath: /var/run/secrets/mazevault
      volumes:
        - name: secrets
          emptyDir:
            medium: Memory

3.4 Kubernetes — DaemonSet

Pro cluster-wide objevování a správu certifikátů:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: mazevault-agent
  namespace: mazevault
spec:
  selector:
    matchLabels:
      app: mazevault-agent
  template:
    metadata:
      labels:
        app: mazevault-agent
    spec:
      serviceAccountName: mazevault-agent
      containers:
        - name: agent
          image: ghcr.io/mazevault/agent:latest
          env:
            - name: MAZEVAULT_SERVER_URL
              value: "https://vault.example.com"
            - name: MAZEVAULT_BOOTSTRAP_TOKEN
              valueFrom:
                secretKeyRef:
                  name: mazevault-bootstrap
                  key: token
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
              memory: 128Mi

4. Konfigurace

4.1 Proměnné prostředí

Vytvořte /etc/mazevault/agent.env:

# Povinné
MAZEVAULT_SERVER_URL=https://vault.example.com
MAZEVAULT_BOOTSTRAP_TOKEN=mvbt_xxxxxxxxxxxxx

# Volitelné — Identita agenta
MAZEVAULT_AGENT_NAME=app-server-01
MAZEVAULT_PROJECT_ID=proj_xxxxxxxxxxxxx

# Volitelné — Úložiště
MAZEVAULT_CERT_STORE_PATH=/var/lib/mazevault/certs
MAZEVAULT_STATE_DIR=/etc/mazevault

# Volitelné — Logování
MAZEVAULT_LOG_LEVEL=info        # debug, info, warn, error
MAZEVAULT_LOG_FORMAT=text       # text, json

# Volitelné — Synchronizace
SYNC_INTERVAL_SECONDS=300       # Výchozí: 300 (5 minut)

4.2 Reference proměnných

Proměnná Povinná Výchozí Popis
MAZEVAULT_SERVER_URL Ano — URL backendu MazeVault
MAZEVAULT_BOOTSTRAP_TOKEN Ano ¹ — Jednorázový registrační token
MAZEVAULT_AGENT_NAME Ne hostname Zobrazovaný název v UI
MAZEVAULT_PROJECT_ID Ne — Project scope pro tajemství
MAZEVAULT_CERT_STORE_PATH Ne /var/lib/mazevault/certs Adresář pro úložiště certifikátů
MAZEVAULT_STATE_DIR Ne /etc/mazevault Adresář konfigurace a stavu
MAZEVAULT_LOG_LEVEL Ne info Úroveň detailu logů
MAZEVAULT_LOG_FORMAT Ne text Formát logů (text nebo json)
SYNC_INTERVAL_SECONDS Ne 300 Interval synchronizace tajemství v sekundách

¹ Povinné pouze při prvotní registraci. Po bootstrapu agent používá mTLS certifikáty.

5. Bootstrap a registrace

Agent používá dvoufázový autentizační model:

Fáze 1: Bootstrap (jednorázový)

  1. Vygenerujte bootstrap token ve webovém UI MazeVault: Nastavení → Nasazení → Agenti → Vygenerovat Bootstrap token
  2. Nakonfigurujte agenta s MAZEVAULT_SERVER_URL a MAZEVAULT_BOOTSTRAP_TOKEN
  3. Spusťte agenta — automaticky se zaregistruje přes POST /api/v1/agents/register

Fáze 2: mTLS (průběžná)

Po úspěšné registraci agent obdrží:

  • Klientský certifikát — Pro mutual TLS autentizaci
  • CA certifikát — Pro ověření serveru
  • Heartbeat interval — Doporučená frekvence hlášení stavu
  • Sync interval — Frekvence synchronizace tajemství

Veškerá další komunikace probíhá přes mTLS. Bootstrap token již není potřeba a může být odvolán.

┌──────────┐          ┌───────────────┐
│  Agent   │──────────│  MazeVault    │
│          │ Bootstrap│  Backend      │
│          │  Token   │               │
│          │◀─────────│               │
│          │ mTLS Cert│               │
│          │          │               │
│          │──────────│               │
│          │ mTLS     │               │
│          │ (průběžně)│               │
└──────────┘          └───────────────┘

6. Pravidelné operace

Agent automaticky spouští několik úloh na pozadí:

Operace Interval Popis
Synchronizace tajemství Konfigurovatelný (výchozí 5m) Synchronizuje tajemství z backendu do lokálního úložiště
Heartbeat 60 sekund Hlásí stav, metriky (CPU, paměť, disk) a verzi backendu
Objevování certifikátů 1 hodina Skenuje nakonfigurované cesty pro certifikáty (filesystem, JKS, Windows cert store)
Kontrola aktualizací 24 hodin Kontroluje dostupnost novější verze agenta
Licenční heartbeat 5 minut Odesílá telemetrii na licenční server (pokud je nakonfigurován)
K8s reconciliace 5 minut Reconcilace Kubernetes Secret certifikátů (pouze K8s)
WebSocket reconnect Exponenciální backoff Udržuje real-time push připojení (1s → 2s → 4s → ...)

Všechny intervaly jsou fixní kromě synchronizace tajemství (SYNC_INTERVAL_SECONDS).

7. Objevování certifikátů

Agent objevuje certifikáty napříč infrastrukturou a hlásí je backendu:

Zdroje objevování

Zdroj Platforma Popis
Souborový systém Linux/Windows Skenuje nakonfigurované adresáře pro PEM, DER, PFX soubory
Java KeyStore (JKS) Všechny Parsuje .jks a .p12 soubory
Windows Certificate Store Windows Enumeruje systémové a uživatelské certifikátové úložiště
Kubernetes Secrets K8s Sleduje kubernetes.io/tls secrets

Konfigurace objevování

Cesty pro objevování se konfigurují ve webovém UI MazeVault:

Projekt → Nastavení → Objevování agenta → Cesty

Výsledky se zobrazí v pohledu Objevené certifikáty na dashboardu.

8. Monitoring

Endpoint stavu

Agent hlásí stav prostřednictvím heartbeatu. Monitorujte stav agentů ve webovém UI:

Nasazení → Agenti

Klíčové hlášené metriky

  • cpu_percent — Vytížení CPU agenta
  • memory_percent — Využití paměti agenta
  • secrets_synced — Počet synchronizovaných tajemství
  • certificates_managed — Počet spravovaných certifikátů
  • last_sync_time — Časové razítko poslední úspěšné synchronizace
  • uptime_seconds — Doba běhu agenta

Prometheus metriky

Backend vystavuje metriky agentů na /metrics:

mazevault_agents_online{environment="production"} 12
mazevault_agent_sync_operations_total{agent_id="agt_xyz"} 1842
mazevault_agent_discovery_findings_total{agent_id="agt_xyz"} 37

9. Řešení problémů

Agent se nespustí

# Kontrola logů
journalctl -u mazevault-agent -f

# Ověření konektivity
curl -sk https://vault.example.com/api/v1/health
Problém Příčina Řešení
connection refused Backend nedostupný Ověřte MAZEVAULT_SERVER_URL a pravidla firewallu
certificate expired Certifikát agenta vypršel Znovu zaregistrujte s novým bootstrap tokenem
bootstrap token invalid Token vypršel nebo byl použit Vygenerujte nový bootstrap token ve webovém UI
TLS handshake error Neshoda CA certifikátu Ověřte řetězec CA certifikátů

Životní cyklus agenta (Nasazení → Agenti)

Registrovaní agenti se spravují v sekci Nasazení → Agenti přes nabídku akcí u každého řádku. Tyto operace pracují s identitou nainstalovaného agenta v řídicí rovině MazeVault a jsou odlišné od smazání vygenerovaného instalačního záznamu v sekci Nasazení → Nasadit.

Akce Co dělá Kdy použít
Odregistrovat Vyřadí agenta, zneplatní jeho mTLS identitu a recovery tokeny, deaktivuje vazby na projekty a zablokuje veškeré budoucí runtime použití. Historie zůstává zachována. Zvolením bezpečnostní kategorie důvodu (kompromitace / ztracený credential / odcizený host) se akce zaznamená jako revokace. Vyřazené, ztracené, offline nebo ručně odstraněné hosty.
Odinstalovat vzdáleně Požádá připojeného agenta, aby se sám odinstaloval z hosta, a před dokončením nahlásí skutečný výsledek zpět. Podporováno na Linuxu (balíčková systemd instalace, agent běžící jako root) a na Windows (MSI service instalace; služba MazeVaultAgent je odebrána přes msiexec). Agent musí být aktuálně připojen. Agent je vyřazen až po potvrzení úspěšného odstranění; pokud odstranění selže, agent zůstane aktivní a konzole zobrazí Odinstalace selhala pro opakování nebo zásah. Čisté odstranění agenta z dostupného Linux nebo Windows hosta.
Přeregistrovat / obnovit identitu Vyřadí starou identitu a vydá jednorázový náhradní bootstrap token (platnost 24 h) pro opětovné zaregistrování hosta. Vypršený nebo kompromitovaný mTLS certifikát; výměna hosta.

Před odregistrací se zobrazí náhled dopadu (spravované certifikáty, vazby na projekty, rotační cíle, SSH klíče, čekající keytab práce). Nevyřešená práce, jako čekající keytab nasazení nebo aktivně spravované certifikáty, vyžaduje pro pokračování volbu Force.

Odregistrace neodinstaluje binárku na hostu. Pro offline hosty nebo tam, kde vzdálená odinstalace není podporována (nebalíčkové/ruční instalace, macOS), agenta odregistrujte a odstraňte lokálně.

Linux:

sudo systemctl stop mazevault-agent && sudo systemctl disable mazevault-agent
sudo apt remove mazevault-agent   # nebo: sudo rpm -e mazevault-agent
sudo rm -rf /etc/mazevault /var/lib/mazevault /var/log/mazevault

Windows (PowerShell, s oprávněním administrátora):

sc.exe stop MazeVaultAgent
$p = Get-WmiObject Win32_Product -Filter "Name='MazeVault Agent'"
if ($p) { $p.Uninstall() } else { sc.exe delete MazeVaultAgent }
Remove-Item -Recurse -Force "$env:ProgramData\MazeVault" -ErrorAction SilentlyContinue

Opětovná registrace

Pokud mTLS certifikát agenta vyprší nebo je kompromitován:

  1. V sekci Nasazení → Agenti otevřete nabídku akcí agenta a zvolte Přeregistrovat / obnovit identitu (nebo Odregistrovat s bezpečnostním důvodem u kompromitovaného hosta).
  2. Zkopírujte jednorázový náhradní bootstrap token z dialogu.
  3. Odstraňte lokální stav na hostu: rm -rf /etc/mazevault/agent-state.json
  4. Restartujte agenta s novým MAZEVAULT_BOOTSTRAP_TOKEN.

Ladící logování

Povolte podrobné logování pro diagnostiku:

MAZEVAULT_LOG_LEVEL=debug mazevault-agent

10. Bezpečnostní aspekty

  • Bootstrap tokeny jsou jednorázové a časově omezené (výchozí: 24 hodin)
  • mTLS certifikáty jsou vázány na konkrétního agenta a projekt
  • Data tajemství jsou šifrována při přenosu (TLS 1.2+) a lokálně uložena šifrovaně
  • Minimální oprávnění — agenti mají přístup pouze k tajemstvím přiřazeným jejich projektu
  • Žádné příchozí porty — agent iniciuje veškerá spojení (pouze odchozí)

Související

  • Agents API — REST API reference pro endpointy agentů
  • FAQ — Často kladené otázky
  • Škálování — Doporučení pro škálování agentů
  • Autentizace — Detaily autentizace agentů
  • Monitoring — Prometheus metriky pro agenty