Dennis-Mircea Ciupitu created FLINK-39808:
---------------------------------------------
Summary: 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
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.
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)
