Blöcke, Actions und Workspaces: Das Baukasten-Prinzip von Polycrate

TL;DR

• Polycrate strukturiert Ansible-Automatisierung in drei Bausteine: Blöcke, Actions und Workspaces – damit verschwindet der klassische Playbook-Wildwuchs und Automatisierung wird wiederfindbar und teilbar.
• Blöcke bringen ihre eigene Konfiguration, Playbooks, Templates und Artefakte mit. Workspace-Konfiguration überschreibt Block-Defaults per Deep-Merge – ideal für wiederverwendbare Standards plus projektspezifische Anpassungen.
• Alle Blöcke laufen in Containern: Kein lokales Ansible-Setup, keine Python-Versionsturbulenzen und eine einheitliche Toolchain für das ganze Team. Distribution erfolgt über eine OCI-Registry und den PolyHub.
• Im Vergleich zu Ansible Roles sind Polycrate-Blöcke selbst-enthaltend, versionierbar, über Registries teilbar und bringen einen klaren Ausführungs- und Konfigurationsrahmen mit – inklusive Workflows für komplexere Abläufe.
• ayedo entwickelt Polycrate und stellt mit offiziellen Block-Kollektionen im PolyHub sowie Dokumentation zu Polycrate-Blöcken eine praxisnahe Plattform zur Verfügung, die von einzelnen Admins bis zu großen Platform-Teams skalierbar ist.

Block, Action, Workspace: das Grundprinzip

Polycrate baut auf Ansible auf, gibt der Automatisierung aber eine klarere Form. Drei Konzepte stehen im Zentrum:

• Block: Ein in sich geschlossener Baustein mit block.poly, Playbooks, Templates und Artefakten.
• Action: Ein benannter Einstiegspunkt in einen Block (z. B. configure, patch, deploy), der genau ein Playbook ausführt.
• Workspace: Der Projektkontext, in dem Blöcke instanziert, konfiguriert, miteinander kombiniert und in Workflows orchestriert werden.

Wichtig: Polycrate führt Ansible immer in einem Container aus. Das löst das klassische Dependency-Problem:

• Kein lokales Ansible installieren
• Keine Python-Versionkonflikte
• Keine heterogenen Tool-Setups im Team

Statt komplexer Ansible-CLI-Aufrufe wie:

ansible-playbook -i inventory.yml site.yml -e "env=prod" --tags "patch"

startest du eine definierte Action:

polycrate run linux-baseline patch

Die Action kennt ihr Playbook, die Konfiguration und den Container-Kontext. Das ist gute DX/UX – auch Kolleg:innen ohne tiefes Ansible-Know-how können Automatisierungen sicher ausführen.

Ausführlich beschrieben sind Blöcke in der offiziellen Dokumentation zu Polycrate-Blöcken.

Block-Anatomie im Detail

Schauen wir uns einen konkreten Block an, der Linux-Basiskonfiguration und Patches ausrollt. Directory-Struktur im Workspace:

acme-corp-automation/
  workspace.poly
  inventory.yml
  blocks/
    linux-baseline/
      block.poly
      patch.yml
      harden.yml
      templates/
        motd.j2
      artifacts/
        baseline-report.md

block.poly: Definition, Konfiguration und Actions

# blocks/linux-baseline/block.poly
name: linux-baseline
version: 0.1.0
kind: generic

config:
  os:
    family: linux
    reboot_after_patch: true
  packages:
    common:
      - vim
      - curl
      - htop
  motd:
    enabled: true
    text: "Managed by Polycrate – ACME Corp"

actions:
  - name: patch
    playbook: patch.yml
    description: "Installiert Updates und optional Reboot"
  - name: harden
    playbook: harden.yml
    description: "Setzt Basis-Hardening (SSH, Sysctl, MOTD)"

Wesentliche Punkte:

• config: Default-Werte des Blocks. Diese werden später im Workspace überschrieben oder ergänzt.
• actions: Jede Action verweist genau auf ein Playbook im selben Verzeichnis.
• version: Version des Block-Templates – wichtig, sobald der Block über eine Registry geteilt wird.

Inventory im Workspace

Das Inventory liegt immer im Workspace-Root als YAML-Datei inventory.yml. Polycrate setzt ANSIBLE_INVENTORY automatisch.

# inventory.yml
all:
  hosts:
    server01.acme-corp.com:
      ansible_user: ubuntu
    server02.acme-corp.com:
      ansible_user: ubuntu

Das Inventory ist YAML im Workspace-Root (kein klassisches INI-Format).

Ansible-Playbook: Nutzung von block.config.*

Das patch.yml greift auf die Block-Konfiguration zu:

# blocks/linux-baseline/patch.yml
- name: Linux patchen mit Polycrate
  hosts: all
  become: true
  gather_facts: true

  vars:
    reboot_after_patch: "{{ block.config.os.reboot_after_patch }}"

  tasks:
    - name: APT Cache aktualisieren
      ansible.builtin.apt:
        update_cache: true
      when: ansible_facts.os_family == "Debian"

    - name: Alle Pakete aktualisieren (Debian/Ubuntu)
      ansible.builtin.apt:
        upgrade: dist
        autoremove: true
      when: ansible_facts.os_family == "Debian"

    - name: YUM/DNF Updates installieren (RHEL/CentOS)
      ansible.builtin.yum:
        name: "*"
        state: latest
      when: ansible_facts.os_family in ["RedHat", "Rocky", "AlmaLinux", "CentOS"]

    - name: Optionaler Reboot nach Patches
      ansible.builtin.reboot:
        msg: "Reboot triggered by Polycrate linux-baseline.patch"
        reboot_timeout: 600
      when: reboot_after_patch | bool

Die Magie passiert bei block.config.os.reboot_after_patch: Diese Variable kommt nicht aus vars_files oder -e, sondern direkt aus block.poly bzw. Workspace-Konfiguration.

Konfigurationsvererbung und Deep-Merge

Damit ein Block wirklich wiederverwendbar wird, braucht er sinnvolle Defaults – aber auch die Möglichkeit, projektspezifisch übersteuert zu werden. Genau hier setzt Polycrate mit Config-Vererbung (Deep-Merge) an.

Block-Defaults in block.poly

Wir haben oben gesehen:

config:
  os:
    family: linux
    reboot_after_patch: true
  packages:
    common:
      - vim
      - curl
      - htop
  motd:
    enabled: true
    text: "Managed by Polycrate – ACME Corp"

Workspace-Instanz mit Overrides

Im Workspace definierst du, wie der Block für ACME Corp konkret aussehen soll:

# workspace.poly
name: acme-corp-automation
organization: acme

blocks:
  - name: linux-baseline
    from: cargo.ayedo.cloud/ayedo/infra/linux-baseline:0.3.1
    config:
      os:
        reboot_after_patch: false
      packages:
        common:
          - vim
          - curl
          - htop
          - jq
      motd:
        text: "ACME Corp – Managed Linux Server"

Wichtig:

• from: ist die OCI-Registry-Referenz inkl. Version im Tag (:0.3.1). Sobald der Block lokal vorliegt (beim ersten polycrate run … können Sie die automatische Installation aus der Registry bestätigen; polycrate blocks pull bleibt optional), liegt er unter blocks/cargo.ayedo.cloud/ayedo/infra/linux-baseline/ (Pfad unter blocks/ entspricht der URL).
• Unter config: überschreibst und erweiterst du die Block-Defaults.

Deep-Merge-Prinzip

Polycrate mergen Block-Config und Workspace-Config tief. Das heißt:

• Maps werden rekursiv zusammengeführt.
• Skalarwerte werden überschrieben.
• Listen werden standardmäßig ersetzt, nicht angehängt (Best Practices siehe Best Practices für Blöcke).

