Best Practices¶

Diese Seite enthält bewährte Verfahren und Empfehlungen für die Arbeit mit Polycrate.

Workspace-Organisation¶

Workspace-Struktur¶

Halten Sie Ihre Workspace-Struktur sauber und organisiert:

my-workspace/
├── blocks/              # Blocks nach Organisation gruppieren
│   ├── infrastructure/
│   │   ├── networking/
│   │   └── security/
│   └── applications/
│       ├── backend/
│       └── frontend/
├── workflows/          # Workflows nach Zweck benennen
│   ├── deploy-all.yml
│   ├── backup.yml
│   └── rollback.yml
├── artifacts/          # Automatisch generiert
├── .logs/             # Automatisch generiert
├── workspace.poly     # Hauptkonfiguration
└── Dockerfile.poly    # Custom Container-Image (optional)

Workspace-Namen¶

Verwenden Sie aussagekräftige Namen: production-cluster, dev-environment
Vermeiden Sie generische Namen wie workspace1, test
Folgen Sie einem konsistenten Namensschema in Ihrer Organisation

Git-Integration¶

Versionieren Sie Ihren Workspace mit Git:

# .gitignore
.logs/
artifacts/
*.log
id_rsa
id_rsa.pub
kubeconfig.yaml
workspace.poly.enc  # Wenn verschlüsselt

Wichtig: Committen Sie keine sensiblen Daten wie SSH-Keys oder unverschlüsselte Credentials!

Block-Management¶

Block-Naming¶

Verwenden Sie eine hierarchische Namensstruktur:

# Gut
ayedo/k8s/cluster
ayedo/docker/registry
company/team/component

# Schlecht
cluster
my-block-1

Block-Versionen¶

Verwenden Sie Semantic Versioning (SemVer): 1.2.3
Pinnen Sie Versionen in Production-Umgebungen
Testen Sie Updates in Dev-Umgebungen vor dem Roll-out

# workspace.poly
blocks:
  - name: ayedo/k8s/cluster
    version: 1.2.3  # Gepinnte Version
  - name: ayedo/monitoring/prometheus
    version: latest  # Nur in Dev empfohlen

Block-Wiederverwendung¶

Erstellen Sie wiederverwendbare Blocks:

# block.poly - Parametrisierbar
name: generic-app

config:
  app_name: ${APP_NAME}
  port: ${PORT:-8080}
  replicas: ${REPLICAS:-3}

actions:
  - name: deploy
    playbook: deploy.yml

Mehrfach instanziieren über dynamische Blocks:

# workspace.poly
blocks:
  - name: frontend
    from: generic-app
    config:
      app_name: frontend
      port: 3000
  - name: backend
    from: generic-app
    config:
      app_name: backend
      port: 8080

Action-Design¶

Action-Namen¶

Verwenden Sie konsistente Action-Namen:

install - Initiale Installation
uninstall - Vollständige Deinstallation
update - Updates und Upgrades
start / stop - Dienste starten/stoppen
backup / restore - Backup-Operationen
status - Status-Abfrage
validate - Validierung

Prompts verwenden¶

Verwenden Sie Prompts für kritische Operationen:

actions:
  - name: delete-database
    prompt:
      message: "WARNUNG: Dies löscht alle Daten! Fortfahren?"
    script:
      - echo "Lösche Datenbank..."

In Produktionsumgebungen können diese mit --force übersprungen werden.

Idempotenz¶

Gestalten Sie Actions idempotent - mehrfaches Ausführen sollte zum gleichen Ergebnis führen:

actions:
  - name: install
    playbook: install.yml  # Ansible ist idempotent

Fehlerbehandlung¶

Nutzen Sie allow_failure in Workflows strategisch:

workflows:
  - name: deploy
    allow_failure: false  # Standard - stoppt bei Fehler
    steps:
      - name: backup
        block: database
        action: backup
        allow_failure: true  # Weitermachen wenn Backup fehlschlägt
      - name: deploy
        block: app
        action: install

Workflows¶

Workflow-Organisation¶

Erstellen Sie Workflows für häufige Aufgaben:

# Deployment-Workflow
workflows:
  - name: deploy-production
    prompt:
      message: "Production-Deployment starten?"
    steps:
      - name: backup
        block: database
        action: backup
      - name: deploy-backend
        block: backend
        action: install
      - name: deploy-frontend
        block: frontend
        action: install
      - name: smoke-tests
        block: tests
        action: run

Workflow-Benennung¶

Verwenden Sie Verben: deploy-all, backup-databases, update-cluster
Fügen Sie Umgebung hinzu: deploy-production, deploy-staging
Seien Sie spezifisch: rollback-to-previous-version statt rollback

Konfiguration¶

Umgebungsvariablen¶

Verwenden Sie Umgebungsvariablen für sensible Daten:

# workspace.poly
config:
  database:
    host: ${DB_HOST}
    password: ${DB_PASSWORD}
    user: ${DB_USER:-admin}  # Mit Default-Wert

# .env (nicht committen!)
DB_HOST=prod-db.example.com
DB_PASSWORD=secret

Konfiguration pro Umgebung¶

Verwenden Sie verschiedene Workspace für verschiedene Umgebungen:

workspaces/
├── production/
│   └── workspace.poly
├── staging/
│   └── workspace.poly
└── development/
    └── workspace.poly

Verschlüsselung¶

Experimental Feature

Workspace-Verschlüsselung ist ein experimentelles Feature und kann sich in zukünftigen Versionen ändern.

Verschlüsseln Sie Workspaces mit sensiblen Daten:

# Verschlüsseln
polycrate workspace encrypt

# Status prüfen
polycrate workspace status

# Entschlüsseln für Bearbeitung
polycrate workspace decrypt

