Recipes - Häufige Workflows¶

Diese Seite enthält praktische Beispiele und Rezepte für häufige Aufgaben mit Polycrate.

Workspace-Setup¶

Neuen Workspace erstellen und initialisieren¶

# Workspace erstellen
mkdir -p ~/workspaces/production-cluster
cd ~/workspaces/production-cluster
polycrate workspace init --with-name production-cluster

# Git-Repository initialisieren
git init
echo ".logs/" >> .gitignore
git add .
git commit -m "Initial Polycrate workspace"

# Ersten Block hinzufügen (vollständiger Registry-Pfad erforderlich)
polycrate blocks pull registry.my-org.com/blocks/k8s/cluster:1.0.0

Keine artifacts/ in .gitignore

Artifacts sollten nicht pauschal ignoriert werden. Nutzen Sie stattdessen Workspace-Verschlüsselung für sensible Daten in artifacts/secrets/.

Workspace aus Template erstellen¶

# Workspace mit Beispiel-Konfiguration erstellen
mkdir -p ~/.polycrate/workspaces/acme/acme-production-1
cd ~/.polycrate/workspaces/acme/acme-production-1
polycrate workspace init --with-name acme-production-1

# workspace.poly konfigurieren
cat > workspace.poly << 'EOF'
name: acme-production-1
organization: acme

config:
  cluster_name: production
  region: eu-west-1

blocks:
  - name: k8s
    from: registry.my-org.com/blocks/k8s/cluster:1.2.0

  - name: monitoring
    from: cargo.ayedo.cloud/ayedo/k8s/victoria-metrics-stack:1.0.0
    kubeconfig:
      from: k8s

workflows:
  - name: deploy-all
    steps:
      - name: setup-cluster
        block: k8s
        action: install
      - name: deploy-monitoring
        block: monitoring
        action: install
EOF

# Blocks werden automatisch gepullt mit --blocks-auto-pull
polycrate workflows run deploy-all --blocks-auto-pull

Multi-Environment Setup¶

Folgen Sie dem empfohlenen Naming-Schema $org-$purpose-$count:

# Empfohlene Struktur
mkdir -p ~/.polycrate/workspaces/acme/{acme-production-1,acme-staging-1,acme-dev-1}

# Production
cd ~/.polycrate/workspaces/acme/acme-production-1
polycrate workspace init --with-name acme-production-1
# Konfiguration für Production

# Staging
cd ~/polycrate-workspaces/staging
polycrate workspace init --with-name staging
# Konfiguration für Staging

# Development
cd ~/polycrate-workspaces/development
polycrate workspace init --with-name development
# Konfiguration für Development

# Ausführung mit spezifischem Workspace
polycrate run my-block install -w ~/polycrate-workspaces/production
polycrate run my-block install -w ~/polycrate-workspaces/staging

Block-Management¶

Block entwickeln und testen¶

# Neuen Block im Workspace erstellen
cd my-workspace
mkdir -p blocks/my-custom-block

# Block-Konfiguration erstellen
cat > blocks/my-custom-block/block.poly << 'EOF'
name: my-custom-block
version: 0.1.0

config:
  app_name: my-app
  port: 8080

actions:
  - name: install
    playbook: playbooks/install.yml
  - name: uninstall
    playbook: playbooks/uninstall.yml
EOF

# README erstellen
cat > blocks/my-custom-block/README.md << 'EOF'
# My Custom Block

## Description
This block deploys my custom application.

## Configuration
- `app_name`: Name of the application
- `port`: Port to run on

## Actions
- `install`: Install the application
- `uninstall`: Remove the application
EOF

# Entwicklungsmodus aktivieren
polycrate run my-custom-block install --dev --local

# Testen
polycrate block validate my-custom-block
polycrate block inspect my-custom-block

Block versionieren und veröffentlichen¶

1. Version in block.poly erhöhen:

cd blocks/my-block
# Version erhöhen (z.B. 0.1.0 → 0.2.0)
sed -i 's/version: 0.1.0/version: 0.2.0/' block.poly

2. CHANGELOG.poly aktualisieren:

# blocks/my-block/CHANGELOG.poly
- version: "0.2.0"
  date: "2025-01-15"
  type: feat  # chore|fix|feat|breaking
  message: "Neue Feature-Beschreibung"
  description: |
    - Feature 1 hinzugefügt
    - Bug X behoben
    - Performance verbessert

- version: "0.1.0"
  date: "2025-01-01"
  type: feat
  message: "Initiales Release"

3. Block testen:

polycrate run my-block install --local

4. Block in Registry pushen:

# Vollständiger Registry-Pfad erforderlich!
polycrate blocks push registry.my-org.com/infra/my-block

5. In anderem Workspace verwenden:

cd ../other-workspace
polycrate blocks pull registry.my-org.com/infra/my-block:0.2.0

Changelog anzeigen

Nutzen Sie polycrate block changelog my-block um das Changelog interaktiv zu browsen.

Block mit Template-Referenz¶

# workspace.poly
blocks:
  # Cluster-Block definieren
  - name: k8s
    from: registry.my-org.com/blocks/k8s/cluster:1.0.0

  # App-Block mit Kubeconfig vom Cluster
  - name: my-app
    from: registry.my-org.com/blocks/k8s/my-app:1.0.0
    kubeconfig:
      from: k8s  # Nutzt Kubeconfig vom k8s-Block
    config:
      namespace: production

# Block-Templates automatisch pullen
polycrate run my-app deploy --blocks-auto-pull

Dependencies über workspace.poly

Block-Dependencies werden über from: und kubeconfig.from/inventory.from in der workspace.poly definiert, nicht über eine dependencies: Stanza in der block.poly.

Dynamische Blocks¶

Mehrere Instanzen eines Blocks¶

# workspace.poly
name: multi-service

blocks:
  # Base-Block
  - name: generic-service
    config:
      service_name: template
      port: 8080
    actions:
      - name: deploy
        playbook: playbooks/deploy.yml

  # Instanzen
  - name: frontend
    from: generic-service
    config:
      service_name: frontend
      port: 3000

  - name: backend
    from: generic-service
    config:
      service_name: backend
      port: 8080

  - name: api
    from: generic-service
    config:
      service_name: api
      port: 8081

# Alle Services deployen
polycrate run frontend deploy
polycrate run backend deploy
polycrate run api deploy

# Oder via Workflow
polycrate workflows run deploy-all

Workflows¶

Komplexer Deployment-Workflow¶

# workspace.poly
workflows:
  - name: full-deployment
    prompt:
      message: "Production deployment starten?"
    steps:
      # Pre-deployment
      - name: pre-deployment-check
        block: healthcheck
        action: validate

      - name: backup-database
        block: database
        action: backup
        allow_failure: true

      # Core deployment
      - name: deploy-database-migrations
        block: database
        action: migrate

      - name: deploy-backend
        block: backend
        action: install

      - name: deploy-frontend
        block: frontend
        action: install

      # Post-deployment
      - name: run-smoke-tests
        block: tests
        action: smoke-test

      - name: notify-team
        block: notifications
        action: send
        allow_failure: true

# Workflow ausführen
polycrate workflow run full-deployment --force

Rollback-Workflow¶

# workspace.poly
workflows:
  - name: rollback
    prompt:
      message: "Wirklich zur vorherigen Version zurückkehren?"
    steps:
      - name: stop-services
        block: services
        action: stop

      - name: restore-database
        block: database
        action: restore

      - name: deploy-previous-version
        block: app
        action: install
        # Version aus Artefakt

      - name: restart-services
        block: services
        action: start

      - name: verify
        block: healthcheck
        action: validate

Workflow mit Bedingungen¶

# workspace.poly
config:
  environment: ${ENVIRONMENT:-production}

workflows:
  - name: conditional-deploy
    steps:
      # Wird immer ausgeführt
      - name: build
        block: app
        action: build

      # Nur in production
      - name: backup
        block: database
        action: backup
        # In Action implementieren: if [ "$ENVIRONMENT" = "production" ]; then ...

      - name: deploy
        block: app
        action: install

Artefakte¶

Artefakte zwischen Actions teilen¶

Komplexe Artefakt-Operationen gehören in Ansible-Playbooks, nicht in Scripts:

# blocks/build/block.poly
actions:
  - name: build
    playbook: playbooks/build.yml