Für unser Beispiel ergibt sich zur Laufzeit folgende effektive Konfiguration:

# Effektive block.config.* in der Action linux-baseline.patch
os:
  family: linux              # aus block.poly
  reboot_after_patch: false  # im Workspace überschrieben
packages:
  common:                    # Liste komplett ersetzt
    - vim
    - curl
    - htop
    - jq
motd:
  enabled: true              # aus block.poly
  text: "ACME Corp – Managed Linux Server"  # im Workspace überschrieben

So erreichst du:

• Einen wiederverwendbaren Standardblock (z. B. von einem Platform-Team gepflegt)
• Feine Mandanten-/Projekt-spezifische Anpassungen in den Workspaces
• Klare Trennung zwischen Block-Definition und -Verwendung

Mehr Details zur Vererbung findest du in der Dokumentation zur Vererbung in Polycrate.

Polycrate-Variablen im Ansible-Playbook

Polycrate stellt in jeder Action eine Reihe von Variablen zur Verfügung, ohne dass du sie explizit übergeben musst:

• block.config.* – die gemergte Block-Konfiguration (wie oben gezeigt)
• workspace.* – Infos und Konfiguration deines Workspaces
• action.* – Metadaten zur aktuell laufenden Action

Ein erweitertes Beispiel:

# blocks/linux-baseline/harden.yml
- name: Linux-Baseline-Hardening mit Polycrate
  hosts: all
  become: true
  gather_facts: false

  tasks:
    - name: SSH Root-Login deaktivieren
      ansible.builtin.lineinfile:
        path: /etc/ssh/sshd_config
        regexp: '^PermitRootLogin'
        line: 'PermitRootLogin no'
        create: false
        backup: true

    - name: MOTD setzen, wenn aktiviert
      ansible.builtin.copy:
        content: "{{ block.config.motd.text }}"
        dest: /etc/motd
      when: block.config.motd.enabled | bool

    - name: Workspace-Name im Log vermerken
      ansible.builtin.lineinfile:
        path: /var/log/polycrate.log
        line: "Hardened by workspace {{ workspace.name }} via action {{ action.name }}"
        create: yes

Hier kommen alle drei Ebenen zusammen:

• block.config.motd.* – block- bzw. workspace-spezifische Konfiguration
• workspace.name – z. B. acme-corp-automation
• action.name – z. B. harden

Wenn du mit Secrets arbeitest (z. B. SSH-Keys, Zertifikate), landen diese typischerweise unter artifacts/secrets/ im Workspace und werden über die integrierte Workspace-Verschlüsselung mit age geschützt. Im Playbook stehen sie dir über workspace.secrets['dateiname'] zur Verfügung.

Von der Action zum Befehl: Ausführung mit polycrate run

Die harden-Action oben startest du einfach:

cd acme-corp-automation

polycrate run linux-baseline harden

Polycrate sorgt dann für:

• Start eines Containers mit Ansible und der definierten Toolchain
• Mount des Workspaces in den Container
• Setzen von Umgebungsvariablen (z. B. ANSIBLE_INVENTORY)
• Bereitstellung der Variablen block, workspace, action im Play
• Ausführung des Playbooks der Action (z. B. harden.yml im Verzeichnis des gezogenen Blocks, typisch blocks/cargo.ayedo.cloud/ayedo/infra/linux-baseline/) gegen das definierte Inventory

Mit plain Ansible müsstest du:

• Ansible und Abhängigkeiten lokal bereitstellen
• ansible.cfg und Inventory-Pfade manuell verwalten
• Extra-Variablen selbst zusammenbauen und übergeben

Mit Polycrate ist dieser Kontext in Block und Workspace modelliert.

Mehr zur Ansible-Integration beschreibt die offizielle Ansible-Integration von Polycrate.

Versionierung und Distribution per OCI-Registry

Dieselbe Registry-Referenz (cargo.ayedo.cloud/...) nutzen Sie zum Teilen und Versionieren von Blöcken – im Team oder über den PolyHub.

