[
https://issues.apache.org/jira/browse/FLINK-39808?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Dennis-Mircea Ciupitu updated FLINK-39808:
------------------------------------------
Description:
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.
was:
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.
> 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
> 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)
