Workspaces¶

Was auch immer Sie mit Polycrate bauen passiert in einem Workspace. Der Workspace enthält Konfiguration, Credentials und Lifecycle-Artefakte, die beim Ausführen von Blöcken entstehen. Ein Workspace ist im Grunde genommen nur ein Ordner auf Ihrer Festplatte der mit Hilfe von git oder anderen Mechanismen versioniert und synchronisiert werden kann.

Der Workspace kann mit Hilfe der Workspace-Konfiguration zusammengestellt werden.

Workspace Directory Layout¶

Ein Workspace folgt einer definierten Verzeichnisstruktur:

graph TB
    WS[my-workspace/] --> Config[workspace.poly]
    WS --> Inv[inventory.yml]
    WS --> Secrets[secrets.poly]
    WS --> DF[Dockerfile.poly]
    WS --> CL[CHANGELOG.poly]
    WS --> Blocks[blocks/]
    WS --> Arts[artifacts/]

    Blocks --> B1[block-1/]
    Blocks --> B2[block-2/]

    B1 --> BP1[block.poly]
    B1 --> CL1[CHANGELOG.poly]
    B1 --> RM1[README.md]
    B1 --> IN1[install.yml]
    B1 --> T1[templates/]

    Arts --> SecretsDir[secrets/]
    Arts --> BlockArts[blocks/]

    SecretsDir --> IdRsa[id_rsa]
    SecretsDir --> IdRsaPub[id_rsa.pub]
    SecretsDir --> WSKube[kubeconfig.yml]
    SecretsDir --> B1Sec[block-1/]
    B1Sec --> DbPwd[database.pwd]

    BlockArts --> BA1[block-1/]

Wichtige Verzeichnisse und Dateien¶

Workspace-Root¶

blocks/ – Block-Verzeichnisse¶

Jeder Block hat sein eigenes Unterverzeichnis unter blocks/:

artifacts/secrets/ – Sensible Dateien¶

artifacts/blocks// – Block-Artefakte¶

Unter artifacts/blocks/<BLOCKNAME>/ liegen vom jeweiligen Block erzeugte Dateien (je nach Block unterschiedlich). Eine Datei hosts_cache.json wird von aktuellen Polycrate-Versionen nicht mehr angelegt (ältere Workspaces können sie noch enthalten).

→ Ausführliche Dokumentation zu Artefakten

.state.poly – Operationaler State¶

.state.poly wird automatisch von der CLI nach jedem Action Run aktualisiert und im Workspace-Root abgelegt. Es dient der Koordination zwischen CLI, API und Operator: welche Komponente verwaltet welchen Block.

# .state.poly – Beispiel
cli:
  polycrate-operator:
    last_action: install
    last_action_at: "2026-02-25T10:00:00Z"
    last_action_exit_code: 0
api:
  polycrate-operator:
    managed_since: "2026-02-01T00:00:00Z"

• Kein Config-Override – .state.poly enthält keinen Block-Inhalt, nur operationalen State.
• Git-versioniert – Das File wird committed und ist für alle sichtbar.
• Konflikt-Erkennung – Wenn ein Block sowohl von der CLI als auch von der API verwaltet wird, bricht polycrate run mit einer Fehlermeldung ab.
• Fehlendes File ist kein Fehler – Der erste Action Run erstellt die Datei.

Konflikt auflösen: Ein Block darf nur von einer Komponente verwaltet werden. Bei Konflikt wählen Sie einen dieser Wege:

Workspace initialisieren¶

# Neuen Workspace erstellen
polycrate workspace init
# oder Kurzform:
polycrate init

# Mit SSH-Keys (werden in artifacts/secrets/ abgelegt)
polycrate workspace init --with-ssh-keys

# Mit Git-Repository
polycrate workspace init --git

Workspace-Organisation¶

Empfohlene Verzeichnisstruktur¶

Workspaces sollten unter $HOME/.polycrate/workspaces/ organisiert werden. Empfohlen ist die Segmentierung:

$HOME/.polycrate/workspaces/<organization>/<name>

