Dein erster produktiver Polycrate-Workspace: Eine Checkliste für den Start

TL;DR

• Ein sauber benannter, klar strukturierter Polycrate-Workspace ist die halbe Miete: ein konsistenter Name (z. B. acme-corp-automation) und eine einfache Verzeichnisstruktur verhindern Chaos, bevor es entsteht.
• Starten Sie mit wenigen, gut gewählten Blöcken – je nach Rolle z. B. Linux-Patching, Windows-Basisverwaltung oder Kubernetes-Deployment – und pinnen Sie Block-Versionen konsequent, statt jemals :latest zu verwenden.
• Aktivieren Sie frühzeitig Workspace-Verschlüsselung, setzen Sie Git auf und bauen Sie Ihren ersten eigenen Block – diese Checkliste macht den Einstieg reproduzierbar und auditierbar.
• Typische Stolperfallen sind unverschlüsselte Secrets, hosts: localhost statt korrekter Inventories und fehlende Version-Pins; mit Polycrate und den Best Practices vermeiden Sie diese Fehler von Anfang an.
• ayedo unterstützt Sie mit Polycrate, praxisnahen Best Practices, Projekten und Beratung dabei, aus Ihrem ersten Workspace eine tragfähige Automatisierungsplattform zu machen.

Warum der erste Workspace zählt

Der erste produktive Workspace ist mehr als ein Testballon. Er legt fest, wie Sie in Zukunft automatisieren:

• Wie konsistent Ihre Teams arbeiten
• Wie gut Sie Compliance-Anforderungen wie der seit dem 25.05.2018 geltenden DSGVO nachkommen
• Wie problemlos Kolleg:innen Automatisierungen übernehmen und erweitern können

Mit plain Ansible starten viele mit einem schnellen ansible-playbook auf dem Laptop – und stehen Monate später vor einem Zoo aus Playbooks, Python-Versionen und Inventories. Ansible ist stark, aber ohne Rahmenbedingungen wächst die Komplexität schneller, als Ihnen lieb ist.

Polycrate gibt Ansible eine klare Struktur:

• Ausführung läuft in einem Container → kein lokales Python- oder Ansible-Chaos
• Workspace als zentrales Projekt → Guardrails gegen Playbook-Wildwuchs
• Blöcke als wiederverwendbare Bausteine → Sharable Automation über Teams und Registries

Dieser Beitrag zeigt eine konkrete Checkliste für Ihren ersten produktiven Workspace – inklusive Name, Struktur, ersten Blöcken, Verschlüsselung, Git und Team-Onboarding.

Workspace-Name und Struktur: Best Practices ab Tag 1

Namenskonzept

Ein guter Workspacename ist:

• sprechend
• stabil über Jahre
• unabhängig von Einzelpersonen oder kurzfristigen Projekten

Bewährtes Muster:

• {firma}-{bereich}-automation oder
• {firma}-{produkt}-platform

Beispiele:

• acme-corp-automation (gesamtunternehmensweite Automatisierung)
• acme-retail-platform (Plattform-Team für Retail-Geschäft)

Vermeiden Sie: Namen mit persönlichen Bezügen oder Umgebungen (max-dev-playground, ansible-test).

Verzeichnisstruktur

Ein typischer Workspace nach den Best Practices für Polycrate-Workspaces sieht so aus:

acme-corp-automation/
  workspace.poly
  inventory.yml
  artifacts/
    secrets/
      kubeconfig.yml        # falls Sie K8s einsetzen
  blocks/
    linux-patch/
      block.poly
      patch.yml
    windows-baseline/
      block.poly
      baseline.yml
    k8s-deploy-app/
      block.poly
      deploy.yml
  .git/

• workspace.poly definiert den Workspace und die Block-Instanzen
• inventory.yml (YAML!) ist das zentrale Inventory für alle Ansible-Playbooks
• blocks/ enthält Ihre lokalen Blöcke mit block.poly und Playbooks im gleichen Verzeichnis
• artifacts/secrets/ ist der naheliegende Ort für verschlüsselte Dateien (über Polycrate-Workspace-Verschlüsselung)

Beispiel workspace.poly

name: acme-corp-automation
organization: acme

