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 --> 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 --> PB1[playbooks/]
    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/]
    BA1 --> AInv[inventory.yml]
    BA1 --> AKube[kubeconfig.yml]
    BA1 --> Cache[hosts_cache.json]

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¶

→ Ausführliche Dokumentation zu Artefakten

Workspace initialisieren¶

# Neuen Workspace erstellen
polycrate workspace 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:

$HOME/.polycrate/workspaces/
├── acme/                        # Organisation
│   ├── acme-production-1/       # Workspace
│   ├── acme-staging-1/
│   └── acme-development-1/
├── other-org/
│   └── other-org-production-1/

Naming-Schema¶

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

Beispiele:

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

Naming Rules¶

^[a-zA-Z]+([-/_]?[a-zA-Z0-9_]+)+$

Erlaubte Namen:

# Gut ✅
name: acme-production-1
organization: acme

# Gut ✅
name: internal-monitoring-1
organization: internal

# Gut ✅ (mit Unterstrichen)
name: my_workspace_v2
organization: my_org

Nicht erlaubte Namen:

# Schlecht ❌
organization: Demo GmbH      # Leerzeichen und Sonderzeichen
organization: ACME Corp.     # Punkt nicht erlaubt
name: 123-project            # Muss mit Buchstabe beginnen
name: my workspace           # Leerzeichen nicht erlaubt

Polycrate validiert diese Felder beim Laden des Workspaces und gibt eine aussagekräftige Fehlermeldung aus:

Validation error: option workspace.organization is malformed: 'Demo GmbH' (regex: `^[a-zA-Z]+([-/_]?[a-zA-Z0-9_]+)+$`)

→ 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 im Root (legacy)
/kubeconfig.yml
/kubeconfig.yaml

# ============================================
# 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¶

• 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