Konfiguration¶

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

Wichtige Einschränkungen¶

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:

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

1. Sicherheit: Keine unbeabsichtigte Code-Execution in Konfigurationsdateien
2. Vorhersagbarkeit: Konfiguration ist deterministisch und reviewbar
3. Einfachheit: YAML-Parsing ohne zusätzliche Template-Engine
4. 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.config ist kein beliebiges Key-Value-Mapping: Beim Laden des Workspaces wird es in die typisierte Struktur WorkspaceConfig (Polycrate CLI) überführt. Erlaubt sind nur die unten genannten YAML-Schlüssel (in der Datei ohne Unterstriche, z. B. blocksroot, artifactsroot). Zusätzliche Schlüssel unter config: werden beim Einlesen in dieses Struct nicht übernommen (z. B. kein freies environment: auf Workspace-Ebene – Umgebungs-/App-Werte gehören in blocks[].config oder in Playbooks).

Unter config: existiert zusätzlich die optionale Sektion release (gleiche Einrückung wie image, blocksroot, …). Sie wird von polycrate release finalize aus der rohen workspace.poly gelesen und ist nicht Teil von WorkspaceConfig, wirkt aber für Release-Automation. → Release-Lifecycle, CLI-Referenz: polycrate release

# workspace.poly (Auszug)
name: my-workspace
organization: my-org
version: 1.0.0

config:
  image:
    reference: cargo.ayedo.cloud/library/polycrate
    version: "0.31.0"
  blocksroot: blocks
  logsroot: .logs
  blocksconfig: block.poly
  workspaceconfig: workspace.poly
  workflowsroot: workflows
  artifactsroot: artifacts
  secretsroot: artifacts/secrets
  containerroot: /workspace
  sshprivatekey: artifacts/secrets/id_rsa
  sshpublickey: artifacts/secrets/id_rsa.pub
  sshkeysource: workspace
  remoteroot: /polycrate
  dockerfile: Dockerfile.poly

  # Optional: globale Key-Value-Map (fortgeschritten)
  globals: {}

  # Optional: Pre/Post-Actions für `polycrate release finalize` (nicht WorkspaceConfig-Felder)
  release:
    post_actions:
      - block: app
        action: deploy

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.config-Schlüssel (Referenz)¶

Workspace-Felder¶

Naming-Regeln¶

Gültige Namen für Workspace, Organisation, Blöcke, Actions und Workflows sind zentral beschrieben:

→ Namenskonventionen

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 (Legacy)¶

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  # Legacy: Kubeconfig-Artefakt vom k8s-Block
    config:
      namespace: production

Block-Instanzen und Inventory¶

Das Ansible-Inventory liegt als inventory.yml im Workspace-Root und gilt für alle Blöcke dieses Workspaces.

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

Block-Instanz-Felder¶

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

→ Workspace-Verschlüsselung

YAML-Anker für wiederverwendbare Werte¶

Empfohlen: gleiche Werte mehrfach literal setzen¶

name: acme-production-1
organization: acme

blocks:
  - name: keycloak
    from: cargo.ayedo.cloud/ayedo/k8s/keycloak:0.4.1
    config:
      ingress:
        host: https://id.acme-corp.com
        class: nginx
        tls:
          issuer: letsencrypt-production

  - name: mattermost
    from: cargo.ayedo.cloud/ayedo/k8s/mattermost:0.1.0
    config:
      s3:
        endpoint: https://s3.loopback.ayedo.cloud
      ingress:
        class: nginx

Grundprinzip von YAML-Ankern (Sprachreferenz)¶

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

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

Beispiel mit Ankern (nur wenn Sie sie bewusst einsetzen)¶

Das folgende Muster funktioniert beim reinen Parsen; nach einem Schreibvorgang durch Polycrate kann es in aufgelöster Form zurückgeschrieben werden:

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
        class: *ingress_class
        tls:
          issuer: *letsencrypt_issuer

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

Häufige Anker-Namen (nur Referenz)¶

Weitere Einschränkungen¶

