Polycrate installieren und den ersten Ansible-Block in 15 Minuten bauen

TL;DR

• Du installierst Polycrate mit einem einzigen curl-Befehl – ohne pip, ohne virtualenv, ohne lokale Ansible-Installation.
• Du initialisierst einen Workspace, verstehst seine Struktur und legst darin deinen ersten Ansible-Block webserver an.
• Du baust ein sinnvolles Hello-World-Playbook, das nginx auf einem Linux-Host installiert, startet und den Status prüft.
• Du siehst, wie Polycrate Ansible immer in einem Container ausführt – dein Team teilt sich damit eine saubere, reproduzierbare Toolchain statt Python-Chaos auf jeder Maschine.
• Du erfährst, wie ayedo mit Polycrate eine strukturierte, teilbare Automatisierungsplattform bereitstellt, die von Einzeladmins bis Enterprise-Teams skaliert und dabei Compliance-Anforderungen adressiert.

Warum Polycrate mit Ansible starten?

Ansible ist für viele Admins und Engineers längst das Schweizer Taschenmesser für Automatisierung: Konfigurationen, Patches, Deployments, Windows-Management, Netzwerk – alles geht mit Playbooks.

Das Problem kennst du vielleicht aus dem Alltag:

• Unterschiedliche Python-Versionen auf den Laptops im Team
• ansible nur in einem alten Virtualenv installiert
• Unklare ansible.cfg-Einstellungen und verstreute Inventories
• Playbook-Wildwuchs in Git-Repos ohne echte Struktur

Polycrate setzt genau hier an – ohne Ansible zu ersetzen:

• Dependency-Problem gelöst: Ansible läuft immer in einem Container, inklusive Toolchain (Python, ssh, optional kubectl, helm usw.). Dein Host braucht nur Polycrate, sonst nichts.
• Guardrails statt Wildwuchs: Ansible-Code wird in Blöcken organisiert. Jeder Block hat klare Metadaten (block.poly), definierte Actions und eine wiederverwendbare Struktur.
• Gute UX/DX: Statt langer ansible-playbook-Kommandos benutzt du einfache Actions wie polycrate run webserver install. Auch Kolleg:innen ohne tiefes Ansible-Wissen können das ausführen.

In diesem Beitrag gehen wir Schritt für Schritt durch:

1. Polycrate installieren
2. Workspace initialisieren
3. Ersten Ansible-Block webserver bauen
4. Action ausführen und verstehen, was im Hintergrund passiert
5. Kurzer Vergleich mit plain Ansible

Wenn du danach weitermachen willst: In späteren Beiträgen geht es tiefer in Themen wie Block-Versionierung, Registry und Workspace-Verschlüsselung. Die Grundlagen legst du heute.

Schritt 1: Polycrate installieren

Polycrate bringt seine eigene, containerisierte Toolchain mit. Du installierst also nicht Ansible direkt auf deinem System, sondern nur die Polycrate-CLI, die sich um alles andere kümmert.

Die jeweils aktuelle Installationsanleitung findest du in der
Installations-Dokumentation.

Typischerweise läuft die Installation auf Linux und macOS auf einen Einzeiler mit curl hinaus. Das Muster sieht so aus:

curl -sSfL https://<aktuelle-install-url-aus-der-doku> | sudo bash

Wichtig:

• Ersetze <aktuelle-install-url-aus-der-doku> mit der URL aus der offiziellen Dokumentation.
• sudo ist nötig, wenn Polycrate systemweit installiert werden soll (z.B. nach /usr/local/bin).
• Nach der Installation sollte polycrate im PATH liegen.

Prüfe danach kurz deine Installation:

polycrate version

Du solltest eine Ausgabe in etwa dieser Form sehen:

polycrate version vX.Y.Z

Damit ist deine lokale Maschine fertig. Ansible, Python etc. werden später im Container bereitgestellt, nicht auf deinem Host.

Schritt 2: Workspace initialisieren

Ein Polycrate-Workspace ist dein Projektordner für Automatisierung – vergleichbar mit einem Git-Repo, aber mit klarer Struktur und Metadaten.

