Registry¶

Was ist die Polycrate Registry?¶

Polycrate-Blöcke können in OCI-kompatible Registries gepusht und von ihnen gepullt werden, ähnlich wie Docker-Images. Dies ermöglicht die Verteilung und Wiederverwendung von Blocks über Teams und Organisationen hinweg.

Als Standard-Registry verwendet Polycrate cargo.ayedo.cloud, um Blöcke zu pullen oder zu pushen.

Registry-Architektur¶

flowchart TB
    Dev("Entwickler") --> Push["polycrate blocks push"]
    Push --> Package["Block wird gepackt"]
    Package --> OCI(("OCI Artifact"))
    OCI --> Registry(("OCI Registry"))

    Registry --> Pull["polycrate blocks pull"]
    Pull --> Extract["Block entpacken"]
    Extract --> Workspace["Workspace blocks/"]

    User("Nutzer") --> AutoPull["polycrate run --blocks-auto-pull"]
    AutoPull --> Check{Block lokal?}
    Check -->|Nein| Pull
    Check -->|Ja| Run["Action ausführen"]

Authentifizierung¶

Polycrate implementiert keine eigene Authentifizierung mit der Registry, sondern nutzt stattdessen Ihren lokalen Docker Credential Helper.

Um sich bei einer Registry zu authentifizieren:

# Bei Registry anmelden
docker login cargo.ayedo.cloud

# Oder bei custom Registry
docker login my-registry.com

# Credentials werden in ~/.docker/config.json gespeichert
# Polycrate nutzt diese automatisch

Registry-Konfiguration¶

Registry-URL im Block-Namen¶

Die Registry-URL muss immer im Block-Namen angegeben werden – sowohl bei pull als auch bei push:

# Vollständiger Registry-Pfad (PFLICHT)
polycrate blocks pull registry.my-org.com/team/my-block:1.0.0

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

Registry-Proxying für Airgapped Umgebungen¶

Für airgapped/on-premise Umgebungen, in denen externe Registries nicht erreichbar sind, können Sie Registry-Proxies auf Workspace-Level konfigurieren. Dies ermöglicht es, Block-Referenzen transparent von einer Registry zu einer anderen umzuleiten.

Anwendungsfall:

In einer airgapped Umgebung ohne Zugriff auf cargo.ayedo.cloud können Sie eine lokale OCI Registry wie Harbor als Proxy verwenden, die die Blocks gespiegelt hat.

Konfiguration in workspace.poly:

name: my-workspace

registry:
  endpoint: registry.enterprise.com
  # Credentials in secrets.poly auslagern (siehe unten)
  proxy:
    # Pattern-basierte Registry-Rewrites
    - from: cargo.ayedo.cloud/ayedo
      to: registry.enterprise.com/cargo-proxy/ayedo

    - from: hub.polycrate.io
      to: registry.enterprise.com/polyhub-mirror

    - from: ghcr.io/company
      to: registry.enterprise.com/github-mirror/company

blocks:
  # Diese Referenz wird automatisch umgeschrieben
  - name: k8s-nginx
    from: cargo.ayedo.cloud/ayedo/k8s/haproxy:2.0.4
    # → wird zu: registry.enterprise.com/cargo-proxy/ayedo/k8s/nginx:1.0.0

Credentials in secrets.poly:

# secrets.poly (wird bei workspace encrypt verschlüsselt)
registry:
  username: admin
  password: geheim123
  proxy:
    - from: cargo.ayedo.cloud/ayedo
      username: proxy-user
      password: proxy-geheim

Wie es funktioniert:

1. Polycrate prüft jede Block-Registry-URL gegen alle proxy-Einträge
2. Bei Match wird from durch to in der URL ersetzt
3. Optional können Pro-Proxy Credentials angegeben werden
4. Falls kein Match, wird die Original-URL verwendet

Beispiel-Rewrite-Logik:

Original:  cargo.ayedo.cloud/ayedo/k8s/haproxy:2.0.4
From:      cargo.ayedo.cloud/ayedo
To:        registry.enterprise.com/cargo-proxy/ayedo
Result:    registry.enterprise.com/cargo-proxy/ayedo/k8s/nginx:1.0.0