Das ist keine Pflicht – jeder beliebige Pfad funktioniert, solange Sie ihn mit --workspace/-w angeben. Die Struktur hilft aber insbesondere im Zusammenspiel mit der Polycrate API und wenn Sie als Managed Service Provider viele Organisationen betreuen: bessere Übersicht, klare Zuordnung und angemessene Isolation zwischen Kunden-Workspaces.

$HOME/.polycrate/workspaces/
├── acme/                        # organization: acme
│   ├── acme-production-1/       # name: acme-production-1
│   ├── acme-staging-1/
│   └── acme-development-1/
├── other-org/
│   └── other-org-production-1/

Naming-Schema¶

Workspace-Namen folgen oft dem Schema: $org-$purpose-$count

Beispiele:

• acme-production-1 – Erste Produktionsumgebung von Acme
• acme-staging-1 – Staging-Umgebung
• startup-dev-1 – Entwicklungsumgebung

name und organization müssen zudem den gleichen Namensregeln wie alle Polycrate-Bezeichner genügen (Regex, erlaubte Zeichen).

→ Namenskonventionen – zentrale Referenz inkl. Muster ^[a-zA-Z]+([-/_]?[a-zA-Z0-9_]+)+$ und Beispiele

Beim Laden des Workspaces validiert Polycrate diese Felder; bei Verstößen erscheint eine entsprechende Fehlermeldung.

→ Ausführliche Best Practices

Workspaces auflisten¶

Der workspace list Command zeigt Workspaces aus der Polycrate API oder aus dem lokalen Workspace-Verzeichnis an.

Remote-Modus (Standard)¶

Wenn die Polycrate API konfiguriert ist, werden Workspaces aus der API geladen:

# API-Workspaces (Standard)
polycrate workspace list

# Mit Filter
polycrate workspace list --filter production

# Tabellenausgabe
polycrate workspace list --no-pager

Action-Menü bei Auswahl (Remote):

• open – Öffnet den Workspace in der Polycrate UI
• gitlab – Öffnet das GitLab-Repository
• clone – Klont das Repository lokal

Lokal-Modus¶

Mit --local werden Workspaces aus ~/.polycrate/workspaces/ gescannt:

# Lokale Workspaces
polycrate workspace list --local

# Mit Filter
polycrate workspace list --local --filter production

# Detaillierte Tabellenausgabe
polycrate workspace list --local --no-pager -v

Action-Menü bei Auswahl (Lokal):

• open – Zeigt Workspace-Details und Pfad
• status – Ruft den Workspace-Status ab
• git-sync – Synchronisiert Git-Änderungen

→ CLI-Referenz: workspace list

Hybride Workspaces (Code + Workspace)¶

In der Praxis werden Workspaces oft gemeinsam mit Quellcode verwaltet – beispielsweise bei Softwareprojekten, die mit Polycrate gebaut und deployed werden. Die polycrate-cli selbst ist ein solches Beispiel: Go-Quellcode und Polycrate-Workspace koexistieren im selben Repository.

Workspace Core-Dateien¶

Diese Dateien und Ordner gehören exklusiv zum Polycrate-Workspace und sollten von Build-Prozessen (Docker, CI/CD) ausgeschlossen werden:

Pflicht-Dateien¶

Optionale Workspace-Dateien¶

Standard-Verzeichnisse¶

Sensible Dateien (artifacts/secrets/)¶

.gitignore für hybride Workspaces¶

Bei hybriden Workspaces (Code + Polycrate) sollte .gitignore alle sensiblen Polycrate-Dateien ausschließen:

# ============================================
# Polycrate Workspace - Sensitive Files
# ============================================

# Unverschlüsselte Secrets (NIEMALS committen!)
secrets.poly
id_rsa
id_rsa.pub

