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

[tshtark]

Summary

Adds support for user-controlled build IDs via spec.workerOptions.customBuildID, 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.

• Related issue - temporal-operator: Build ID regeneration for non-workflow code changes causes excessive deployments with PINNED versioning #165

Result: 10-15 active deployments running simultaneously, causing resource waste and operational complexity.

Solution

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

Key Changes

• Add CustomBuildID field to WorkerOptions struct in API types
• Update ComputeBuildID to use custom field when set
• Implement hash-based drift detection using SHA256 of user-provided pod template spec
• Store hash in temporal.io/pod-template-spec-hash annotation on deployments
• Extract ApplyControllerPodSpecModifications as shared helper for code reuse
• Only check for drift when customBuildID is explicitly set by user

Drift Detection

When spec.workerOptions.customBuildID is set, the controller detects spec drift by comparing a SHA256 hash of the user-provided pod template spec against the hash stored in the deployment annotation.

How it works:

1. When a deployment is created, the controller computes a hash of the user-provided pod template spec (before controller modifications) and stores it in an annotation
2. On each reconciliation, the controller computes the hash of the current spec and compares it to the stored hash
3. If hashes differ, a rolling update is triggered

This approach:

• Detects ALL changes to the pod template spec (images, env vars, commands, volumes, resources, etc.)
• Avoids issues with cluster-provided values and timestamps
• Maintains backwards compatibility (legacy deployments without the hash annotation are not affected)

Usage

apiVersion: temporal.io/v1alpha1
kind: TemporalWorkerDeployment
metadata:
  name: my-worker
spec:
  workerOptions:
    connectionRef:
      name: my-connection
    temporalNamespace: default
    # Set this to your workflow code hash (e.g., from CI/CD)
    customBuildID: "wf-a1b2c3d4"
  template:
    spec:
      containers:
        - name: worker
          image: my-worker:v1.2.3  # Can change without new deployment

Behavior Matrix

Scenario	Build ID	Result
No customBuildID field	Auto-generated from image + hash	Existing behavior
customBuildID set, first deploy	Uses field value	New deployment
customBuildID unchanged, spec changed	Same build ID	Rolling update
customBuildID changed	New build ID	New deployment
Empty/invalid customBuildID	Falls back to auto-generated	Existing behavior

Backwards Compatibility

• Empty or invalid customBuildID values fall back to existing hash-based generation
• No changes required for users who don't use this feature
• Drift detection only runs when spec.workerOptions.customBuildID is explicitly set
• Legacy deployments without the pod template spec hash annotation are not affected

Test plan

• CustomBuildID spec field override (6 test cases)
• Hash computation tests (determinism, different images/env vars/commands/volumes)
• Drift detection with hash comparison (7 test cases)
• Backwards compatibility for legacy deployments without hash annotation
• Edge cases: empty values, invalid chars, long values
• go test ./... passes

[carlydf]

Hi there, sorry for the late review, just getting back to this after the holidays. I'm committed to turning this PR around quickly though and I think it's really close! I'll be keeping an eye on this tomorrow so we can iterate quickly.

[carlydf]

So close to approving! The main decision I still want to make together is how to name the new field.

My review was delayed today because I wanted to write an integration test for this new functionality, which you can look at in this commit. Confirmed it works :) In the early phases of this project, features that only had unit tests and no integration tests experienced regressions, so I want to make sure that doesn't happen here. Feel free to cherry-pick my test commit onto your fork (if that can be done with a fork), or I can merge my integration test right after your PR merges.

[carlydf]

approved! you'll need to run make fmt-imports to get the linter to pass.
I also changed the repo settings so the CI jobs should all run when you next push instead of requiring admin approval.

[tshtark]

@carlydf Thanks!
But actually I see that the CI workflows are still waiting for approval to run..
Could you approve those?