Mehrere Proxy-Patterns:

registry:
  proxy:
    # Spezifische Namespace-Proxies (werden zuerst geprüft)
    - from: cargo.ayedo.cloud/ayedo/k8s
      to: registry.enterprise.com/kubernetes-blocks

    # Catch-all für restliche ayedo-Blocks
    - from: cargo.ayedo.cloud/ayedo
      to: registry.enterprise.com/ayedo-mirror

    # Andere Registries
    - from: docker.io/library
      to: registry.enterprise.com/dockerhub-library

Best Practices für Registry-Proxying:

1. Spezifische Patterns zuerst: Sortieren Sie Proxies von spezifisch zu generisch
2. Credentials Management: Nutzen Sie secrets.poly für Passwörter oder docker login
3. Registry-Spiegelung: Stellen Sie sicher, dass die Proxy-Registry die Blocks enthält
4. Testing: Testen Sie die Proxy-Konfiguration mit --loglevel 2 für Debug-Output

Harbor als Registry-Proxy einrichten:

Harbor ist eine beliebte OCI-Registry für on-premise Deployments:

# workspace.poly - Harbor Proxy-Setup
registry:
  endpoint: harbor.company.com
  proxy:
    - from: cargo.ayedo.cloud
      to: harbor.company.com/proxy-cache

# secrets.poly - Credentials (verschlüsselt speichern!)
registry:
  username: admin
  password: harbor-admin-password
  proxy:
    - from: cargo.ayedo.cloud
      username: proxy-bot
      password: proxy-bot-password

In Harbor: 1. Erstellen Sie ein Projekt proxy-cache 2. Konfigurieren Sie einen Proxy-Cache-Endpoint zu cargo.ayedo.cloud 3. Harbor lädt Blocks on-demand und cached sie lokal

Troubleshooting:

# Debug-Modus aktivieren für Registry-Resolution
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/haproxy:2.0.4 --loglevel 2

# Ausgabe zeigt:
# INFO: Registry proxy match found: cargo.ayedo.cloud/ayedo/k8s/haproxy -> registry.enterprise.com/cargo-proxy/ayedo/k8s/nginx
# DEBUG: Using proxy credentials for registry: registry.enterprise.com/cargo-proxy

Blocks pullen¶

Manuelles Pullen¶

Um Blocks dynamisch aus der Registry zum Workspace hinzuzufügen:

# Block mit spezifischer Version pullen
polycrate blocks pull registry.my-org.com/infra/postgres:1.2.0

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

# Von Docker Hub pullen (falls Blocks dort gehostet)
polycrate blocks pull index.docker.io/myuser/my-block:1.0.0

Der Block wird nach blocks/<block-name>/ im Workspace heruntergeladen.

Automatisches Pullen mit --blocks-auto-pull¶

Statt Blocks manuell zu pullen, können Sie das --blocks-auto-pull Flag verwenden:

# Bei Action-Ausführung
polycrate run my-app install --blocks-auto-pull

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

# Bei Block-Inspection
polycrate blocks inspect my-app --blocks-auto-pull

Polycrate pulled dann automatisch alle fehlenden Dependencies.

Pull-Prozess¶

sequenceDiagram
    participant CLI
    participant Docker
    participant Registry
    participant Workspace

    CLI->>CLI: Parse block name & Version
    CLI->>Docker: Check credentials
    Docker-->>CLI: Credentials OK
    CLI->>Registry: Request manifest
    Registry-->>CLI: Manifest & Layers
    CLI->>Registry: Download layers
    Registry-->>CLI: Layer data
    CLI->>CLI: Extract package
    CLI->>Workspace: Write blocks/<name>/
    CLI-->>CLI: Pull complete

Blocks deinstallieren¶

# Block aus Workspace entfernen
polycrate blocks uninstall postgres-base

# Oder manuell löschen
rm -rf blocks/postgres-base

Blocks pushen¶

Basic Push¶

Um einen Block in eine OCI-kompatible Registry zu pushen:

# Vollständiger Registry-Pfad (PFLICHT)
polycrate blocks push registry.my-org.com/team/my-block

# Zu cargo.ayedo.cloud pushen
polycrate blocks push cargo.ayedo.cloud/my-org/k8s/my-block

Beispiel:

# blocks/my-block/block.poly
name: my-block
version: 1.2.3

# Pusht als my-registry.com/team/my-block:1.2.3
polycrate blocks push my-registry.com/team/my-block

Push-Prozess¶

sequenceDiagram
    participant CLI
    participant Workspace
    participant Docker
    participant Registry

    CLI->>Workspace: Read block.poly
    Workspace-->>CLI: Name & Version
    CLI->>CLI: Package block
    CLI->>Docker: Check credentials
    Docker-->>CLI: Credentials OK
    CLI->>Registry: Push manifest
    CLI->>Registry: Push layers
    Registry-->>CLI: Push complete
    CLI-->>CLI: Success

Beispiele¶

# Zu eigener Registry pushen
polycrate blocks push registry.my-org.com/team/my-block

# Zu cargo.ayedo.cloud pushen
polycrate blocks push cargo.ayedo.cloud/my-org/k8s/my-block

# Zu Docker Hub pushen
polycrate blocks push index.docker.io/myuser/my-block

Praktische Beispiele¶

Beispiel 1: Team-Library aufbauen¶

# 1. Basis-Block erstellen (Name = vollständiger Registry-Pfad)
mkdir -p my-workspace/blocks/registry.mycompany.com/infra/postgres
cd my-workspace/blocks/registry.mycompany.com/infra/postgres
cat > block.poly <<EOF
name: registry.mycompany.com/infra/postgres
version: 1.0.0
kind: k8sapp
actions:
  - name: install
    playbook: playbooks/install.yml
EOF

# 2. Zur Team-Registry pushen
polycrate blocks push registry.mycompany.com/infra/postgres

# 3. Team-Mitglieder können pullen
polycrate blocks pull registry.mycompany.com/infra/postgres:1.0.0

Beispiel 2: Multi-Registry Setup¶

# workspace.poly mit mehreren Registries
name: my-workspace

blocks:
  # Von cargo.ayedo.cloud (ayedo Blocks)
  - name: postgres
    from: cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

  # Von privater Company Registry
  - name: company-base
    from: registry.mycompany.com/infra/base:2.0.0

  # Von Docker Hub
  - name: some-tool
    from: index.docker.io/someuser/tool:1.0.0

Beispiel 3: CI/CD Pipeline¶

# .github/workflows/publish-block.yml
name: Publish Block

on:
  push:
    tags:
      - 'v*'

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

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

      - name: Docker Login
        run: echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login registry.mycompany.com -u "${{ secrets.REGISTRY_USERNAME }}" --password-stdin

      - name: Push Block
        run: polycrate blocks push registry.mycompany.com/infra/my-block

Beispiel 4: Versionierte Releases¶

# Version in block.poly erhöhen
sed -i 's/version: 1.0.0/version: 1.1.0/' blocks/my-block/block.poly

# Git Commit und Tag
git add blocks/my-block/block.poly
git commit -m "Bump my-block to v1.1.0"
git tag v1.1.0
git push --tags

# Push zur Registry
polycrate blocks push registry.mycompany.com/infra/my-block
# Pushed als my-block:1.1.0

OCI-Kompatible Registries¶

Polycrate unterstützt alle OCI-kompatiblen Registries:

Öffentliche Registries¶

• cargo.ayedo.cloud: ayedo-betriebene Registry für Polycrate Blocks
• Docker Hub: index.docker.io
• GitHub Container Registry: ghcr.io
• Quay.io: quay.io

Self-Hosted Registries¶

• Harbor: Open-Source Enterprise Registry
• GitLab Container Registry: Integriert in GitLab
• Artifactory: JFrog Artifactory
• Nexus Repository: Sonatype Nexus
• Distribution: Docker Registry (Distribution)

Cloud Provider Registries¶

• AWS ECR: <account-id>.dkr.ecr.<region>.amazonaws.com
• Azure ACR: <registry-name>.azurecr.io
• Google GCR: gcr.io, eu.gcr.io, us.gcr.io
• DigitalOcean Registry: registry.digitalocean.com

Block Packaging¶

Wenn Sie einen Block pushen, erstellt Polycrate ein OCI Artifact mit folgender Struktur:

OCI Artifact: my-block:1.2.3
├── Manifest
│   ├── Config Layer (block.poly Metadata)
│   └── Content Layers
│       ├── block.poly
│       ├── templates/*
│       ├── playbooks/*
│       ├── scripts/*
│       ├── README.md
│       └── CHANGELOG.poly

Nicht gepackt werden:

• .git/ Verzeichnis
• artifacts/ Verzeichnis
• Temporäre Dateien

Best Practices¶

1. Semantische Versionierung verwenden¶

# block.poly
name: my-block
version: 1.2.3  # MAJOR.MINOR.PATCH

• MAJOR: Breaking Changes (1.x.x → 2.0.0)
• MINOR: Neue Features, rückwärtskompatibel (1.2.x → 1.3.0)
• PATCH: Bugfixes (1.2.3 → 1.2.4)

2. Versionierte Tags in from: verwenden¶

# workspace.poly
blocks:
  # ✅ Gut: Pinned version mit vollem Registry-Pfad
  - 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

3. Private Registries für proprietäre Blocks¶

# Company-interne Blocks
polycrate blocks push registry.mycompany.com/infra/proprietary-block

# Öffentliche Basis-Blocks (von cargo.ayedo.cloud)
polycrate blocks pull cargo.ayedo.cloud/ayedo/k8s/cloudnative-pg:1.3.1

4. Namespace-Organisation¶

registry.mycompany.com/
├── infra/           # Infrastructure Blocks
│   ├── postgres-base
│   ├── redis-base
│   └── nginx-base
├── apps/            # Application Blocks
│   ├── webapp-base
│   └── api-base
└── tools/           # Utility Blocks
    ├── backup-tools
    └── monitoring-base

Troubleshooting¶

Authentication failed¶

Error: authentication required

# Lösung: Docker Login
docker login cargo.ayedo.cloud
# Oder für custom Registry
docker login my-registry.com

Block not found¶

Error: block 'my-block:1.0.0' not found in registry

# Prüfen ob Block existiert
docker manifest inspect cargo.ayedo.cloud/my-org/my-block:1.0.0

# Prüfen verfügbare Tags
docker search cargo.ayedo.cloud/my-org/my-block

# Richtigen Namen verwenden
polycrate blocks pull cargo.ayedo.cloud/my-org/my-block:1.0.0

Push permissions denied¶

Error: denied: insufficient permissions

# Lösung 1: Mit richtigen Credentials einloggen
docker login registry.mycompany.com -u myuser

# Lösung 2: Prüfen ob Namespace existiert
# Namespace muss existieren: registry.mycompany.com/namespace/block

# Lösung 3: Registry-Admin kontaktieren für Permissions

Version conflict¶

Error: block 'my-block' already exists with different version

# Lösung: Version in block.poly erhöhen
sed -i 's/version: 1.0.0/version: 1.0.1/' blocks/my-block/block.poly

# Dann erneut pushen
polycrate blocks push registry.mycompany.com/infra/my-block

Registry nicht erreichbar¶

Error: failed to connect to registry

# Prüfen Netzwerk-Verbindung
ping registry.mycompany.com
curl https://registry.mycompany.com/v2/

# Prüfen Docker Konfiguration
cat ~/.docker/config.json

# Prüfen Proxy-Einstellungen
echo $HTTP_PROXY
echo $HTTPS_PROXY

Zusammenhang mit anderen Konzepten¶

• Polycrate Hub: Öffentliche Registry für Community-Blocks
• Dependencies: Blocks können Dependencies aus Registry pullen
• Vererbung: from: stanza referenziert Registry-Blocks
• Blocks: Registry verteilt Blocks