# Sensible Artifacts
artifacts/secrets/*
!artifacts/secrets/*/
!artifacts/secrets/*.age
artifacts/secrets/*/*
!artifacts/secrets/*/*.age

# Kubeconfig (liegt unter artifacts/secrets/kubeconfig.yml – wird durch artifacts/secrets/* erfasst)
# Inventory im Workspace-Root ist nicht sensibel und wird committed
# inventory.yml

# ============================================
# Polycrate Workspace - Optional excludes
# ============================================

# Build-Artefakte (falls vorhanden)
dist/

# Verschlüsselungs-Marker beibehalten
!.workspace-encrypted

.dockerignore für hybride Workspaces¶

Bei Docker-Builds ist es kritisch, dass keine Workspace-spezifischen Dateien ins Image gelangen:

# ============================================
# Polycrate Workspace - ALLE ausschließen!
# ============================================

# Workspace-Konfiguration (nicht für Runtime benötigt)
workspace.poly
secrets.poly
secrets.poly.age
CHANGELOG.poly
inventory.yml

# Workspace-Verzeichnisse
blocks/
artifacts/

# SSH-Keys (NIEMALS ins Image!)
id_rsa
id_rsa.pub
ssh-passphrase.poly

# Encryption Marker
.workspace-encrypted

# Custom Polycrate Dockerfile (nicht für App-Build)
Dockerfile.poly

# ============================================
# Development & Documentation
# ============================================

# Specs und Cursor Rules
.specs/
.cursor/

# Documentation
*.md
!README.md  # Optional: README im Image behalten

# Git
.git/
.gitignore
.gitlab-ci.yml

# IDE
.vscode/
.idea/

Beispiel: polycrate-cli Repository¶

Die polycrate-cli demonstriert einen hybriden Workspace:

polycrate-cli/
├── # === Go-Quellcode ===
├── main.go
├── go.mod
├── go.sum
├── cmd/                    # CLI-Commands
├── pkg/                    # Packages
│
├── # === Docker ===
├── Dockerfile              # Production-Build
├── Dockerfile.poly         # Polycrate Container (optional)
│
├── # === Polycrate Workspace ===
├── workspace.poly          # ← Workspace-Konfiguration
├── CHANGELOG.poly          # ← Release-Changelog
├── blocks/                 # ← Block-Definitionen
│   ├── app/                #    Release-Management
│   ├── cargo.ayedo.cloud/  #    Registry-Blocks
│       └── ayedo/
│           └── build-tools/
│               ├── golang/ #    Go-Build
│               └── docker/ #    Docker-Build
├── artifacts/              # ← Generierte Dateien
│   ├── secrets/            #    SSH-Keys, Kubeconfigs
│   └── blocks/             #    Block-Artefakte
│
├── # === Build Output ===
├── dist/                   # Go-Binaries + Archives
│
├── # === Sonstiges ===
├── .gitignore
├── .dockerignore
├── Makefile
└── README.md

Best Practices für hybride Workspaces¶

1. Klare Trennung: Workspace-Dateien (workspace.poly, blocks/, artifacts/) sind Infrastruktur-Konfiguration, nicht Quellcode.

2. Secrets nie unverschlüsselt: Aktivieren Sie Workspace-Verschlüsselung bevor Sie committen.

3. Git-Hooks nutzen: Polycrate kann automatisch Pre-Commit-Hooks installieren, die vor unverschlüsselten Secrets warnen:

   polycrate workspace encrypt --install-git-hook
   

4. CI/CD-Separation: In CI/CD-Pipelines sollte der Workspace separat behandelt werden:

   # .gitlab-ci.yml Beispiel
   build:
     script:
       - polycrate run golang build
       - polycrate run docker push
     only:
       changes:
         - "**/*.go"
         - "go.mod"
         - "Dockerfile"
   

5. Docker Multi-Stage: Nutzen Sie Multi-Stage-Builds um sicherzustellen, dass nur benötigte Binaries im finalen Image landen:

   # Build-Stage
   FROM golang:1.23 AS builder
   COPY . /src
   RUN go build -o /app/binary .
   
   # Runtime-Stage (minimal, keine Workspace-Dateien)
   FROM alpine:latest
   COPY --from=builder /app/binary /usr/local/bin/
   

Zusammenhang mit anderen Konzepten¶

• Namenskonventionen: Regex und gültige Namen für name und organization
• Blocks: Workspaces enthalten und orchestrieren Blocks
• Artefakte: Persistente Daten werden in artifacts/ gespeichert
• Verschlüsselung: Secrets werden automatisch verschlüsselt
• Git-Integration: Versionskontrolle und Synchronisation
• Best Practices: Empfehlungen für Workspace-Organisation