SSH¶

Polycrate bietet native SSH-Integration für schnellen Zugriff auf Hosts aus dem Ansible-Inventory. Diese Integration ermöglicht direkten SSH-Zugriff ohne manuelle Konfiguration.

Voraussetzungen¶

Die SSH-Integration funktioniert nur, wenn ein inventory.yml im Workspace vorhanden ist. Polycrate ermittelt automatisch:

• SSH-Host-Adresse (ansible_host)
• SSH-Port (ansible_ssh_port, default: 22)
• SSH-User (ansible_user)
• SSH-Schlüssel aus dem Workspace

Verfügbare Hosts anzeigen¶

Um alle verfügbaren Hosts im Workspace anzuzeigen:

polycrate ssh list

Ausgabe:

Available SSH hosts:
- web-1 (192.168.1.10)
- web-2 (192.168.1.11)
- db-1 (192.168.1.20)

SSH-Verbindung herstellen¶

Mit Hostname¶

Um eine SSH-Verbindung zu einem bestimmten Host herzustellen:

polycrate ssh <hostname>

Beispiel:

polycrate ssh web-1

Interaktive Host-Auswahl¶

Wenn kein Hostname angegeben wird, zeigt Polycrate eine interaktive Auswahl aller verfügbaren Hosts:

polycrate ssh

Ausgabe:

? Select a host to connect to:
  👉 web-1 (ubuntu@192.168.1.10:22)
     web-2 (ubuntu@192.168.1.11:22)
     db-1 (postgres@192.168.1.20:2222)

--------- Host Details ----------
Name:   web-1
Host:   192.168.1.10
User:   ubuntu

• Mit Pfeiltasten durch die Hosts navigieren
• Mit Enter die Verbindung herstellen
• Mit Ctrl+C abbrechen

Tab-Completion¶

Polycrate unterstützt Shell-Autocompletion für den SSH-Befehl. Mit Tab werden alle verfügbaren Hosts angezeigt:

polycrate ssh <TAB>
# Zeigt: web-1  web-2  db-1

Siehe Shell-Autocompletion für die Einrichtung.

Polycrate: 1. Liest das Ansible-Inventory 2. Ermittelt automatisch die Verbindungsinformationen 3. Nutzt den SSH-Schlüssel aus dem Workspace (id_rsa) 4. Stellt die direkte SSH-Verbindung her

Beispiel-Workflow¶

1. Inventory erstellen¶

Polycrate unterstützt beide gängigen Ansible-Inventory-Muster:

Muster 1: Variablen pro Host

# inventory.yml im Workspace
all:
  hosts:
    web-1:
      ansible_host: 192.168.1.10
      ansible_user: ubuntu
      ansible_ssh_port: 22

    web-2:
      ansible_host: 192.168.1.11
      ansible_user: ubuntu

    db-1:
      ansible_host: 192.168.1.20
      ansible_user: postgres
      ansible_ssh_port: 2222

Muster 2: Variablen in all.vars (ab 0.30.4)

Gemeinsame Variablen können zentral unter all.vars definiert und an alle Hosts vererbt werden – Ansible-konform. Host-Level-Werte überschreiben die Gruppenvariablen.

# inventory.yml – Variablen in all.vars
all:
  vars:
    ansible_user: sysops
    ansible_ssh_port: 4422
  hosts:
    cr1:
      ansible_host: 10.10.10.101
    cr2:
      ansible_host: 10.10.10.102
# → polycrate ssh cr1 nutzt sysops@10.10.10.101:4422

2. Verfügbare Hosts anzeigen¶

polycrate ssh list

3. Verbindung herstellen¶

polycrate ssh web-1

Verwendung¶

Direkter Zugriff für Debugging¶

# SSH zu Host
polycrate ssh web-1

# Befehl auf Host ausführen (interaktive Sitzung)
polycrate ssh web-1
# Dann im SSH-Terminal:
$ sudo systemctl status nginx
$ tail -f /var/log/application.log

Nach Ansible-Deployment¶

# 1. Server mit Ansible konfigurieren
polycrate run webservers configure

# 2. SSH für manuelle Checks
polycrate ssh web-1

# 3. Logs prüfen, Service neu starten, etc.

Shell-Autocompletion¶

Polycrate unterstützt Tab-Completion für alle Commands, einschließlich dynamischer Host-Completion für polycrate ssh.

Zsh¶

# Einmalig aktivieren
source <(polycrate completion zsh)