# blocks/build/playbooks/build.yml
- name: Application bauen
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Artifacts-Verzeichnis erstellen
      file:
        path: "{{ block.artifacts.local_path }}"
        state: directory

    - name: Version speichern
      copy:
        content: "v1.2.3"
        dest: "{{ block.artifacts.local_path }}/version.txt"

    - name: Application archivieren
      archive:
        path: ./app
        dest: "{{ block.artifacts.local_path }}/app.tar.gz"
        format: gz

# blocks/deploy/playbooks/install.yml
- name: Application deployen
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Version aus Build-Artifact lesen
      slurp:
        src: "{{ workspace.config.artifacts_root }}/blocks/build/version.txt"
      register: version_file

    - name: Version anzeigen
      debug:
        msg: "Deploying version {{ version_file.content | b64decode | trim }}"

    - name: Artifact entpacken
      unarchive:
        src: "{{ workspace.config.artifacts_root }}/blocks/build/app.tar.gz"
        dest: /opt/app
        remote_src: true

Artefakt-Cleanup¶

# blocks/cleanup/playbooks/prune.yml
- name: Alte Artifacts aufräumen
  hosts: localhost
  gather_facts: false
  tasks:
    - name: Alte Logs löschen (älter als 7 Tage)
      find:
        paths: "{{ workspace.config.artifacts_root }}"
        patterns: "*.log"
        age: 7d
      register: old_logs

    - name: Logs entfernen
      file:
        path: "{{ item.path }}"
        state: absent
      loop: "{{ old_logs.files }}"

    - name: Alte Backups löschen (älter als 30 Tage)
      find:
        paths: "{{ workspace.config.artifacts_root }}"
        patterns: "backup-*.tar.gz"
        age: 30d
      register: old_backups

    - name: Backups entfernen
      file:
        path: "{{ item.path }}"
        state: absent
      loop: "{{ old_backups.files }}"

→ Ausführliche Dokumentation zu Artefakten

SSH und Remote-Hosts¶

SSH-Setup für Remote-Hosts¶

# SSH-Keys generieren
ssh-keygen -t ed25519 -f ./id_rsa -C "polycrate@example.com"

# Public Key auf Remote-Hosts verteilen
ssh-copy-id -i ./id_rsa.pub user@host1
ssh-copy-id -i ./id_rsa.pub user@host2

# Inventory erstellen
cat > inventory.yml << 'EOF'
all:
  hosts:
    host1:
      ansible_host: 192.168.1.10
      ansible_user: admin
    host2:
      ansible_host: 192.168.1.11
      ansible_user: admin
  vars:
    ansible_ssh_private_key_file: id_rsa
EOF

# SSH-Verbindung testen
polycrate ssh host1

SSH mit Passphrase¶

Experimental Feature

SSH-Key-Passphrase-Support ist ein experimentelles Feature und kann sich in zukünftigen Versionen ändern.

# Passphrase in Datei speichern
echo "my-secure-passphrase" > ssh-passphrase.poly

# Workspace verschlüsseln (inklusive Passphrase)
polycrate workspace encrypt

# Actions mit SSH-Passphrase ausführen
polycrate run my-block install --ssh-use-passphrase

Ansible-Playbook mit SSH¶

# blocks/deploy/install.yml
---
- name: Deploy application
  hosts: all
  tasks:
    - name: Copy application files
      copy:
        src: "{{ workspace_root }}/app/"
        dest: "/opt/app/"

    - name: Start service
      systemd:
        name: myapp
        state: started
        enabled: yes

# Playbook ausführen
polycrate run deploy install

Container-Customization¶

Custom Tools im Container¶

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

# System-Pakete installieren (Ubuntu-basiert!)
RUN apt-get update && apt-get install -y --no-install-recommends \
    nodejs \
    npm \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# Node.js Tools
RUN npm install -g \
    typescript \
    @angular/cli

# Python Tools
RUN pip3 install --no-cache-dir \
    requests \
    pyyaml