1. Kein Teilen mit secrets.poly – YAML-Anker gelten nur innerhalb einer Datei; zwischen workspace.poly und secrets.poly sind sie nicht nutzbar.
2. Manuelle Anker-Definition – Wenn Sie Anker dennoch verwenden, definieren Sie sie vor dem blocks:-Abschnitt, damit die Datei für Menschen lesbar bleibt (die Struktur kann bei einem Polycrate-Schreibvorgang trotzdem geändert werden).

→ Ausführliche Best Practices | Vollständiges Beispiel (historisch mit Ankern)

Container-Konfiguration¶

Das Polycrate-Image kann pro Workspace angepasst werden.

→ Der Polycrate Container (Konzept, Lifecycle, Tooling im Container) · Dockerfile.poly (Custom Image, config.dockerfile, Build mit --build)

Image-Version festlegen¶

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

Custom Dockerfile¶

Ausführlich: Dockerfile.poly (Pfad config.dockerfile, FROM-Konvention, Build).

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

Persistente System- und Community-Pakete (apt)¶

Alles, was Sie per RUN apt-get install … in das Image schreiben, steht dauerhaft in jedem Polycrate-Container dieses Workspaces zur Verfügung – z. B. Hilfsprogramme, die Ihre Playbooks oder Rollen erwarten (jq, zusätzliche Python-Module über python3-pip, Datenbank-Clients):

RUN apt-get update && apt-get install -y --no-install-recommends \
    jq \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

Ansible Galaxy: Collections und Roles dauerhaft installieren¶

ansible-galaxy ist im Polycrate-Image enthalten. Installieren Sie Collections und Roles im Build des Custom Images, damit sie nicht bei jeder Action erneut heruntergeladen werden müssen und überall gleich verfügbar sind (Standard-Pfade unter /root/.ansible/ bzw. konfigurierbar über ansible.cfg im Workspace).

Einzelne Collection und Role:

RUN ansible-galaxy collection install community.general && \
    ansible-galaxy role install geerlingguy.nginx

Über requirements.yml (empfohlen für mehrere Einträge):

Legen Sie im Workspace z. B. ansible-galaxy-requirements.yml ab und referenzieren Sie sie im Dockerfile:

# ansible-galaxy-requirements.yml (Beispiel)
---
collections:
  - name: community.general
roles:
  - name: geerlingguy.nginx

COPY ansible-galaxy-requirements.yml /tmp/ansible-galaxy-requirements.yml
RUN ansible-galaxy install -r /tmp/ansible-galaxy-requirements.yml

Hinweis: COPY bezieht sich auf den Build-Kontext (Workspace-Root beim Image-Build). Pfade zu Rollen/Collections in Playbooks (roles: / collections:) müssen zu den installierten Namen passen – wie bei einem normalen Ansible-Projekt.

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

Runtime-Verzeichnis (CLI-Flag)¶

Das globale Flag --runtime-dir ist nicht Teil von polycrate.yml; es wird auf der Kommandozeile gesetzt. Es bestimmt, wo Polycrate temporäre Dateien pro Transaktion ablegt (Standard: ~/.polycrate/run). Zusammen mit --config-dir können Sie in eingeschränkten Umgebungen (Sandboxes, CI, Remote-Editoren) sowohl die Konfigurationsbasis als auch die Laufzeit-Ablage auf beschreibbare Pfade legen, ohne HOME zu erweitern.

→ Ausführlich: CLI-Referenz — Runtime-Verzeichnis

SSH-Konfiguration (bei sshkeysource: user)¶

Wenn der Workspace config.sshkeysource: user verwendet, kann der Pfad zum persönlichen SSH-Key hier festgelegt werden:

ssh:
  user_key_path: "~/.ssh/work_ed25519"   # optional; Standard: ~/.ssh/id_rsa
  user_key_path_by_workspace:            # optional; workspace.name → Key-Pfad
    laser24: "~/.ssh/laser_ed25519"
    archenemy: "~/.ssh/ayedo_work"

→ SSH-Integration

→ 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
• Namenskonventionen – Regex und gültige Namen
• Dependencies – Block-Dependencies verwalten
• Vererbung – from:-Vererbung; Legacy: kubeconfig.from / inventory.from
• CLI-Referenz – Alle verfügbaren Commands