blocks:
  - name: linux-patch
    from: linux-patch
    config:
      target_hosts: "linux_servers"

  - name: windows-baseline
    from: windows-baseline
    config:
      target_hosts: "windows_servers"

  - name: k8s-deploy-app
    from: k8s-deploy-app
    config:
      kubeconfig_path: ""

Wichtig:

• from: zeigt bei lokalen Blöcken auf das Unterverzeichnis unter blocks/
• keine Felder wie source: oder version: im Block-Eintrag (die Version steht in der Block-Definition bzw. im Registry-Tag)
• config auf Workspace-Ebene ist kein freies Key-Value-Mapping – nur dokumentierte Felder (z. B. Toolchain-Image, Pfade); siehe Konfiguration. SSH-Benutzer setzen Sie sinnvollerweise pro Host im inventory.yml (wie oben bei ansible_user)
• In workspace.poly gibt es keine Auswertung von Jinja wie {{ workspace.secrets[...] }}. Sensible Werte für kubeconfig_path tragen Sie in secrets.poly nach (Merge mit workspace.poly), nicht als Template in der workspace.poly
• Den leeren Platzhalter kubeconfig_path: "" ersetzen Sie nach dem Anlegen von secrets.poly durch den effektiven Pfad bzw. lassen Overrides in secrets.poly

Der erste eigene Block: Von Null zur produktiven Action

Starten wir mit einem minimalen, aber produktiven Beispiel für Linux-Admins: ein Block zum Patchen aller Linux-Server.

block.poly: Linux-Patching

name: linux-patch
version: 0.1.0
kind: generic

config:
  target_hosts: "linux_servers"

actions:
  - name: patch
    description: "Linux-Server patchen"
    playbook: patch.yml

• version des Blocks ist explizit gesetzt – niemals unversioniert arbeiten
• config.target_hosts definiert die Host-Gruppe, auf die das Playbook zielt
• Die Action patch beschreibt klar, was passiert: Patching über Ansible

inventory.yml: Zielsysteme definieren

all:
  children:
    linux_servers:
      hosts:
        server01.acme-corp.com:
          ansible_user: ubuntu
        server02.acme-corp.com:
          ansible_user: ubuntu
    windows_servers:
      hosts:
        win01.acme-corp.com:
          ansible_user: Administrator
          ansible_connection: winrm
          ansible_port: 5986
          ansible_winrm_server_cert_validation: ignore

Dieses Inventory liegt im Workspace-Root (inventory.yml). Polycrate setzt ANSIBLE_INVENTORY automatisch auf diese Datei; Sie müssen im Block nichts weiter konfigurieren.

Ansible-Playbook: patch.yml

- name: Linux-Server patchen
  hosts: "{{ block.config.target_hosts }}"
  become: true
  gather_facts: true

  tasks:
    - name: Paket-Cache aktualisieren
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600

    - name: Alle Pakete aktualisieren
      ansible.builtin.apt:
        upgrade: dist
        autoremove: true

Wichtig:

• Kein hosts: localhost und kein connection: local – das würde nur im Polycrate-Container wirken
• hosts wird aus der Block-Konfiguration gezogen und verweist auf eine Gruppe aus inventory.yml
• Idempotenz: Mehrfaches Ausführen des Playbooks führt nicht zu unerwarteten Nebenwirkungen

Ausführung mit Polycrate

polycrate run linux-patch patch

Das unterscheidet sich fundamental von plain Ansible:

• Kein ansible-playbook -i inventory.yml patch.yml auf einem lokal konfigurierten System
• Keine Diskussion um Python 2.7 vs. 3.x, Pip-Versionen oder globale ansible.cfg
• Ansible läuft in einem Container, dessen Toolchain Sie zentral definieren – identisch auf allen Workstations

Mehr zur Ansible-Integration finden Sie in der offiziellen Dokumentation:
https://docs.ayedo.de/polycrate/ansible/

Welche Blöcke zuerst? Empfehlungen je Zielgruppe

Für Linux-Admins

Ziel: Routineaufgaben stabil und reproduzierbar machen.

Empfohlene erste Blöcke:

1. linux-patch (wie oben)
2. Benutzer- und SSH-Key-Management (linux-users)
3. Basis-Hardening (z. B. CIS oder unternehmensinterne Mindeststandards)

