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: playbooks/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
    alias:                     # Optional: Alternative Namen
      - setup
      - deploy
    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 (Pattern: `^[a-zA-Z]+([-/]?[a-zA-Z0-9]+)+$`)
`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)
`alias`	list	❌	Alternative Namen für die Action
`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: playbooks/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"

Kein Templating in Scripts

Scripts haben keinen Zugriff auf Workspace-Informationen.

Kein Inline-Templating ({{ workspace... }}, {{ block.config... }})
Keine automatische Integration mit Workspace/Block-Konfiguration
Alle Logik zur Verarbeitung von Konfigurationswerten muss selbst implementiert werden
Konfiguration nur über Umgebungsvariablen ($CONFIG_*) möglich, die vom Entwickler selbst ausgewertet werden müssen

Verwenden Sie stattdessen playbook: - Ansible-Playbooks erhalten automatisch Zugriff auf:

{{ workspace.name }}, {{ workspace.config }}, {{ workspace.secrets }}
{{ block.name }}, {{ block.config }}, {{ block.artifacts }}
{{ action.name }}, {{ transaction.id }}
Alle weiteren Workspace-Daten via Jinja2-Templating

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: playbooks/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

Prompt in Workflows

Prompts können auch auf Workflow-Step-Ebene definiert werden. Wenn sowohl Action als auch Step einen Prompt haben, muss der Benutzer zweimal bestätigen.

Interactive Mode¶

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

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

Script-Ausnahme für Interactive

Bei interaktiven Shell-Sessions ist script: akzeptabel, da keine Konfigurationswerte benötigt werden:

- name: shell
  interactive: true
  script:
    - /bin/bash

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

Use Cases:

Debug-Shells
Interaktive Editoren
Passwort-Prompts in Playbooks

Alias¶

Alternative Namen für eine Action:

actions:
  - name: install
    alias:
      - setup
      - deploy
      - i
    playbook: playbooks/install.yml

Alle diese Aufrufe sind äquivalent:

polycrate run my-block install
polycrate run my-block setup
polycrate run my-block deploy
polycrate run my-block i

Labels¶

Metadaten für Kategorisierung und Filterung:

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

  - name: destroy
    labels:
      category: cleanup
      risk: high
      requires-confirmation: "true"
    playbook: playbooks/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: playbooks/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"
    alias: [deploy, i]
    playbook: playbooks/install.yml
    labels:
      category: deployment

  - name: uninstall
    description: "Entfernt die Anwendung aus dem Cluster"
    alias: [remove, rm]
    playbook: playbooks/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: playbooks/status.yml

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

  - name: logs
    description: "Zeigt die Logs der Anwendung"
    config:
      tail: 100
      follow: false
    playbook: playbooks/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

Naming Rules¶

Action-Namen müssen dem Pattern entsprechen:

^[a-zA-Z]+([-/]?[a-zA-Z0-9]+)+$

Gültig:

install
do-backup
run-migrations
v2-deploy

Ungültig:

_install (beginnt mit Unterstrich)
123-test (beginnt mit Zahl)
install--twice (doppelter Bindestrich)

Datenpersistenz¶

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

Workspace-Directory: Änderungen in /workspace (gemountet)
Artefakte: Empfohlener Weg für persistente Daten

# Beispiel: Daten als Artifact speichern
- name: Generate state in Ansible
  copy:
    content: "{{ state_data | to_nice_yaml }}"
    dest: "{{ block.artifacts.local_path }}/state.yml"

Zusammenhang mit anderen Konzepten¶

Blocks: Actions sind Teil von Blocks
Workflows: Orchestrieren mehrere Actions
Artefakte: Persistenz zwischen Action-Runs
Ansible: Playbook-Integration