🏭 Workflows¶

Polycrate unterstützt Workflows, d.h. die geordnete Ausführung von Blockaktionen. Ein Workflow orchestriert mehrere Block-Actions in einer definierten Reihenfolge und ermöglicht so komplexe Deployment- und Orchestrierungs-Szenarien.

Workflow-Konzept¶

graph LR
    WF[Workflow] --> S1[Step 1]
    WF --> S2[Step 2]
    WF --> S3[Step 3]

    S1 --> B1A[Block-1: Action-A]
    S2 --> B2A[Block-2: Action-A]
    S3 --> B1B[Block-1: Action-B]

    B1A --> TX1[Transaction 1]
    B2A --> TX2[Transaction 2]
    B1B --> TX3[Transaction 3]

    style WF fill:#e1f5ff
    style TX1 fill:#e1ffe1
    style TX2 fill:#e1ffe1
    style TX3 fill:#e1ffe1

Wichtige Eigenschaften: - Workflows werden in der workspace.poly definiert - Jeder Step führt eine Block-Action aus - Steps werden sequenziell ausgeführt - Jeder Step erzeugt eine eigene Transaction - Workflows können Prompts für Bestätigung enthalten - Fehlgeschlagene Steps können mit allow_failure toleriert werden

workspace.poly¶

name: workflow-workspace

blocks:
  - name: block-1
    actions:
      - name: action-1
        prompt: 
          message: "Do you really want to run this action?"
        script:
          - echo "block 1 action 1"
  - name: block-2
    actions:
      - name: action-1
        script:
          - echo "block 2 action 1"
workflows:
  - name: workflow-1
    prompt: 
          message: "Do you really want to run this workflow?"
    allow_failure: true
    steps:
      - name: block-1-action-1
        block: block-1
        action: action-1
      - name: block-2-action-1
        block: block-2
        action: action-1
        prompt: 
          message: "Do you really want to run this step?"

Sie können diesen Workflow mit

polycrate workflows run workflow-1

(oder kurz polycrate run workflow-1) ausführen.

Workflow-Ausführung¶

Wenn Sie einen Workflow ausführen, läuft folgender Ablauf ab:

sequenceDiagram
    participant User
    participant CLI
    participant Step1
    participant Step2
    participant Step3

    User->>CLI: polycrate workflows run workflow-1
    CLI->>CLI: Lade Workflow-Definition
    CLI->>CLI: Validiere Steps

    alt Workflow hat Prompt
        CLI->>User: Prompt: "Run workflow?"
        User->>CLI: Bestätigen
    end

    CLI->>Step1: Execute block-1 action-1

    alt Step hat Prompt
        Step1->>User: Prompt: "Run step?"
        User->>Step1: Bestätigen
    end

    Step1->>Step1: Führe Action aus

    alt Action erfolgreich
        Step1-->>CLI: Success (Exit 0)
        CLI->>Step2: Execute block-2 action-1
        Step2->>Step2: Führe Action aus
        Step2-->>CLI: Success (Exit 0)
        CLI->>Step3: Execute block-3 action-1
        Step3->>Step3: Führe Action aus
        Step3-->>CLI: Success (Exit 0)
        CLI-->>User: Workflow completed successfully
    else Action fehlgeschlagen
        Step1-->>CLI: Failure (Exit 1)
        alt allow_failure: true
            CLI->>Step2: Continue to next step
        else allow_failure: false
            CLI-->>User: Workflow aborted
        end
    end

    style CLI fill:#e1f5ff
    style User fill:#fff4e1

Workflow-Features¶

1. Prompts und Bestätigung¶

Falls der Workflow, einer seiner Schritte oder eine Aktion die Aufforderungsangabe mit einer nicht-leeren Nachricht enthält, wird Polycrate den Workflow unterbrechen und den Benutzer um Bestätigung bitten:

workflows:
  - name: deploy-production
    prompt:
      message: "Deploy to PRODUCTION? This will affect live users!"
    steps:
      - name: backup-database
        block: database
        action: backup
        prompt:
          message: "Create backup before deployment?"

      - name: deploy-app
        block: application
        action: deploy

Prompts überspringen:

polycrate workflows run deploy-production --force

2. Fehlerbehandlung mit allow_failure¶

Wenn allow_failure auf true gesetzt ist, wird die Ausführung fortgesetzt, selbst wenn einzelne Schritte fehlschlagen:

workflows:
  - name: deploy-with-monitoring
    allow_failure: true
    steps:
      - name: deploy-app
        block: application
        action: deploy
        # Dieser Step ist kritisch

      - name: send-notification
        block: monitoring
        action: notify
        # Falls Notification fehlschlägt, Workflow trotzdem erfolgreich

3. Dependencies automatisch auflösen¶

Workflows können automatisch Block-Dependencies pullen:

polycrate workflows run deploy-stack --blocks-auto-pull

Praktische Beispiele¶

Beispiel 1: Multi-Tier Application Deployment¶

name: microservices-workspace

blocks:
  - name: infrastructure
    from: terraform-base
    actions:
      - name: provision
        script:
          - terraform -chdir=terraform apply -auto-approve

  - name: database
    from: postgres-base
    actions:
      - name: install
        playbook: playbooks/install.yml

  - name: backend-api
    from: k8s-app-base
    actions:
      - name: deploy
        playbook: playbooks/deploy.yml

  - name: frontend
    from: k8s-app-base
    actions:
      - name: deploy
        playbook: playbooks/deploy.yml

