🧱 Blöcke¶

Blöcke¶

Ein Polycrate-Workspace ist ein modulares System, das aus sogenannten Blöcken besteht. Blöcke sind spezialisierte Code-/Funktionsbausteine, die über die Block Config (default: block.poly) oder die Workspace Config (default: workspace.poly) konfiguriert werden können. Blöcke bieten Actions an, die mit polycrate run $BLOCK_NAME $ACTION_NAME ausgeführt werden können.

Polycrate sucht nach Blöcken in der Block-Root Directory (default: blocks in der Workspace Directory). Verschachtelte Verzeichnisse (z.B. blocks/foo/bar/baz) sind zulässig.

Info

Wenn der Name eines Blocks einen oder mehrere Schrägstriche (/) enthält und aus der Registry installiert wird, legt Polycrate automatisch eine verschachtelte Verzeichnisstruktur an: ayedo/k8s/harbor wird z.B. unter blocks/ayedo/k8s/harbor gespeichert, die zugehörigen Artefakte unter artifacts/blocks/ayedo/k8s/harbor.

Dynamische Blöcke¶

Blöcke können dynamisch erstellt werden, indem ihre Konfiguration direkt in der Workspace-Konfiguration definiert wird. Diese Blöcke verwenden keinen benutzerdefinierten Code, sondern stützen sich nur auf die im Polycrate-Container verfügbaren Tools.

Dynamische Blöcke können auch ihre Standardkonfiguration und ihre Workdir von bereits existierenden Blöcken im Block-Root-Verzeichnis erben, indem die Angabe from: $BLOCK in der jeweiligen Block-Konfiguration der Workspace-Konfiguration verwendet wird.

Dadurch können Sie Blöcke im Workspace mehrfach instanziieren und mit unterschiedlicher Konfiguration ausführen.

Block Directory Struktur¶

Die Block Directory ist das Verzeichnis, das den benutzerdefinierten Code und die Block-Konfiguration (block.poly) eines Blocks unterhalb der Block-Root enthält.

Typische Struktur:

blocks/my-block/
├── block.poly          # Block-Konfiguration (Pflicht)
├── README.md           # Dokumentation
├── CHANGELOG.poly      # Versionshistorie
├── templates/          # Jinja2 Templates für Ansible
│   ├── deployment.yml.j2
│   └── service.yml.j2
├── playbooks/          # Ansible Playbooks (falls genutzt)
│   ├── install.yml
│   └── backup.yml
└── scripts/            # Bash/Python Scripts (falls genutzt)
    └── init.sh

Naming Convention

Per Konvention entspricht der Name des Blockverzeichnisses dem in der Name-Stanza des Blocks definierten Wert.

Block-Konfiguration (block.poly)¶

Die Block-Konfiguration enthält die Metadaten und Konfiguration für einen einzelnen Block.

Minimale block.poly¶

name: custom-block
version: 1.0.0

actions:
  - name: install
    script:
      - echo "Installing..."

Erweiterte block.poly¶

name: custom-block
version: 1.2.3
kind: k8sapp
type: database
flavor: postgresql

# Von anderem Block erben
from: postgres-base:1.0.0

# Frei definierbare Konfiguration
config:
  namespace: production
  replicas: 3
  database:
    name: mydb
    user: dbuser
  persistence:
    enabled: true
    size: 50Gi
    storageClass: fast-ssd

# Actions (können Elternblock überschreiben)
actions:
  - name: install
    playbook: playbooks/install.yml

  - name: backup
    script:
      - pg_dump {{ .block.config.database.name }} > backup.sql

  - name: restore
    script:
      - psql {{ .block.config.database.name }} < backup.sql

# Kubeconfig von anderem Block erben
kubeconfig:
  from: my-cluster

# Inventory von anderem Block erben
inventory:
  from: infrastructure

Die Config-Stanza ist frei definierbar und nicht typisiert. Sie können sie verwenden, um die Konfigurationsstruktur Ihres Blocks nach Ihren Bedürfnissen zu definieren.

Naming Rules¶

Block-Namensregeln

Blocknamen dürfen nur dem Muster ^[a-zA-Z]+([-/]?[a-zA-Z0-9]+)+$ folgen. Diese Einschränkung gilt für alle Namensangaben in Polycrate.

Erlaubte Namen:

✅ postgres-base
✅ my-app
✅ infra/postgres-base
✅ team/apps/webapp

Nicht erlaubte Namen:

❌ _postgres (beginnt mit Underscore)
❌ postgres_base (Underscores nicht erlaubt)
❌ 123-app (beginnt mit Zahl)
❌ my..app (doppelte Punkte)

Siehe auch¶

Registry: Blocks in Registries pushen und pullen
Dependencies: Block-Dependencies verwalten
Vererbung: Blocks von anderen Blocks erben lassen
Actions: Block-Actions definieren und ausführen