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

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 (→ Block Changelog)
├── sbom.poly               # Software Bill of Materials (generiert)
├── vulnerabilities.poly    # Security-Findings (generiert)
├── 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

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
    playbook: playbooks/install.yml

Erweiterte block.poly¶

# blocks/custom-postgres/block.poly
name: custom-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: playbooks/install.yml

  - name: backup
    playbook: playbooks/backup.yml

  - name: restore
    playbook: playbooks/restore.yml

# workspace.poly
blocks:
  - name: my-app
    from: registry.my-org.com/blocks/k8s/my-app:1.0.0
    kubeconfig:
      from: my-cluster  # Erbt Kubeconfig vom Block "my-cluster"
    inventory:
      from: infrastructure  # Erbt Inventory vom Block "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¶

Erlaubte Namen:

✅ postgres-base
✅ my-app
✅ my_app                     (Unterstriche erlaubt)
✅ infra/postgres-base
✅ team/apps/webapp
✅ cargo.ayedo.cloud/ayedo/k8s/keycloak

Nicht erlaubte Namen:

❌ _postgres                  (muss mit Buchstabe beginnen)
❌ 123-app                    (muss mit Buchstabe beginnen)
❌ my app                     (Leerzeichen nicht erlaubt)
❌ Demo GmbH                  (Sonderzeichen nicht erlaubt)
❌ my--app                    (keine doppelten Bindestriche)

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

Block Changelog¶

Jeder Block kann eine CHANGELOG.poly Datei enthalten, die die Versionshistorie dokumentiert.

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: "/playbooks/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¶

• 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