Polycrate verwendet OCI-Registries – das gleiche Protokoll wie Docker/OCI-Container-Images. Die from-Zeile im Workspace ist die kanonische Quelle; die Version steht immer als Tag am Ende (:0.3.1).

Wichtige Punkte:

• Niemals :latest verwenden – Sie wollen reproduzierbare Automatisierung und kontrollierte Updates.
• Zum lokalen Entwickeln eines Blocks (vor dem Push) legen Sie ihn unter blocks/<name>/ an – in workspace.poly referenzieren Sie ihn trotzdem über die volle Registry-URL, sobald der Block publiziert ist (siehe Vererbung).

Blöcke in die Registry pushen und daraus ziehen

Als Block-Autor möchtest du deine Arbeit teilen:

# Im Block-Verzeichnis
cd acme-corp-automation/blocks/linux-baseline

# In die Registry pushen (Version steht in block.poly)
polycrate blocks push cargo.ayedo.cloud/acme/infra/linux-baseline

Auf einem anderen System oder in einem anderen Workspace kannst du denselben Block dann einsetzen:

# Block aus Registry lokal verfügbar machen (optional – oft reicht der erste polycrate run)
polycrate blocks pull cargo.ayedo.cloud/acme/infra/linux-baseline:0.1.0

Ein explizites polycrate blocks pull brauchst du im Alltag oft nicht: Fehlt der Block lokal, erkennt Polycrate das beim ersten polycrate run … und fragt, ob der Block automatisch installiert werden soll. Anschließend referenzierst du ihn in workspace.poly mit dieser URL. Das ist Sharable Automation in Reinform: einmal gebaut, vielfach nutzbar – in deinem Team oder öffentlich über den PolyHub.

Im Vergleich zu Ansible Galaxy:

• Ein Polycrate-Block ist selbst-enthaltend (inkl. Container-Toolchain und Konfiguration).
• Du musst kein globales Ansible-Rollenverzeichnis und keine Python-Umgebung pflegen.
• Die Registry ist kein Zusatztool, sondern integraler Bestandteil von Polycrate (siehe auch Registry-Dokumentation).

PolyHub erkunden: das Polycrate-Ökosystem

Der PolyHub ist die zentrale Anlaufstelle für wiederverwendbare Blöcke:

• Offizielle ayedo-Blöcke für Infrastruktur, Kubernetes, Monitoring, Security, Storage und mehr
• Community-Blöcke für spezifische Plattformen oder Branchen
• Versionierte Artefakte, die du direkt per from: in deinen Workspace einbindest

Beispiele für Einsatzszenarien:

• Linux-Admins: Baseline-Hardening, Patch-Management, Monitoring-Agent-Rollout
• Windows-Admins: AD-Benutzerverwaltung, GPO-Deployment, Software-Rollouts
• Compliance: CIS-Benchmarks als Policy-as-Code-Blocks, reproduzierbare Audit-Runs
• Edge/IoT: Raspberry-Pi-Bootstrapping, OTA-Updates für Edge-Nodes

Polycrate bietet mit dem Block-Modell Guardrails: Du konsumierst vorgefertigte Actions, statt beliebige Playbooks auszuführen. Das reduziert Risiken und erleichtert Auditierbarkeit.

Eine Übersicht zu Block-Struktur und Best Practices findest du in der Dokumentation zu Polycrate-Blöcken.

Workflows: mehrere Actions orchestrieren

Ein Block repräsentiert eine logische Einheit, aber reale Abläufe bestehen oft aus mehreren Schritten. Dafür gibt es Workflows auf Workspace-Ebene.

Ein Beispiel: Du möchtest nacheinander Hardening und Patching ausführen.

# workspace.poly
name: acme-corp-automation
organization: acme

blocks:
  - name: linux-baseline
    from: cargo.ayedo.cloud/ayedo/infra/linux-baseline:0.3.1

