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¶

⚠️ = 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

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

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¶

• Namenskonventionen: Slug-Regeln für name
• Blocks: Actions sind Teil von Blocks
• Workflows: Orchestrieren mehrere Actions
• Artefakte: Persistenz zwischen Action-Runs
• Ansible: Playbook-Integration