Container-Nutzung¶

Custom Dockerfile.poly¶

Erweitern Sie das Polycrate-Image nur wenn nötig:

# Dockerfile.poly
FROM cargo.ayedo.cloud/library/polycrate:latest

# Installiere zusätzliche Tools
RUN apk add --no-cache \
    nodejs \
    npm

# Installiere spezifische CLI-Tools
RUN npm install -g some-cli-tool

Performance¶

Verwenden Sie --pull false wenn Sie das Image bereits haben
Verwenden Sie --build false wenn kein Custom Dockerfile.poly.poly vorhanden ist
Nutzen Sie --local für einfache Bash-Scripts (wenn alle Tools lokal vorhanden)

# Schnelle Ausführung
polycrate run my-block status --pull false --build false

# Lokal für einfache Scripte
polycrate run my-block validate --local

Mounts¶

Mounten Sie nur notwendige Verzeichnisse:

# Zusätzliche Daten mounten
polycrate run my-block deploy --mount /home/user/data:/data

Sicherheit¶

SSH-Keys¶

Generieren Sie dedizierte SSH-Keys pro Workspace
Verwenden Sie SSH-Passphrases ⚠️ Experimental:

Experimental Feature

SSH-Key-Passphrase-Support ist ein experimentelles Feature und kann sich in zukünftigen Versionen ändern.

# SSH-Key mit Passphrase generieren
ssh-keygen -t ed25519 -f ./id_rsa -C "workspace@example.com"

# Passphrase in Datei speichern (verschlüsselt)
echo "my-passphrase" > ssh-passphrase.poly

# Workspace verschlüsseln
polycrate workspace encrypt

Nutzen Sie --ssh-use-passphrase für geschützte Keys

Secrets¶

Speichern Sie Secrets niemals im Klartext in der Workspace-Konfiguration
Nutzen Sie Workspace-Verschlüsselung für sensible Konfigurationen
Verwenden Sie externe Secret-Management-Tools (Vault, etc.)

Registry-Zugriff¶

Authentifizieren Sie sich vor dem Push/Pull von privaten Blocks:

# Docker login verwenden
docker login cargo.ayedo.cloud

# Dann Block pushen
polycrate block push private/my-block

Artefakte¶

Artefakt-Organisation¶

Organisieren Sie Artefakte strukturiert:

# Artefakte werden automatisch in artifacts/blocks/<block-name>/ gespeichert
config:
  artifacts:
    - name: kubeconfig
      path: kubeconfig.yaml
    - name: certificates
      path: certs/
    - name: backup
      path: backups/${DATE}.tar.gz

Artefakt-Cleanup¶

Nutzen Sie prune Actions für Aufräumarbeiten:

actions:
  - name: prune
    script:
      - find artifacts/blocks/my-block -name "*.log" -mtime +7 -delete
      - find artifacts/blocks/my-block/backups -mtime +30 -delete

Testing¶

Snapshot-Testing¶

Testen Sie Ihre Konfiguration mit Snapshots:

# Snapshot generieren und prüfen
polycrate run my-block install --snapshot > snapshot.yml

# Snapshot validieren
cat snapshot.yml | grep "expected_value"

Dry-Runs¶

Wenn möglich, implementieren Sie Dry-Run-Funktionalität:

config:
  dry_run: ${DRY_RUN:-false}

actions:
  - name: deploy
    playbook: deploy.yml  # Ansible unterstützt --check

# Mit Dry-Run
DRY_RUN=true polycrate run my-block deploy

Performance-Optimierung¶

Dependency-Management¶

Minimieren Sie Dependencies zwischen Blocks:

# Gut - lose gekoppelt
blocks:
  - name: database
  - name: app
    # Dependencies über Artefakte statt direkter Abhängigkeit

# Schlecht - tight coupling
blocks:
  - name: app
    config:
      db_connection: ${blocks.database.config.connection_string}

Parallele Workflows¶

Nutzen Sie parallele Steps wo möglich:

workflows:
  - name: deploy-all
    steps:
      # Diese Steps können parallel laufen
      - name: deploy-service-a
        block: service-a
        action: install
      - name: deploy-service-b
        block: service-b
        action: install
      - name: deploy-service-c
        block: service-c
        action: install

Logging¶

Verwenden Sie angemessene Log-Levels:

# Normaler Betrieb
polycrate run my-block install

# Mehr Details für Debugging
polycrate run my-block install --loglevel 2

# Minimale Ausgabe
polycrate run my-block install --loglevel 0

Dokumentation¶

Block-README¶

Jeder Block sollte eine README.md enthalten:

# Block-Name

## Beschreibung
Kurze Beschreibung des Blocks

## Konfiguration
\`\`\`yaml
config:
  parameter1: description
  parameter2: description
\`\`\`

## Actions
- `install` - Beschreibung
- `uninstall` - Beschreibung

## Dependencies
- Block X
- Tool Y (bereits im Polycrate-Container)

## Beispiele
\`\`\`bash
polycrate run my-block install
\`\`\`

Workspace-Dokumentation¶

Dokumentieren Sie Ihren Workspace:

# Production Workspace

## Übersicht
Dieser Workspace verwaltet die Production-Infrastruktur

## Blocks
- `infrastructure/network` - Netzwerk-Setup
- `infrastructure/storage` - Storage-Konfiguration
- `applications/backend` - Backend-Services
- `applications/frontend` - Frontend-Services

## Workflows
- `deploy-all` - Vollständiges Deployment
- `backup` - Backup aller Services
- `rollback` - Rollback zu vorheriger Version

## Wartung
- Backups laufen täglich um 2:00 Uhr
- Updates werden Sonntags eingespielt