workflows:
  - name: deploy-complete-stack
    prompt:
      message: "Deploy complete microservices stack?"
    steps:
      - name: provision-infrastructure
        block: infrastructure
        action: provision

      - name: deploy-database
        block: database
        action: install

      - name: deploy-backend
        block: backend-api
        action: deploy

      - name: deploy-frontend
        block: frontend
        action: deploy

Ausführung:

polycrate workflows run deploy-complete-stack --blocks-auto-pull

Beispiel 2: Backup und Maintenance Workflow¶

workflows:
  - name: maintenance
    allow_failure: true
    steps:
      - name: notify-users
        block: monitoring
        action: send-maintenance-notification

      - name: backup-database
        block: database
        action: backup
        prompt:
          message: "Create database backup?"

      - name: backup-volumes
        block: storage
        action: backup

      - name: update-application
        block: application
        action: update

      - name: verify-health
        block: application
        action: healthcheck

      - name: notify-complete
        block: monitoring
        action: send-complete-notification

Beispiel 3: Multi-Environment Deployment¶

workflows:
  - name: deploy-to-staging
    steps:
      - name: deploy-staging
        block: application
        action: deploy
        # Block verwendet staging kubeconfig

  - name: deploy-to-production
    prompt:
      message: "Deploy to PRODUCTION?"
    steps:
      - name: backup-prod-db
        block: prod-database
        action: backup

      - name: deploy-prod-app
        block: production-application
        action: deploy

      - name: verify-prod
        block: production-application
        action: healthcheck

Workflow-Commands¶

Workflow ausführen¶

# Vollständiger Befehl
polycrate workflows run <workflow-name>

# Kurzform
polycrate run <workflow-name>

# Mit auto-pull
polycrate workflows run deploy-stack --blocks-auto-pull

# Ohne Prompts
polycrate workflows run deploy-prod --force

Workflows anzeigen¶

# Alle verfügbaren Workflows
polycrate workflows list

# Workflow-Details
polycrate workflows inspect deploy-stack

Best Practices¶

1. Sinnvolle Step-Namen¶

# ✅ Gut: Beschreibende Namen
steps:
  - name: provision-cloud-infrastructure
    block: infrastructure
    action: provision

  - name: deploy-database-cluster
    block: database
    action: install

# ❌ Schlecht: Generische Namen
steps:
  - name: step1
    block: infrastructure
    action: provision

  - name: step2
    block: database
    action: install

2. Kritische Steps mit Prompts schützen¶

workflows:
  - name: destroy-infrastructure
    prompt:
      message: "DANGER: This will destroy all infrastructure. Continue?"
    steps:
      - name: destroy
        block: infrastructure
        action: destroy
        prompt:
          message: "Final confirmation: Really destroy?"

3. Idempotente Actions verwenden¶

Stellen Sie sicher, dass Ihre Block-Actions idempotent sind, sodass Workflows sicher wiederholt werden können:

# Ansible ist von Natur aus idempotent
actions:
  - name: deploy
    playbook: playbooks/deploy.yml

4. Rollback-Workflows erstellen¶

workflows:
  - name: deploy
    steps:
      - name: backup
        block: application
        action: backup
      - name: deploy
        block: application
        action: deploy

  - name: rollback
    steps:
      - name: restore-backup
        block: application
        action: restore
      - name: redeploy-previous
        block: application
        action: deploy-previous-version

5. Monitoring und Notifications¶

workflows:
  - name: deploy-with-monitoring
    allow_failure: true
    steps:
      - name: notify-start
        block: monitoring
        action: notify-deployment-start

      - name: deploy
        block: application
        action: deploy

      - name: verify
        block: application
        action: healthcheck

      - name: notify-complete
        block: monitoring
        action: notify-deployment-complete

Troubleshooting¶

Workflow schlägt bei einem Step fehl¶

# 1. Finden Sie die Transaction-ID des fehlgeschlagenen Steps
polycrate workflows run deploy-stack
# Output zeigt: "Step 'deploy-database' failed with transaction 550e8400..."

# 2. Inspizieren Sie die Transaction (falls Logging aktiviert)
cat .logs/2025-01-30/550e8400-e29b-41d4-a716-446655440000.yml

# 3. Führen Sie den fehlgeschlagenen Step einzeln aus
polycrate run database install

# 4. Führen Sie den Workflow erneut aus
polycrate workflows run deploy-stack

Workflow hängt bei Prompt¶

# Verwenden Sie --force um alle Prompts zu überspringen
polycrate workflows run deploy-stack --force

Step-Reihenfolge ändern¶

Workflows werden strikt sequenziell ausgeführt. Um die Reihenfolge zu ändern, bearbeiten Sie die workspace.poly:

workflows:
  - name: deploy
    steps:
      - name: first
        block: block-a
        action: install
      - name: second  # Wird nach 'first' ausgeführt
        block: block-b
        action: install

Zusammenhang mit anderen Konzepten¶

Blocks: Workflows orchestrieren Block-Actions
Actions: Jeder Workflow-Step führt eine Action aus
Transactions: Jeder Step erzeugt eine Transaction
Dependencies: Workflows können Dependencies mit --blocks-auto-pull auflösen
Events: Workflow-Ausführung erzeugt Events

Workflow-Orchestrierung

Workflows sind perfekt für komplexe Multi-Step-Deployments. Kombinieren Sie Terraform-Provisioning, Ansible-Konfiguration und Kubernetes-Deployments in einem einzigen Workflow!