Zum Inhalt

Dependencies

Polycrate unterstützt Block-Dependencies durch die from: Referenz in der workspace.poly. Wenn ein Block-Instanz von einem Template-Block erbt, wird dieser automatisch als Dependency behandelt.

from: nur in workspace.poly

Die from:-Angabe erfolgt ausschließlich in der workspace.poly, nicht in der block.poly. Siehe Vererbung für Details.

Wie funktionieren Dependencies?

In der workspace.poly referenzieren Block-Instanzen Template-Blocks via from::

# workspace.poly
blocks:
  - name: my-postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # <- Dependency
    config:
      namespace: production

In diesem Beispiel ist der Registry-Block cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1 eine Dependency. Polycrate erkennt dies automatisch und pullt den Block bei Bedarf.

Dependency-Auflösung

Interaktiver Dependency-Prompt

Ab Version 0.28.0 zeigt Polycrate einen interaktiven Prompt, wenn beim Laden eines Workspaces fehlende oder veraltete Block-Dependencies erkannt werden.

Erkannte Status:

Status Bedeutung Aktion
[MISSING] Block ist nicht installiert Block wird gepullt
[UPGRADE] Installierte Version ist älter als angefordert Update auf neue Version
[DOWNGRADE] Installierte Version ist neuer als angefordert ⚠️ Warnung + Bestätigung erforderlich

Beispiel-Prompt:

┌─────────────────────────────────────────────────────────────────────────────┐
│  Block Dependency Issues                                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  The following block dependencies need to be resolved:                      │
│                                                                             │
│  ● cargo.ayedo.cloud/ayedo/k8s/cert-manager:v2.0.0          [MISSING]      │
│    └─ required by: cert-manager                                             │
│                                                                             │
│  ● cargo.ayedo.cloud/ayedo/k8s/ingress-nginx:v1.5.0         [UPGRADE]      │
│    └─ installed: v1.4.0 → requested: v1.5.0                                │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  ▸ Install/Update all                                                       │
│    Solve manually                                                           │
└─────────────────────────────────────────────────────────────────────────────┘

Optionen:

  1. Install/Update all - Alle Abhängigkeiten automatisch auflösen
  2. Solve manually - Zeigt die benötigten Befehle zur manuellen Auflösung

Downgrade-Warnung

Bei Downgrades (Installation einer älteren Version als bereits installiert) wird eine zusätzliche Bestätigung angefordert, da Downgrades zu Datenverlust oder Inkompatibilitäten führen können.

CI/CD-Umgebungen:

In nicht-interaktiven Umgebungen (CI/CD-Pipelines, Pipes) wird automatisch eine detaillierte Fehlermeldung mit allen benötigten Befehlen ausgegeben:

Block dependency issues found:

  MISSING: cargo.ayedo.cloud/ayedo/k8s/cert-manager:v2.0.0
    required by: cert-manager

  UPGRADE: cargo.ayedo.cloud/ayedo/k8s/ingress-nginx
    installed: v1.4.0 → requested: v1.5.0

To resolve, run:
  polycrate block pull cargo.ayedo.cloud/ayedo/k8s/cert-manager:v2.0.0
  polycrate block pull cargo.ayedo.cloud/ayedo/k8s/ingress-nginx:v1.5.0

Or use: polycrate run --blocks-auto-pull <block>.<action>

Polycrate erkennt automatisch gängige CI/CD-Umgebungen (GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.) und deaktiviert interaktive Prompts.

Automatische Auflösung mit --blocks-auto-pull

Alternativ können Sie das --blocks-auto-pull Flag verwenden. Polycrate pullt dann automatisch alle fehlenden Dependencies ohne Prompt:

# Bei jeder Workspace-Interaktion
polycrate run my-postgres install --blocks-auto-pull

# Bei Workflow-Ausführung
polycrate workflows run deploy-stack --blocks-auto-pull

Mit --blocks-auto-pull werden alle in der workspace.poly referenzierten Blocks automatisch von der Registry gepullt, falls sie nicht lokal vorhanden sind.

Nicht-interaktiver Modus

Mit dem Flag --non-interactive können Sie interaktive Prompts explizit deaktivieren:

polycrate run my-block install --non-interactive

In diesem Modus wird bei fehlenden Dependencies ein Fehler ausgegeben statt eines Prompts.

Manuelles Pullen von Dependencies

Sie können Dependencies auch manuell pullen:

# Block von Registry pullen (vollständiger Pfad erforderlich)
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

# Von eigener Registry pullen
polycrate blocks pull registry.my-org.com/infra/postgres:1.2.0

Vollständiger Registry-Pfad erforderlich

Kurznamen wie postgres-base:1.2.0 funktionieren nicht. Sie müssen immer den vollständigen Registry-Pfad angeben:

# ❌ Falsch
polycrate blocks pull postgres-base:1.2.0

# ✅ Korrekt
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

Dependencies in workspace.poly

Alle Dependencies werden in der workspace.poly definiert:

# workspace.poly
name: my-workspace

