Empfehlungen¶

Kurze Betriebsregeln für Workspaces und Blocks. Schema und Feldreferenzen stehen in den Konzeptseiten — hier nur das „wie wir’s machen“.

Workspace-Organisation¶

Speicherort und Struktur¶

Workspaces unter $HOME/.polycrate/workspaces/<organization>/<workspace>/ ablegen, damit polycrate workspace list, polycrate workspace clone und die üblichen Pfade stimmen.

acme-production-1/
├── workspace.poly
├── secrets.poly          # bzw. secrets.poly.age
├── CHANGELOG.poly
├── Dockerfile.poly       # optional
├── inventory.yml         # optional, ein Inventory pro Workspace
├── blocks/
├── artifacts/
└── README.md

Naming¶

Schema: <org>-<purpose>-<count> (z. B. acme-production-1). Organization-Namen slugifiziert (acme, nicht ACME Corp.).

→ Regex und Regeln: Namenskonventionen

Eine Umgebung = ein Workspace¶

Keine Env-Variablen oder Templates in .poly-Dateien. Production und Staging sind getrennte Workspaces mit eigenen literalen Werten.

# acme-production-1/workspace.poly
name: acme-production-1
organization: acme
blocks:
  - name: my-app
    from: cargo.ayedo.cloud/acme/k8s/my-app:1.0.0
    config:
      replicas: 3

→ Warum keine Substitution: Konfiguration

Git und Changelog¶

• Regelmäßig polycrate git sync (oder add/commit/pull/push).
• Workspace-Änderungen in CHANGELOG.poly mitführen; anzeigen mit polycrate workspace changelog.

→ Git

Inventory und Kubeconfig¶

Pro Workspace ein Inventory (inventory.yml im Root) und eine Kubeconfig (artifacts/secrets/kubeconfig.yml). kubeconfig.from / inventory.from an Block-Instanzen sind Legacy.

→ Vererbung · Artefakte

Blocks¶

Versionen¶

• Immer explizites Tag im from:: …/block:1.2.3, nie bare / :latest in Production.
• Eine installierte Block-Version ist ein Singleton im Workspace — nach blocks pull alle Instanzen anpassen, dann validieren:

polycrate validate workspace-poly ./workspace.poly

→ Details: Dependencies – Singletons · Blöcke

Metadaten, Examples, CVE¶

Feldkataloge und Schema gehören in die Block-Doku:

Kurzregeln für Template-Blocks (Hub/Catalogue):

• display_name, icon_url, kind/type/flavor, app_version, Upstream-URLs setzen.
• Mindestens ein Example in examples.poly.
• Für CVE-Matching: vulnerability.products pflegen.
• Nach blocks push (CLI ≥ 0.51.3): API-display_name = Registry-URL; menschenlesbarer Titel bleibt in block.poly für Hub/lokal.

Block-Schnitt¶

Ein App-Block = eine App = ein Chart = ein Namespace. Dependencies (DB, Cache) als eigene Blocks. CHANGELOG.poly am Block pflegen (SemVer, Conventional-Commit-type).

Polycrate-Labels unter block.labels an Helm/Manifeste durchreichen.

Actions und Workflows¶

Übliche Action-Namen: install, uninstall, update, backup/restore, status, validate. Kritische Schritte mit prompt:; in CI --force. Actions idempotent halten (Ansible).

Workflows für wiederkehrende Ketten (deploy-production, backup-databases); bei Bedarf allow_failure nur bewusst setzen.

→ Actions · Workflows

Container¶

Image ist Ubuntu/Debian (apt-get, nicht apk). Zusätzliche Tools über Dockerfile.poly. Extra-Mounts: polycrate run … --mount host:container.

→ Der Polycrate Container · Konfiguration – Container

Sicherheit¶

• Pro Workspace eigene SSH-Keys unter artifacts/secrets/ (bei workspace init); keine persönlichen Keys kopieren.
• Sensible Workspaces verschlüsseln: polycrate workspace encrypt.
• Secrets nur in secrets.poly (bzw. .age), nie in workspace.poly. Keine Env-Subst in .poly.

→ Workspace-Verschlüsselung · SSH

Logging¶

polycrate --loglevel 2 run my-block install

→ CLI-Referenz

Konfiguration (Verweis)¶

YAML-Anker in workspace.poly technisch möglich, aber nicht empfohlen (CLI/API schreiben die Datei neu). Wiederkehrende Werte literal setzen.

→ Konfiguration

Siehe auch¶

• Blöcke
• Konfiguration
• Dependencies
• Namenskonventionen
• Workspaces
• Production-Beispiel