Zum Inhalt

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
echo "artifacts/" >> .gitignore
echo "id_rsa" >> .gitignore
echo "id_rsa.pub" >> .gitignore
git add .
git commit -m "Initial Polycrate workspace"

# Ersten Block hinzufügen
polycrate block pull ayedo/k8s/cluster

Workspace aus Template erstellen

# Workspace mit Beispiel-Konfiguration erstellen
mkdir -p ~/workspaces/my-k8s-cluster
cd ~/workspaces/my-k8s-cluster
polycrate workspace init --with-name my-k8s-cluster

# Basis-Struktur aufbauen
# (Konfiguration folgt im bestehenden Verzeichnis)

# workspace.poly konfigurieren
cat > workspace.poly << 'EOF'
name: my-k8s-cluster

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

blocks:
  - name: ayedo/k8s/cluster
    version: 1.2.0
  - name: ayedo/k8s/monitoring
    version: 1.0.0

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

# Blocks pullen
polycrate block pull ayedo/k8s/cluster:1.2.0
polycrate block pull ayedo/k8s/monitoring:1.0.0

Multi-Environment Setup

# Struktur für mehrere Umgebungen
mkdir -p ~/polycrate-workspaces/{production,staging,development}

# Production
cd ~/polycrate-workspaces/production
polycrate workspace init --with-name production
# 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
    script:
      - echo "Installing ${CONFIG_APP_NAME} on port ${CONFIG_PORT}"
      - echo "Workspace: ${POLYCRATE_WORKSPACE_NAME}"
  - name: uninstall
    script:
      - echo "Uninstalling ${CONFIG_APP_NAME}"
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

# Version in block.poly erhöhen
cd blocks/my-block
sed -i 's/version: 0.1.0/version: 0.2.0/' block.poly

# Block testen
polycrate run my-block install --local

# Block in Registry pushen
polycrate block push my-org/my-block

# Spezifische Version in anderem Workspace verwenden
cd ../other-workspace
polycrate block pull my-org/my-block:0.2.0

Block mit Dependencies

# blocks/my-app/block.poly
name: my-app
version: 1.0.0

dependencies:
  - name: ayedo/k8s/cluster
    version: ">=1.0.0"

config:
  cluster_endpoint: ${blocks.ayedo/k8s/cluster.config.endpoint}

actions:
  - name: deploy
    script:
      - echo "Deploying to ${CONFIG_CLUSTER_ENDPOINT}"

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

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
        script:
          - echo "Deploying ${CONFIG_SERVICE_NAME} on ${CONFIG_PORT}"

  # 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

Dynamische Block-Konfiguration aus Datei

# services.yml
services:
  - name: service-a
    port: 8080
  - name: service-b
    port: 8081
  - name: service-c
    port: 8082

# workspace.poly
name: dynamic-services

config:
  services_file: services.yml

blocks:
  - name: service-deployer
    actions:
      - name: deploy-all
        script:
          - |
            yq eval '.services[]' services.yml | while read -r service; do
              name=$(echo "$service" | yq eval '.name' -)
              port=$(echo "$service" | yq eval '.port' -)
              echo "Deploying $name on port $port"
            done

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

# blocks/build/block.poly
actions:
  - name: build
    script:
      - echo "Building application..."
      - mkdir -p ${POLYCRATE_ARTIFACTS_ROOT}/blocks/build
      - echo "v1.2.3" > ${POLYCRATE_ARTIFACTS_ROOT}/blocks/build/version.txt
      - tar czf ${POLYCRATE_ARTIFACTS_ROOT}/blocks/build/app.tar.gz ./app

# blocks/deploy/block.poly
actions:
  - name: install
    script:
      - VERSION=$(cat ${POLYCRATE_ARTIFACTS_ROOT}/blocks/build/version.txt)
      - echo "Deploying version $VERSION"
      - tar xzf ${POLYCRATE_ARTIFACTS_ROOT}/blocks/build/app.tar.gz

Artefakt-Cleanup

