From 43e38050d193e30c84fb522bfd3970290bf0f7be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Wed, 4 Oct 2023 17:47:50 +0200 Subject: [PATCH 1/8] docs: release notes for 4.5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/_data/sidebar.yml | 4 +++- docs/documentation/v4-5-migration.md | 22 ++++++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 docs/documentation/v4-5-migration.md diff --git a/docs/_data/sidebar.yml b/docs/_data/sidebar.yml index d2572f5734..8c083a6cc1 100644 --- a/docs/_data/sidebar.yml +++ b/docs/_data/sidebar.yml @@ -30,4 +30,6 @@ - title: Migrating from v4.2 to v4.3 url: /docs/v4-3-migration - title: Migrating from v4.3 to v4.4 - url: /docs/v4-4-migration \ No newline at end of file + url: /docs/v4-4-migration + - title: Migrating from v4.4 to v4.5 + url: /docs/v4-5-migration \ No newline at end of file diff --git a/docs/documentation/v4-5-migration.md b/docs/documentation/v4-5-migration.md new file mode 100644 index 0000000000..4019044ee7 --- /dev/null +++ b/docs/documentation/v4-5-migration.md @@ -0,0 +1,22 @@ +--- +title: Migrating from v4.4 to v4.5 +description: Migrating from v4.4 to v4.5 +layout: docs +permalink: /docs/v4-5-migration +--- + +# Migrating from v4.4 to v4.5 + +This version some improvements how event are handled mainly in relation with Dependent Resources more precisely the +[caching and event handling](https://javaoperatorsdk.io/docs/dependent-resources#caching-and-event-handling-in-kubernetesdependentresource) +related functionality. As a result the kubernetes resources managed using +the [KubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java#L72-L72) +will add an annotation to the resource containing the resource version for the update. This can be turned off by +feature +a [feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) + +This functionality by default - in order to cover some corner cases - will also parse resource version. While +this against of recommendations in Kubernetes, will work. If in some rare circumstances or some special usages +of Kubernetes this would cause a problem, it can be turned off by +the [following feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L390-L390). + From 162a2d055ee7df6016d5ce16b9a303070976fccf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Wed, 4 Oct 2023 17:56:38 +0200 Subject: [PATCH 2/8] format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/documentation/v4-5-migration.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/documentation/v4-5-migration.md b/docs/documentation/v4-5-migration.md index 4019044ee7..76b204e2bd 100644 --- a/docs/documentation/v4-5-migration.md +++ b/docs/documentation/v4-5-migration.md @@ -9,14 +9,14 @@ permalink: /docs/v4-5-migration This version some improvements how event are handled mainly in relation with Dependent Resources more precisely the [caching and event handling](https://javaoperatorsdk.io/docs/dependent-resources#caching-and-event-handling-in-kubernetesdependentresource) -related functionality. As a result the kubernetes resources managed using -the [KubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java#L72-L72) +related functionality. As a result the kubernetes resources managed using the +[KubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java#L72-L72) will add an annotation to the resource containing the resource version for the update. This can be turned off by -feature -a [feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) +feature a +[feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) This functionality by default - in order to cover some corner cases - will also parse resource version. While this against of recommendations in Kubernetes, will work. If in some rare circumstances or some special usages -of Kubernetes this would cause a problem, it can be turned off by -the [following feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L390-L390). +of Kubernetes this would cause a problem, it can be turned off by the +[following feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L390-L390). From 87c1801f5561a999d7b5f2fad4b574926cf57db6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Wed, 4 Oct 2023 18:01:37 +0200 Subject: [PATCH 3/8] wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/documentation/v4-5-migration.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/documentation/v4-5-migration.md b/docs/documentation/v4-5-migration.md index 76b204e2bd..689b4e0ce4 100644 --- a/docs/documentation/v4-5-migration.md +++ b/docs/documentation/v4-5-migration.md @@ -7,13 +7,14 @@ permalink: /docs/v4-5-migration # Migrating from v4.4 to v4.5 -This version some improvements how event are handled mainly in relation with Dependent Resources more precisely the +Version 4.5 introduces improvements how events are handled mainly in relation with Dependent Resources more precisely the [caching and event handling](https://javaoperatorsdk.io/docs/dependent-resources#caching-and-event-handling-in-kubernetesdependentresource) -related functionality. As a result the kubernetes resources managed using the +features. As a result the kubernetes resources managed using the [KubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java#L72-L72) -will add an annotation to the resource containing the resource version for the update. This can be turned off by -feature a +will add an annotation to the resource containing the resource version during and update or create. +This can be turned off by feature a [feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) +if causes some issues in your use case. This functionality by default - in order to cover some corner cases - will also parse resource version. While this against of recommendations in Kubernetes, will work. If in some rare circumstances or some special usages From da2ee061b993f6c192f1fc4ecf90e66097e8f5dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Wed, 4 Oct 2023 18:03:28 +0200 Subject: [PATCH 4/8] more wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/documentation/v4-5-migration.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/documentation/v4-5-migration.md b/docs/documentation/v4-5-migration.md index 689b4e0ce4..c8f462c841 100644 --- a/docs/documentation/v4-5-migration.md +++ b/docs/documentation/v4-5-migration.md @@ -16,8 +16,11 @@ This can be turned off by feature a [feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) if causes some issues in your use case. -This functionality by default - in order to cover some corner cases - will also parse resource version. While -this against of recommendations in Kubernetes, will work. If in some rare circumstances or some special usages +This functionality by default - in order to cover some corner cases - will also parse resource version. +While resource version in metadata of a Kubernetes resource should be considered as a string, it is consistently +a monotonically increasing decimal number in the background. +While this against of recommendations in Kubernetes helps to cover some corner cases. +If in some rare circumstances or some special usages of Kubernetes this would cause a problem, it can be turned off by the [following feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L390-L390). From d7bc34e4a88ab0dd1c2696f24087ce78084d68ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Wed, 4 Oct 2023 18:04:18 +0200 Subject: [PATCH 5/8] wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/documentation/v4-5-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/documentation/v4-5-migration.md b/docs/documentation/v4-5-migration.md index c8f462c841..c2178e067d 100644 --- a/docs/documentation/v4-5-migration.md +++ b/docs/documentation/v4-5-migration.md @@ -7,11 +7,11 @@ permalink: /docs/v4-5-migration # Migrating from v4.4 to v4.5 -Version 4.5 introduces improvements how events are handled mainly in relation with Dependent Resources more precisely the +Version 4.5 introduces improvements related to event handling for Dependent Resources, more precisely the [caching and event handling](https://javaoperatorsdk.io/docs/dependent-resources#caching-and-event-handling-in-kubernetesdependentresource) features. As a result the kubernetes resources managed using the [KubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java#L72-L72) -will add an annotation to the resource containing the resource version during and update or create. +or subclasses, will add an annotation to the resource containing the resource version during and update or create. This can be turned off by feature a [feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) if causes some issues in your use case. From 22d5501fb1a57419a3905c9202f3e2bddf2d1bab Mon Sep 17 00:00:00 2001 From: Chris Laprun Date: Thu, 5 Oct 2023 10:03:06 +0200 Subject: [PATCH 6/8] docs: rewording Signed-off-by: Chris Laprun --- docs/documentation/v4-5-migration.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/documentation/v4-5-migration.md b/docs/documentation/v4-5-migration.md index c2178e067d..1ca54d0b9d 100644 --- a/docs/documentation/v4-5-migration.md +++ b/docs/documentation/v4-5-migration.md @@ -9,18 +9,16 @@ permalink: /docs/v4-5-migration Version 4.5 introduces improvements related to event handling for Dependent Resources, more precisely the [caching and event handling](https://javaoperatorsdk.io/docs/dependent-resources#caching-and-event-handling-in-kubernetesdependentresource) -features. As a result the kubernetes resources managed using the +features. As a result the Kubernetes resources managed using [KubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java#L72-L72) -or subclasses, will add an annotation to the resource containing the resource version during and update or create. -This can be turned off by feature a +or its subclasses, will add an annotation recording the resource's version whenever JOSDK updates or creates such +resources. This can be turned off using a [feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) -if causes some issues in your use case. +if this feature causes issues for your use case. -This functionality by default - in order to cover some corner cases - will also parse resource version. -While resource version in metadata of a Kubernetes resource should be considered as a string, it is consistently -a monotonically increasing decimal number in the background. -While this against of recommendations in Kubernetes helps to cover some corner cases. -If in some rare circumstances or some special usages -of Kubernetes this would cause a problem, it can be turned off by the +While Kubernetes resource versions should be considered as opaque and their interpretation discouraged, Kubernetes has, +at least so far, implemented them as a monotonically increasing integer. As a result, JOSDK will currently use +this information to support some corner cases. Of course, should this change, JOSDK will revise its implementation. +Also, if this interpreting of the resource versions causes issues, you can turn the feature off using the [following feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L390-L390). From 9470f0e530b79981ba5fcd500c078d1aceb3870f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Thu, 5 Oct 2023 10:26:41 +0200 Subject: [PATCH 7/8] improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/documentation/v4-5-migration.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/documentation/v4-5-migration.md b/docs/documentation/v4-5-migration.md index 1ca54d0b9d..271e558cb8 100644 --- a/docs/documentation/v4-5-migration.md +++ b/docs/documentation/v4-5-migration.md @@ -14,11 +14,20 @@ features. As a result the Kubernetes resources managed using or its subclasses, will add an annotation recording the resource's version whenever JOSDK updates or creates such resources. This can be turned off using a [feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) -if this feature causes issues for your use case. +if causes some issues in your use case. + +This functionality by default will also parse field `metadata.resourceVersion` of +managed resources. Again by default just in case of Dependent Resource are used. + +This helps to ensure that in the cache resources are with monotonically increasing resources version, +with all the additional consistency guarantees that mentioned features above provide. +In other words (and more precisely) if this is not done, it can happen in rare corner cases that for a +very short time cache will contain a resource with older version, however there was already a newer +version present before; so resource in the cache can jump to an older version (again for a short period of time). +Note that this will eventually resolve, so eventual consistency is guaranteed in all cases. While Kubernetes resource versions should be considered as opaque and their interpretation discouraged, Kubernetes has, at least so far, implemented them as a monotonically increasing integer. As a result, JOSDK will currently use this information to support some corner cases. Of course, should this change, JOSDK will revise its implementation. Also, if this interpreting of the resource versions causes issues, you can turn the feature off using the [following feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L390-L390). - From 46e6ce390377539276dd8c59ce3534f0d143cf6c Mon Sep 17 00:00:00 2001 From: Chris Laprun Date: Thu, 5 Oct 2023 11:14:19 +0200 Subject: [PATCH 8/8] docs: rewording Signed-off-by: Chris Laprun --- docs/documentation/v4-5-migration.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/docs/documentation/v4-5-migration.md b/docs/documentation/v4-5-migration.md index 271e558cb8..0ff08eef13 100644 --- a/docs/documentation/v4-5-migration.md +++ b/docs/documentation/v4-5-migration.md @@ -16,18 +16,11 @@ resources. This can be turned off using a [feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L375-L375) if causes some issues in your use case. -This functionality by default will also parse field `metadata.resourceVersion` of -managed resources. Again by default just in case of Dependent Resource are used. - -This helps to ensure that in the cache resources are with monotonically increasing resources version, -with all the additional consistency guarantees that mentioned features above provide. -In other words (and more precisely) if this is not done, it can happen in rare corner cases that for a -very short time cache will contain a resource with older version, however there was already a newer -version present before; so resource in the cache can jump to an older version (again for a short period of time). -Note that this will eventually resolve, so eventual consistency is guaranteed in all cases. - -While Kubernetes resource versions should be considered as opaque and their interpretation discouraged, Kubernetes has, -at least so far, implemented them as a monotonically increasing integer. As a result, JOSDK will currently use -this information to support some corner cases. Of course, should this change, JOSDK will revise its implementation. -Also, if this interpreting of the resource versions causes issues, you can turn the feature off using the +Using this feature, JOSDK now tracks versions of cached resources. It also uses, by default, that information to prevent +unneeded reconciliations that could occur when, depending on the timing of operations, an outdated resource would happen +to be in the cache. This relies on the fact that versions (as recorded by the `metadata.resourceVersion` field) are +currently implemented as monotonically increasing integers (though they should be considered as opaque and their +interpretation discouraged). Note that, while this helps preventing unneeded reconciliations, things would eventually +reach consistency even in the absence of this feature. Also, if this interpreting of the resource versions causes +issues, you can turn the feature off using the [following feature flag](https://github.com/java-operator-sdk/java-operator-sdk/blob/73b1d8db926a24502c3a70da34f6bcac4f66b4eb/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L390-L390).