Lege zuerst ein neues Verzeichnis an und wechsle hinein:

mkdir acme-corp-automation
cd acme-corp-automation

Initialisiere nun den Workspace:

polycrate workspace init

Polycrate fragt dich nach einem Namen für den Workspace und legt dann die Basisdateien an. Der Name wird in workspace.poly geschrieben und dient u.a. als logischer Bezeichner in größeren Setups.

Warum dieser Schritt wichtig ist:

• Er verankert deine Automatisierung in einer konsistenten Projektstruktur.
• Er ist die Grundlage für Features wie Workspace-Verschlüsselung, Block-Vererbung und Workflows.
• Er sorgt dafür, dass Polycrate genau weiß, wo es nach Blöcken, Inventories und Secrets suchen muss.

Details zu Workspaces findest du in der
Workspace-Dokumentation.

Schritt 3: Workspace-Struktur verstehen

Nach polycrate workspace init sieht dein Verzeichnis typischerweise so aus:

.
├── workspace.poly
├── blocks/
├── artifacts/
│   └── secrets/
└── CHANGELOG.poly

Die wichtigsten Elemente:

• workspace.poly
  Zentrales Manifest des Workspaces. Hier definierst du, welche Blöcke in diesem Workspace aktiv sind, welche Workflows es gibt und kannst arbeitsplatzweite Konfigurationen hinterlegen.

• blocks/
  Hier liegen deine lokalen Blöcke. Jeder Block ist ein Unterordner mit mindestens einer block.poly und den dazugehörigen Dateien (z.B. Ansible-Playbooks).

• artifacts/secrets/
  Speicherort für sensible Dateien, z.B. Kubeconfigs oder später verschlüsselte Secrets. Polycrate unterstützt Workspace-Verschlüsselung mit age, sodass du auch in regulierten Umgebungen sicher arbeiten kannst (siehe Workspace-Verschlüsselung).

• CHANGELOG.poly
  Optional, aber hilfreich für Nachvollziehbarkeit. Hier kannst du Änderungen an Blöcken und Workflows dokumentieren – nützlich für Compliance und Audits.

Schau dir workspace.poly kurz an. Direkt nach dem Init könnte sie so aussehen:

name: acme-corp-automation

Wir erweitern diese Datei gleich um unseren ersten Block.

Schritt 4: Inventory für deinen Webserver anlegen

Bevor wir den ersten Block bauen, braucht Ansible einen Zielhost. Polycrate nutzt immer ein YAML-Inventory im Workspace-Root als Standard.

Lege eine Datei inventory.yml im Workspace-Root an:

touch inventory.yml

Fülle sie z.B. so:

all:
  hosts:
    web01.acme-corp.com:
      ansible_user: ubuntu

Erklärungen:

• all.hosts.web01.acme-corp.com ist dein Zielhost. Ersetze das mit dem realen FQDN oder der IP deines Servers.
• ansible_user ist der SSH-Benutzer, z.B. ubuntu bei Ubuntu-Cloud-Images.

Wie genau Polycrate deine SSH-Keys und Verbindungen in den Container bekommt, ist in der
SSH-Dokumentation beschrieben. Für dieses Tutorial gehen wir davon aus, dass du SSH-Zugriff auf den Host einrichten kannst.

Wichtig: Das Inventory liegt immer im Workspace-Root und heißt inventory.yml. Polycrate setzt die Umgebungsvariable ANSIBLE_INVENTORY automatisch auf diese Datei.

Schritt 5: Ersten Block webserver anlegen

Jetzt wird es konkret. Wir bauen einen Block, der:

• nginx auf deinem Host installiert
• sicherstellt, dass der Dienst läuft
• den Status prüft und ausgibt

5.1 Block-Ordner anlegen

Lege den Block-Ordner an:

mkdir -p blocks/webserver
cd blocks/webserver

5.2 Block-Metadaten: block.poly

In jedem Block gibt es eine block.poly, die beschreibt:

• Wie der Block heißt
• Welche Konfiguration er erwartet
• Welche Actions er anbietet und welche Playbooks sie ausführen

Erstelle blocks/webserver/block.poly mit folgendem Inhalt:

name: webserver
kind: ansible

config:
  package_name: "nginx"

actions:
  - name: install
    description: "Installiert nginx, startet den Dienst und prüft den Status"
    playbook: install.yml

Wichtige Punkte:

• name
  Der logische Name des Blocks. Wir referenzieren ihn später im Workspace als webserver.

• kind: ansible
  Sagt Polycrate, dass dieser Block Ansible-Playbooks ausführt.

• config
  Konfigurierbare Werte des Blocks. Hier z.B. welches Paket installiert wird. Später kannst du hier auch Portnummern, Pfade usw. definieren und im Playbook als Jinja2-Variablen nutzen.

• actions
  Liste von Actions, die dieser Block anbietet. Jede Action hat mindestens:

  • name: Bezeichner für polycrate run <block> <action>
  • description: Dokumentation
  • playbook: das auszuführende Ansible-Playbook (relativ zum Block-Ordner)

Mehr zu Blöcken: Block-Dokumentation und
Best Practices.

5.3 Ansible-Playbook: install.yml

Jetzt kommt unser erstes sinnvolles Hello-World-Playbook. Erstelle blocks/webserver/install.yml:

- name: Webserver mit nginx bereitstellen
  hosts: all
  become: true
  gather_facts: true

  vars:
    webserver_package: "{{ block.config.package_name }}"

  tasks:
    - name: Paket-Cache aktualisieren (Debian/Ubuntu)
      ansible.builtin.apt:
        update_cache: true
      when: ansible_os_family == "Debian"

    - name: nginx installieren
      ansible.builtin.package:
        name: "{{ webserver_package }}"
        state: present

    - name: nginx-Dienst sicherstellen (läuft und aktiviert)
      ansible.builtin.service:
        name: "{{ webserver_package }}"
        state: started
        enabled: true

    - name: nginx-Status abrufen
      ansible.builtin.command: systemctl status "{{ webserver_package }}"
      register: nginx_status
      changed_when: false

    - name: nginx-Status ausgeben
      ansible.builtin.debug:
        msg: "{{ nginx_status.stdout_lines }}"

Was passiert hier?

• hosts: all
  Alle Hosts aus inventory.yml. Polycrate sorgt dafür, dass das Inventory im Container verfügbar ist.

• become: true
  Ansible nutzt sudo, um Pakete zu installieren und Dienste zu verwalten.

• vars.webserver_package
  Wert aus block.config.package_name (unser config-Block aus block.poly). Dadurch kannst du denselben Block später auch für andere Webserver-Pakete verwenden, ohne das Playbook zu ändern.

• Tasks:

  • Aktualisieren des Paket-Caches (Debian/Ubuntu-spezifisch)
  • Installation von nginx (oder dem konfigurierten Paketnamen)
  • Sicherstellen, dass der Dienst läuft und aktiviert ist
  • Abrufen und Ausgeben des systemctl status – damit siehst du im Output, ob alles passt

Ansible ist idempotent: Wenn nginx schon installiert und gestartet ist, werden keine unnötigen Änderungen gemacht. Polycrate profitiert voll von dieser Stärke.

Schritt 6: Block im Workspace registrieren

Damit Polycrate weiß, dass es diesen Block gibt, musst du ihn im Workspace registrieren.

Wechsle zurück ins Workspace-Root:

cd ../../

Öffne workspace.poly und ergänze den Block-Eintrag:

name: acme-corp-automation

blocks:
  - name: webserver
    from: webserver
    config:
      package_name: "nginx"

Erläuterung:

• blocks
  Liste aller Block-Instanzen in diesem Workspace.

• name: webserver
  Name der Instanz im Workspace. Muss nicht, kann aber gleich dem Blocknamen sein.

• from: webserver
  Pfad zu deinem lokalen Block. Für Blöcke aus einer Registry (z.B. PolyHub) würde hier eine URL mit expliziter Version stehen, z.B.
  from: cargo.ayedo.cloud/ayedo/infra/nginx:0.3.1
  – zu Versionierung und Sharing kommen wir in einem späteren Beitrag dieser Reihe.

