Troubleshooting¶

Dieser Leitfaden hilft bei der Lösung häufiger Probleme mit Polycrate.

Docker-Probleme¶

"Cannot connect to Docker daemon"¶

Problem: Polycrate kann keine Verbindung zum Docker-Daemon herstellen.

Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Lösungen:

1. Prüfen Sie, ob Docker läuft:

   docker ps
   

2. Starten Sie Docker:

   # Linux (systemd)
   sudo systemctl start docker
   
   # macOS/Windows
   # Starten Sie Docker Desktop
   

3. Prüfen Sie Berechtigungen:

   # Linux - Benutzer zur docker-Gruppe hinzufügen
   sudo usermod -aG docker $USER
   newgrp docker
   

4. Prüfen Sie den Socket-Pfad:

   ls -la /var/run/docker.sock
   

"Image not found" oder Pull-Fehler¶

Problem: Polycrate kann das Workspace-Image nicht finden oder herunterladen.

Error: Error response from daemon: pull access denied for cargo.ayedo.cloud/library/polycrate

Lösungen:

1. Prüfen Sie Ihre Internetverbindung

2. Authentifizieren Sie sich bei der Registry:

   docker login cargo.ayedo.cloud
   

3. Verwenden Sie ein anderes Image:

   polycrate run my-block install --image-ref <alternative-image>
   

4. Überspringen Sie den Pull (wenn Image bereits lokal):

   polycrate run my-block install --pull false
   

Container startet nicht¶

Problem: Der Polycrate-Container startet nicht oder stürzt sofort ab.

Lösungen:

1. Prüfen Sie die Container-Logs:

   docker logs <container-id>
   

2. Prüfen Sie die Polycrate-Logs:

   ls -la .logs/
   cat .logs/<latest-log-file>
   

3. Erhöhen Sie den Log-Level:

   polycrate run my-block install --loglevel 2
   

4. Testen Sie den Container manuell:

   docker run -it --rm cargo.ayedo.cloud/library/polycrate:latest /bin/sh
   

Workspace-Probleme¶

"Not a valid workspace"¶

Problem: Polycrate erkennt das Verzeichnis nicht als Workspace.

Error: Not a valid workspace: workspace.poly not found

Lösungen:

1. Prüfen Sie, ob workspace.poly existiert:

   ls -la workspace.poly
   

2. Initialisieren Sie einen neuen Workspace (im Zielverzeichnis):

   mkdir -p ~/polycrate-workspaces/my-workspace
   cd ~/polycrate-workspaces/my-workspace
   polycrate workspace init --with-name my-workspace
   

3. Geben Sie den Workspace-Pfad explizit an:

   polycrate run my-block install --workspace /path/to/workspace
   

Workspace-Verschlüsselung schlägt fehl¶

Problem: Verschlüsselung oder Entschlüsselung des Workspace schlägt fehl.

Lösungen:

1. Prüfen Sie den Verschlüsselungsstatus:

   polycrate workspace status
   

2. Stellen Sie sicher, dass Sie die richtige Passphrase verwenden

3. Prüfen Sie, ob verschlüsselte Dateien existieren:

   ls -la *.enc
   

4. Backup vor Verschlüsselung erstellen:

   cp workspace.poly workspace.poly.backup
   polycrate workspace encrypt
   

Snapshot-Fehler¶

Problem: Snapshot kann nicht generiert werden.

Lösungen:

1. Validieren Sie Ihre Workspace-Konfiguration:

   polycrate workspace inspect
   

2. Prüfen Sie auf Syntax-Fehler in workspace.poly:

   # Verwenden Sie einen YAML-Validator
   yamllint workspace.poly
   

3. Testen Sie den Snapshot isoliert:

   polycrate workspace snapshot
   

Block-Probleme¶

"Block not found"¶

Problem: Polycrate kann einen Block nicht finden.

Error: Block 'my-block' not found in workspace

Lösungen:

1. Listen Sie alle verfügbaren Blocks auf:

   polycrate block list
   

2. Prüfen Sie die Block-Directory:

   ls -la blocks/
   

3. Pullen Sie den Block aus der Registry:

   polycrate block pull my-block
   

4. Prüfen Sie die Block-Konfiguration:

   cat blocks/my-block/block.poly
   

Block-Validation schlägt fehl¶

Problem: Block-Validierung schlägt fehl.

Error: Block configuration validation failed

Lösungen:

1. Validieren Sie den Block:

   polycrate block validate my-block
   

2. Prüfen Sie die block.poly auf Syntax-Fehler:

   yamllint blocks/my-block/block.poly
   

3. Inspizieren Sie die Block-Konfiguration:

   polycrate block inspect my-block
   

Block Push/Pull schlägt fehl¶

Problem: Block kann nicht in die Registry gepusht oder von ihr gepullt werden.

