Best Practices & Konventionen¶

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

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

# Schlecht ❌
organization: Demo GmbH      # Leerzeichen und Sonderzeichen
organization: ACME Corp.     # Punkt und Großbuchstaben

# CHANGELOG.poly
- version: "2.0.0"
  date: "2025-06-15"
  type: feat
  message: "Major Upgrade: Kubernetes 1.30 und neue Apps"
  description: |
    - Kubernetes auf 1.30 aktualisiert
    - Authentik SSO hinzugefügt
    - Grafana Monitoring Stack erweitert

- version: "1.2.0"
  date: "2025-06-01"
  type: feat
  message: "Grafana Monitoring hinzugefügt"
  description: |
    - Prometheus Stack installiert
    - Grafana Dashboards für alle Services
    - Alerting konfiguriert

- version: "1.1.0"
  date: "2025-05-20"
  type: fix
  message: "Database Backup automatisiert"
  description: |
    - Automatische PostgreSQL Backups
    - Backup-Rotation implementiert

- version: "1.0.0"
  date: "2025-05-01"
  type: feat
  message: "Initial Setup"
  description: |
    - Kubernetes Cluster mit RKE2
    - PostgreSQL Datenbank
    - Redis Cache

# ❌ FALSCH: Mehrere Umgebungen in einem Workspace
config:
  environment: ${ENV:-development}  # Das funktioniert nicht!
  replicas: ${ENV == "production" ? 3 : 1}  # Das funktioniert nicht!

# ✅ acme-production-1/workspace.poly
name: acme-production-1
organization: acme

blocks:
  - name: my-app
    from: cargo.ayedo.cloud/acme/k8s/my-app:1.0.0
    config:
      replicas: 3
      resources:
        memory: 4Gi

# ✅ acme-staging-1/workspace.poly
name: acme-staging-1
organization: acme

blocks:
  - name: my-app
    from: cargo.ayedo.cloud/acme/k8s/my-app:1.0.0
    config:
      replicas: 1
      resources:
        memory: 1Gi

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

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

# ═══════════════════════════════════════════════════════════════════
# YAML-ANKER (Workspace-weite Konstanten)
# ═══════════════════════════════════════════════════════════════════
domain: &domain acme-corp.com
s3_endpoint: &s3_endpoint https://s3.loopback.ayedo.cloud
keycloak_realm: &keycloak_realm acme
keycloak_base_url: &keycloak_base_url https://id.acme-corp.com

letsencrypt_email: &letsencrypt_email admin@acme-corp.com
letsencrypt_issuer: &letsencrypt_issuer letsencrypt-production
ingress_class: &ingress_class nginx

# Workspace-Metadaten
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  # → letsencrypt-production

  - name: mattermost
    from: cargo.ayedo.cloud/ayedo/k8s/mattermost:0.1.0
    config:
      s3:
        endpoint: *s3_endpoint  # → https://s3.loopback.ayedo.cloud
      oidc:
        discovery_url: !join [*keycloak_base_url, "/realms/", *keycloak_realm, "/.well-known/openid-configuration"]
      ingress:
        host: !join ["chat.", *domain]  # → chat.acme-corp.com
        class: *ingress_class

# Gut ✅ - Vollständiger Registry-Pfad
blocks:
  - name: zammad
    from: cargo.ayedo.cloud/ayedo/k8s/zammad:0.1.7

  - name: n8n
    from: cargo.ayedo.cloud/ayedo/k8s/n8n:0.1.3

  - name: open-webui
    from: cargo.ayedo.cloud/ayedo/k8s/open-webui:0.0.3

# Für workspace-spezifische Anpassungen (z.B. Cilium IP Pool)
blocks:
  - name: kustomizations
    # Kein "from:" = lokaler Block in blocks/kustomizations/
    config:
      cilium_lb_pool: 10.0.100.0/24

# Gut ✅ - Version im Namen
blocks:
  - name: zammad
    from: cargo.ayedo.cloud/ayedo/k8s/zammad:0.1.7

  - name: n8n
    from: cargo.ayedo.cloud/ayedo/k8s/n8n:0.1.3