Für Hardening können Sie überlegen, einen offiziellen Block aus dem PolyHub (hub.polycrate.io) einzusetzen oder einen eigenen Block zu bauen, der interne Policies abbildet.

Für Windows-Admins

Ziel: Standardaufgaben rund um AD, GPO und Software-Ausbringung automatisieren.

Typische Start-Blöcke:

1. windows-baseline: Basisrollen, PowerShell-Policy, Agenten
2. windows-software-deploy: Standardsoftware per Ansible win_*-Module
3. ad-user-mgmt: Benutzer- und Gruppenpflege via Ansible-Module für Active Directory

Ein block.poly für windows-baseline könnte z. B. so aussehen:

name: windows-baseline
version: 0.2.0
kind: generic

config:
  target_hosts: "windows_servers"

actions:
  - name: apply
    description: "Windows-Baseline anwenden"
    playbook: baseline.yml

Die Playbooks nutzen hosts: "{{ block.config.target_hosts }}" und die windows_servers-Gruppe aus dem Inventory – genau wie im Linux-Beispiel.

Für Kubernetes- und Plattform-Teams

Ziel: Cluster-Operationen über Ansible und zusätzliche Tools (kubectl, Helm) automatisieren.

Sinnvolle erste Blöcke:

1. k8s-deploy-app: Anwendung ausliefern (Manifeste oder Helm-Charts)
2. k8s-cert-manager (oft sinnvoll, per PolyHub-Block mit gepinnter Version)
3. k8s-backup-ops: Wiederkehrende Backup-/Restore-Aufgaben

Ein block.poly, der eine Kubeconfig aus dem Workspace nutzt:

name: k8s-deploy-app
version: 0.1.0
kind: generic

config:
  kubeconfig_path: ""

actions:
  - name: deploy
    description: "App im Cluster ausrollen"
    playbook: deploy.yml

Im Playbook arbeiten Sie dann mit hosts: localhost und connection: local, weil die API-Aufrufe (z. B. kubernetes.core.k8s) direkt aus dem Polycrate-Container gegen den Cluster gehen – das ist hier korrekt, da der Ziel-Endpunkt eine API, nicht der Container selbst ist. Mehr Details finden Sie in der Kubernetes-Dokumentation:
https://docs.ayedo.de/polycrate/kubernetes/

Checkliste: Vom leeren Git-Repo zum produktiven Workspace

Diese Schritte haben sich für den Einstieg bewährt:

1. Git-Repository anlegen

   • git init acme-corp-automation
   • .gitignore für lokale Artefakte, z. B. *.retry, temporäre Dateien
   • Remote einrichten (GitHub, GitLab, interne Git-Plattform)

2. Workspace erstellen

   • Verzeichnis anlegen, workspace.poly schreiben (siehe oben)
   • inventory.yml anlegen und erste Hosts eintragen – sauber getrennt nach Gruppen

3. Ersten Block anlegen

   • Unter blocks/linux-patch/ block.poly und patch.yml anlegen
   • Version im Block setzen (version: 0.1.0)
   • Playbook testen: polycrate run linux-patch patch

4. Workspace-Verschlüsselung aktivieren
   Polycrate bringt eingebaute Verschlüsselung mit age.
   Typischer Ablauf:

   polycrate workspace encrypt

   • Polycrate führt Sie durch die Einrichtung der Schlüssel
   • Dateien wie artifacts/secrets/kubeconfig.yml werden verschlüsselt gespeichert
   • Sie brauchen keinen externen Vault – für viele Teams reicht die eingebaute Lösung völlig aus

5. Block-Versionen konsequent pinnen

   • Eigene Blöcke: version-Feld in block.poly pflegen
   • Registry-Blöcke (Beispiel mit fiktiver Firmen-Registry): immer mit Tag:

     - name: nginx-ingress
       from: registry.acme-corp.com/acme/infra/nginx-ingress:0.3.1

     Niemals :latest verwenden – das ist die häufigste Quelle für “plötzlich ist alles anders”.

