Zum Inhalt

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

+-----------------------------+
| blocks/  Template-Block     |
| postgres-base/block.poly    |
+-----------------------------+
               |
               |  from: postgres-base
               v
+-----------------------------+
| workspace.poly              |
| Block-Instanz: my-postgres  |
+-----------------------------+

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: install.yml
  - name: backup
    playbook: 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:

  Template-Block Config              Block-Instanz Config
           \                               /
            \                             /
             --------  Deep Merge  --------
                           |
                           v
                 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: install.yml

  - name: backup
    playbook: backup.yml

Block-Instanz (workspace.poly):

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

      - name: migrate
        playbook: 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

Empfohlene Konvention (aktuell)

  • inventory.yml im Workspace-Root – ein gemeinsames Ansible-Inventory für den gesamten Workspace (Standarddateiname, siehe Workspace-Konfiguration bei Abweichungen).
  • artifacts/secrets/kubeconfig.yml – eine workspace-weite Kubeconfig; die CLI erkennt die Datei und stellt die Pfade im Snapshot bereit.

Damit bleibt der Scope pro Workspace klar abgegrenzt. → Best Practices: Kubeconfig und Inventory

kubeconfig.from / inventory.from (Legacy)

Optional können Block-Instanzen in der workspace.poly kubeconfig.from bzw. inventory.from setzen und damit auf Artefakte anderer Block-Instanzen verweisen (nicht auf deren config: – das ist ein anderer Mechanismus als from:).

# workspace.poly (Muster – aus Best-Practice-Sicht nicht empfohlen)
blocks:
  - name: my-cluster
    from: registry.acme.corp/acme/k8s/cluster:1.0.0

  - name: my-app
    from: registry.acme.corp/acme/k8s/my-app:1.0.0
    kubeconfig:
      from: my-cluster  # Kubeconfig-Artefakt vom Block "my-cluster"

Discouraged

Dieses Muster wird nur noch für Bestands-Workspaces dokumentiert. Für neue Setups: ein Inventory, eine Kubeconfig – ohne *.from-Verkettung zwischen Blöcken.

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: install.yml
  - name: backup
    playbook: 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.