Actions

Actions

Actions sind die ausführbaren Einheiten eines Blocks. Sie definieren, was ein Block tatsächlich tun kann – z.B. install, uninstall, status oder backup.

Action-Schema

Eine Action wird in der block.poly unter der actions: Liste definiert:

# block.poly
actions:
  - name: install              # Pflicht: Eindeutiger Name
    description: "Installiert die Anwendung"  # Optional: Beschreibung
    playbook: install.yml           # Entweder playbook ODER script
    # script:                  # Alternative zu playbook
    #   - echo "Hello"
    prompt:                    # Optional: Benutzerbestätigung
      message: "Möchten Sie die Installation starten?"
    interactive: false         # Optional: TTY-Modus
    labels:                    # Optional: Metadaten
      category: deployment
      risk: low
    config:                    # Optional: Action-spezifische Config
      timeout: 300

Felder im Detail

Feld Typ Pflicht Beschreibung
name string ✅ Eindeutiger Identifier; die CLI validiert Action-Namen als Slug (siehe Namenskonventionen)
description string ❌ Menschenlesbare Beschreibung der Action
playbook string ⚠️ Pfad zum Ansible-Playbook (relativ zur block.poly)
script list ⚠️ Liste von Shell-Befehlen
prompt object ❌ Benutzerbestätigung vor Ausführung
interactive bool ❌ TTY-Modus für interaktive Befehle (default: false)
labels map ❌ Key-Value-Paare für Metadaten
config map ❌ Action-spezifische Konfiguration

⚠️ = playbook und script schließen sich gegenseitig aus. Eines von beiden ist erforderlich.

Playbook vs Script

Playbook (empfohlen)

Ansible-Playbooks bieten die beste Integration mit Polycrate:

actions:
  - name: install
    playbook: install.yml

Vorteile:

  • Zugriff auf workspace, block, action Variablen via Jinja2
  • Idempotente Ausführung
  • Strukturierte Fehlerbehandlung
  • Umfangreiche Module für Cloud, K8s, etc.

→ Ansible-Integration

Script (nicht empfohlen)

Für triviale Befehle ohne Variablenzugriff:

actions:
  - name: status
    script:
      - kubectl get pods
      - echo "Status check complete"

Einschränkungen:

  • Keine strukturierte Fehlerbehandlung
  • Keine idempotente Ausführung
  • Nur für Befehle ohne Konfigurationsabhängigkeit geeignet

Prompt (Benutzerbestätigung)

Actions können eine Bestätigung vom Benutzer anfordern:

actions:
  - name: destroy
    playbook: destroy.yml
    prompt:
      message: "⚠️ Diese Aktion löscht alle Ressourcen unwiderruflich. Fortfahren?"

Verhalten:

  • Polycrate zeigt die Nachricht und wartet auf y/n
  • Bei n wird die Action abgebrochen
  • Bei y wird die Action ausgeführt

Prompt überspringen

# Einzelne Action automatisch bestätigen
polycrate run my-block destroy --force

# Global für alle Actions
polycrate --force run my-block destroy

Interactive Mode

Für Actions die TTY-Interaktion benötigen (z.B. Passwort-Eingaben, vim):

actions:
  - name: shell
    interactive: true
    playbook: shell.yml

actions:
  - name: edit-config
    interactive: true
    playbook: edit-config.yml

Use Cases:

  • Debug-Shells
  • Interaktive Editoren
  • Passwort-Prompts in Playbooks

Labels

Metadaten für Kategorisierung und Filterung:

actions:
  - name: backup
    labels:
      category: maintenance
      risk: low
      duration: long
    playbook: backup.yml

  - name: destroy
    labels:
      category: cleanup
      risk: high
      requires-confirmation: "true"
    playbook: destroy.yml

Labels können in Workflows oder externen Tools zur Filterung verwendet werden.

Action-spezifische Config

Actions können eigene Konfigurationsparameter haben:

actions:
  - name: backup
    config:
      retention_days: 30
      compress: true
    playbook: backup.yml

Im Playbook verfügbar als {{ action.config.retention_days }}.

Vollständiges Beispiel

# blocks/my-app/block.poly
name: my-app
kind: k8sapp
version: 1.0.0

config:
  namespace: production
  replicas: 3

actions:
  - name: install
    description: "Installiert die Anwendung im Kubernetes-Cluster"
    playbook: install.yml
    labels:
      category: deployment

  - name: uninstall
    description: "Entfernt die Anwendung aus dem Cluster"
    playbook: uninstall.yml
    prompt:
      message: "Soll die Anwendung wirklich deinstalliert werden?"
    labels:
      category: cleanup
      risk: medium

  - name: status
    description: "Zeigt den aktuellen Status der Anwendung"
    playbook: status.yml

  - name: shell
    description: "Öffnet eine Shell im ersten Pod"
    interactive: true
    playbook: shell.yml

  - name: logs
    description: "Zeigt die Logs der Anwendung"
    config:
      tail: 100
      follow: false
    playbook: logs.yml

Actions ausführen

# Standard
polycrate run my-block install

# Mit Workspace-Angabe
polycrate run my-block install -w /path/to/workspace

# Mit Force (überspringt Prompts)
polycrate run my-block destroy --force

# Mit erhöhtem Log-Level
polycrate run my-block install --loglevel 2

# Interaktiv
polycrate run my-block shell

Runtime Config Overrides (--set)

Mit dem --set Flag können action.config-Werte zur Laufzeit überschrieben werden, ohne workspace.poly oder block.poly zu verändern. Die Syntax folgt dem Helm-Standard.

# Einfacher Wert
polycrate run my-block migrate --set database.host=prod-db.internal

# Mehrere Overrides
polycrate run my-block deploy \
  --set replicas=5 \
  --set namespace=production \
  --set image.tag=v2.1.0

# Array-Werte
polycrate run my-block backup \
  --set targets[0]=cluster-a \
  --set targets[1]=cluster-b

Priorität (von niedrig zu hoch)

  1. block.poly – Defaults in der Block-Definition
  2. workspace.poly – Partielle Overrides im Workspace
  3. --set Flag – Runtime-Overrides bei Ausführung (höchste Priorität)

Hinweise

  • Alle Werte sind Strings (wie bei Helm): --set replicas=3 → "3" im Playbook. Typisierung in Ansible via | int, | bool etc.
  • Maps werden deep-merged: --set db.host=x überschreibt nur db.host, andere Schlüssel unter db bleiben erhalten.
  • Listen werden vollständig ersetzt: --set items[0]=x ersetzt die gesamte Liste durch ["x"].
  • Punkte im Key escapen: --set 'key\.name=value'
  • --set schreibt ausschließlich in action.config – block.config wird nicht beeinflusst.
# Playbook-Zugriff
- name: Deploy
  ansible.builtin.debug:
    msg: "Host: {{ action.config.database.host }}, Replicas: {{ action.config.replicas | int }}"

Namensregeln

Action-Namen folgen in der CLI dem Slug-Muster (Kleinbuchstaben, Ziffern, einfache Bindestriche). Details, Regex und Beispiele: Namenskonventionen – Slug.

Datenpersistenz

Daten werden zwischen Action-Runs nicht automatisch persistiert, außer:

  1. Workspace-Directory: Änderungen in /workspace (gemountet)
  2. Artefakte: Empfohlener Weg für persistente Daten
# Beispiel: Daten als Artifact speichern
# block.artifacts.path wählt automatisch local_path oder container_path (je nach --local / Container)
- name: Generate state in Ansible
  copy:
    content: "{{ state_data | to_nice_yaml }}"
    dest: "{{ block.artifacts.path }}/state.yml"

Zusammenhang mit anderen Konzepten