# Permanent in ~/.zshrc
echo 'source <(polycrate completion zsh)' >> ~/.zshrc

Bash¶

# Einmalig aktivieren
source <(polycrate completion bash)

# Permanent in ~/.bashrc
echo 'source <(polycrate completion bash)' >> ~/.bashrc

Fish¶

polycrate completion fish > ~/.config/fish/completions/polycrate.fish

Nach der Aktivierung:

polycrate ssh <TAB>
# Zeigt alle verfügbaren Hosts aus dem Inventory

polycrate ssh web<TAB>
# Vervollständigt zu passenden Hosts (z.B. web-1, web-2)

SSH Passphrase Support¶

Polycrate unterstützt SSH-Keys mit Passphrase über einen integrierten ssh-agent.

Aktivierung¶

# Beim Workspace-Init
polycrate --ssh-use-passphrase workspace init

# Bei Action-Ausführung
polycrate --ssh-use-passphrase run my-block deploy

# Für alle Commands
polycrate --ssh-use-passphrase ssh web-1

Passphrase-Quellen (Priorität)¶

ssh-passphrase.poly:

# Passphrase in Datei speichern (optional)
echo "meine-passphrase" > ssh-passphrase.poly

# Berechtigungen setzen
chmod 600 ssh-passphrase.poly

Funktionsweise¶

1. ssh-agent Start: Polycrate startet automatisch einen ssh-agent
2. Key laden: Der SSH-Key wird mit der Passphrase geladen
3. Socket-Mount: Der Agent-Socket wird in Docker-Container gemountet
4. Ansible-Integration: Ansible nutzt automatisch den Agent

graph LR
    Polycrate[Polycrate CLI] -->|1. Agent starten| Agent[ssh-agent]
    Polycrate -->|2. Key laden| Agent
    Agent -->|3. Socket| Container[Docker Container]
    Container -->|4. SSH-Auth| Ansible[Ansible]
    Ansible -->|5. Verbinden| Host[Remote Host]

Troubleshooting¶

"Permission denied (publickey)":

# Prüfen ob Agent läuft
ssh-add -l

# Key manuell zum Agent hinzufügen
ssh-add artifacts/secrets/id_rsa

# Dann erneut versuchen
polycrate --ssh-use-passphrase run my-block deploy

"Agent refused connection":

# Agent-Socket prüfen
echo $SSH_AUTH_SOCK

# Polycrate mit neuem Agent starten
polycrate --ssh-use-passphrase run my-block deploy

SSH-Schlüssel-Quelle (sshkeysource)¶

Standardmäßig nutzt Polycrate den Workspace-Key (artifacts/secrets/id_rsa). Mit config.sshkeysource: user können Sie stattdessen Ihren persönlichen SSH-Key verwenden – ideal für einheitliche User-Authentifizierung und Nutzung des ssh-agent.

Aktivierung¶

# workspace.poly
config:
  sshkeysource: user   # workspace (Standard) | user

Verhalten bei user¶

User-Key-Pfad konfigurieren¶

Der Pfad zum persönlichen Key wird in ~/.polycrate/polycrate.yml festgelegt (nicht im Workspace, da nutzerspezifisch):

# ~/.polycrate/polycrate.yml
ssh:
  user_key_path: "~/.ssh/work_ed25519"   # optional; Standard: ~/.ssh/id_rsa
  user_key_path_by_workspace:            # optional; workspace.name → Key-Pfad
    laser24: "~/.ssh/laser_ed25519"
    archenemy: "~/.ssh/ayedo_work"

→ CLI-Konfiguration

Ansible become/sudo Passwort¶

Für Ansible-Tasks, die become: yes (sudo) verwenden, können Sie vor der Action-Ausführung interaktiv das Passwort abfragen lassen:

polycrate run my-block install --ask-become-pass
# oder kurz:
polycrate run my-block install -K

Der Prompt erscheint vor dem Container-Start. Das Passwort wird als ANSIBLE_BECOME_PASSWORD an Ansible übergeben und nicht im Snapshot oder in Logs gespeichert.

Hinweise¶

• SSH-Schlüssel: Polycrate nutzt standardmäßig id_rsa aus dem Workspace-Root oder artifacts/secrets/id_rsa; bei sshkeysource: user den persönlichen Key
• Port: Standard ist Port 22, kann aber per ansible_ssh_port im Inventory überschrieben werden
• User: Wird aus ansible_user im Inventory gelesen (Standard: root)