Konfiguration¶

Diese Seite dokumentiert alle Konfigurationsmöglichkeiten in Polycrate – von Workspace-Einstellungen bis zu Block-Instanzen.

Wichtige Einschränkungen¶

Keine Template-Substitution in .poly-Dateien

In workspace.poly und block.poly ist keine Template-Substitution möglich – weder Jinja2, Bash, noch andere Templating-Mechanismen. Die Dateien werden als reine YAML-Konfiguration geparst.

Was NICHT funktioniert¶

# ❌ FALSCH: Jinja2-Syntax funktioniert NICHT
blocks:
  - name: cert-manager
    from: cargo.ayedo.cloud/ayedo/k8s/cert-manager:0.4.0
    config:
      letsencrypt:
        cloudflare:
          api_token: "{{ secrets.cloudflare_api_token }}"  # ❌ Wird NICHT ersetzt!

# ❌ FALSCH: Bash-Variablen funktionieren NICHT
blocks:
  - name: my-app
    config:
      database_url: "${DATABASE_URL}"      # ❌ Wird NICHT ersetzt!
      home_dir: "$HOME/data"               # ❌ Wird NICHT ersetzt!

# ❌ FALSCH: Environment-Referenzen funktionieren NICHT
blocks:
  - name: my-app
    config:
      environment: ${ENV:-production}       # ❌ Wird NICHT ersetzt!

Was stattdessen funktioniert¶

1. Secrets in separater Datei (secrets.poly):

# workspace.poly - Nicht-sensitive Konfiguration
blocks:
  - name: cert-manager
    from: cargo.ayedo.cloud/ayedo/k8s/cert-manager:0.4.0
    config:
      letsencrypt:
        solver:
          type: dns01
          provider: cloudflare

# secrets.poly - Sensitive Konfiguration (wird verschlüsselt)
blocks:
  - name: cert-manager
    config:
      letsencrypt:
        cloudflare:
          api_token: "actual-secret-token-here"  # ✅ Echter Wert

2. Konfiguration wird zur Runtime gemerged:

Polycrate merged workspace.poly und secrets.poly automatisch zur Laufzeit. Die Werte aus secrets.poly überschreiben/ergänzen die Werte aus workspace.poly.

3. Templates in Ansible-Playbooks:

Jinja2-Templating funktioniert in Ansible-Playbooks und Templates, NICHT in .poly-Dateien:

# playbooks/deploy.yml - Hier funktioniert Jinja2!
- name: Deploy with config
  kubernetes.core.k8s:
    state: present
    definition:
      apiVersion: v1
      kind: Secret
      metadata:
        name: "{{ block.name }}-secrets"
      data:
        api_token: "{{ block.config.letsencrypt.cloudflare.api_token | b64encode }}"