workflows:
  - name: linux-hardening-and-patch
    description: "Erst Hardening, dann Patches auf allen Linux-Servern"
    steps:
      - block: linux-baseline
        action: harden
      - block: linux-baseline
        action: patch

Ausführung:

polycrate workflows run linux-hardening-and-patch

Polycrate führt dann sequentiell:

1. linux-baseline.harden
2. linux-baseline.patch

im gleichen Workspace-Kontext aus. Du bekommst:

• Wiederholbare End-to-End-Abläufe
• Einfache Dokumentation: Der Workflow ist deine lebende Runbook-Doku
• Einen Startpunkt für nicht-technische Nutzer: ein Befehl statt mehrere Actions

Mehr zu Workflows gibt es in der Workflows-Dokumentation.

Polycrate-Blöcke vs. Ansible Roles

Ansible Roles sind ein starkes Konzept, aber sie lösen nicht alle praktischen Probleme in Teams.

Was Ansible Roles gut können

• Strukturierung von Tasks, Templates, Handlers, Vars
• Wiederverwendbare Bausteine innerhalb eines Ansible-Projekts
• Integration über Galaxy (ansible-galaxy install ...)

Wo Polycrate-Blöcke weitergehen

1. Container-Isolation & Dependency-Management

   • Roles laufen in deiner lokalen Umgebung, abhängig von System-Python, Ansible-Version, installierten Collections.
   • Polycrate-Blöcke laufen in einem Container: Toolchain, Python, Ansible, kubectl, helm etc. sind im Block-Image bzw. Workspace-Image definiert.
   • Keine „funktioniert bei mir, aber nicht bei dir“-Diskussionen mehr.

2. Eingebaute Konfiguration und Vererbung

   • Roles verwenden defaults/main.yml, vars/main.yml, group_vars, host_vars.
   • Polycrate-Blöcke haben eine einheitliche config-Sektion in block.poly, die im Workspace per Deep-Merge überschrieben wird.
   • Keine verstreute Variablen-Landschaft, sondern ein klarer Konfigurationsvertrag pro Block.

3. Sharable Automation über OCI-Registry

   • Galaxy verteilt Roles, aber nicht deine komplette Ausführungsumgebung.
   • Polycrate-Blöcke werden über OCI-Registries bzw. den PolyHub geteilt – inklusive Versionierung und klarer Referenz (from: registry/space/block:1.2.3).

4. Guardrails & UX

   • Bei Roles startest du typischerweise ein „großes“ Playbook mit vielen Rollen – wer welche Rolle wie verwendet, ist frei.
   • Polycrate-Blöcke definieren Actions als benannte Einstiegspunkte. Das senkt die Einstiegshürde und reduziert Fehlbedienung, gerade bei nicht-täglichen Automation-Usern.

5. Workspace-Verschlüsselung

   • Secrets in Ansible-Projekten landen oft in Vault-Dateien, externen Tools oder unsicheren Textdateien.
   • Polycrate bringt Workspace-Verschlüsselung mit age direkt mit – inklusive guter UX für Teams (kein HashiCorp Vault erforderlich).

Ansible bleibt das Herz der Ausführung – Polycrate bringt Struktur, Container-Isolation, Distribution und Konfigurationsmodell oben drauf. Weitere Details zur Plattform findest du auf der Seite zu Polycrate.

Häufige Fragen

Kann ich bestehende Ansible-Roles in Polycrate weiterverwenden?

Ja. Polycrate ändert nichts an Ansible selbst – du kannst innerhalb eines Blocks ganz normal Roles verwenden:

# Beispiel-Playbook in einem Block
- name: Webserver deployen
  hosts: all
  roles:
    - role: geerlingguy.nginx

