[FLINK-40639][kubernetes] Deprecated kubernetes.pod-template-file takes precedence over kubernetes.pod-template-file.default - #29167

What is the purpose of the change

JOB_MANAGER_POD_TEMPLATE and TASK_MANAGER_POD_TEMPLATE register the deprecated kubernetes.pod-template-file through withFallbackKeys(getDeprecatedKeys(defaultPodTemplate)). getDeprecatedKeys returns keys whose FallbackKey#isDeprecated is true, but withFallbackKeys rebuilds them with FallbackKey#createFallbackKey, dropping the flag. Two problems follow.

The deprecated key wins over the current one. withFallbackKeys prepends ("put fallback keys first so that they are prioritized") while withDeprecatedKeys appends ("put deprecated keys last so that they are de-prioritized"), so the legacy key is checked ahead of kubernetes.pod-template-file.default. A user who moves to the new key but leaves the old one in their configuration silently keeps running the old pod template.

No deprecation warning is logged. Configuration#loggingFallback logs WARN only for deprecated keys and INFO otherwise. The only option still carrying the flag is KUBERNETES_POD_TEMPLATE, which no main source reads (KubernetesJobManagerParameters reads JOB_MANAGER_POD_TEMPLATE, PodTemplateMountDecorator reads TASK_MANAGER_POD_TEMPLATE), so users of the legacy key have never seen a deprecation warning.

Brief change log

• Register the legacy pod-template key with withDeprecatedKeys instead of withFallbackKeys, restoring both the precedence and the deprecation flag
• Add KubernetesConfigOptionsTest

Verifying this change

This change added tests and can be verified as follows:

• testPodTemplateDefaultKeyTakesPrecedenceOverDeprecatedKey resolves to /deprecated.yaml before the change and /default.yaml after
• testPodTemplateLegacyKeyIsRegisteredAsDeprecated is false before and true after
• testPodTemplateDeprecatedKeyIsStillHonoredOnItsOwn passes either way and guards the legacy path

Both failing cases were confirmed red against unmodified master before the fix. Existing Kubernetes suites stay green locally (199 tests across *PodTemplate*, Kubernetes{JobManager,TaskManager}Parameters*, Kubernetes{JobManager,TaskManager}Factory*, *Decorator*). Generated config docs are unaffected: the options' key, type, default and description do not change, and the docs generator does not render fallback or deprecated keys.

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): no
• The public API, i.e., is any changed class annotated with @Public(Evolving): no
• The serializers: no
• The runtime per-record code paths (performance sensitive): no
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: yes, Kubernetes pod template resolution
• The S3 file system connector: no

Documentation

• Does this pull request introduce a new feature? no
• If yes, how is the feature documented? not applicable

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: Claude Code (Claude Opus 5)