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.

• 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.buildID. When the build ID is stable but pod spec changes, trigger a rolling update instead of creating a new deployment.

Key Changes

• Add BuildID field to WorkerOptions struct in API types
• Update ComputeBuildID to use spec field instead of annotation
• 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
• Only check for drift when buildID is explicitly set by user

Drift Detection

When spec.workerOptions.buildID 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)

When drift is detected: Controller triggers a rolling update of the existing deployment (preserves same build ID).

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
    buildID: "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 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
Empty/invalid buildID	Falls back to auto-generated	Existing behavior

Backwards Compatibility

• Empty or invalid buildID 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.buildID is explicitly set
• Legacy deployments without the pod template spec hash annotation are not affected

Test plan

• Build ID 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 ./internal/k8s/... ./internal/planner/... -v 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]

can you re-use the pod-spec-modification code from NewDeploymentWithOwnerRef (if the whole thing can't be reused, maybe a shared helper function) so that we don't have to keep two separate functions in sync?

[carlydf]

I'd prefer to name this in a way that makes it clear that providing your own Build ID is not required, since as we say in the warning, it's not safe unless you do work on your own side to ensure that Build ID is updated when incompatible changes happen.

I worry that people could get confused, not read the doc-string description of the field, and copy-pasta themselves into a situation where they're not updating the Build ID and get NDEs in their workflows despite "using versioning."

Would you be opposed to calling it something like CustomBuildID?