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:

Polycrate prüft jede Block-Registry-URL gegen alle proxy-Einträge
Bei Match wird from durch to in der URL ersetzt
Optional können Pro-Proxy Credentials angegeben werden
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:

Spezifische Patterns zuerst: Sortieren Sie Proxies von spezifisch zu generisch
Credentials Management: Nutzen Sie secrets.poly für Passwörter oder docker login
Registry-Spiegelung: Stellen Sie sicher, dass die Proxy-Registry die Blocks enthält
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: 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/*
│       ├── *.yml (Playbooks)
│       ├── scripts/*
│       ├── README.md
│       └── CHANGELOG.poly

Standardmäßig ausgeschlossen:

.specs/ – Spezifikationen und Entwicklungsdokumente (Default)

Weitere Verzeichnisse und Dateien können über Exclude-Patterns konfiguriert werden.

Exclude-Patterns beim Push

Beim Pushen eines Blocks können bestimmte Verzeichnisse und Dateien vom OCI-Image ausgeschlossen werden. Die Pattern-Syntax entspricht .dockerignore/.gitignore.

Standard-Verhalten

Standardmäßig wird .specs/ in jedem Block-Verzeichnis vom Push ausgeschlossen:

# .specs/ wird automatisch ausgeschlossen
polycrate blocks push cargo.ayedo.cloud/my-org/my-block

`--exclude` Flag

Mit dem --exclude Flag können eigene Patterns angegeben werden. Das Flag kann mehrfach verwendet oder mit kommaseparierten Werten übergeben werden:

# Einzelne Patterns
polycrate blocks push cargo.ayedo.cloud/my-org/my-block \
  --exclude .specs \
  --exclude .git \
  --exclude "*.log"

# Kommasepariert
polycrate blocks push cargo.ayedo.cloud/my-org/my-block \
  --exclude ".specs,.git,*.log"

# Pfad relativ zum Block-Root ausschließen
polycrate blocks push cargo.ayedo.cloud/my-org/my-block \
  --exclude test/fixtures

Flag überschreibt den Default

Sobald --exclude explizit angegeben wird, ersetzt es den Default [".specs"] vollständig. Wenn .specs weiterhin ausgeschlossen werden soll, muss es explizit mit angegeben werden:

polycrate blocks push ... --exclude .specs --exclude .git

Ausschluss deaktivieren

Um alle Excludes zu deaktivieren und den vollständigen Block-Inhalt zu pushen:

polycrate blocks push cargo.ayedo.cloud/my-org/my-block --exclude ""

Konfiguration in `polycrate.yml`

Statt das Flag bei jedem Push anzugeben, kann eine persistente Ausschlussliste in ~/.polycrate/polycrate.yml hinterlegt werden:

# ~/.polycrate/polycrate.yml
registry:
  url: cargo.ayedo.cloud
  block_push_exclude:
    - .specs
    - .git
    - "*.log"
    - test/fixtures

Die Priorität ist:

--exclude Flag (wenn explizit angegeben)
registry.block_push_exclude in polycrate.yml
Default: [".specs"]

Pattern-Syntax

Die Syntax entspricht vollständig .dockerignore und unterstützt:

Zeichen	Bedeutung	Beispiel	Trifft
`*`	Beliebige Zeichen ohne Pfad-Separator	`*.log`	`error.log`, `access.log`
`**`	Beliebige Zeichen inkl. Pfad-Separatoren (rekursiv)	`logs/**`	`logs/a.log`, `logs/sub/b.log`
`?`	Einzelnes beliebiges Zeichen	`access?.log`	`access0.log`, `accessA.log`
`[abc]`	Zeichenklasse	`file[123].txt`	`file1.txt`, `file2.txt`

Pattern ohne / werden gegen den Basisnamen auf jeder Verzeichnistiefe geprüft:

.specs      → .specs/ überall im Block-Verzeichnisbaum
*.log       → alle .log-Dateien auf jeder Ebene

Pattern mit / werden gegen den vollständigen relativen Pfad vom Block-Root geprüft:

test/fixtures   → nur test/fixtures/ relativ zum Block-Root
logs/**         → alles unterhalb von logs/
**/build        → jedes build-Verzeichnis auf beliebiger Tiefe

Beispiele

# Default: .specs/ wird ausgeschlossen
polycrate blocks push cargo.ayedo.cloud/my-org/my-block

# .specs und .git ausschließen
polycrate blocks push cargo.ayedo.cloud/my-org/my-block \
  --exclude .specs --exclude .git

# Alle Log-Dateien ausschließen
polycrate blocks push cargo.ayedo.cloud/my-org/my-block \
  --exclude "*.log"

# Bestimmtes Unterverzeichnis ausschließen
polycrate blocks push cargo.ayedo.cloud/my-org/my-block \
  --exclude test/fixtures

# Rekursiv: alles in docs/ ausschließen
polycrate blocks push cargo.ayedo.cloud/my-org/my-block \
  --exclude "docs/**"

# Inhalt des gepushten Images verifizieren
crane export cargo.ayedo.cloud/my-org/my-block:1.0.0 - | tar t

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:-Angabe referenziert Registry-Blocks
Blocks: Registry verteilt Blocks

Registry

Registry

Was ist die Polycrate Registry?

Registry-Architektur

Authentifizierung

Registry-Konfiguration

Registry-URL im Block-Namen

Registry-Proxying für Airgapped Umgebungen

Blocks pullen

Manuelles Pullen

Automatisches Pullen mit --blocks-auto-pull

Pull-Prozess

Blocks deinstallieren

Blocks pushen

Basic Push

Push-Prozess

Beispiele

Praktische Beispiele

Beispiel 1: Team-Library aufbauen

Beispiel 2: Multi-Registry Setup

Beispiel 3: CI/CD Pipeline

Beispiel 4: Versionierte Releases

OCI-Kompatible Registries

Öffentliche Registries

Self-Hosted Registries

Cloud Provider Registries

Block Packaging

Exclude-Patterns beim Push

Standard-Verhalten

--exclude Flag

Ausschluss deaktivieren

Konfiguration in polycrate.yml

Pattern-Syntax

Beispiele

Best Practices

1. Semantische Versionierung verwenden

2. Versionierte Tags in from: verwenden

3. Private Registries für proprietäre Blocks

4. Namespace-Organisation

Troubleshooting

Authentication failed

Block not found

Push permissions denied

Version conflict

Registry nicht erreichbar

Zusammenhang mit anderen Konzepten

`--exclude` Flag

Konfiguration in `polycrate.yml`