feat(api): add stable build ID override via spec.workerOptions.buildID

[tshtark]

Summary

Adds support for user-controlled build IDs via spec.workerOptions.buildID, enabling rolling updates for non-workflow code changes while preserving new deployment creation for workflow code changes.

Problem

With PINNED versioning strategy and long-running workflows, any pod spec change (image tag, env vars, resources) generates a new build ID, causing deployment proliferation - potentially 10-15 active deployments running simultaneously, causing resource waste and operational complexity.

Solution

Allow users to set a stable build ID via spec.workerOptions.buildID. When the build ID is stable but pod spec changes, trigger a rolling update instead of creating a new deployment.

API Changes

New optional field in WorkerOptions:

// BuildID optionally overrides the auto-generated build ID for this worker deployment.
// When set, the controller uses this value instead of computing a build ID from the
// pod template hash. This enables rolling updates for non-workflow code changes
// (bug fixes, config changes) while preserving the same build ID.
//
// WARNING: Using a custom build ID requires careful management. If workflow code changes
// but BuildID stays the same, pinned workflows may execute on workers running incompatible
// code. Only use this when you have a reliable way to compute a hash of your workflow
// definitions (e.g., hashing workflow source files in CI/CD).
// +optional
// +kubebuilder:validation:MaxLength=63
// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$`
BuildID string `json:"buildID,omitempty"`

Usage

apiVersion: temporal.io/v1alpha1
kind: TemporalWorkerDeployment
metadata:
  name: my-worker
spec:
  workerOptions:
    connectionRef:
      name: my-connection
    temporalNamespace: default
    buildID: "wf-a1b2c3d4"  # Set to your workflow code hash
  template:
    spec:
      containers:
        - name: worker
          image: my-worker:v1.2.3  # Can change without new deployment

Drift Detection

When spec.workerOptions.buildID is set, the controller detects spec drift by directly comparing the deployed spec with the desired spec (images, resources, replicas, etc.). This is simple and transparent - no hidden state required.

Behavior Matrix

Scenario	Build ID	Result
No buildID field	Auto-generated from image + hash	Existing behavior
BuildID set, first deploy	Uses field value	New deployment
BuildID unchanged, spec changed	Same build ID	Rolling update
BuildID changed	New build ID	New deployment

Test Plan

• Build ID spec field override tests (6 test cases)
• Drift detection with direct spec comparison (5 test cases)
• All existing tests pass
• go test ./... passes

🤖 Generated with Claude Code

[CLAassistant]

All committers have signed the CLA.