Du packst deine Playbooks und Roles einfach in das Block-Verzeichnis, definierst Actions in block.poly und lässt Polycrate sich um Container-Umgebung, Inventory und Konfiguration kümmern. Damit kombinierst du vorhandenes Galaxy-Know-how mit den Vorteilen des Block-Modells. Brauchst du zusätzliche Systempakete oder Ansible-Collections dauerhaft im Polycrate-Container, erweiterst du das Workspace-Image über eine Dockerfile.poly (z. B. apt-get oder ansible-galaxy install in RUN-Schritten) – siehe Custom Dockerfile in der Konfigurationsdokumentation.

Wie gehe ich mit sensiblen Daten und Compliance-Anforderungen um?

Sensible Daten (SSH-Keys, Zertifikate, API-Tokens) legst du im Workspace unter artifacts/secrets/ ab und verschlüsselst den Workspace mit der integrierten Workspace-Verschlüsselung. Polycrate nutzt dafür age:

• Keine zusätzliche Vault-Infrastruktur nötig
• Gute Integrationsmöglichkeiten in Git-basierte Workflows
• Klare Trennung zwischen Konfiguration (workspace.poly, block.poly) und Secrets (verschlüsselte Artefakte)

Im Playbook greifst du über workspace.secrets['datei'] darauf zu. So kombinierst du Automatisierung, Nachvollziehbarkeit und Datenschutzanforderungen (z. B. nach DSGVO) auf einer Plattform.

Wie passt Polycrate in meine bestehende Toolchain?

Polycrate lässt sich schrittweise einführen:

• Du kannst mit einem einzigen Block in einem Pilot-Workspace starten.
• Bestehende Inventories konvertierst du nach YAML und legst sie als inventory.yml ab.
• Schritt für Schritt packst du bestehende Playbooks in Blöcke, definierst Actions und Workflows.

Durch die Container-Ausführung kollidiert Polycrate nicht mit deinem bestehenden Python-/Ansible-Setup. Polycrate funktioniert gut neben klassischen CI/CD-Systemen und kann z. B. über deren Shell-Schritte aufgerufen werden. Details zu CLI-Befehlen findest du in der CLI-Referenz.

Weitere Fragen? Siehe unsere FAQ

Von der Theorie zur Umsetzung

Mit Blöcken, Actions und Workspaces bringt Polycrate Ordnung in Ansible-basierte Automatisierung – vom Einzel-Admin bis zum Enterprise-Platform-Team. Du hast gesehen, wie:

• Ein Block seine eigene Struktur, Konfiguration und Actions mitbringt.
• Workspace-Konfiguration über Deep-Merge Block-Defaults sinnvoll überschreibt.
• Polycrate-Variablen (block.config.*, workspace.*, action.*) direkt im Ansible-Playbook nutzbar sind.
• Versionierte Blöcke über OCI-Registries verteilt und im Workspace fest gepinnt werden.
• Workflows mehrere Actions zu reproduzierbaren Abläufen verbinden.

Als Maintainer von Polycrate sorgt ayedo dafür, dass dieses Baukasten-Prinzip in der Praxis funktioniert: mit einer stabilen CLI, klaren Best Practices und einem wachsenden Ökosystem an offiziellen Blöcken für Betrieb, Sicherheit, Compliance und Plattform-Themen. Der PolyHub ist dabei dein Einstieg in wiederverwendbare Automatisierung – egal, ob du zunächst konsumieren oder eigene Blöcke teilen willst.

Wenn du die hier vorgestellten Konzepte konkret ausprobieren möchtest, ist der nächste logische Schritt, bestehende Playbooks in einen ersten Block zu heben und dazu passende Actions und Workflows zu definieren. Die offiziellen ayedo-Blöcke im PolyHub dienen dir dabei als Vorbild, wie wiederverwendbare Automatisierung in Polycrate aussieht – von Linux-Baselines bis zu komplexeren Plattformaufgaben.

Nutze diese Bausteine, um deine eigene Automatisierungs-Landschaft strukturierter, sicherer und besser teilbar zu machen – und entdecke Schritt für Schritt, welche Aufgaben du aus deinem Alltag in wiederverwendbare Blöcke überführen kannst: PolyHub erkunden