• config
  Workspace-spezifische Konfiguration für diese Instanz. Diese Werte landen im Playbook als block.config.*.

Polycrate trennt bewusst:

• Block-Definition (block.poly im Block-Ordner)
• Block-Instanz im Workspace (blocks: in workspace.poly)

Damit kannst du denselben Block mit unterschiedlichen Konfigurationen mehrfach verwenden.

Schritt 7: Action ausführen

Jetzt kommt der Moment der Wahrheit: Wir führen unseren Block aus.

Im Workspace-Root:

polycrate run webserver install

Was passiert:

1. Polycrate liest workspace.poly und findet dort den Block webserver.
2. Es startet einen Container mit der konfigurierten Toolchain (u.a. Ansible).
3. Es mountet den Workspace (inkl. blocks/ und inventory.yml) in den Container.
4. Es führt Ansible mit deinem Playbook blocks/webserver/install.yml aus.
5. Nach der Ausführung wird der Container gelöscht – keine dauerhaften Seiteneffekte auf deinem Host.

Du solltest eine typische Ansible-Ausgabe sehen, inklusive der Tasks und am Ende die Debug-Ausgabe mit dem nginx-Status.

Wenn etwas schiefgeht (SSH, Paketquelle, Rechte), siehst du die gewohnte Ansible-Fehlerdiagnose. Nur eben strukturiert über eine Polycrate-Action.

Was im Hintergrund passiert: Container statt Chaos

Der entscheidende Unterschied zu plain Ansible: Du führst ansible-playbook nicht direkt auf deinem Laptop aus, sondern immer innerhalb eines ephemeral Containers, den Polycrate verwaltet.

Das löst mehrere typische Probleme:

• Keine lokale Ansible-Installation nötig
  Du brauchst weder pip install ansible noch ein Virtualenv. Polycrate bringt seine eigene, definierte Version mit.

• Kein Python-Versions-Chaos
  Ob dein Host Python 2, 3 oder gar kein Python installiert hat, ist egal. Für Ansible zählt nur der Container.

• Reproduzierbare Toolchain im Team
  Alle Teammitglieder nutzen denselben Container-Stack. Was bei dir funktioniert, funktioniert auch auf dem Laptop der Kolleg:innen oder in CI/CD-Pipelines.

• Klare Guardrails
  Durch das Block-Modell wird Ansible strukturiert: Playbooks sind Aktionen innerhalb eines Blocks, nicht lose Dateien in beliebigen Verzeichnissen.

Wenn du tiefer einsteigen willst, wie Polycrate und Ansible zusammenspielen, lohnt sich ein Blick in die
Ansible-Integrationsdokumentation.

Vergleich mit plain Ansible

Um den Unterschied greifbar zu machen, schauen wir uns kurz an, wie dieselbe Aufgabe mit plain Ansible aussehen würde.

Mit plain Ansible

Du benötigst:

1. Lokale Installation:

   pip install ansible

2. Irgendeine Projektstruktur (selbst gewählt).
3. Eine ansible.cfg (optional, aber meist nötig).
4. Das Inventory (z.B. inventory.yml).
5. Das Playbook (z.B. site.yml).

Ausführung:

ansible-playbook site.yml -i inventory.yml

Du musst dabei selbst sicherstellen:

• Welche Ansible-Version installiert ist
• Welche Python-Version genutzt wird
• Dass alle Teammitglieder dieselbe Umgebung haben
• Wo welche Playbooks liegen und wie sie benannt sind

Mit Polycrate

Du hast:

• Einen strukturierten Workspace (workspace.poly, blocks/, artifacts/).
• Einen klar definierten Block mit Metadaten (blocks/webserver/block.poly).
• Dein Playbook als Teil dieses Blocks (blocks/webserver/install.yml).

Ausführung:

polycrate run webserver install

Der Unterschied in der Praxis:

• Mit plain Ansible müsstest du jetzt erst sichergehen, dass deine lokale Umgebung stimmt:
  richtige ansible-Version, python, ssh, Pfade etc.

• Mit Polycrate reicht der eine Command – der Container kümmert sich um Tooling, und der Block kümmert sich um Struktur und Wiederverwendbarkeit.