6. PolyHub-Blöcke einbinden (wo sinnvoll)

   • Standard-Themen wie Ingress, Monitoring, Logging können oft als fertige Bausteine aus PolyHub kommen
   • Unternehmensspezifische Themen (Policies, Namenskonventionen, interne APIs) lieber in eigenen Blöcken abbilden
     Dokumentation zur Registry:
     https://docs.ayedo.de/polycrate/registry/
     Übersicht der offiziellen Blöcke:
     https://docs.ayedo.de/polycrate/polyhub/ und https://hub.polycrate.io/

7. Team-Readme schreiben

   • Kurze Beschreibung: Zweck des Workspaces
   • Beispiele:

     polycrate run linux-patch patch
     polycrate run windows-baseline apply
     polycrate run k8s-deploy-app deploy

   • Hinweise zu Workspace-Verschlüsselung und Onboarding

Mit dieser Checkliste haben Sie nach kurzer Zeit einen Workspace, der:

• reproduzierbar
• versionskontrolliert
• verschlüsselt
• teamfähig

ist – nicht nur ein Experiment auf dem eigenen Laptop.

Häufige Fehler beim Einstieg – und wie Sie sie vermeiden

1. hosts: localhost für echte Server verwenden

   • Problem: Ansible läuft im Polycrate-Container und ändert nur diesen – der Container wird danach gelöscht
   • Lösung: Immer Gruppen aus inventory.yml verwenden (linux_servers, windows_servers etc.), kein connection: local, wenn Sie Hosts per SSH/WinRM verwalten

2. Secrets unverschlüsselt im Git-Repo speichern

   • Problem: Compliance, Security, DSGVO (seit 25.05.2018) – unverschlüsselte Zugangsdaten in Git sind heute nicht mehr akzeptabel
   • Lösung: Workspace-Verschlüsselung früh aktivieren, alle sensitiven Dateien nach artifacts/secrets/ legen und dort verschlüsselt verwalten

3. Block-Versionen nicht pinnen

   • Problem: Ein Update im PolyHub oder eine lokale Änderung am Block bricht bestehende Deployments
   • Lösung: Versionen in block.poly und Registry-Tags immer explizit setzen, Änderungen über neue Versionen ausrollen

4. Zu viele Blöcke auf einmal bauen

   • Problem: Sie verlieren den Überblick, bevor irgendein Block wirklich stabil ist
   • Lösung: Mit 1–3 Kern-Blöcken starten (Linux-Patching, Windows-Baseline, ein K8s-Deployment) und erst dann weitere Themen modularisieren

5. Playbooks nicht teamtauglich benennen

   • Problem: In ein paar Monaten weiß niemand mehr, was misc.yml eigentlich macht
   • Lösung: Klare Namen (patch.yml, baseline.yml, deploy.yml) und passende Action-Namen (patch, apply, deploy)

Team-Onboarding: Kolleg:innen in den Workspace holen

Polycrate soll nicht das Tool einer einzelnen Person sein, sondern eine gemeinsame Plattform. Gute Erfahrungen machen Teams mit:

1. Einfachen Einstiegskommandos

   • Startseite im README: “So führst du ein Patching durch”
   • Konkrete Befehle zum Kopieren:

     polycrate run linux-patch patch

   • Kein Vorwissen über Ansible-CLI notwendig – Polycrate abstrahiert die Komplexität über Actions

2. Rollenbasierten Einstiegen

   • Linux-Admins: Fokus auf linux-patch und linux-users
   • Windows-Admins: windows-baseline, windows-software-deploy
   • K8s-Team: k8s-deploy-app, plus ggf. offizielle K8s-Blöcke aus PolyHub
     So entsteht ein Gefühl: “Das hier ist mein Bereich, und ich kann selbst aktiv werden.”

3. Gemeinsam definierten Guardrails

   • Konventionen für Blocknamen, Action-Namen, Playbook-Struktur
   • Entscheidung: Welche Dinge kommen aus PolyHub, was bleibt bewusst intern?
     Dokumentierte Best Practices helfen hier sehr:
     https://docs.ayedo.de/polycrate/best-practices/

4. Schulungen und Pairing

   • Kurze Sessions, in denen ein erfahrener Kollege zeigt, wie ein neuer Block entsteht
   • Pairing zu Beginn, damit mehr Leute Blocks anpassen können, ohne Hemmschwelle

