Worker versioning

Active contributors: yichaoyang, alex, david

Purpose

Workers ship workflow code that is intrinsically deterministic — older workflows expect older code. Worker versioning lets operators safely run multiple worker versions against the same task queue and pin specific workflows to specific versions. The current iteration is v3 ("worker deployments").

Three versions, one repo

Version	Status	Notes
v1	Deprecated	Original "build ID compatibility sets". Tests in tests/versioning_test.go.
v2	Deprecated	Iterative refinement of v1. Same test file; the public API still references it.
v3	Current	"Worker deployments". Largest functional test in the repo: tests/versioning_3_test.go (~292KB).

All three are still queryable via the API; v3 is what new clusters should use.

Source map

Surface	File / package
Public proto	temporal.api.workflow.v1.*, temporal.api.taskqueue.v1.*, temporal.api.deployment.v1.*
Worker-versioning helpers (server-internal)	common/worker_versioning/
Matching: per-task-queue user data	service/matching/user_data_manager.go
Matching: version sets / rules	service/matching/version_sets.go, service/matching/version_rule_helpers.go
Reachability	service/matching/reachability.go
Worker deployment system workflows (v3)	service/worker/workerdeployment/
Build-ID scanner	service/worker/scanner/build_ids/
History engine (versioning support)	service/history/worker_versioning_util.go

How v3 works

graph LR
    Op[Operator: register deployment] --> Sys[worker-deployment system workflow]
    Sys -->|update user data| TQ[task queue user data]
    Worker[Worker with build-id] -->|poll declares build-id| Match[Matching]
    Match -->|consults rules| TQ
    Match -->|delivers task| Worker

A worker deployment is a versioned bundle of build IDs and routing rules. The state lives in a system workflow per deployment; updates propagate to every Matching host that owns a partition of the affected task queue, persisted as part of the user data row.

When a worker polls, it declares its own build ID. Matching consults the rules in the user data and either delivers the task or rejects it. Workflows pinned to a particular version stay on that version even when newer ones exist.

Reachability (is build ID xyz still seeing traffic?) is computed by walking the task queue's user data and the open-workflow status; the implementation in service/matching/reachability.go is the most reused piece — it's exposed via the OperatorService API and used by the worker-deployment workflows.

Entry points for modification

• Adding a routing rule type: edit the public proto, regen, then implement in service/matching/version_rule_helpers.go and update the user-data merge logic in service/matching/user_data_manager.go.
• Tuning system workflows: the worker-deployment workflows live in service/worker/workerdeployment/; their dynamic-config keys are in system.workerdeployment.*.

Related pages

• Matching service
• Internal Worker
• Task queue primitive