Temporal統合

このページは、Temporalクライアントとワーカーの設定リファレンスです。最後のレジストリ断片はエントリ同士の接続方法を示すものであり、単独で完結するプロジェクトではありません。

temporal.clientとtemporal.workerのエントリ種別は、WippyのワークフローとアクティビティをTemporalに接続します。

クライアント設定

temporal.clientエントリ種別は、Temporalサーバーへの接続を定義します。

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

必須フィールド

オプションフィールド

認証

認証なし

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

APIキー（Temporal Cloud）

次のいずれかの方法でAPIキーを指定します。

# 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"

認証および認証情報フィールドは、デコード時に${env:NAME}プレースホルダを環境変数システム経由で解決します。従来のapi_key_env / key_pem_envディレクティブも同じように解決されますが非推奨です。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"

証明書とキーはPEM文字列または環境レジストリからも提供できます：

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

TLS設定

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)

ヘルスチェック

health_check:
  enabled: true
  interval: "30s"

セキュリティコンテキストの伝播

Wippyは、呼び出し元のアクターとスコープを、署名されたTemporalヘッダーとしてワークフローとアクティビティに伝播します。署名はHMAC-SHA256で、鍵はクライアントエントリが保持します:

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

どちらのフィールドもバイト列フィールドであるため、YAMLではbase64で記述します。デコード後32バイト未満の鍵は設定検証時に拒否され、security_hmac_keyなしでsecurity_hmac_previous_keysを宣言した場合も同様です。新しいヘッダーは常にsecurity_hmac_keyで署名され、検証時には列挙されたすべての以前の鍵が試行されます。したがってローテーションの手順は、新しい鍵をsecurity_hmac_keyとして追加し、古い鍵をsecurity_hmac_previous_keysへ移し、その鍵を持つ実行中のものがなくなった時点で削除する、という流れになります。

アクターまたはスコープの下でワークフローを開始するには鍵が必要です。 呼び出し元にセキュリティコンテキストがあり、クライアントに署名鍵がない場合、ヘッダーに署名できないため開始は失敗します。鍵を持たないクライアントは、アクターもスコープも持たないコンテキストからのみワークフローを開始できます。

ワーカーは参照するクライアントエントリから鍵を取得するため、ワーカー自身は何も設定しなくてもclient:から署名と検証を継承します。ワークフローとアクティビティを参照してください。

ワーカー設定

temporal.workerエントリ種別は、ワークフローとアクティビティを実行するワーカーを定義します。

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

必須フィールド

ワーカーオプション

ワーカーの動作を設定します。

- name: worker
  kind: temporal.worker
  client: app:temporal_client
  task_queue: "my-app-queue"
  worker_options:
    # アイデンティティ
    identity: ""                          # ワーカーのアイデンティティ（Temporal UIに表示）

    # 並行性
    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}              # 環境レジストリから読み取り
    use_versioning: false
    default_versioning_behavior: "pinned" # or "auto_upgrade"

認証情報および識別子フィールドは、デコード時に${env:NAME}プレースホルダを環境変数システム経由で解決します。従来のbuild_id_envディレクティブも同じように解決されますが非推奨です。build_id: ${env:NAME}を使用してください。

バージョニング動作

default_versioning_behaviorは、use_versioningが有効な場合に、新しいワークフロー実行がワーカーのビルドIDを選択する方法を制御します。

build_id: ${env:NAME}は、リテラルのbuild_idが指定されていない場合に環境レジストリからビルドIDを読み取ります。

セッションワーカー

enable_session_worker: trueを設定すると、ワーカーはTemporal Sessionsを実行できます。これは、単一のワーカーに固定された一連のアクティビティです（一時ディレクトリや開かれた接続などのローカル状態をアクティビティ間で共有する場合に便利です）。max_concurrent_session_execution_sizeは、ワーカー上の同時セッション数を制限します。

並行性のデフォルト値

設定例

このレジストリ断片は、1つのワークフローと1つのアクティビティをワーカーに接続します。localhost:7233でTemporalサーバーに到達でき、参照される2つのLuaソースファイルが存在することを前提としています。実装については、ワークフローとアクティビティのページを参照してください。

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

関連項目

• アクティビティ - アクティビティの定義
• ワークフロー - ワークフローの実装