Mit Polycrate haben Sie dafür die richtige Grundlage: Containerisierte Ausführung löst das Dependency-Problem, das Block-Modell sorgt für Struktur und Guardrails, und Workspace-Verschlüsselung macht es leichter, Compliance-Anforderungen einzuhalten – ohne schwergewichtige externe Tools.

Häufige Fragen

Muss ich auf allen Admin-Rechnern Ansible und Python installieren?

Nein. Polycrate löst genau dieses Dependency-Problem, indem Ansible vollständig im Container läuft. Sie brauchen lokal nur Polycrate und einen Container-Runtime (z. B. Docker oder Podman). Die Ansible-Version, Python-Pakete und zusätzliche Tools (kubectl, Helm, Azure-CLI usw.) definieren Sie zentral im Toolchain-Container – alle im Team arbeiten damit identisch.

Kann ich meine bestehenden Ansible-Playbooks weiterverwenden?

Ja. In vielen Einstiegsprojekten packen wir vorhandene Playbooks in neue Blöcke, statt alles neu zu schreiben:

• inventory nach inventory.yml im Workspace migrieren
• hosts-Angaben so anpassen, dass sie auf Host-Gruppen und/oder Block-Konfiguration verweisen
• ansible-playbook-Aufrufe werden durch polycrate run BLOCK ACTION ersetzt

Der Mehrwert kommt dann aus der Struktur (Blocks, Workflows) und der containerisierten Ausführung. Eine tiefergehende Migration können wir im Rahmen unserer Beratung gemeinsam planen.

Was macht ayedo konkret in Polycrate-Einstiegsprojekten?

Typischerweise:

• Gemeinsame Definition von Workspace-Struktur und Namenskonzept
• Aufbau von 2–4 Kern-Blöcken (Linux, Windows, ggf. Kubernetes/Cloud)
• Einführung von Workspace-Verschlüsselung und Git-Workflows
• Begleitung beim Team-Onboarding (Workshops, Pairing, Reviews)

Ziel ist immer, dass Ihr Team Polycrate selbstständig weiterentwickeln kann – wir liefern das Anfangsgerüst und das Know-how. Wenn Sie dazu Fragen haben, melden Sie sich gerne über unser Kontaktformular oder direkt über https://ayedo.de/kontakt/.

Weitere Fragen? Siehe unsere FAQ

Der nächste Schritt

Am Ende dieser Artikel-Reihe steht nicht ein fertiges Produkt, sondern ein Werkzeugkasten: Mit einem ersten sauber aufgesetzten Workspace, klaren Blöcken und konsequenter Versionierung haben Sie die Basis für Automatisierung, die bleibt.

Polycrate adressiert typische Hürden, die viele Teams mit plain Ansible erleben:

• Das Dependency-Problem verschwindet, weil die komplette Toolchain im Container läuft – konsistent über alle Workstations.
• Das Block-Modell gibt Playbooks eine Struktur, die sich sauber versionieren, teilen und wiederverwenden lässt – im Team oder über Registries wie PolyHub.
• Workspace-Verschlüsselung mit age vereinfacht den Umgang mit sensitiven Daten und unterstützt Sie dabei, Compliance-Anforderungen (z. B. aus der seit dem 25.05.2018 geltenden DSGVO) pragmatisch zu erfüllen, ohne zusätzliche Vault-Produkte einführen zu müssen.

Als Team hinter Polycrate unterstützen wir bei ayedo genau in dieser Phase: vom ersten produktiven Workspace bis hin zu unternehmensweiten Automatisierungsplattformen. In unseren Beratungsangeboten kombinieren wir Praxis aus Platform-Engineering-Projekten mit tiefem Verständnis für Compliance, Security und Enterprise-Architekturen.

Ob Sie Linux- und Windows-Administration vereinheitlichen, Kubernetes-Cluster integrieren oder Policy as Code für Audits etablieren möchten – gemeinsam definieren wir eine Workspace-Struktur und Block-Landschaft, die zu Ihrer Organisation passt, statt umgekehrt.

Wenn Sie Ihren ersten produktiven Workspace nicht allein planen möchten oder bestehende Ansible-Strukturen sauber in Polycrate überführen wollen, sprechen Sie uns an – gerne auch mit konkreten Beispielen aus Ihrem Alltag.

Einstieg mit Terminen und Formaten: Workshops · individuelle Begleitung: Beratung.