PolyHub¶

Was ist PolyHub?¶

hub.polycrate.io ist die zentrale Plattform für das Polycrate-Ökosystem mit drei Kernfunktionen:

1. Block Marketplace & Showroom – Durchsuchen, entdecken und inspizieren von Polycrate Blocks
2. CLI-Download-Plattform – Bereitstellung der Polycrate CLI für alle Plattformen
3. Update-Check-Server – Automatische Versionsprüfung für polycrate update

Architektur¶

graph TB
    subgraph "Container Registry (Harbor)"
        Proj1[Project: ayedo/k8s]
        Proj2[Project: ayedo/linux]
        Proj3[Project: library]
    end

    subgraph "PolyHub (Showroom)"
        API[API Server]
        Web[Web Interface]
        CLI_DL[CLI Downloads]
    end

    Proj1 -->|Webhooks| API
    Proj2 -->|Webhooks| API
    Proj3 -->|Scheduled Sync| API
    API --> Web
    API --> CLI_DL

    User[Entwickler] --> Web
    User --> CLI_DL
    Polycrate[Polycrate CLI] --> API
    Polycrate -->|Pull/Push| Proj1

Hub als Showroom für die Registry¶

Zusammenspiel Hub ↔ Registry:

Wie das Hub Blocks importiert:

1. Registry-Verknüpfung: Ein Hub ist mit genau einer Container Registry verbunden
2. Projekt-Import: Das Hub kann mehrere Repositories (in Harbor: "Projekte") importieren
3. Webhooks: Bei Push-Events in der Registry wird das Hub automatisch benachrichtigt
4. Scheduled Sync: Zusätzlich synchronisiert das Hub regelmäßig mit der Registry
5. Block-Interpretation: Das Hub liest die Block-Struktur aus und präsentiert:
6. Verfügbare Versionen (Tags)
7. block.poly – Konfigurationsschema und Actions
8. README.md – Dokumentation
9. CHANGELOG.poly – Änderungshistorie

Block-Referenzierung:

registry.my-org.com / ayedo / k8s / postgres : 1.2.0
└── Registry URL ──┘ └─ Project ─┘ └ Block ┘ └ Tag ┘

Wenn ein Block-Name keine Registry-URL enthält, nimmt Polycrate an, dass der Block lokal im blocks/ Verzeichnis liegt.

Zugriff auf das Hub¶

Web Interface¶

Besuchen Sie hub.polycrate.io:

• Block Browser – Alle verfügbaren Blocks durchsuchen
• Suche – Volltextsuche über Blocks, Beschreibungen und Tags
• Block Details – Versions, README, CHANGELOG und block.poly anzeigen
• CLI Downloads – Polycrate CLI für alle Plattformen herunterladen

CLI mit interaktiver TUI¶

Der polycrate hub list Command bietet eine interaktive TUI zum Durchsuchen:

# Interaktive TUI (Standard)
polycrate hub list

# Mit Vorfilter
polycrate hub list --filter postgres

# Nach Block-Typ filtern
polycrate hub list --kind k8sapp

# Tabellenausgabe ohne TUI
polycrate hub list --no-tui

TUI-Navigation:

Action-Menü nach Auswahl:

• view-versions – Alle verfügbaren Versionen anzeigen
• view-block – block.poly der neuesten Version anzeigen
• view-readme – README anzeigen
• copy-name – Block-Name für workspace.poly ausgeben

Block-Details inspizieren¶

# Block-Details (block.poly)
polycrate hub inspect infra/postgres

# README anzeigen
polycrate hub inspect infra/postgres --readme

# Changelog anzeigen
polycrate hub inspect infra/postgres --changelog

# Spezifische Version
polycrate hub inspect infra/postgres:1.2.0

CLI-Downloads und Updates¶

Das Hub dient als zentrale Download-Plattform für die Polycrate CLI:

# Update auf neueste Version
polycrate update

# Update auf spezifische Version
polycrate update 0.28.0

# Verfügbare Versionen anzeigen
polycrate version --check

Die CLI prüft automatisch beim Start auf verfügbare Updates und zeigt eine Benachrichtigung an.

→ Installation & Updates

Blocks verwenden¶

In workspace.poly referenzieren¶

name: my-workspace

blocks:
  # Vollständiger Registry-Pfad (PFLICHT für Remote-Blocks)
  - name: my-postgres
    from: registry.my-org.com/infra/postgres:1.2.0
    config:
      namespace: production
      replicas: 3

Mit auto-pull verwenden¶

# Block wird automatisch von der Registry gepullt wenn nicht lokal vorhanden
polycrate run my-postgres install --blocks-auto-pull

Manuell pullen¶

# Block von der Registry pullen
polycrate blocks pull registry.my-org.com/infra/postgres:1.2.0

Block-Dokumentation¶

Jeder Block im Hub hat standardisierte Dokumentation:

README.md¶

Enthält:

• Block-Beschreibung und Features
• Voraussetzungen
• Installation und Usage
• Konfigurationsoptionen
• Beispiele
• Troubleshooting

CHANGELOG.poly¶

Versionierte Änderungshistorie im YAML-Format:

- version: "1.2.0"
  date: "2025-01-30"
  type: feat
  message: "Automated backup support"
  description: |
    - Added automated backup support
    - Improved high-availability configuration
    - Fixed connection pooling issues

- version: "1.1.0"
  date: "2025-01-15"
  type: feat
  message: "Monitoring integration"

block.poly¶

Vollständige Block-Konfiguration mit:

• Alle verfügbaren Actions
• Config-Schema (als Beispiel/Defaults)
• Dependencies und Vererbung

Self-Hosting¶

Das PolyHub kann selbst gehostet werden für:

• Private Blocks – Interne Blocks für Ihr Team
• Air-Gapped Environments – Offline-Nutzung
• Custom Branding – Eigenes Look & Feel

Architektur¶

Ein Self-Hosted Setup besteht aus zwei Komponenten:

┌─────────────────────────────────────────────────────────┐
│                    Ihre Infrastruktur                   │
├─────────────────────────┬───────────────────────────────┤
│   OCI Registry          │   PolyHub (lizenziert)        │
│   registry.my-org.com   │   hub.my-org.com              │
│                         │                               │
│   • Speichert Blocks    │   • Showroom für Registry     │
│   • OCI-Artefakte       │   • Web-Interface             │
│   • Versionierung       │   • CLI-Downloads             │
│   • Access Control      │   • Block-Dokumentation       │
└─────────────────────────┴───────────────────────────────┘

Voraussetzungen¶

• Gültige PolyHub-Lizenz von ayedo
• OCI-kompatible Registry (Harbor empfohlen)
• Kubernetes-Cluster für das Hub-Deployment
• Webhook-Konfiguration zwischen Registry und Hub

Deployment¶

Nach Erhalt der Lizenz erhalten Sie Zugang zum polyhub Block:

# workspace.poly
blocks:
  - name: polyhub
    from: cargo.ayedo.cloud/ayedo/k8s/polyhub
    config:
      domain: hub.my-org.com
      registry_url: registry.my-org.com
      license_key: "{{ secrets.polyhub_license }}"

→ Registry – Details zu OCI-Registries, Harbor-Setup und Airgapped-Konfiguration

Best Practices¶

1. Immer vollständigen Registry-Pfad verwenden¶

# ✅ Gut: Vollständiger Registry-Pfad mit Version
from: registry.my-org.com/infra/postgres:1.2.0

# ❌ Schlecht: Ohne Registry (wird als lokal interpretiert)
from: postgres:1.2.0

# ❌ Schlecht: Latest (kann unerwartet brechen)
from: registry.my-org.com/infra/postgres:latest

2. Lese die Dokumentation¶

# README und Changelog vor Nutzung im Hub lesen
polycrate hub inspect infra/postgres --readme
polycrate hub inspect infra/postgres --changelog

3. Teste in Staging zuerst¶

Verwenden Sie separate Workspaces für Staging und Production:

~/.polycrate/workspaces/
├── acme-staging-1/    # Neue Block-Versionen testen
└── acme-production-1/ # Bewährte Versionen

4. Updates regelmäßig prüfen¶

# Verfügbare Versionen eines Blocks im Hub anzeigen
polycrate hub inspect infra/postgres --versions

# Changelog der neuen Version prüfen
polycrate hub inspect infra/postgres:1.3.0 --changelog

MCP-Integration für AI-Assistenten¶

Das Hub ist über den Polycrate MCP Server für AI-Assistenten zugänglich:

→ MCP Server Integration

Zusammenhang mit anderen Konzepten¶

• Registry: PolyHub synchronisiert mit OCI-Registries – technische Details zu Pull/Push, Authentifizierung und Proxying
• Dependencies: Hub-Blocks als Dependencies nutzen
• Vererbung: Hub-Blocks als Basis-Blocks vererben
• Blocks: PolyHub macht Blocks discoverable