Empfehlungen

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:

Thema Quelle
Empfohlene block.poly-Felder Blöcke – Metadaten
examples.poly Blöcke – Examples
vulnerability.products Blöcke – Vulnerability Products · API

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

Level Einsatz
0 CI / minimal
1 Alltag (Default)
2 Debug einer Action
3 Trace (selten) 
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