# Custom Scripts
COPY scripts/ /usr/local/bin/
RUN chmod +x /usr/local/bin/*

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

Spezifische Tool-Versionen¶

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

# Helm in spezifischer Version
RUN wget https://get.helm.sh/helm-v3.12.0-linux-amd64.tar.gz \
    && tar xzf helm-v3.12.0-linux-amd64.tar.gz \
    && mv linux-amd64/helm /usr/local/bin/ \
    && rm -rf linux-amd64 helm-v3.12.0-linux-amd64.tar.gz

# kubectl in spezifischer Version
RUN curl -LO "https://dl.k8s.io/release/v1.28.0/bin/linux/amd64/kubectl" \
    && chmod +x kubectl \
    && mv kubectl /usr/local/bin/

Verschlüsselung und Secrets¶

Workspace mit Secrets verschlüsseln¶

Die secrets.poly hat das gleiche Format wie workspace.poly – Secrets werden pro Block definiert:

# secrets.poly - Sensitive Block-Konfiguration
blocks:
  - name: database
    config:
      password: super-secret-password
      admin_user: admin

  - name: my-app
    config:
      api_keys:
        aws: AKIAIOSFODNN7EXAMPLE
        github: ghp_xxxxxxxxxxxxxxxxxxxx

# Workspace verschlüsseln (secrets.poly → secrets.poly.age)
polycrate workspace encrypt

# Status prüfen
polycrate workspace status
# Output: Workspace is encrypted

# Actions ausführen (automatische Entschlüsselung)
polycrate run my-app install

# Für Bearbeitung entschlüsseln
polycrate workspace decrypt
vi secrets.poly
polycrate workspace encrypt

→ Ausführliche Dokumentation zur Workspace-Verschlüsselung

Secrets aus externen Quellen¶

Für Secrets aus Passwort-Managern wie 1Password oder HashiCorp Vault erstellen Sie ein separates Script, das die secrets.poly generiert:

#!/bin/bash
# generate-secrets.sh

# Secrets aus 1Password abrufen
DB_PASSWORD=$(op read "op://vault/database/password")
API_KEY=$(op read "op://vault/my-app/api_key")

# secrets.poly mit den abgerufenen Werten schreiben
cat > secrets.poly << SECRETS_EOF
blocks:
  - name: database
    config:
      password: "${DB_PASSWORD}"

  - name: my-app
    config:
      api_key: "${API_KEY}"
SECRETS_EOF

echo "secrets.poly generated"

# Script ausführen
./generate-secrets.sh

# Workspace verschlüsseln
polycrate workspace encrypt

# Actions ausführen
polycrate run my-app install

Keine Templating in YAML

${VAR} oder $(...) Syntax funktioniert nicht in workspace.poly, secrets.poly oder block.poly. Diese Dateien sind statisches YAML. Verwenden Sie externe Scripts um Secrets einzufügen.

CI/CD Integration¶

GitLab CI¶

# .gitlab-ci.yml
stages:
  - build
  - test
  - deploy

variables:
  POLYCRATE_VERSION: "0.22.1"

before_script:
  - curl -sSL https://get.polycrate.io | bash
  - export PATH="$PATH:/usr/local/bin"

build:
  stage: build
  script:
    - polycrate run build-block build --force

test:
  stage: test
  script:
    - polycrate run test-block test --force

deploy:
  stage: deploy
  only:
    - main
  script:
    - polycrate run deploy-block install --force
  environment:
    name: production

GitHub Actions¶

# .github/workflows/deploy.yml
name: Deploy with Polycrate

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Polycrate
        run: |
          curl -sSL https://get.polycrate.io | bash
          echo "$HOME/.polycrate/bin" >> $GITHUB_PATH

      - name: Setup credentials
        env:
          KUBECONFIG_CONTENT: ${{ secrets.KUBECONFIG }}
        run: |
          echo "$KUBECONFIG_CONTENT" > kubeconfig.yaml

      - name: Deploy
        run: |
          polycrate run my-app install --force

Jenkins¶

// Jenkinsfile
pipeline {
    agent any

    environment {
        POLYCRATE_VERSION = '0.22.1'
    }

    stages {
        stage('Install Polycrate') {
            steps {
                sh 'curl -sSL https://get.polycrate.io | bash'
            }
        }

        stage('Deploy') {
            steps {
                sh 'polycrate run my-app install --force'
            }
        }
    }
}