Snapshot¶

Was ist ein Snapshot?¶

Immer wenn Sie eine Action mit Polycrate ausführen, wird ein Snapshot des aktuellen Workspace-Zustands erstellt. Ein Snapshot ist eine vollständige Momentaufnahme aller relevanten Konfigurationen und Daten, die für die Action-Ausführung benötigt werden.

Der Snapshot dient mehreren Zwecken:

• Reproduzierbarkeit: Jede Action kann exakt mit demselben Zustand reproduziert werden
• Template-Injection: Scripts und Playbooks können auf Snapshot-Daten zugreifen
• Debugging: Mit --snapshot kann der Zustand ohne Ausführung inspiziert werden

Snapshot-Mechanismus¶

graph TB
    Start[Action-Ausführung startet] --> Load[Lade Workspace]
    Load --> Resolve[Resolve Blocks mit Vererbung]
    Resolve --> Snapshot[Erstelle Snapshot]

    Snapshot --> WS[Workspace-Config]
    Snapshot --> Block[Block-Config aufgelöst]
    Snapshot --> Inv[Inventory]
    Snapshot --> Kube[Kubeconfig]
    Snapshot --> Env[Runtime-Env inkl. Snapshot-Dateipfad]
    Snapshot --> Meta[Metadaten Transaction, User]

    WS --> JSON[snapshot.json/yaml]
    Block --> JSON
    Inv --> JSON
    Kube --> JSON
    Env --> JSON
    Meta --> JSON

    JSON --> Template[Template-Injection in Scripts]
    JSON --> AnsibleVars[Ansible Extra-Vars]

    Template --> Exec[Action-Ausführung]
    AnsibleVars --> Exec
    Env --> Exec

    Exec --> Persist[Snapshot-Datei temporär, Mount im Container]

Was enthält ein Snapshot?¶

Ein Snapshot enthält folgende Daten:

1. Workspace-Konfiguration¶

Die komplette Workspace-Konfiguration aus workspace.poly:

• Name, Beschreibung, Labels
• Container-Image-Konfiguration
• SSH-Konfiguration
• Sync-Optionen (Git)

2. Block-Konfiguration (aufgelöst)¶

Die vollständig aufgelöste Block-Konfiguration nach Anwendung der Vererbung:

• Alle geerbten und überschriebenen Werte
• Chart-Konfiguration (bei K8s-Blocks)
• Dependencies
• Actions-Definitionen

3. Ansible-Inventory¶

Im Snapshot steht nicht der vollständige Inventory-Inhalt, sondern die aufgelösten Pfade zur Inventory-Datei (lokal und im Container), sofern ein Inventory konfiguriert ist. Die eigentliche Inventory-Datei liegt unter dem konfigurierten Pfad im Workspace bzw. in den Artefakten.

4. Kubeconfig¶

Entsprechend enthält der Snapshot nicht die vollständige Kubeconfig (keine Cluster-Contexts oder Credentials eingebettet), sondern nur die Pfade zur Kubeconfig-Datei. Der Inhalt wird von Tools wie kubectl oder Ansible aus der gemounteten Datei gelesen.

5. Metadaten¶

Bei Ausführung über die Polycrate API oder verbundene Dienste stehen u. a. folgende Angaben zur Verfügung (nicht zwingend als Felder in der Snapshot-YAML-Datei):

• Transaction-ID: Eindeutige UUID der Operation
• User: Username und E-Mail
• Timestamp: Zeitpunkt der Snapshot-Erstellung
• Command: Ausgeführter Polycrate-Befehl
• Git-Commit: Aktueller Git-Commit-SHA (falls Git-Repo)

Snapshot-Struktur (Beispiel)¶

workspace:
  name: my-workspace
  config:
    image:
      reference: ghcr.io/polycrate-hub/workspace
      version: latest
    blocks_root: blocks
    artifacts_root: artifacts
    ssh_private_key: id_rsa
    ssh_public_key: id_rsa.pub

  inventory:
    path: artifacts/inventory/hosts.ini
    filename: hosts.ini
    localpath: /home/user/my-workspace/artifacts/inventory/hosts.ini
    containerpath: /workspace/artifacts/inventory/hosts.ini

  kubeconfig:
    path: artifacts/kubeconfig/config
    filename: config
    localpath: /home/user/my-workspace/artifacts/kubeconfig/config
    containerpath: /workspace/artifacts/kubeconfig/config

block:
  name: my-postgres
  kind: k8sapp
  type: db
  flavor: postgresql
  implementation: cnpg
  version: 1.0.0
  from: postgres-base  # Elternblock

  config:
    namespace: production
    chart:
      name: postgresql
      version: 12.0.0
      repo:
        name: bitnami
        url: https://charts.bitnami.com/bitnami

    app:
      auth:
        username: postgres
        password: secretpassword
      persistence:
        enabled: true
        size: 50Gi
        storageClass: standard
      replicas: 2

action:
  name: install
  description: Install PostgreSQL
  playbook: install.yml

