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.

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:

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

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

# ❌ 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

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.

# ❌ 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¶

# 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¶

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

Block-Versionen sind Singletons¶

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

Keine parallelen Versionen desselben Blocks¶

Ein schrittweiser Rollout oder ein Canary mit zwei verschiedenen Tags desselben Registry-Blocks in einer workspace.poly ist nicht vorgesehen: Der Workspace arbeitet mit genau einer installierten Version dieser Vorlage.

Stattdessen:

• Anderer Workspace (oder Klon) für Tests mit einer neueren from:-Version
• Nacheinander: Version in allen from:-Zeilen anheben, pullen, validieren (polycrate workspace compile), deployen
• Getrennte Umgebungen (z. B. staging vs. production) mit jeweils eigener workspace.poly und einer konsistenten Version pro Umgebung

Registry nicht erreichbar¶

Error: Failed to pull from registry

Lösung (OCI-Registry):

# Netzwerk und Authentifizierung für die Registry, von der Sie pullen
# (Hostname aus Ihrem from:-Pfad, z. B. cargo.ayedo.cloud)
docker login cargo.ayedo.cloud
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

Der Polycrate Hub (Weboberfläche zur Suche und Dokumentation) ist kein Docker-Registry-Endpunkt und ersetzt kein docker login. Authentifizierung fürs Pull von Block-Images erfolgt immer gegen die OCI-Registry, die im from:-Pfad steht.

Hub-URL nur für die Hub-Website/API (Browse, Metadaten), nicht fürs Pull:

export POLYCRATE_HUB_URL=https://hub.polycrate.io

Eine „alternative Hub“-URL ändert nicht, von welcher Registry polycrate blocks pull Images bezieht – dafür ist ausschließlich der from:-Pfad in der workspace.poly maßgeblich.

Polycrate Hub¶

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

hub.polycrate.io

Der Hub bietet unter anderem:

• Fertige Blocks für häufige Use Cases (Postgres, Redis, Nginx, usw.)
• 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: Katalog und Dokumentation öffentlicher Blocks (nicht identisch mit der OCI-Registry)
• Blocks: Dependencies sind Blocks, die von anderen Blocks genutzt werden

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