{# templates/config.yml.j2 - Hier funktioniert Jinja2! #}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ block.name }}-config
data:
  environment: {{ block.config.environment }}

Warum diese Einschränkung?¶

Sicherheit: Keine unbeabsichtigte Code-Execution in Konfigurationsdateien
Vorhersagbarkeit: Konfiguration ist deterministisch und reviewbar
Einfachheit: YAML-Parsing ohne zusätzliche Template-Engine
Separation of Concerns: Konfiguration (.poly) vs. Logik (Ansible/Playbooks)

→ Secrets-Verwaltung | Ansible-Integration

Workspace-Konfiguration (workspace.poly)¶

Die Konfiguration des Workspace (default: workspace.poly) enthält die Einstellungen für einen Workspace und muss im Root-Verzeichnis des Workspace liegen.

Benutzerdefinierte Konfigurationsdatei¶

Sie können eine benutzerdefinierte Konfigurationsdatei für den Workspace angeben:

polycrate run my-block install --workspace-config pfad/zu/workspace-config.yml

Dies kann insbesondere bei der Verwendung von Polycrate in CI/CD-Pipelines hilfreich sein.

Vollständige workspace.poly Struktur¶

# workspace.poly
name: my-workspace
organization: my-org

config:
  # Workspace-weite Konfiguration
  environment: production

  # Container-Image Konfiguration (optional)
  image:
    reference: cargo.ayedo.cloud/library/polycrate
    version: latest

blocks:
  - name: my-app
    from: cargo.ayedo.cloud/ayedo/k8s/my-app:1.0.0
    config:
      replicas: 3

workflows:
  - name: deploy-all
    steps:
      - name: deploy-app
        block: my-app
        action: install

Workspace-Felder¶

Feld	Typ	Pflicht	Beschreibung
`name`	string	✅	Eindeutiger Workspace-Name
`organization`	string	❌	Organisation/Team
`config`	map	❌	Workspace-weite Konfiguration
`blocks`	list	❌	Block-Instanzen
`workflows`	list	❌	Workflow-Definitionen

Naming-Regeln¶

Der Name des Workspace ist auf bestimmte Zeichen beschränkt: ^[a-zA-Z]+([-/]?[a-zA-Z0-9]+)+$. Diese Einschränkung gilt für alle Namensangaben in Polycrate.

Erlaubte Namen:

✅ acme-production-1
✅ my-app
✅ internal-monitoring-1

Nicht erlaubte Namen:

❌ _my-workspace (beginnt mit Underscore)
❌ my_workspace (Underscores nicht erlaubt)
❌ 123-workspace (beginnt mit Zahl)

Block-Konfiguration (workspace.poly)¶

Blocks werden in der workspace.poly instanziiert. Jede Block-Instanz referenziert einen Template-Block via from:.

Block aus Registry¶

blocks:
  - name: kubernetes-cluster
    from: cargo.ayedo.cloud/ayedo/k8s/cluster:1.2.3
    config:
      node_count: 3
      region: eu-central-1

Lokaler Template-Block¶

blocks:
  - name: my-app
    from: my-app-template  # Block in blocks/my-app-template/
    config:
      port: 8080

Block mit Kubeconfig-Referenz¶

blocks:
  - name: k8s
    from: cargo.ayedo.cloud/ayedo/k8s/cluster:1.0.0

  - name: my-app
    from: cargo.ayedo.cloud/ayedo/k8s/my-app:1.0.0
    kubeconfig:
      from: k8s  # Nutzt Kubeconfig vom k8s-Block
    config:
      namespace: production

Block mit Inventory-Referenz¶

blocks:
  - name: infrastructure
    from: cargo.ayedo.cloud/ayedo/infra/servers:1.0.0

  - name: my-service
    from: cargo.ayedo.cloud/ayedo/services/my-service:1.0.0
    inventory:
      from: infrastructure  # Nutzt Inventory vom infrastructure-Block

Block-Instanz-Felder¶

Feld	Typ	Pflicht	Beschreibung
`name`	string	✅	Eindeutiger Instanz-Name im Workspace
`from`	string	❌	Template-Block (Registry oder lokal)
`config`	map	❌	Block-spezifische Konfiguration
`kubeconfig.from`	string	❌	Block-Name für Kubeconfig-Vererbung
`inventory.from`	string	❌	Block-Name für Inventory-Vererbung

Explizite Versionen verwenden

Immer die Version im from:-Key angeben: from: .../block:1.2.3 → Details zu Block-Versionen

Secrets-Konfiguration (secrets.poly)¶

Sensitive Konfiguration gehört in secrets.poly (gleiches Format wie workspace.poly):

# secrets.poly
blocks:
  - name: my-app
    config:
      database_password: geheim
      api_key: abc123

  - name: cert-manager
    config:
      letsencrypt:
        cloudflare:
          api_token: "cloudflare-api-token-here"

Nach Verschlüsselung wird secrets.poly.age erstellt:

polycrate workspace encrypt

Merge-Verhalten

secrets.poly wird zur Laufzeit mit workspace.poly gemerged. Werte aus secrets.poly überschreiben/ergänzen Werte aus workspace.poly für denselben Block.

→ Workspace-Verschlüsselung

YAML-Anker für wiederverwendbare Werte¶

YAML-Anker (&) und Aliase (*) ermöglichen die Definition und Wiederverwendung von Werten innerhalb einer workspace.poly. Das reduziert Redundanz und macht die Konfiguration wartbarer.

Grundprinzip¶

# Definition eines Ankers mit &name
my-value: &my-anchor "wiederverwendbarer-wert"

# Verwendung des Ankers mit *name
other-key: *my-anchor  # → "wiederverwendbarer-wert"

Anwendung in workspace.poly¶

# YAML-Anker am Dateianfang definieren
domain: &domain acme-corp.com
s3_endpoint: &s3_endpoint https://s3.loopback.ayedo.cloud
keycloak_base_url: &keycloak_base_url https://id.acme-corp.com
ingress_class: &ingress_class nginx
letsencrypt_issuer: &letsencrypt_issuer letsencrypt-production

name: acme-production-1
organization: acme

blocks:
  - name: keycloak
    from: cargo.ayedo.cloud/ayedo/k8s/keycloak:0.4.1
    config:
      ingress:
        host: *keycloak_base_url  # → https://id.acme-corp.com
        class: *ingress_class     # → nginx
        tls:
          issuer: *letsencrypt_issuer

  - name: mattermost
    from: cargo.ayedo.cloud/ayedo/k8s/mattermost:0.1.0
    config:
      s3:
        endpoint: *s3_endpoint  # → https://s3.loopback.ayedo.cloud
      ingress:
        class: *ingress_class

Häufige Anker-Patterns¶

Anker	Typischer Wert	Verwendung
`&domain`	`example.com`	Basis-Domain für alle Services
`&s3_endpoint`	`https://s3.provider.com`	S3-kompatibles Storage
`&keycloak_base_url`	`https://id.example.com`	SSO-Provider URL
`&letsencrypt_issuer`	`letsencrypt-production`	cert-manager Issuer
`&ingress_class`	`nginx`	Ingress Controller Class

Vorteile¶

Single Source of Truth – Werte nur einmal definieren
Konsistenz – Alle Blöcke nutzen garantiert dieselben Werte
Wartbarkeit – Änderungen nur an einer Stelle
Fehlerreduktion – Keine Copy-Paste-Fehler

Anker am Dateianfang definieren

Definieren Sie alle YAML-Anker vor dem blocks:-Abschnitt. So sind alle Konstanten auf einen Blick sichtbar.

Anker sind datei-lokal

YAML-Anker funktionieren nur innerhalb einer einzelnen Datei. Sie können nicht zwischen workspace.poly und secrets.poly geteilt werden.

→ Ausführliche Best Practices | Vollständiges Beispiel

Container-Konfiguration¶

Das Polycrate-Image kann pro Workspace angepasst werden.

Image-Version festlegen¶

# workspace.poly
config:
  image:
    reference: cargo.ayedo.cloud/library/polycrate
    version: "0.28.0"  # Spezifische Version statt :latest

Custom Dockerfile¶

Für zusätzliche Tools erstellen Sie eine Dockerfile.poly:

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

# Zusätzliche Tools installieren (Ubuntu-basiert!)
RUN apt-get update && apt-get install -y --no-install-recommends \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*

# Image bauen und verwenden
polycrate run my-block install --build

Ubuntu-basiert

Das Polycrate-Image ist Ubuntu-basiert, nicht Alpine! Verwenden Sie apt-get, nicht apk.

CLI-Konfiguration (~/.polycrate/polycrate.yml)¶

Globale CLI-Einstellungen werden in ~/.polycrate/polycrate.yml konfiguriert:

# ~/.polycrate/polycrate.yml
api:
  enabled: true
  url: https://hub.polycrate.io
  api_key: <your-api-key>

hub:
  url: https://hub.polycrate.io
  docs_url: https://docs.ayedo.de

→ API-Integration

Best Practices¶

Explizite Versionen: Verwenden Sie spezifische Versionen für Blocks (:1.2.3 statt :latest)
Secrets separieren: Speichern Sie keine Secrets in workspace.poly – nutzen Sie secrets.poly
YAML-Anker nutzen: Definieren Sie wiederverwendbare Werte als Anker am Dateianfang
Vollständige Registry-Pfade: Verwenden Sie immer den vollständigen Registry-Pfad mit Version
Changelog pflegen: Führen Sie CHANGELOG.poly für Workspace und Blocks
Keine Templates in .poly: Jinja2/Bash nur in Ansible-Playbooks, nicht in .poly-Dateien

→ Ausführliche Best Practices

Siehe auch¶

Workspaces – Workspace-Struktur und -Organisation
Blocks – Block-Definition und Actions
Dependencies – Block-Dependencies verwalten
Vererbung – Kubeconfig/Inventory-Vererbung
CLI-Referenz – Alle verfügbaren Commands