env:
  POLYCRATE_WORKSPACE: /workspace
  POLYCRATE_WORKSPACE_SNAPSHOT_YAML: /tmp/550e8400-abc-workspace-snapshot.yml
  # ... weitere Laufzeit-Variablen von Polycrate

mounts:
  /tmp/550e8400-abc-workspace-snapshot.yml: /tmp/550e8400-abc-workspace-snapshot.yml

Hinweis: Zusätzliche Metadaten (z. B. zu einer API-Transaction) können außerhalb dieser Snapshot-Datei geführt werden; die serialisierte WorkspaceSnapshot-Struktur enthält vor allem workspace, block, action, env und mounts.

Snapshot nutzen¶

In Ansible-Playbooks¶

Der Snapshot wird automatisch als Extra-Vars an Ansible übergeben:

---
- name: Install Application
  hosts: localhost
  connection: local

  tasks:
    - name: Debug Snapshot-Variablen
      debug:
        msg: |
          Workspace: {{ workspace.name }}
          Block: {{ block.name }}
          Action: {{ action.name }}
          Namespace: {{ block.config.namespace }}
          Transaction ID: {{ transaction.id }}

    - name: Deploy mit Helm
      kubernetes.core.helm:
        name: "{{ block.name }}"
        namespace: "{{ block.config.namespace }}"
        chart_ref: "{{ block.config.chart.repo.name }}/{{ block.config.chart.name }}"
        values: "{{ block.config.app }}"

Polycrate ruft Ansible so auf:

ansible-playbook -e '@/path/to/snapshot.json' playbook.yml

Während der Ausführung setzt Polycrate u. a. POLYCRATE_WORKSPACE_SNAPSHOT_YAML auf den Pfad der serialisierten Snapshot-Datei (und bindet diese Datei in den Container ein). Das ersetzt nicht den Zugriff auf workspace, block und action über Ansible Extra-Vars; einzelne Snapshot-Felder stehen nicht als generische WORKSPACE_*-Variablen in der Umgebung.

Snapshot inspizieren¶

Mit --snapshot Flag¶

Sie können den Snapshot ausgeben ohne die Action auszuführen:

# YAML-Format (default)
polycrate run my-block install --snapshot

# JSON-Format
polycrate run my-block install --snapshot -o json

# In Datei speichern
polycrate run my-block install --snapshot > snapshot.yml

Beispiel-Output¶

polycrate run my-postgres install --snapshot

Auszug (gekürzt; vollständige Ausgabe enthält u. a. workspace mit inventory/kubeconfig-Pfaden, env, mounts):

workspace:
  name: my-workspace
  config:
    blocks_root: blocks
    artifacts_root: artifacts

block:
  name: my-postgres
  kind: k8sapp
  config:
    namespace: production

action:
  name: install
  playbook: install.yml

Snapshot und Protokollierung¶

Workspace-weite Verzeichnisse wie .logs/ für Transaction-Dumps werden von Polycrate nicht mehr standardmäßig befüllt. Für Reproduzierbarkeit und Nachvollziehbarkeit nutzen Sie --snapshot (lokale Ausgabe), die Polycrate API (Action Runs, Audit) oder Ihre CI-/GitOps-Prozesse.

Best Practices¶

1. Snapshot für Debugging nutzen¶

Wenn eine Action fehlschlägt, inspizieren Sie den Snapshot:

# Snapshot anzeigen
polycrate run my-block install --snapshot

# Prüfen Sie:
# - Sind alle Config-Werte korrekt?
# - Zeigen workspace.inventory.* und workspace.kubeconfig.* auf die erwarteten Dateien?
# - Sind Inventory- und Kubeconfig-Dateien am referenzierten Pfad vorhanden und gültig?

2. Template-Variablen verwenden¶

Nutzen Sie Snapshot-Variablen statt Hardcoding:

# ✅ Gut: Dynamische Variablen im Playbook
# deploy.yml
- name: Deploy application
  hosts: localhost
  tasks:
    - name: Apply manifest
      kubernetes.core.k8s:
        state: present
        namespace: "{{ block.config.namespace }}"
        src: app.yml

# ❌ Schlecht: Hardcoded Values
# Namespace sollte aus block.config kommen, nicht hardcoded sein

3. Auditing und Nachvollziehbarkeit¶

Für prüfbare Ausführungen (wer hat wann was mit welchem Zustand ausgeführt) nutzen Sie die Polycrate API (Action Runs, Audit-Log) oder exportieren Sie Snapshots gezielt mit --snapshot und versionieren die Ausgabe in Ihrer Pipeline – nicht über ein veraltetes .logs/-Verzeichnis im Workspace.

Zusammenhang mit anderen Konzepten¶

• Vererbung: Der Snapshot enthält die aufgelöste Block-Konfiguration nach Vererbung
• Container: Der Snapshot wird in den Container gemountet
• Artefakte: Inventory und Kubeconfig liegen als Dateien im Workspace; der Snapshot verweist darauf per Pfad, nicht als eingebetteter Inhalt