[
https://issues.apache.org/jira/browse/FLINK-39808?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
ASF GitHub Bot updated FLINK-39808:
-----------------------------------
Labels: pull-request-available (was: )
> Tighten FlinkVersion.isSupported() to reject @Deprecated versions and restore
> the deprecate-and-raise-floor pattern
> -------------------------------------------------------------------------------------------------------------------
>
> Key: FLINK-39808
> URL: https://issues.apache.org/jira/browse/FLINK-39808
> Project: Flink
> Issue Type: Improvement
> Components: Kubernetes Operator
> Affects Versions: kubernetes-operator-1.15.0
> Reporter: Dennis-Mircea Ciupitu
> Priority: Minor
> Labels: pull-request-available
> Fix For: kubernetes-operator-1.16.0
>
>
> h1. Summary
> {{org.apache.flink.kubernetes.operator.api.spec.FlinkVersion}} carries two
> independent statements about which Flink versions are usable, and they
> currently disagree.
> h2. The Two Statements
> *Statement 1: the {{@Deprecated}} annotations on enum constants*
> {{FlinkVersion.java}} marks early constants with javadoc deprecation notes:
> * {{v1_13}} - "No longer supported since 1.7 operator release"
> * {{v1_14}} - "No longer supported since 1.7 operator release"
> * {{v1_15}} - "Deprecated since 1.10 operator release"
> * {{v1_16}} - "Deprecated since 1.11 operator release"
> * {{{}v1_17{}}}, {{v1_18}} - {{@Deprecated}} with no javadoc note
> *Statement 2: the runtime check {{isSupported()}}*
> {code:java}
> public static boolean isSupported(FlinkVersion version) {
> return version != null && version.isEqualOrNewer(FlinkVersion.v1_15);
> }
> {code}
> This call is invoked from {{ValidatorUtils.validateSupportedVersion()}} and
> surfaces an {{UnsupportedFlinkVersion}} event when it returns {{{}false{}}}.
> h2. The Contradiction
> A user can deploy a {{FlinkDeployment}} with {{spec.flinkVersion: v1_15}}
> today. The runtime check accepts it (because {{v1_15.isEqualOrNewer(v1_15)}}
> is {{{}true{}}}), but the enum constant carries a deprecation notice saying
> the version is "Deprecated since 1.10 operator release". Same for
> {{{}v1_16{}}}, {{{}v1_17{}}}, {{{}v1_18{}}}.
> This makes it impossible to document the supported-versions list honestly
> without either explaining the contradiction in user-facing text or one of the
> two statements changing in code.
> The [Flink Kubernetes Operator 1.15.0 Release
> Announcement|https://flink.apache.org/2026/05/26/apache-flink-kubernetes-operator-1.15.0-release-announcement/]
> cite the following:
> _"_
> _Operator 1.15.0 is fully validated against Apache Flink 2.2. The supported
> Flink version matrix is:_
> _*2.2.x, 2.1.x, 2.0.x, 1.20.x, 1.19.x*_
> _"_
> h2. Historical Context
> The project had a working pattern for handling Flink version deprecation, and
> the contradiction grew because subsequent commits stopped following it.
> *The established pattern*
> ([FLINK-33089|https://github.com/apache/flink-kubernetes-operator/commit/02d8dd5d915b7d890d09c23c9003580ab63e6dc1]
> - "Clean up 1.13 and 1.14 references from docs and code"):
> When {{v1_13}} and {{v1_14}} were retired, the commit did three things
> consistently:
> # Added {{@Deprecated}} with explicit javadoc notes ("No longer supported
> since 1.7 operator release") to both enum constants.
> # Updated {{isSupported()}} to raise the floor from {{v1_14}} to
> {{{}v1_15{}}}, so the runtime check rejected the now-deprecated versions.
> # Updated docs ({{{}overview.md{}}}, {{{}reference.md{}}}) to reflect the
> new supported set and surface the "no longer supported" notes for users.
> All three statements agreed afterward.
> *The drift* (two later commits):
> [FLINK-37236|https://github.com/apache/flink-kubernetes-operator/commit/d6e20e22ff832abe644eee91d520238b230fa374]
> - "Bump Flink dependencies to 1.20 and add v2_0 version": Added new versions
> and removed older ones from the CI matrix, but did not update
> {{isSupported()}} or the runtime semantics for the versions being retired.
> [FLINK-38147|https://github.com/apache/flink-kubernetes-operator/commit/b0274cb2ea724c758182401de2d77908f2a2271e]
> - "Add Flink 2.1 support": Added {{@Deprecated}} to {{v1_17}} and {{v1_18}}
> (without javadoc notes), added {{v2_1}} and {{{}v2_2{}}}, but again did not
> update {{{}isSupported(){}}}.
> The result is the current contradiction: {{v1_17}} and {{v1_18}} carry
> {{@Deprecated}} but are still accepted at runtime, and
> {{{}v1_15{}}}/{{{}v1_16{}}} continue to be runtime-accepted despite the
> explicit "deprecated since X operator release" javadoc set in commit 1's era.
> h2. Concrete Effects
> * The auto-generated table in
> {{docs/content/docs/custom-resource/reference.md}} shows {{v1_15}} and
> {{v1_16}} with "Deprecated since X operator release" notes, but no statement
> that they are actually still accepted at runtime.
> * The {{UnsupportedFlinkVersion}} event documented in
> {{docs/content/docs/operations/events.md}} only fires for versions older than
> {{v1_15}} (i.e. {{v1_13}} and {{{}v1_14{}}}). Users running
> deprecated-but-accepted {{v1_15}} through {{v1_18}} get no event, no warning,
> no log indication that they are on a version slated for removal.
> * The {{Compatibility}} docs page cannot include a "Supported Flink
> versions" section without a contradiction footnote.
> * New deprecations from {{v1_19}} onward will require a third manual update
> (annotation + {{isSupported()}} + docs) that contributors have already shown
> they will miss, perpetuating the drift.
> h1. Proposed Resolution
> Restore the pattern established in
> [FLINK-33089|https://github.com/apache/flink-kubernetes-operator/commit/02d8dd5d915b7d890d09c23c9003580ab63e6dc1].
> The runtime check {{isSupported()}} should be the authoritative source of
> truth, deriving its decision from the {{@Deprecated}} annotation so that
> future deprecations propagate automatically without contributors having to
> remember three separate code sites.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
