🧱 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)
├── sbom.poly               # Software Bill of Materials (generiert)
├── vulnerabilities.poly    # Security-Findings (generiert)
├── 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. Sie legt die Konfigurationsstruktur Ihres Blocks fest.

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 workspace compile 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 Datei enthalten, die die Versionshistorie dokumentiert. Ein gepflegtes Changelog ist Best Practice für wiederverwendbare Blöcke. → Changelog führen

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 Security Scanning¶

Polycrate ermöglicht Security-Scanning von Blöcken zur Erkennung von Vulnerabilities, Security-Misconfigurations und zur Generierung von SBOMs (Software Bill of Materials).

Verfügbare Scanner¶

Block analysieren¶

# Mit Checkov analysieren (Standard, für IaC)
polycrate block analyze my-block

# Mit Trivy analysieren (für Dependencies)
polycrate block analyze my-block --tool trivy

# Mit Syft + Grype analysieren (Production)
polycrate block analyze my-block --tool syft

# Lokal ausführen (Tools müssen installiert sein)
polycrate block analyze my-block --local

Ergebnisse anzeigen¶

# SBOM anzeigen (interaktive TUI)
polycrate block sbom inspect my-block

# Vulnerabilities anzeigen (interaktive TUI)
polycrate block vulnerabilities inspect my-block
polycrate block vulns inspect my-block  # Alias

# Plain-Output für CI/CD
polycrate block sbom inspect my-block --no-pager
polycrate block vulns inspect my-block --no-pager

Output-Dateien¶

Nach der Analyse werden zwei Dateien im Block-Verzeichnis erstellt:

Beispiel sbom.poly:

# sbom.poly - Auto-generated by polycrate block analyze
# Block: cargo.ayedo.cloud/ayedo/k8s/keycloak
# Version: 1.0.0
# Tool: trivy

bomFormat: CycloneDX
specVersion: "1.6"
components:
  - type: library
    name: java
    version: "21.0.1"

Beispiel vulnerabilities.poly (Checkov):

# vulnerabilities.poly - Auto-generated by polycrate block analyze
# Block: cargo.ayedo.cloud/ayedo/linux/hardening
# Tool: checkov

passed: 15
failed: 3
skipped: 2
results:
  failed_checks:
    - check_id: CKV_ANSIBLE_1
      check_name: "Ensure no plaintext passwords"
      file_path: "/install.yml"
      severity: HIGH

Instanziierte Blöcke scannen¶

Bei instanziierten Blöcken (mit from:) wird der offizielle Template-Name in den Outputs verwendet:

# workspace.poly
blocks:
  - name: keycloak           # Instanz-Name
    from: cargo.ayedo.cloud/ayedo/k8s/keycloak:1.0.0

# Beide Varianten funktionieren:
polycrate block analyze keycloak
polycrate block sbom inspect keycloak

# Output zeigt Template-Namen:
# "Block: cargo.ayedo.cloud/ayedo/k8s/keycloak"

Scanner-Optionen¶

Checkov (Standard)¶

Checkov ist der Standard-Scanner und ideal für Infrastructure-as-Code:

• Scannt Ansible-Playbooks auf Security-Misconfigurations
• Prüft Terraform-Konfigurationen
• Analysiert Kubernetes-Manifeste
• Findet unsichere Dockerfile-Patterns

Trivy¶

Trivy ist ein All-in-One-Scanner mit umfassenden Fähigkeiten:

# Alle Scanner aktiviert (Standard)
polycrate block analyze my-block --tool trivy

# Nur Vulnerability-Scanner
polycrate block analyze my-block --tool trivy --scanners vuln

# Verfügbare Scanner:
# - vuln: CVE-Vulnerabilities
# - secret: Hardcodierte Credentials
# - misconfig: IaC-Misconfigurations
# - license: Lizenz-Compliance

Syft + Grype¶

Die "Best of Breed"-Kombination für Production-Umgebungen:

• Syft: Generiert präzise SBOMs
• Grype: Schnelles Vulnerability-Matching gegen SBOM

polycrate block analyze my-block --tool syft

CI/CD-Integration¶

Für CI/CD-Pipelines nutzen Sie --no-pager für strukturierten Output:

# In CI/CD-Pipeline
polycrate block analyze my-block --tool trivy
polycrate block vulns inspect my-block --no-pager

# Exit-Code prüfen
if [ $? -ne 0 ]; then
  echo "Security issues found!"
  exit 1
fi

→ Integrationen: Security Scanning

Siehe auch¶

• Namenskonventionen: Regex und gültige Namen für alle Objekttypen
• 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
• Integrationen: Security Scanning: Security-Scanner-Integration
• Best Practices: Empfehlungen für Block-Versionen