Lösungen:

1. Authentifizieren Sie sich bei der Registry:

   docker login cargo.ayedo.cloud
   # oder für custom Registry:
   docker login my.registry.com
   

2. Prüfen Sie die Registry-URL:

   # Explizite Registry-URL angeben
   polycrate block pull my.registry.com/my-org/my-block
   

3. Prüfen Sie die Block-Version:

   # In block.poly
   cat blocks/my-block/block.poly | grep version
   

4. Prüfen Sie Netzwerk-Verbindung zur Registry:

   curl -I https://cargo.ayedo.cloud
   

Action-Probleme¶

"Action not found"¶

Problem: Action existiert nicht oder kann nicht gefunden werden.

Error: Action 'install' not found in block 'my-block'

Lösungen:

1. Listen Sie alle verfügbaren Actions auf:

   polycrate action list
   

2. Inspizieren Sie den Block:

   polycrate block inspect my-block
   

3. Prüfen Sie die Block-Konfiguration:

   cat blocks/my-block/block.poly
   

Action schlägt fehl¶

Problem: Action-Ausführung schlägt mit Fehler fehl.

Lösungen:

1. Erhöhen Sie den Log-Level:

   polycrate run my-block install --loglevel 2
   

2. Prüfen Sie die Logs:

   cat .logs/<latest-log-file>
   

3. Führen Sie die Action lokal aus (für Debugging):

   polycrate run my-block install --local
   

4. Inspizieren Sie die Action:

   polycrate action inspect my-block install
   

5. Testen Sie mit Snapshot (ohne Ausführung):

   polycrate run my-block install --snapshot
   

Ansible-Fehler¶

Problem: Ansible-Playbook schlägt fehl.

Lösungen:

1. Prüfen Sie die Ansible-Syntax:

   # Im Block-Verzeichnis
   ansible-playbook --syntax-check install.yml
   

2. Erhöhen Sie Ansible-Verbosity:

   polycrate run my-block install --loglevel 2
   

3. Prüfen Sie das Inventory:

   cat inventory.yml
   ansible-inventory -i inventory.yml --list
   

4. Testen Sie Ansible-Verbindung:

   ansible all -i inventory.yml -m ping
   

Workflow-Probleme¶

Workflow schlägt fehl¶

Problem: Workflow-Ausführung schlägt fehl.

Lösungen:

1. Listen Sie alle Workflows auf:

   polycrate workflow list
   

2. Inspizieren Sie den Workflow:

   polycrate workflow inspect my-workflow
   

3. Führen Sie Steps einzeln aus:

   # Führen Sie jeden Step einzeln aus, um den fehlerhaften Step zu finden
   polycrate run step-1-block step-1-action
   

4. Verwenden Sie allow_failure für optionale Steps:

   workflows:
     - name: my-workflow
       steps:
         - name: optional-step
           block: my-block
           action: optional-action
           allow_failure: true
   

SSH-Probleme¶

SSH-Verbindung schlägt fehl¶

Problem: SSH-Verbindung zu Remote-Host schlägt fehl.

Error: SSH connection failed

Lösungen:

1. Prüfen Sie SSH-Keys:

   ls -la id_rsa id_rsa.pub
   chmod 600 id_rsa
   chmod 644 id_rsa.pub
   

2. Testen Sie SSH-Verbindung manuell:

   ssh -i id_rsa user@host
   

3. Prüfen Sie das Inventory:

   cat inventory.yml
   

4. Verwenden Sie SSH-Passphrase ⚠️ Experimental:

   echo "my-passphrase" > ssh-passphrase.poly
   polycrate workspace encrypt
   polycrate run my-block install --ssh-use-passphrase
   

5. Prüfen Sie authorized_keys auf Remote-Host:

   cat ~/.ssh/authorized_keys
   

Performance-Probleme¶

Polycrate ist langsam¶

Problem: Polycrate-Ausführung dauert sehr lange.

Lösungen:

1. Überspringen Sie Image-Pull (wenn bereits vorhanden):

   polycrate run my-block install --pull false
   

2. Überspringen Sie Image-Build (wenn kein Custom Dockerfile.poly):

   polycrate run my-block install --build false
   

3. Führen Sie lokal aus (wenn möglich):

   polycrate run my-block install --local
   

4. Prüfen Sie Docker-Performance:

   docker stats
   

5. Erhöhen Sie Docker-Ressourcen (Docker Desktop):

6. Settings → Resources → Increase CPU/Memory

Container baut lange¶

Problem: Custom Container-Image braucht lange zum Bauen.

Lösungen:

1. Optimieren Sie Ihr Dockerfile.poly:

   # Dockerfile.poly
   FROM cargo.ayedo.cloud/library/polycrate:latest
   
   # Cache-freundliche Layer-Reihenfolge
   RUN apk add --no-cache tool1 tool2
   
   # Vermeiden Sie unnötige Pakete
   