# Schlecht ❌ - Separate version-Angabe (funktioniert nicht)
blocks:
  - name: zammad
    from: cargo.ayedo.cloud/ayedo/k8s/zammad
    version: 0.1.7  # Das funktioniert nicht!

# workspace.poly - Beide Instanzen nutzen denselben Template-Block
blocks:
  - name: frontend
    from: cargo.ayedo.cloud/acme/k8s/generic-app:1.0.0  # ← Teilen sich
    config:
      app_name: frontend

  - name: backend
    from: cargo.ayedo.cloud/acme/k8s/generic-app:1.0.0  # ← denselben Block!
    config:
      app_name: backend

# workspace.poly - Nach dem Update: BEIDE Instanzen anpassen!
blocks:
  - name: frontend
    from: cargo.ayedo.cloud/acme/k8s/generic-app:2.0.0  # ← Aktualisiert
    config:
      app_name: frontend

  - name: backend
    from: cargo.ayedo.cloud/acme/k8s/generic-app:2.0.0  # ← Aktualisiert
    config:
      app_name: backend

# workspace.poly - INKONSISTENT: Verschiedene Versionen!
blocks:
  - name: frontend
    from: cargo.ayedo.cloud/acme/k8s/generic-app:1.0.0  # ← Alte Version (nicht mehr installiert!)
    config:
      app_name: frontend

  - name: backend
    from: cargo.ayedo.cloud/acme/k8s/generic-app:2.0.0  # ← Neue Version (installiert)
    config:
      app_name: backend

# block.poly
name: generic-app
kind: k8sapp

config:
  app_name: ""        # Muss im Workspace gesetzt werden
  port: 8080          # Default-Wert
  replicas: 3         # Default-Wert

actions:
  - name: deploy
    playbook: deploy.yml

# workspace.poly
blocks:
  - name: frontend
    from: cargo.ayedo.cloud/acme/k8s/generic-app:1.0.0
    config:
      app_name: frontend
      port: 3000

  - name: backend
    from: cargo.ayedo.cloud/acme/k8s/generic-app:1.0.0
    config:
      app_name: backend
      port: 8080

actions:
  - name: delete-database
    prompt:
      message: "WARNUNG: Dies löscht alle Daten! Fortfahren?"
    playbook: delete.yml

actions:
  - name: install
    playbook: install.yml  # Ansible ist von Natur aus idempotent

workflows:
  - name: deploy
    steps:
      - name: backup
        block: database
        action: backup
        allow_failure: true  # Deployment fortsetzen auch wenn Backup fehlschlägt

      - name: deploy
        block: app
        action: install
        allow_failure: false  # Bei Fehler stoppen (Standard)

workflows:
  - name: deploy-production
    prompt:
      message: "Production-Deployment starten?"
    steps:
      - name: backup
        block: database
        action: backup
      - name: deploy-backend
        block: backend
        action: install
      - name: deploy-frontend
        block: frontend
        action: install
      - name: smoke-tests
        block: tests
        action: run

# block.poly - Beispiel mit Metadaten
name: my-postgres
kind: k8sapp
type: db
flavor: postgresql
description: "PostgreSQL Datenbank mit CloudNativePG"
app_version: "16.2"
license: Apache-2.0
website_url: https://cloudnative-pg.io
documentation_url: https://cloudnative-pg.io/documentation/

# block.poly
name: my-block
kind: k8sapp
config:
  namespace: my-namespace
  create_namespace: true
  chart:
    name: my-chart
    version: 1.0.0
    repo:
      url: https://charts.example.com

- version: "0.1.0"
  date: "2025-06-15"
  type: feat
  message: "My App Helm Chart von 1.12.2 auf 1.14.2 aktualisiert"
  description: |
    - Helm Chart aktualisiert
    - Neue Config-Optionen hinzugefügt

- version: "0.0.1"
  date: "2025-06-01"
  type: feat
  message: "Initial Commit"

labels:
  blocks.polycrate.io/kind: k8sappinstance
  blocks.polycrate.io/name: my-block
  organizations.polycrate.io/name: my-org
  workspaces.polycrate.io/name: my-workspace

# values.yaml.j2
commonLabels: {{ block.labels }}

# manifest.yaml.j2
metadata:
  labels: {{ block.labels }}