blocks:
  # Cluster-Block (Template von Registry)
  - name: k8s
    from: registry.my-org.com/blocks/k8s/cluster:1.0.0

  # Datenbank-Block (Template von Registry)
  - name: postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1
    kubeconfig:
      from: k8s  # Nutzt Kubeconfig vom k8s-Block
    config:
      namespace: databases

  # App-Block (lokaler Template-Block)
  - name: my-app
    from: my-app-template  # Lokaler Block in blocks/my-app-template/
    kubeconfig:
      from: k8s

Ein Level Vererbung

Es gibt nur ein Level der Vererbung: Block-Instanz → Template-Block. Keine Verkettung von from: in verschiedenen block.poly Dateien.

Dependency-Quellen

Dependencies werden in der workspace.poly definiert und können aus verschiedenen Quellen stammen:

1. Lokale Template-Blocks

# workspace.poly
blocks:
  - name: my-app
    from: base-app  # Lokaler Block in blocks/base-app/

Wenn base-app im lokalen Workspace existiert (in blocks/base-app/), wird er direkt als Template verwendet.

2. Registry-Blocks

# workspace.poly
blocks:
  - name: my-app
    from: registry.my-org.com/blocks/k8s/base-app:1.0.0

Wenn der Block nicht lokal vorhanden ist, wird er von der angegebenen Registry gepullt.

Vollständiger Registry-Pfad erforderlich

Kurznamen wie postgres-base werden nicht automatisch vom Hub gepullt. Polycrate interpretiert sie als lokale Blocks. Verwenden Sie immer den vollständigen Registry-Pfad:

# ❌ Falsch: Wird als lokaler Block interpretiert
from: postgres-base

# ✅ Korrekt: Vollständiger Registry-Pfad
from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

Praktische Workflows

Workflow 1: Projekt-Setup mit Dependencies

# 1. Workspace klonen
git clone https://github.com/myorg/my-workspace.git
cd my-workspace

# 2. Alle Dependencies automatisch pullen (bei vollständigen Registry-Pfaden in workspace.poly)
polycrate run my-app install --blocks-auto-pull

# Oder manuell:
# polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1
# polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/redis:0.1.5
# polycrate run my-app install

Workflow 2: Dependency aktualisieren

Achtung: Block-Versionen sind Singletons

Eine Block-Version kann nur einmal im Workspace existieren. Beim Pullen einer neuen Version wird der bestehende Template-Block vollständig überschrieben. Alle Block-Instanzen, die diesen Block nutzen, müssen danach aktualisiert werden!

# 1. Prüfen, welche Instanzen den Block nutzen
grep -r "cloudnative-pg" workspace.poly

# 2. Neue Version pullen (überschreibt alte Version!)
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0

# 3. ALLE Block-Instanzen in workspace.poly anpassen:
#    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0

# 4. Workspace validieren
polycrate workspace compile

# 5. Testen
polycrate run my-postgres install

Wichtig: Wenn mehrere Instanzen denselben Template-Block nutzen, müssen alle from:-Referenzen aktualisiert werden, sonst kompiliert der Workspace nicht.

Workflow 3: CI/CD mit Dependencies

# .github/workflows/deploy.yml
name: Deploy

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install Polycrate
        run: |
          curl -sSL https://get.polycrate.io | bash

      - name: Deploy with auto-pull
        run: |
          polycrate run my-app install --blocks-auto-pull

Dependency-Management Best Practices

1. Explizite Versionierung verwenden

Immer explizite Versionen angeben

Block-Instanzen sollten die Block-Version im from:-Key immer explizit angeben, um böse Überraschungen zu vermeiden. Ohne explizite Version riskieren Sie, dass polycrate block pull unbeabsichtigt eine andere Version installiert.

Nutzen Sie spezifische Versionen für stabile Dependencies:

# workspace.poly
blocks:
  # ✅ Gut: Explizite, spezifische Version
  - name: my-postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

  # ❌ Schlecht: Latest (kann unerwartet brechen)
  - name: my-postgres-bad
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:latest

  # ❌ Schlecht: Keine Version (riskiert unerwartete Updates)
  - name: my-postgres-risky
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg

Warum explizite Versionen kritisch sind:

  • Reproduzierbarkeit: Identisches Verhalten bei jedem polycrate block pull
  • Keine Überraschungen: Kein versehentliches Up-/Downgrade
  • Team-Konsistenz: Alle Team-Mitglieder arbeiten mit derselben Version
  • Rollback-Sicherheit: Bei Problemen wissen Sie genau, zu welcher Version Sie zurückkehren können

2. Lokale Kopien für Anpassungen

Wenn Sie eine Dependency anpassen müssen, pullen Sie sie lokal:

# Dependency lokal pullen
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

# Jetzt ist sie in blocks/cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg/
# Sie können sie anpassen (z.B. Playbooks modifizieren)

# workspace.poly - Block nutzt automatisch die lokale Kopie
blocks:
  - name: my-postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # Nutzt lokale Kopie wenn vorhanden

3. Private Registries

