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 drift detection by comparing deployed spec with desired spec
• 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 directly comparing the deployed pod spec with the desired spec.

Currently monitored fields:

• Replicas
• MinReadySeconds
• Container images
• Container resources (limits/requests)
• Init container images

Not currently monitored: env vars, volumes, commands (documented in BuildID field comment)

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

Note on CRD Changes

The CRD regeneration includes some unrelated changes from controller-gen (default values for name fields, x-kubernetes-map-type annotations). These are standard regeneration artifacts when running make manifests and don't affect functionality.

Test plan

• Build ID spec field override (6 test cases)
• Drift detection with direct spec comparison (5 test cases)
• Edge cases: empty values, invalid chars, long values
• go test ./internal/k8s/... ./internal/planner/... -v passes