🧱 Blöcke

🧱 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.

Block-Instanzen

Eine Block-Instanz ist ein Eintrag unter blocks: in der workspace.poly. Sie kann ad-hoc nur aus Konfiguration bestehen (ohne eigenes Block-Verzeichnis unter blocks/) und nutzt dann ausschließlich die im Polycrate-Container verfügbaren Tools – oder sie verweist mit from: auf einen Template-Block.

Template-Blöcke liegen unter blocks/ (lokal) oder werden typischerweise aus einer OCI-kompatiblen Registry bezogen. Die Instanz kann Defaults und Working Directory vom Template übernehmen und bei Bedarf config: sowie actions: überschreiben oder ergänzen.

Umgangssprachlich werden Block-Instanzen und Template-Blöcke oft gemeinsam als „Block“ bzw. „Blöcke“ bezeichnet.

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 (→ Block Changelog)
├── examples.poly           # Konfigurationsbeispiele (→ Block Examples)
├── install.yml             # Ansible Playbook: Installation
├── uninstall.yml           # Ansible Playbook: Deinstallation
├── backup.yml              # Ansible Playbook: Backup (optional)
├── templates/              # Jinja2 Templates für Ansible
│   ├── values.yaml.j2
│   └── deployment.yml.j2
└── scripts/                # Bash/Python Scripts (falls genutzt)
    └── init.sh

Block-Konfiguration (block.poly)

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

Minimale block.poly

name: acme-demo-app
version: 1.0.0

actions:
  - name: install
    playbook: install.yml

Erweiterte block.poly

# blocks/acme-demo-postgres/block.poly
name: acme-demo-postgres
version: 1.2.3
kind: k8sapp
type: database
flavor: postgresql

# Frei definierbare Konfiguration (Defaults)
config:
  namespace: default
  replicas: 1
  database:
    name: mydb
    user: dbuser
  persistence:
    enabled: true
    size: 10Gi
    storageClass: standard

# Actions
actions:
  - name: install
    playbook: install.yml

  - name: backup
    playbook: backup.yml

  - name: restore
    playbook: restore.yml

Die config:-Sektion ist frei definierbar und nicht typisiert.

Empfohlene Metadaten

Für Template-Blocks, die im Hub oder als Catalogue App landen, sollten die folgenden Felder gesetzt sein. Quelle der Wahrheit ist die block.poly.

Identität & Klassifikation

Version & Lizenz

URLs

* besonders für Catalogue Apps mit Upstream-Tracking.

name: postgres
display_name: "CloudNativePG PostgreSQL"
icon_url: https://cdn.example.com/icons/postgresql.svg
kind: k8sapp
type: db
flavor: postgresql
implementation: cnpg
supports_ha: true
description: "PostgreSQL mit CloudNativePG"
app_version: "16.2"
license: Apache-2.0
website_url: https://cloudnative-pg.io
documentation_url: https://cloudnative-pg.io/documentation/
git_repository_url: https://github.com/cloudnative-pg/cloudnative-pg
releases_url: https://github.com/cloudnative-pg/cloudnative-pg/releases

→ Kurzregeln: Empfehlungen – Metadaten

Vulnerability Products

Optional Schlüssel vulnerability.products — für Template-Blocks, die als Catalogue App landen: Produkt-Identitäten für CVE-/OSV-Matching.

Die Sektion ist nur Identity (Vendor/Product/PURL/…). Keine CVE-Listen und kein Enrichment in block.poly.

# block.poly (Ausschnitt)
name: authentik
version: 0.12.0
kind: k8sapp
app_version: "2025.2.0"
releases_url: https://github.com/goauthentik/authentik/releases
git_repository_url: https://github.com/goauthentik/authentik

vulnerability:
  products:
    - vendor: goauthentik
      product: authentik
      ecosystem: Go
      purl: "pkg:golang/goauthentik.io/authentik"
      # cvefeed_product_id: "12345"   # optional
      # cpe: "cpe:2.3:a:goauthentik:authentik:*:*:*:*:*:*:*:*"  # optional

Verhalten

• Fehlt die Sektion: Block bleibt gültig; Products können manuell im Catalogue-App-Tab Vulnerability Products gepflegt werden.
• Mit Sektion: Nach Hub-/Template-Block-Import bzw. periodischem Sync übernimmt die API die Einträge als VulnerabilityProduct (source=block). Block ist Source of Truth für diese Keys; manuell angelegte Rows (source=manual) bleiben erhalten.
• Ohne Products in Block und UI: der CVE-Katalog-Enrichment (OSV) hat nichts zu matchen.

→ Empfehlungen · API: Vulnerability Management

Naming Rules

Kurzüberblick – Details, Regex und Beispiele:

→ Namenskonventionen

Registry-Beispiele in dieser Dokumentation verwenden oft die fiktive Organisation acme und die Registry registry.acme.corp (Konvention für generische Beispiele).