Das wird besonders spannend, wenn du Automatisierungen teilen willst:
Ein Block lässt sich versioniert über eine OCI-Registry oder PolyHub sharen. Was du heute für deinen Webserver baust, kann morgen ein Kollege in einem anderen Workspace wiederverwenden – inklusive aller Best Practices.

Häufige Fragen

Brauche ich noch Ansible auf meinem Laptop, wenn ich Polycrate nutze?

Nein. Polycrate bringt Ansible im Container mit. Alles, was du lokal brauchst, ist:

• Die Polycrate-CLI
• Einen Container-Runtime (Docker oder kompatibel)

Ansible, Python und alle weiteren Tools liegen im Container, den Polycrate für jede Action startet. Wenn du Ansible trotzdem lokal installieren möchtest (z.B. für Ad-hoc-Tests), spricht nichts dagegen – Polycrate ist davon unabhängig.

Kann ich bestehende Playbooks in einen Polycrate-Block überführen?

Ja, sehr gut sogar. Ein typisches Vorgehen:

1. Workspace anlegen (polycrate workspace init).
2. Block-Ordner in blocks/ anlegen, z.B. blocks/linux-patch/.
3. block.poly erstellen und deine bestehenden Playbooks hineinlegen.
4. Actions definieren, z.B. patch, verify, rollback.
5. Block in workspace.poly referenzieren.

So migrierst du schrittweise von losen Playbooks zu strukturierten Blöcken – ohne deine bestehende Ansible-Logik wegzuwerfen.

Wie hilft mir das bei Compliance und Audits?

Polycrate unterstützt dich auf mehreren Ebenen:

• Strukturierte Workspaces mit workspace.poly und CHANGELOG.poly erleichtern Nachvollziehbarkeit.
• Workspace-Verschlüsselung (mit age) ermöglicht es, sensible Daten sicher im Repository zu halten (z.B. in artifacts/secrets/) – wichtig etwa für DSGVO-konforme Verarbeitung oder CIS-harte Umgebungen.
• Sharable Blöcke erlauben es, geprüfte Automatisierung (z.B. CIS-konforme Baselines) als Versionen zu verteilen, statt Skripte per Copy & Paste zu duplizieren.

Weitere Fragen? Siehe unsere FAQ

Von der Theorie zur Umsetzung

In diesem Beitrag hast du Polycrate nicht nur installiert, sondern deinen ersten Ansible-Block gebaut, ausgeführt und verstanden, was im Hintergrund passiert:

• Du hast gesehen, wie Polycrate Ansible in einen Container verlagert und damit das klassische Dependency-Problem löst.
• Du hast mit workspace.poly, blocks/ und artifacts/ eine klare Struktur kennengelernt, die den Wildwuchs einzelner Playbooks eindämmt.
• Du hast einen realistischen, aber einfachen Anwendungsfall automatisiert: nginx installieren, Dienst sicherstellen und Status prüfen – alles in einem Block, der sich problemlos erweitern oder teilen lässt.

Für ayedo ist genau diese Kombination entscheidend: pragmatische Automatisierung für Admins, Engineers und Compliance-Verantwortliche, die im Alltag funktioniert – unabhängig davon, ob du Linux-Server, Windows-Hosts, IoT-Geräte oder Kubernetes-Cluster betreust. Mit Polycrate können wir in Projekten:

• Bestehende Ansible-Landschaften in strukturierte Blöcke überführen
• Teamübergreifende Automatisierung über Registries und PolyHub teilen
• Compliance-Anforderungen (Auditability, Secrets-Handling, Policy as Code) direkt in deine technische Basis integrieren

Wenn du den nächsten Schritt gehen möchtest, ist der beste Startpunkt, Polycrate selbst auszuprobieren – so wie in diesem Beitrag beschrieben. Installiere die CLI, lege deinen ersten Workspace an und bring deine bestehenden Playbooks in Form. Bei Bedarf unterstützen wir dich dabei, von den ersten Schritten bis zum unternehmensweiten Platform-Setup.

Polycrate installieren