Temporal-Integration

Diese Seite ist eine Konfigurationsreferenz für Temporal-Clients und -Worker. Das abschließende Registry-Fragment zeigt, wie die Einträge verbunden werden; es ist kein eigenständiges Projekt.

Die Entry-Typen temporal.client und temporal.worker verbinden Wippy-Workflows und -Activities mit Temporal.

Client-Konfiguration

Der temporal.client-Entry-Typ definiert eine Verbindung zu einem Temporal-Server.

- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  namespace: "default"
  lifecycle:
    auto_start: true

Erforderliche Felder

Optionale Felder

Authentifizierung

Keine Authentifizierung

- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  auth:
    type: none

API-Schlüssel (Temporal Cloud)

Stellen Sie den API-Schlüssel über eine dieser Methoden bereit:

# Direct value
- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key: "your-api-key"

# From environment variable
- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key: ${env:TEMPORAL_API_KEY}

# From file
- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key_file: "/etc/secrets/temporal-api-key"

Auth- und Credential-Felder lösen ${env:NAME}-Platzhalter beim Dekodieren über die Umgebungs-Registry auf. Die Legacy-Direktiven api_key_env / key_pem_env werden auf dieselbe Weise aufgelöst, sind aber veraltet; bevorzugen Sie api_key: ${env:NAME} / key_pem: ${env:NAME}.

mTLS

- name: temporal_client
  kind: temporal.client
  address: "temporal.example.com:7233"
  namespace: "production"
  auth:
    type: mtls
    cert_file: "/path/to/client.pem"
    key_file: "/path/to/client.key"
  tls:
    enabled: true
    ca_file: "/path/to/ca.pem"

Zertifikat und Schlüssel können auch als PEM-Strings oder aus der Umgebung bereitgestellt werden:

auth:
  type: mtls
  cert_pem: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----    
  key_pem: ${env:TEMPORAL_CLIENT_KEY}

TLS-Konfiguration

tls:
  enabled: true
  ca_file: "/path/to/ca.pem"
  server_name: "temporal.example.com"    # Override server name verification
  insecure_skip_verify: false            # Skip verification (dev only)

Gesundheitsprüfungen

health_check:
  enabled: true
  interval: "30s"

Propagierung des Sicherheitskontexts

Wippy propagiert den aufrufenden Akteur und dessen Scope als signierten Temporal-Header an Workflows und Activities. Signiert wird mit HMAC-SHA256 und einem Schlüssel, den der Client-Eintrag hält:

- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  security_hmac_key: ${env:TEMPORAL_SECURITY_KEY}
  security_hmac_previous_keys:
    - ${env:TEMPORAL_SECURITY_KEY_PREVIOUS}

Beide Felder sind in YAML base64-kodiert, weil es Byte-Felder sind. Ein Schlüssel mit weniger als 32 dekodierten Bytes wird bei der Konfigurationsvalidierung abgelehnt, ebenso das Deklarieren von security_hmac_previous_keys ohne security_hmac_key. Neue Header werden immer mit security_hmac_key signiert; bei der Verifizierung wird jeder aufgeführte vorherige Schlüssel probiert. Die Rotation lautet also: den neuen Schlüssel als security_hmac_key hinzufügen, den alten nach security_hmac_previous_keys verschieben und ihn entfernen, sobald keine laufende Ausführung ihn mehr trägt.

Das Starten eines Workflows unter einem Akteur oder Scope erfordert den Schlüssel. Hat der Aufrufer einen Sicherheitskontext und der Client keinen Signierschlüssel, kann der Header nicht signiert werden und der Start schlägt fehl. Ein Client ohne Schlüssel kann Workflows nur aus einem Kontext starten, der weder Akteur noch Scope trägt.

Der Worker bezieht die Schlüssel aus dem Client-Eintrag, auf den er verweist, sodass ein Worker Signierung und Verifizierung von client: erbt, ohne selbst etwas zu konfigurieren. Siehe Workflows und Activities.

Worker-Konfiguration

Der temporal.worker-Entry-Typ definiert einen Worker, der Workflows und Activities ausführt.