Block-Versionen und Instanzen

Best Practices:

• Explizite Versionen: Immer die Version im from:-Key angeben (from: .../block:1.2.3)
• Konsistenz: Bei Updates alle Instanzen gleichzeitig aktualisieren
• Validierung: Nach Version-Updates polycrate validate workspace-poly ./workspace.poly ausführen

→ Detaillierte Informationen in Dependencies

Fehlende Block-Abhängigkeiten

Wenn ein Block in workspace.poly per from: auf einen Block verweist, der nicht im Workspace vorhanden ist (oder eine andere Version hat als angefordert), bricht der Befehl mit einer Fehlermeldung ab (Auszug, je nach Codepfad leicht variierend):

dependency 'cargo.ayedo.cloud/ayedo/k8s/postgres' not found in the Workspace. Please run `polycrate workspace update`, `polycrate block pull cargo.ayedo.cloud/ayedo/k8s/postgres` or run Polycrate with the `--blocks-auto-pull` flag

(polycrate block und polycrate blocks sind dasselbe Kommando.)

Auflösung:

1. Abhängigkeit einbinden: polycrate workspace update und/oder polycrate block pull <registry/pfad/block-name>:<version> (Alias: polycrate blocks pull …)
2. Automatisch beim Run: polycrate run ... --blocks-auto-pull – fehlende Blocks werden vor der Ausführung automatisch gepullt

→ Vererbung und from:

Block Changelog

Jeder Block kann eine CHANGELOG.poly enthalten. Für wiederverwendbare Blöcke empfohlen — Format siehe unten; SemVer-Hinweise: Empfehlungen – Block-Schnitt.

Das Format sieht kein Autorenfeld vor; Autorschaft kann bei Bedarf in description: oder im Git-Commit dokumentiert werden.

CHANGELOG.poly Format

# blocks/my-block/CHANGELOG.poly
- version: "1.2.0"
  date: "2025-12-30"
  type: feat
  message: "Neues Feature hinzugefügt"
  description: |
    - Feature A implementiert
    - Bug B behoben
    - Performance verbessert

- version: "1.1.0"
  date: "2025-12-15"
  type: fix
  message: "Bugfixes und Verbesserungen"
  description: |
    - Kritischen Bug behoben
    - Dokumentation aktualisiert

Changelog-Typen

Changelog anzeigen

# Block-Changelog in interaktiver TUI anzeigen
polycrate block changelog my-block

# Changelog-Format-Spezifikation anzeigen
polycrate block changelog --spec

Die TUI zeigt alle Versionen mit Details an und ermöglicht Navigation mit j/k oder Pfeiltasten.

Block Examples (examples.poly)

Blöcke können eine examples.poly-Datei im Block-Verzeichnis mitliefern, die typische Konfigurationsszenarien als benannte Beispiele enthält. Die Beispiele werden in der CLI als interaktive TUI oder als Plaintext angezeigt und dienen als Vorlage für workspace.poly.

Format

examples.poly ist ein YAML-Mapping aus Beispiel-Namen auf eine config:-Sektion:

# blocks/acme-postgres/examples.poly
single-node:
  config:
    replicas: 1
    database:
      name: devdb
      user: devuser
    persistence:
      enabled: false

ha-production:
  config:
    replicas: 3
    database:
      name: proddb
      user: appuser
    persistence:
      enabled: true
      size: 100Gi
      storageClass: fast-ssd

read-replica:
  config:
    replicas: 2
    read_replica: true
    persistence:
      enabled: true
      size: 50Gi

Die config:-Sektion jedes Beispiels entspricht direkt der config:-Sektion, die in workspace.poly unter der Block-Instanz eingetragen werden kann.

Beispiele anzeigen

# Interaktive TUI (wählen + Detail ansehen)
polycrate block examples my-block

# Plaintext-Ausgabe (CI, Scripting)
polycrate block examples my-block --no-pager

Die TUI zeigt alle Beispiele als navigierbare Liste. Mit Enter wird die vollständige config:-Sektion des ausgewählten Beispiels als YAML angezeigt, mit Esc kehrt man zur Liste zurück.

Beispiel im Workspace verwenden

# workspace.poly — Beispielkonfiguration übernehmen
blocks:
  - name: postgres
    from: cargo.ayedo.cloud/ayedo/k8s/postgres:2.1.0
    config:
      replicas: 3
      database:
        name: proddb
        user: appuser
      persistence:
        enabled: true
        size: 100Gi
        storageClass: fast-ssd

Hub-Anzeige

Blöcke, die auf dem PolyHub veröffentlicht sind, zeigen ihre examples.poly-Inhalte in der Block-Detailansicht an. Beim Block-Push wird die Datei automatisch als Teil des Block-Pakets hochgeladen.

Siehe auch

• Namenskonventionen
• Registry
• Dependencies — Singletons und from:-Versionen
• Vererbung
• Actions
• PolyHub
• Empfehlungen