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ý)¶

Vygenerujte bootstrap token ve webovém UI MazeVault: Nastavení → Nasazení → Agenti → Vygenerovat Bootstrap token
Nakonfigurujte agenta s MAZEVAULT_SERVER_URL a MAZEVAULT_BOOTSTRAP_TOKEN
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ů

Opětovná registrace¶

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

Smažte agenta z webového UI (Nasazení → Agenti → Smazat)
Odstraňte lokální stav: rm -rf /etc/mazevault/agent-state.json
Vygenerujte nový bootstrap token
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