- name: worker
  kind: temporal.worker
  client: app:temporal_client
  task_queue: "my-app-queue"
  lifecycle:
    auto_start: true
    requires:
      - app:temporal_client

Erforderliche Felder

Worker-Optionen

Worker-Verhalten konfigurieren:

- name: worker
  kind: temporal.worker
  client: app:temporal_client
  task_queue: "my-app-queue"
  worker_options:
    # Identität
    identity: ""                          # Worker-Identität (erscheint in der Temporal-UI)

    # Nebenläufigkeit
    max_concurrent_activity_execution_size: 1000
    max_concurrent_workflow_task_execution_size: 1000
    max_concurrent_local_activity_execution_size: 1000
    max_concurrent_session_execution_size: 1000
    max_concurrent_eager_activity_execution_size: 0

    # Pollers
    max_concurrent_activity_task_pollers: 20
    max_concurrent_workflow_task_pollers: 20

    # Rate limiting
    worker_activities_per_second: 0        # 0 = unlimited
    worker_local_activities_per_second: 0
    task_queue_activities_per_second: 0

    # Timeouts
    sticky_schedule_to_start_timeout: "5s"
    worker_stop_timeout: "0s"
    deadlock_detection_timeout: "0s"
    max_heartbeat_throttle_interval: "0s"
    default_heartbeat_throttle_interval: "0s"

    # Feature flags
    enable_logging_in_replay: false
    enable_session_worker: false
    disable_workflow_worker: false
    local_activity_worker_only: false
    disable_eager_activities: false
    disable_registration_aliasing: false

    # Versioning
    deployment_name: ""
    build_id: ""
    build_id: ${env:BUILD_ID}              # Aus der Env-Registry lesen
    use_versioning: false
    default_versioning_behavior: "pinned" # or "auto_upgrade"

Credential- und Bezeichnerfelder lösen ${env:NAME}-Platzhalter beim Dekodieren über die Umgebungs-Registry auf. Die Legacy-Direktive build_id_env wird auf dieselbe Weise aufgelöst, ist aber veraltet; bevorzugen Sie build_id: ${env:NAME}.

Versionierungsverhalten

default_versioning_behavior steuert, wie neue Workflow-Läufe eine Worker-Build-ID auswählen, wenn use_versioning aktiviert ist:

build_id: ${env:NAME} liest die Build-ID aus der Env-Registry, wenn keine literale build_id angegeben ist.

Session Worker

enable_session_worker: true lässt den Worker Temporal Sessions ausführen: eine Reihe von Activities, die an einen einzelnen Worker gebunden sind (nützlich, wenn Activities lokalen Zustand wie ein temporäres Verzeichnis oder eine offene Verbindung teilen). max_concurrent_session_execution_size begrenzt die gleichzeitigen Sessions auf dem Worker.

Nebenläufigkeits-Standards

Konfigurationsbeispiel

Dieses Registry-Fragment verbindet einen Workflow und eine Activity mit einem Worker. Es setzt einen erreichbaren Temporal-Server unter localhost:7233 und die beiden referenzierten Lua-Quelldateien voraus; deren Implementierungen finden Sie auf den Seiten zu Workflows und Activities.

version: "1.0"
namespace: app

entries:
  - name: temporal_client
    kind: temporal.client
    address: "localhost:7233"
    namespace: "default"
    lifecycle:
      auto_start: true

  - name: worker
    kind: temporal.worker
    client: app:temporal_client
    task_queue: "orders"
    lifecycle:
      auto_start: true
      requires:
        - app:temporal_client

  - name: order_workflow
    kind: workflow.lua
    source: file://order_workflow.lua
    method: main
    modules:
      - funcs
      - time
    meta:
      temporal:
        workflow:
          worker: app:worker

  - name: charge_payment
    kind: function.lua
    source: file://payment.lua
    method: charge
    modules:
      - env
      - errors
      - http_client
      - json
    meta:
      temporal:
        activity:
          worker: app:worker

Siehe auch

• Activities - Activity-Definitionen
• Workflows - Workflow-Implementierung