2. Verwenden Sie Docker Build-Cache:

   # Docker Desktop Build-Cache aktivieren
   

3. Überspringen Sie Build wenn möglich:

   polycrate run my-block install --build false
   

Konfigurationsprobleme¶

Umgebungsvariablen werden nicht aufgelöst¶

Problem: Umgebungsvariablen in der Konfiguration werden nicht ersetzt.

config:
  api_key: ${API_KEY}  # Bleibt als ${API_KEY}

Lösungen:

1. Setzen Sie die Umgebungsvariable:

   export API_KEY="my-secret-key"
   polycrate run my-block install
   

2. Übergeben Sie sie als Flag:

   polycrate run my-block install -e API_KEY=my-secret-key
   

3. Verwenden Sie eine .env-Datei:

   # .env
   API_KEY=my-secret-key
   
   # Laden vor Ausführung
   set -a
   source .env
   set +a
   polycrate run my-block install
   

Merge-Konflikte in Konfiguration¶

Problem: Konfigurationen werden nicht korrekt zusammengeführt.

Lösungen:

1. Aktivieren Sie Merge-Debugging:

   polycrate run my-block install --merge-debug
   

2. Verwenden Sie Merge v2:

   polycrate run my-block install --merge-v2
   

3. Inspizieren Sie den finalen Snapshot:

   polycrate run my-block install --snapshot > snapshot.yml
   cat snapshot.yml
   

Registry-Probleme¶

"Registry authentication failed"¶

Problem: Authentifizierung bei der Registry schlägt fehl.

Lösungen:

1. Login via Docker:

   docker login cargo.ayedo.cloud
   Username: your-username
   Password: your-password
   

2. Prüfen Sie Docker-Config:

   cat ~/.docker/config.json
   

3. Verwenden Sie API-Key statt Passwort:

   docker login cargo.ayedo.cloud -u your-username -p your-api-key
   

"Rate limit exceeded"¶

Problem: Zu viele Requests zur Registry.

Lösungen:

1. Authentifizieren Sie sich (höhere Limits für authentifizierte User):

   docker login cargo.ayedo.cloud
   

2. Warten Sie und versuchen Sie es später erneut

3. Verwenden Sie einen Mirror/Cache

Häufige Fehlermeldungen¶

"permission denied"¶

• Prüfen Sie Datei-Berechtigungen: chmod 755 file
• Prüfen Sie Docker-Berechtigungen: sudo usermod -aG docker $USER
• Prüfen Sie SSH-Key-Berechtigungen: chmod 600 id_rsa

"no space left on device"¶

• Prüfen Sie Speicherplatz: df -h
• Bereinigen Sie Docker: docker system prune -a
• Bereinigen Sie Polycrate-Logs: rm -rf .logs/*
• Bereinigen Sie Artefakte: polycrate prune my-block

"port already in use"¶

• Prüfen Sie verwendete Ports: netstat -tuln | grep <port>
• Stoppen Sie konfligierende Container: docker ps und docker stop <container>
• Verwenden Sie anderen Port in der Konfiguration

"connection timeout"¶

• Prüfen Sie Netzwerk-Verbindung
• Prüfen Sie Firewall-Regeln
• Erhöhen Sie Timeout-Werte
• Prüfen Sie DNS-Auflösung: nslookup host

Debugging-Tipps¶

Erweiterte Logs¶

# Maximaler Log-Level
polycrate run my-block install --loglevel 2

# JSON-Format für maschinelle Verarbeitung
polycrate run my-block install --logformat json

# YAML-Format
polycrate run my-block install --logformat yaml

Interaktiver Modus¶

# Container bleibt offen für interaktive Befehle
polycrate run my-block install --interactive

Snapshot analysieren¶

# Snapshot generieren und analysieren
polycrate run my-block install --snapshot > snapshot.yml

# Prüfen auf spezifische Werte
cat snapshot.yml | grep "key_name"

# Mit yq filtern
yq eval '.blocks[].config' snapshot.yml

Container debuggen¶

# Shell im Container öffnen
docker run -it --rm \
  -v $(pwd):/workspace \
  cargo.ayedo.cloud/library/polycrate:latest \
  /bin/sh

# Im Container
cd /workspace
ls -la

Support¶

Wenn Sie das Problem nicht lösen können:

1. Dokumentation prüfen:
2. CLI-Referenz

3. Best Practices

4. Community fragen:

5. Discord Server

6. GitHub Discussions

7. Issue erstellen:

8. GitHub Issues
9. Fügen Sie Logs, Konfiguration und Reproduktionsschritte hinzu

Siehe auch¶

• CLI-Referenz
• Best Practices
• Installation
• Der Polycrate Container