feat(common): support rollout strategy in options

[l-qing]

Changes

Fixes #3812

Adds spec.strategy (Deployment) and spec.updateStrategy (StatefulSet) to the
set of fields that options copies onto the generated manifests.

Why

options does not merge the embedded object — the transformer copies an
explicit list of fields, documented under
Deployments.
replicas, affinity and topologySpreadConstraints are on that list; the
rollout strategy is not, so a strategy block under options is stored by the
API server (the field is x-kubernetes-preserve-unknown-fields, so it is not
validated) and then dropped by the reconciler without any error, warning or
condition.

That combination has a concrete failure mode, because the fields already
supported are exactly the ones needed to construct it:

options:
  deployments:
    tekton-pipelines-controller:
      spec:
        replicas: 3
        template:
          spec:
            affinity:
              podAntiAffinity:
                requiredDuringSchedulingIgnoredDuringExecution:
                  - topologyKey: kubernetes.io/hostname
                    labelSelector:
                      matchLabels:
                        app.kubernetes.io/name: controller

Three HA replicas, hard anti-affinity so no two share a node. None of the
shipped Deployments declare spec.strategy, so Kubernetes applies the default
RollingUpdate with maxSurge: 25% / maxUnavailable: 25%, computed by
rounding the surge up and the unavailable count down. At replicas: 3
that is maxSurge: 1, maxUnavailable: 0.

On a cluster with exactly three eligible nodes, all three already hold a
replica. The surge pod has no node satisfying the anti-affinity rule and stays
Pending, and maxUnavailable: 0 forbids terminating any old pod to make room.
The rollout cannot complete — not as a scheduling race, but arithmetically, and
maxUnavailable rounds to 0 for any replicas ≤ 3, which is the common
on-premises cluster size. topologySpreadConstraints with
whenUnsatisfiable: DoNotSchedule deadlocks identically.

The remedy is maxSurge: 0 with maxUnavailable: 1 — replace the replicas one
at a time, never needing a spare node — or type: Recreate. That is exactly the
field options will not carry over, and there is no way to set it from outside
options either: resourceReconcileFields() returns spec for Deployment and
StatefulSet and copyResourceFields() applies
unstructured.SetNestedField(dst.Object, fieldValue, "spec"), so the whole
spec is overwritten from the expected manifest and a hand-edited strategy is
reverted on the next reconcile.

I do not think the operator should infer this. Whether a spare eligible node
exists is not knowable from the Deployment alone, clusters with headroom
genuinely want the surge behaviour, and inference would not cover the adjacent
cases (a full namespace ResourceQuota leaving no room for the surge pod —
which the operator already detects via ReplicaSetReplicaFailure /
FailedCreate — or single-node clusters). It is an environment-specific
decision, the same reasoning behind priorityClassName, runtimeClassName and
topologySpreadConstraints being added to options.

Implementation

Two symmetric additions, in updateDeployments() and updateStatefulSets(),
guarded on a non-empty strategy type to match the existing
PriorityClassName != "" style in the same functions:

if deploymentOptions.Spec.Strategy.Type != "" {
    targetDeployment.Spec.Strategy = deploymentOptions.Spec.Strategy
}

Three semantics worth calling out, each covered by a test:

• The whole struct is replaced, not merged field by field. rollingUpdate
  may not be set when the type is Recreate (OnDelete for StatefulSets); a
  field-wise merge would leave the base manifest's rollingUpdate block behind
  and produce an object the API server rejects. That is the failure mode the
  Recreate test case exists to catch.
• An empty type is a no-op, keeping the base manifest's strategy. This
  matches the "non-empty wins" semantics of every other field in the
  transformer.
• A self-contradictory strategy is passed through as given rather than
  partially dropped, so the user gets a real API server error instead of a
  silent half-application.

updateDeploymentHashValue() already zeroes Spec.Strategy before computing
the pod-template hash, so changing only the strategy leaves
operator.tekton.dev/deployment-spec-applied-hash unchanged and does not
trigger a rollout through that mechanism — which is the behaviour you want, and
is now asserted by a test.

