Vererbung¶

Was ist Block-Vererbung?¶

Block-Vererbung ermöglicht die Wiederverwendung und Anpassung von bestehenden Blocks. Ein Block, der in der workspace.poly instanziiert wird, kann von einem Template-Block erben und dessen Eigenschaften übernehmen:

Konfiguration (config) – wird per Deep-Merge zusammengeführt
Actions – können überschrieben oder erweitert werden
Working Directory – wird auf den Template-Block gesetzt

Vererbung ist auf EIN Level beschränkt

Die from:-Angabe erfolgt ausschließlich in der workspace.poly, nicht in der block.poly. Ein Block in der workspace.poly kann von einem Template-Block in der blocks/-Directory erben – mehr Vererbungsebenen gibt es nicht.

Vererbungs-Hierarchie¶

graph LR
    subgraph "blocks/ Directory"
        Template[Template-Block<br/>postgres-base/block.poly]
    end

    subgraph "workspace.poly"
        Instance[Block-Instanz<br/>my-postgres]
    end

    Template -->|from: postgres-base| Instance

    style Template fill:#e1f5fe
    style Instance fill:#c8e6c9

Wichtig: Es gibt nur EIN Level der Vererbung:

Template-Block (blocks/postgres-base/block.poly) – definiert Actions, Config-Defaults, Playbooks
Block-Instanz (workspace.poly) – erbt via from: und überschreibt bei Bedarf

Vererbung definieren¶

Template-Block (block.poly)¶

Ein Template-Block definiert die Basis-Funktionalität:

# blocks/postgres-base/block.poly
name: postgres-base
kind: k8sapp
version: 1.0.0

config:
  namespace: default
  app:
    persistence:
      size: 10Gi
      storageClass: standard
    replicas: 1

actions:
  - name: install
    playbook: playbooks/install.yml
  - name: backup
    playbook: playbooks/backup.yml

Block-Instanz (workspace.poly)¶

In der workspace.poly wird der Template-Block instanziiert und angepasst:

# workspace.poly
blocks:
  - name: my-postgres
    from: postgres-base  # Erbt von lokalem Template-Block
    config:
      namespace: production  # Override
      app:
        persistence:
          size: 100Gi  # Override

  - name: harbor
    from: registry.my-org.com/blocks/k8s/harbor:1.2.0  # Erbt von Registry-Block
    config:
      namespace: harbor-prod

Registry-Blocks

Bei from: cargo.ayedo.cloud/... wird der Block automatisch von der Registry gepullt und als Template verwendet.

Merge-Verhalten¶

Beim Zusammenführen (Merge) der Konfigurationen gilt:

graph LR
    Template[Template-Block Config] --> Merge[Deep Merge]
    Instance[Block-Instanz Config] --> Merge
    Merge --> Result[Resultierende Config]

Wichtig: Instanz-Werte überschreiben Template-Werte!

Beispiel: Config-Merge¶

Template-Block (blocks/postgres-base/block.poly):

name: postgres-base
config:
  namespace: default
  app:
    persistence:
      size: 10Gi
      storageClass: standard
    replicas: 1

Block-Instanz (workspace.poly):

blocks:
  - name: my-postgres
    from: postgres-base
    config:
      namespace: production
      app:
        persistence:
          size: 50Gi

Resultierende Config (Workspace Snapshot):

# my-postgres nach Merge
config:
  namespace: production      # überschrieben
  app:
    persistence:
      size: 50Gi             # überschrieben
      storageClass: standard # geerbt
    replicas: 1              # geerbt

Actions vererben und überschreiben¶

Actions werden ebenfalls vererbt, können aber in der Block-Instanz überschrieben werden:

Template-Block (blocks/postgres-base/block.poly):

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

  - name: backup
    playbook: playbooks/backup.yml

Block-Instanz (workspace.poly):

blocks:
  - name: my-postgres
    from: postgres-base
    actions:
      - name: install
        playbook: playbooks/custom-install.yml  # Überschreibt Template-Action

      - name: migrate
        playbook: playbooks/migrate.yml  # Neue Action

Resultat: Die Block-Instanz my-postgres hat drei Actions:

install (überschrieben mit custom-install.yml)
backup (geerbt vom Template-Block)
migrate (neu hinzugefügt)

Inventory und Kubeconfig referenzieren¶

Block-Instanzen können Inventory und Kubeconfig von anderen Blocks im Workspace referenzieren:

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

  - name: infrastructure
    # Generiert inventory.yml

  - name: my-app
    from: registry.my-org.com/blocks/k8s/my-app:1.0.0
    kubeconfig:
      from: my-cluster  # Nutzt Kubeconfig von Block "my-cluster"
    inventory:
      from: infrastructure  # Nutzt Inventory von Block "infrastructure"

Dies ist besonders nützlich, wenn mehrere Blocks dasselbe Ziel-Cluster oder dieselbe Infrastruktur nutzen.

Unterschied zu from:

kubeconfig.from und inventory.from referenzieren Artefakte anderer Blocks, nicht deren Konfiguration. Das ist kein Vererbungsmechanismus, sondern eine Referenzierung.

Best Practices¶

1. Template-Blocks erstellen¶

Erstellen Sie wiederverwendbare Template-Blocks in der blocks/ Directory:

# blocks/postgres-template/block.poly
name: postgres-template
kind: k8sapp
version: 1.0.0

config:
  # Sinnvolle Defaults
  namespace: default
  persistence:
    enabled: true
    size: 10Gi
  monitoring:
    enabled: true

actions:
  - name: install
    playbook: playbooks/install.yml
  - name: backup
    playbook: playbooks/backup.yml

2. Sinnvolle Overrides in workspace.poly¶

Überschreiben Sie nur das Nötigste:

# workspace.poly
blocks:
  # ✅ Gut: Nur spezifische Werte überschreiben
  - name: my-postgres-prod
    from: postgres-template
    config:
      namespace: production
      persistence:
        size: 100Gi

  # ❌ Schlecht: Gesamte Config wiederholen
  - name: my-postgres-bad
    from: postgres-template
    config:
      namespace: production
      persistence:
        enabled: true   # Unnötig, wird geerbt
        size: 100Gi
      monitoring:
        enabled: true   # Unnötig, wird geerbt

3. Registry-Blocks verwenden¶

Für produktionsreife Blocks empfehlen wir die Verwendung von Registry-Blocks:

# workspace.poly
blocks:
  - name: my-harbor
    from: registry.my-org.com/blocks/k8s/harbor:1.2.0
    config:
      namespace: harbor-production

Polycrate pulled den Block automatisch von der Registry und verwendet ihn als Template.

Working Directory

Bei der Ausführung einer Action wird die Working Directory auf die des Template-Blocks gesetzt. Playbooks und Scripts werden relativ zum Template-Block-Verzeichnis ausgeführt.