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

Standard-Registry festlegen¶

Sie können die Standard-Registry auf mehrere Arten festlegen:

1. CLI Flag:

polycrate blocks push my-block --registry-url my-registry.com

2. Umgebungsvariable:

export POLYCRATE_REGISTRY_URL=my-registry.com
polycrate blocks push my-block

3. workspace.poly:

name: my-workspace

config:
  registry:
    url: my-registry.com
    base_image: my-registry.com/library/scratch:latest

Registry-URL im Block-Namen¶

Sie können die Registry-URL auch direkt im Block-Namen angeben, genau wie bei Docker:

# Mit Registry-URL im Namen
polycrate blocks pull my-registry.com/team/my-block:1.0.0

# Ohne Registry-URL (verwendet Standard-Registry)
polycrate blocks pull my-block:1.0.0

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
  username: ${REGISTRY_USERNAME}
  password: ${REGISTRY_PASSWORD}
  proxy:
    # Pattern-basierte Registry-Rewrites
    - from: cargo.ayedo.cloud/ayedo
      to: registry.enterprise.com/cargo-proxy/ayedo
      username: proxy-user
      password: ${PROXY_PASSWORD}

    - 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/nginx:1.0.0
    # → wird zu: registry.enterprise.com/cargo-proxy/ayedo/k8s/nginx:1.0.0

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/nginx:1.0.0
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 Umgebungsvariablen für Passwörter
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:

# Harbor Proxy-Setup
registry:
  endpoint: harbor.company.com
  username: admin
  password: ${HARBOR_PASSWORD}
  proxy:
    - from: cargo.ayedo.cloud
      to: harbor.company.com/proxy-cache
      username: proxy-bot
      password: ${HARBOR_PROXY_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 ayedo/k8s/nginx --loglevel 2

# Ausgabe zeigt:
# INFO: Registry proxy match found: cargo.ayedo.cloud/ayedo/k8s/nginx -> 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 postgres-base:1.2.0

# Block mit "latest" Version pullen
polycrate blocks pull postgres-base

# Von custom Registry pullen
polycrate blocks pull my-registry.com/team/postgres-base:1.2.0

# Von Docker Hub pullen
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:

# Block zur Standard-Registry pushen
polycrate blocks push my-block

# Zu custom Registry pushen (Registry-URL im Namen)
polycrate blocks push my-registry.com/team/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

Mit spezifischer Registry¶

# Registry per Flag
polycrate blocks push my-block --registry-url my-registry.com

# Registry in Block-Namen
polycrate blocks push my-registry.com/team/my-block

# Registry in workspace.poly konfiguriert
# (siehe Registry-Konfiguration oben)
polycrate blocks push my-block

Praktische Beispiele¶

Beispiel 1: Team-Library aufbauen¶

# 1. Basis-Block erstellen
cd my-workspace/blocks/postgres-base
cat > block.poly <<EOF
name: postgres-base
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-base

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

Beispiel 2: Multi-Registry Setup¶

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

blocks:
  # Von öffentlichem Hub
  - name: postgres-base
    from: hub.polycrate.io/ayedo/postgres-base:1.0.0

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

• Polycrate Hub: hub.polycrate.io (ayedo-betrieben)
• 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 - .logs/ 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. README.md und CHANGELOG.poly pflegen¶

# README.md
# my-block

PostgreSQL Database Block für Kubernetes.

## Features
- Automated backups
- High availability
- Monitoring integration

## Usage
\`\`\`bash
polycrate run my-postgres install
\`\`\`

# CHANGELOG.poly
- version: 1.2.0
  date: 2025-01-30
  changes:
    - Added backup automation
    - Improved HA configuration
    - Fixed connection pooling issue

3. Versionierte Tags in from: verwenden¶

# ✅ Gut: Pinned version
name: my-app
from: postgres-base:1.2.0

# ❌ Schlecht: Latest (kann unerwartet brechen)
name: my-app
from: postgres-base:latest

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

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

# Öffentliche Basis-Blocks
polycrate blocks pull hub.polycrate.io/ayedo/postgres-base:1.0.0

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