Open to feedback: requiring type means the common case above has to
spell out type: RollingUpdate alongside rollingUpdate, even though it is
not changing the type. I chose that over honouring a bare rollingUpdate:
block because the latter has to decide whether an unset type inherits the base
strategy's type or falls back to the Kubernetes default, and either answer is
surprising in some case. Happy to change it if reviewers prefer the looser
form.

Tests

Added to the existing table-driven golden-file test in
transformer_additional_options_test.go:

Case	Covers
test-strategy-recreate-for-deployments	base has RollingUpdate + a rollingUpdate block, options set Recreate → result is Recreate with no rollingUpdate key
test-strategy-rollingupdate-tuning-for-deployments	maxSurge / maxUnavailable tuning is applied (the case from the description)
test-strategy-recreate-to-rollingupdate-for-deployments	the reverse direction, base Recreate → options RollingUpdate
test-strategy-not-set-for-deployments	options present without a strategy → base strategy preserved (regression guard)
test-strategy-rollingupdate-without-type-is-ignored-for-deployments	rollingUpdate without type is a no-op
test-strategy-recreate-with-rollingupdate-is-passed-through-for-deployments	contradictory options are passed through, not partially dropped
test-updatestrategy-ondelete-for-statefulsets	StatefulSet OnDelete drops the base rollingUpdate block
test-updatestrategy-partition-tuning-for-statefulsets	partition is applied
test-updatestrategy-not-set-for-statefulsets	regression guard

Plus TestDeploymentStrategyDoesNotAffectSpecHash, which the golden-file cases
cannot cover because the shared test helper strips the hash label before
comparing. It pairs the assertion with a replicas change as a vacuity guard,
so it cannot pass by hashing nothing.

Falsified against the source change: with
pkg/reconciler/common/transformer_additional_options.go reverted, the four
feature cases fail and the three regression guards still pass.

Docs

docs/TektonConfig.md:

• strategy and updateStrategy added to the supported-field lists under
  #### Deployments and #### StatefulSets.
• Both options examples extended with the maxSurge: 0 / maxUnavailable: 1
  form, since that is the shape people will actually need.
• A note in the Additional fields as options section stating that the embedded
  objects are not merged as a whole and that the per-kind lists are exhaustive —
  fields outside them are ignored silently. The lists were already there and
  correct, but nothing said they were the complete story, and the silent drop is
  easy to mistake for a bug in your own YAML.

Submitter Checklist

These are the criteria that every PR should meet, please check them off as you
review them:

• Run make test lint before submitting a PR
• Includes tests (if functionality changed/added)
• Includes docs (if user facing)
• Commit messages follow commit message best practices

See the contribution guide for more details.

This change was AI-assisted (Claude Opus 5 via Claude Code) and is disclosed
with an Assisted-by: trailer on the commit, per the
AI contribution policy.
I have reviewed and tested it, I understand it, and I take responsibility for
it.

Release Notes

`options` now applies `deployments[].spec.strategy` and
`statefulSets[].spec.updateStrategy` to the generated workloads instead of
ignoring them. This makes it possible to set, for example,
`rollingUpdate.maxSurge: 0` on a component whose replicas are pinned
one-per-node by anti-affinity, where the default surge-based rollout cannot
schedule the extra pod.

[l-qing]

/kind feature

[l-qing]

/assign @l-qing

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 25.41%. Comparing base (5a94d1b) to head (b115281).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3813      +/-   ##
==========================================
+ Coverage   25.40%   25.41%   +0.01%     
==========================================
  Files         449      449              
  Lines       23477    23481       +4     
==========================================
+ Hits         5964     5968       +4     
  Misses      16822    16822              
  Partials      691      691              

Flag	Coverage Δ
unit-tests	25.41% <ø> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jkhelil]

/approve

[tekton-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jkhelil

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [jkhelil]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment