🦕 PolyHub¶

Was ist PolyHub?¶

hub.polycrate.io ist die zentrale Registry für Blocks, die von ayedo entwickelt und bereitgestellt werden. Der PolyHub bietet eine kuratierte Sammlung von Production-Ready Blocks für häufige Infrastructure-as-Code Patterns.

Alle Blocks auf PolyHub sind: - 🆓 Open Source - Apache 2.0 lizenziert - ✅ Production-Tested - In realen Projekten eingesetzt - 📖 Gut dokumentiert - Mit README, Beispielen und CHANGELOG - 🔄 Versioniert - Semantische Versionierung - 🧪 Erweiterbar - Durch Vererbung anpassbar

Verfügbare Block-Kategorien¶

Kubernetes Applications (k8sapp)¶

Deployment von Anwendungen auf Kubernetes-Clustern:

• postgres-base - PostgreSQL mit CloudNativePG Operator
• redis-base - Redis mit Sentinel HA
• mongodb-base - MongoDB mit Replica Sets
• nginx-base - NGINX Ingress Controller
• cert-manager-base - Let's Encrypt Certificate Management
• harbor-base - Container Registry und Vulnerability Scanning
• grafana-base - Monitoring und Visualisierung
• prometheus-base - Metrics Collection und Alerting
• vault-base - Secrets Management
• rabbitmq-base - Message Broker

Kubernetes Clusters (k8scluster)¶

Provisioning von Kubernetes-Clustern:

• k3s-base - Lightweight K3s Cluster
• rke2-base - Rancher RKE2 Cluster
• talos-base - Talos Linux Kubernetes
• kubeadm-base - Vanilla Kubernetes mit kubeadm

Linux Applications (linuxapp)¶

Configuration Management für Linux-Server:

• docker-host-base - Docker Host Setup
• haproxy-base - Load Balancer
• nfs-server-base - Network File System
• backup-server-base - Borg Backup Server

Docker Applications (dockerapp)¶

Docker Compose Deployments:

• wordpress-base - WordPress mit MySQL
• nextcloud-base - Nextcloud File Sharing
• gitea-base - Git Server
• mailserver-base - Complete Mail Server Stack

Libraries (library)¶

Wiederverwendbare Basis-Blocks:

• base - Generischer Basis-Block für alle Typen
• ansible-base - Ansible-spezifische Helper
• terraform-base - Terraform-spezifische Helper

Blocks vom Hub nutzen¶

Direkt pullen¶

# Neueste Version pullen
polycrate blocks pull postgres-base

# Spezifische Version pullen
polycrate blocks pull postgres-base:1.2.0

# Mit vollständiger Hub-URL
polycrate blocks pull hub.polycrate.io/ayedo/k8s/postgres-base:1.2.0

In workspace.poly referenzieren¶

name: my-workspace

blocks:
  # Short form (ohne Registry-URL)
  - name: my-postgres
    from: postgres-base:1.2.0
    config:
      namespace: production
      app:
        persistence:
          size: 100Gi

  # Long form (mit vollständiger Hub-URL)
  - name: my-redis
    from: hub.polycrate.io/ayedo/k8s/redis-base:1.0.0
    config:
      namespace: production

Mit auto-pull verwenden¶

# Dependencies werden automatisch vom Hub gepullt
polycrate run my-postgres install --blocks-auto-pull

Hub-Integration¶

graph TB
    Hub[PolyHub<br/>hub.polycrate.io] --> Search[Block Search]
    Hub --> Browse[Browse Categories]
    Hub --> Docs[Documentation]

    Search --> Pull[polycrate blocks pull]
    Browse --> Pull
    Docs --> Pull

    Pull --> Local[Lokaler Workspace]
    Local --> Extend[Anpassen via Vererbung]
    Extend --> Deploy[Deploy]

    User[Entwickler] --> Search
    User --> Browse

    style Hub fill:#e1f5ff
    style Local fill:#e1ffe1
    style Deploy fill:#fff4e1

Praktische Beispiele¶

Beispiel 1: PostgreSQL Deployment¶

# 1. Block vom Hub pullen
polycrate blocks pull postgres-base:1.2.0

# 2. Eigenen Block erstellen der davon erbt
cat > workspace.poly <<EOF
name: my-workspace

blocks:
  - name: prod-postgres
    from: postgres-base:1.2.0
    config:
      namespace: production
      app:
        replicas: 3
        persistence:
          size: 100Gi
          storageClass: fast-ssd
        backup:
          enabled: true
          schedule: "0 2 * * *"
EOF

# 3. Deployen
polycrate run prod-postgres install --blocks-auto-pull

Beispiel 2: Complete Monitoring Stack¶

name: monitoring-workspace

blocks:
  - name: prometheus
    from: prometheus-base:2.0.0
    config:
      namespace: monitoring
      retention: 30d
      storage: 50Gi

  - name: grafana
    from: grafana-base:1.5.0
    config:
      namespace: monitoring
      datasources:
        - name: Prometheus
          type: prometheus
          url: http://prometheus:9090

  - name: alertmanager
    from: alertmanager-base:1.0.0
    config:
      namespace: monitoring
      slack:
        webhook_url: https://hooks.slack.com/services/xxx

workflows:
  - name: deploy-monitoring
    steps:
      - name: deploy-prometheus
        block: prometheus
        action: install

      - name: deploy-grafana
        block: grafana
        action: install

      - name: deploy-alertmanager
        block: alertmanager
        action: install

polycrate workflows run deploy-monitoring --blocks-auto-pull

Beispiel 3: K3s Cluster mit Apps¶

name: k3s-stack

blocks:
  # Cluster provisioning
  - name: k3s-cluster
    from: k3s-base:1.0.0
    config:
      servers: 3
      agents: 5
      version: v1.28.5+k3s1

  # Apps auf Cluster
  - name: nginx-ingress
    from: nginx-base:1.0.0
    kubeconfig:
      from: k3s-cluster

  - name: cert-manager
    from: cert-manager-base:1.0.0
    kubeconfig:
      from: k3s-cluster

  - name: my-app
    from: webapp-base:1.0.0
    kubeconfig:
      from: k3s-cluster
    config:
      domain: myapp.example.com
      replicas: 3

workflows:
  - name: deploy-complete-stack
    steps:
      - name: provision-cluster
        block: k3s-cluster
        action: provision

      - name: setup-ingress
        block: nginx-ingress
        action: install

      - name: setup-certs
        block: cert-manager
        action: install

      - name: deploy-app
        block: my-app
        action: deploy

Block-Suche¶

Im PolyHub Browser¶

Besuchen Sie hub.polycrate.io und nutzen Sie:

• Search Bar - Volltextsuche über alle Blocks
• Categories - Browsen nach Block-Typ (k8sapp, linuxapp, etc.)
• Tags - Filtern nach Tags (database, monitoring, etc.)
• Popular - Meistgenutzte Blocks
• Recent - Neueste Releases

Via CLI¶

# Blocks durchsuchen (zukünftiges Feature)
polycrate hub search postgres

# Block-Details anzeigen
polycrate hub inspect postgres-base

# Verfügbare Versionen
polycrate hub versions postgres-base

Block-Dokumentation¶

Jeder Block auf PolyHub hat standardisierte Dokumentation:

README.md¶

Enthält: - Block-Beschreibung und Features - Voraussetzungen - Installation und Usage - Konfigurationsoptionen - Beispiele - Troubleshooting

CHANGELOG.poly¶

Versionierte Änderungshistorie:

- version: 1.2.0
  date: 2025-01-30
  changes:
    - Added automated backup support
    - Improved high-availability configuration
    - Fixed connection pooling issues
  breaking_changes:
    - Renamed config.replicas to config.app.replicas

- version: 1.1.0
  date: 2025-01-15
  changes:
    - Added monitoring integration
    - Performance improvements

block.poly¶

Vollständige Block-Konfiguration mit: - Alle verfügbaren Actions - Config-Schema (als Beispiel) - Dependencies - Default-Werte

Best Practices¶

1. Pinne Versionen¶

# ✅ Gut: Spezifische Version
from: postgres-base:1.2.0

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

2. Lese die Dokumentation¶

# Block lokal pullen um Doku zu lesen
polycrate blocks pull postgres-base:1.2.0

# README lesen
cat blocks/postgres-base/README.md

# Changelog prüfen
cat blocks/postgres-base/CHANGELOG.poly

3. Teste in Staging zuerst¶

# Staging environment
blocks:
  - name: staging-postgres
    from: postgres-base:1.3.0  # Neue Version testen
    config:
      namespace: staging

# Production environment (alte Version)
blocks:
  - name: prod-postgres
    from: postgres-base:1.2.0  # Bewährte Version
    config:
      namespace: production

4. Customization via Vererbung¶

# Basis-Block vom Hub
- name: custom-postgres
  from: postgres-base:1.2.0
  config:
    namespace: production
    # Nur nötige Werte überschreiben
    app:
      persistence:
        size: 200Gi  # Custom value
      # Alles andere wird geerbt

5. Updates regelmäßig prüfen¶

# Prüfe verfügbare Versionen
polycrate hub versions postgres-base

# Neuere Version pullen
polycrate blocks pull postgres-base:1.3.0

# Changelog review
cat blocks/postgres-base/CHANGELOG.poly

# Testen, dann workspace.poly updaten

Community und Contribution¶

Feature Requests¶

Wenn Sie ein Feature für einen Hub-Block wünschen:

1. Prüfen Sie die Block-Dokumentation
2. Öffnen Sie ein Issue im Block-Repository
3. Beschreiben Sie Use Case und gewünschte Funktionalität

Bug Reports¶

Falls Sie einen Bug finden:

1. Prüfen Sie ob Bug bereits gemeldet wurde
2. Sammeln Sie Informationen:
3. Block-Name und Version
4. Polycrate Version
5. Fehlermeldung / Logs
6. Reproduktionsschritte
7. Öffnen Sie ein Issue mit diesen Details

Eigene Blocks vorschlagen¶

Um einen Block zum PolyHub beizutragen:

1. Entwickeln Sie den Block
2. Dokumentieren Sie ihn vollständig (README, CHANGELOG)
3. Testen Sie ihn gründlich
4. Kontaktieren Sie ayedo für Review
5. Nach Approval wird er auf PolyHub veröffentlicht

Hub vs. Private Registry¶

Recommendation: - Nutzen Sie PolyHub als Basis für Standard-Patterns - Erstellen Sie eigene Blocks (erben von Hub) für Custom-Logic - Teilen Sie diese in Private Registry mit Ihrem Team

# Kombinierter Ansatz
blocks:
  # Basis von PolyHub
  - name: company-postgres-base
    from: hub.polycrate.io/ayedo/postgres-base:1.2.0
    # Pushen zur Company Registry
    # polycrate blocks push registry.company.com/infra/postgres-base

  # Custom App verwendet Company Block
  - name: my-app-postgres
    from: registry.company.com/infra/postgres-base:1.0.0
    config:
      namespace: production

Zusammenhang mit anderen Konzepten¶

• Registry: PolyHub ist eine spezielle OCI-Registry
• Dependencies: Hub-Blocks sind Dependencies
• Vererbung: Hub-Blocks werden häufig als Basis-Blocks vererbt
• Blocks: PolyHub verteilt Blocks