Für private/proprietäre Blocks nutzen Sie private Registries:

# workspace.poly
blocks:
  - name: my-internal-app
    from: registry.mycompany.com/apps/base-app:1.0.0

Authentifizierung über: 

# Docker Registry Login
docker login registry.mycompany.com

# Polycrate nutzt Docker-Credentials
polycrate blocks pull registry.mycompany.com/apps/base-app:1.0.0

4. Dependency-Dokumentation

Dokumentieren Sie Dependencies in der Workspace-README:

# my-workspace

## Externe Dependencies

| Block | Template | Version | Beschreibung |
|-------|----------|---------|--------------|
| `my-postgres` | `cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg` | `1.2.0` | PostgreSQL-Datenbank |
| `my-app` | `registry.mycompany.com/apps/base-app` | `1.0.0` | Interne App |

## Installation

    polycrate run my-postgres install --blocks-auto-pull

Troubleshooting

Dependency nicht gefunden

Error: Block 'postgres-base' not found

Lösung: 

# Manuell pullen mit vollständigem Registry-Pfad
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

# Oder auto-pull verwenden (bei vollständigem Registry-Pfad in workspace.poly)
polycrate run my-app install --blocks-auto-pull

Vollständiger Registry-Pfad

Stellen Sie sicher, dass in workspace.poly der vollständige Registry-Pfad verwendet wird, z.B. from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

Block-Versionen sind Singletons

Kritisches Konzept verstehen

Eine Block-Version kann nur einmal im Workspace existieren. Das bedeutet:

  • Jede Version eines Blocks (cloudnative-pg:1.3.1, cloudnative-pg:1.4.0) ist ein separater Template-Block
  • Beim polycrate block pull wird der bestehende Template-Block vollständig überschrieben
  • Alle Instanzen eines Blocks müssen dieselbe Version referenzieren

Beispiel: Mehrere Instanzen, eine Version:

# workspace.poly - Beide Instanzen teilen sich denselben Template-Block
blocks:
  - name: app-database
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # ← Teilen sich
    config:
      namespace: app

  - name: analytics-database
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # ← denselben Block!
    config:
      namespace: analytics

Was passiert bei einem Update:

# Neue Version pullen - ÜBERSCHREIBT den bestehenden Block!
polycrate block pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0

Nach dem Pull müssen alle Instanzen aktualisiert werden:

# workspace.poly - ALLE from:-Referenzen anpassen!
blocks:
  - name: app-database
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0  # ← Aktualisiert

  - name: analytics-database
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0  # ← Aktualisiert

Workflow für sichere Updates

  1. Vor dem Pull: grep -r "block-name" workspace.poly um alle Instanzen zu finden
  2. Pull durchführen: polycrate block pull ...
  3. Alle Referenzen aktualisieren: Jeden from:-Eintrag in workspace.poly anpassen
  4. Validieren: polycrate workspace compile ausführen
  5. Testen: Alle betroffenen Instanzen einzeln testen

Verschiedene Versionen im Workspace

Wenn Sie verschiedene Versionen desselben Blocks benötigen (z.B. für einen schrittweisen Rollout), können Sie beide Versionen parallel installieren:

# workspace.poly - Verschiedene Versionen sind möglich
blocks:
  - name: postgres-stable
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1  # Stabile Version
    config:
      namespace: production

  - name: postgres-canary
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0  # Neue Version zum Testen
    config:
      namespace: canary

In diesem Fall existieren beide Template-Blocks nebeneinander: - blocks/cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1/ - blocks/cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.4.0/

Best Practice

Verschiedene Versionen desselben Blocks im Workspace sollten nur temporär für Migrationen oder Tests verwendet werden. Für Konsistenz und einfachere Wartung empfehlen wir eine einheitliche Version pro Workspace.

Registry nicht erreichbar

Error: Failed to pull from registry

Lösung: 

# Prüfen Sie Netzwerk und Authentifizierung
docker login cargo.ayedo.cloud

# Alternativen Hub verwenden
export POLYCRATE_HUB_URL=https://alternative-hub.example.com

Polycrate Hub

Von ayedo bereitgestellte, öffentlich verfügbare Blocks finden Sie im Polycrate Hub:

🌐 hub.polycrate.io

Der Hub bietet: - Fertige Blocks für häufige Use Cases (Postgres, Redis, Nginx, etc.) - Versionierte Releases für stabile Deployments - Dokumentation für jeden Block - Suchfunktion um passende Blocks zu finden

Zusammenhang mit anderen Konzepten

  • Vererbung: Dependencies basieren auf der from: Vererbung
  • Registry: Dependencies werden von OCI-Registries gepullt
  • Polycrate Hub: Zentrale Registry für öffentliche Blocks
  • Blocks: Dependencies sind Blocks, die von anderen Blocks genutzt werden

Auto-Pull im Alltag

Fügen Sie --blocks-auto-pull als Alias hinzu für einfacheren Alltags-Workflow: 

alias pr='polycrate run --blocks-auto-pull'
pr my-app install  # Pullt automatisch alle Dependencies