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 - Auditing: Alle Snapshots werden mit Transactions geloggt - 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[Environment-Variablen]
    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]
    JSON --> EnvVars[Container Environment]

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

    Exec --> Log[Transaction-Log mit Snapshot]

    style Snapshot fill:#e1f5ff
    style JSON fill:#ffe1e1
    style Exec fill:#f0ffe1
    style Log fill:#fff4e1

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 - Event-Handler-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¶

Das Ansible-Inventory (falls vorhanden): - Hosts mit Verbindungsinformationen - Gruppen - Variablen

4. Kubeconfig¶

Die Kubernetes-Konfiguration (falls vorhanden): - Cluster-Informationen - Contexts - User-Credentials

5. Metadaten¶

• 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
    logs_root: .logs
    blocks_root: blocks
    artifacts_root: artifacts
    ssh_private_key: id_rsa
    ssh_public_key: id_rsa.pub

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: playbooks/install.yml

inventory:
  all:
    hosts:
      db1:
        ansible_host: 192.168.1.10
        ansible_user: ubuntu

kubeconfig:
  apiVersion: v1
  kind: Config
  clusters:
    - name: prod-cluster
      cluster:
        server: https://k8s.example.com
        certificate-authority-data: ...
  contexts:
    - name: prod
      context:
        cluster: prod-cluster
        user: admin

transaction:
  id: 550e8400-e29b-41d4-a716-446655440000
  timestamp: "2025-01-30T10:30:00Z"
  user:
    name: John Doe
    email: john@example.com
  command: "polycrate run my-postgres install"
  git:
    commit_sha: abc123def456
    branch: main

Snapshot nutzen¶

In Bash-Scripts¶

In Script-Actions können Sie Snapshot-Werte per Template-Syntax nutzen:

actions:
  - name: deploy
    script:
      - echo "Deploying {{ .block.name }} to {{ .block.config.namespace }}"
      - kubectl apply -n {{ .block.config.namespace }} -f manifest.yml
      - echo "Database: {{ .block.config.app.auth.username }}"

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

Als Environment-Variablen¶

Im Container sind Snapshot-Daten als Environment-Variablen verfügbar:

# In einem Script
echo "Workspace: $WORKSPACE_NAME"
echo "Block: $BLOCK_NAME"
echo "Namespace: $BLOCK_CONFIG_NAMESPACE"
echo "Snapshot-Pfad: $POLYCRATE_WORKSPACE_SNAPSHOT_YAML"

Die Environment-Variable POLYCRATE_WORKSPACE_SNAPSHOT_YAML enthält den Pfad zum Snapshot-File.

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

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

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

action:
  name: install
  playbook: playbooks/install.yml

transaction:
  id: 550e8400-e29b-41d4-a716-446655440000
  timestamp: "2025-01-30T10:30:00Z"

Snapshot in Transaction-Logs¶

Wenn Transaction-Logging aktiviert ist, wird jeder Snapshot zusammen mit dem Transaction-Log persistiert:

.logs/2025-01-30/550e8400-e29b-41d4-a716-446655440000.yml

Dieser Log enthält: - Den vollständigen Snapshot - Die Ausgabe der Action (stdout/stderr) - Den Exit-Code - Timestamps (Start/End)

So können Sie später exakt nachvollziehen, mit welchem Zustand eine Action ausgeführt wurde.

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?
# - Ist das Inventory vollständig?
# - Ist der Kubeconfig richtig?

2. Template-Variablen verwenden¶

Nutzen Sie Snapshot-Variablen statt Hardcoding:

# ✅ Gut: Snapshot-Variablen
script:
  - kubectl apply -n {{ .block.config.namespace }} -f app.yml

# ❌ Schlecht: Hardcoded
script:
  - kubectl apply -n production -f app.yml

3. Sensible Daten maskieren¶

Polycrate maskiert automatisch Secrets in Logs, aber seien Sie vorsichtig beim Teilen von Snapshots:

# Snapshot ohne Secrets
polycrate run my-block install --snapshot | grep -v password

4. Snapshots für Auditing¶

Transaction-Logs mit Snapshots sind perfekt für Compliance und Auditing:

# Alle Actions der letzten Woche anzeigen
find .logs/ -name "*.yml" -mtime -7

# Snapshot einer spezifischen Transaction anzeigen
cat .logs/2025-01-30/550e8400-e29b-41d4-a716-446655440000.yml

Zusammenhang mit anderen Konzepten¶

• Transactions: Jede Transaction erstellt einen Snapshot
• Vererbung: Der Snapshot enthält die aufgelöste Block-Konfiguration nach Vererbung
• Container: Der Snapshot wird in den Container gemountet
• Events: Events enthalten den Snapshot für externe Systeme
• Artefakte: Artifacts (Inventory, Kubeconfig) sind Teil des Snapshots