# blocks/cleanup/block.poly
actions:
  - name: prune
    script:
      - echo "Cleaning up old artifacts..."
      # Alte Logs löschen (älter als 7 Tage)
      - find ${POLYCRATE_ARTIFACTS_ROOT} -name "*.log" -mtime +7 -delete
      # Alte Backups löschen (älter als 30 Tage)
      - find ${POLYCRATE_ARTIFACTS_ROOT} -name "backup-*.tar.gz" -mtime +30 -delete

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
RUN apk add --no-cache \
    nodejs \
    npm \
    python3 \
    py3-pip

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

# Python Tools
RUN pip3 install \
    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

# Terraform in spezifischer Version
RUN wget https://releases.hashicorp.com/terraform/1.5.0/terraform_1.5.0_linux_amd64.zip \
    && unzip terraform_1.5.0_linux_amd64.zip \
    && mv terraform /usr/local/bin/ \
    && rm terraform_1.5.0_linux_amd64.zip

# 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

Verschlüsselung und Secrets

Workspace mit Secrets verschlüsseln

Experimental Feature

Workspace-Verschlüsselung ist ein experimentelles Feature und kann sich in zukünftigen Versionen ändern.

# Secrets in workspace.poly
cat > workspace.poly << 'EOF'
name: production

config:
  database:
    password: super-secret-password
  api_keys:
    aws: AKIAIOSFODNN7EXAMPLE
    github: ghp_xxxxxxxxxxxxxxxxxxxx
EOF

# Workspace verschlüsseln
polycrate workspace encrypt

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

# Actions ausführen (automatische Entschlüsselung)
polycrate run my-block install
# Passphrase wird abgefragt

# Für Bearbeitung entschlüsseln
polycrate workspace decrypt
# Bearbeiten
vi workspace.poly
# Wieder verschlüsseln
polycrate workspace encrypt

Secrets aus externen Quellen

# workspace.poly
config:
  database:
    password: ${DB_PASSWORD}  # Aus Umgebungsvariable
  api_key: ${API_KEY}

# Secrets aus 1Password/LastPass/etc. laden
export DB_PASSWORD=$(op read "op://vault/item/password")
export API_KEY=$(op read "op://vault/item/api_key")

# Actions ausführen
polycrate run my-block install

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'
            }
        }
    }
}

Testing und Validation

Snapshot-Tests

# Snapshot generieren
polycrate run my-block install --snapshot > expected-snapshot.yml

# Bei späteren Changes vergleichen
polycrate run my-block install --snapshot > current-snapshot.yml
diff expected-snapshot.yml current-snapshot.yml

Validierungs-Block

# blocks/validate/block.poly
name: validate

actions:
  - name: check-config
    script:
      - echo "Validating configuration..."
      - test -n "${CONFIG_CLUSTER_NAME}" || (echo "cluster_name missing" && exit 1)
      - test -n "${CONFIG_REGION}" || (echo "region missing" && exit 1)
      - echo "Configuration valid!"

  - name: check-connectivity
    script:
      - echo "Checking connectivity..."
      - kubectl cluster-info
      - helm list
      - echo "Connectivity check passed!"

# Vor Deployment validieren
polycrate run validate check-config
polycrate run validate check-connectivity
polycrate run deploy install

Monitoring und Logging

Strukturiertes Logging

# blocks/app/block.poly
actions:
  - name: deploy
    script:
      - echo '{"timestamp":"'$(date -Iseconds)'","level":"INFO","message":"Starting deployment"}'
      - echo '{"timestamp":"'$(date -Iseconds)'","level":"INFO","message":"Deployment complete"}'

# JSON-Logs
polycrate run app deploy --logformat json > deployment.log

# Logs analysieren
cat deployment.log | jq '.[] | select(.level=="ERROR")'

Events an externes System senden

# workspace.poly
config:
  event_endpoint: https://webhook.example.com/polycrate

actions:
  - name: deploy
    script:
      - echo "Deploying..."
      - |
        curl -X POST ${CONFIG_EVENT_ENDPOINT} \
          -H "Content-Type: application/json" \
          -d '{"event":"deployment_started","workspace":"'${POLYCRATE_WORKSPACE_NAME}'"}'

Siehe auch