From ea20e96d4c3cd6e4b5aa502e6a648dd80491e78f Mon Sep 17 00:00:00 2001 From: Chris Laprun Date: Mon, 19 May 2025 16:19:12 +0200 Subject: [PATCH 1/3] docs: document annotation-based dependent resource configuration Fixes #2791 Signed-off-by: Chris Laprun --- .../en/docs/documentation/configuration.md | 35 ++++++++++++++----- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/docs/content/en/docs/documentation/configuration.md b/docs/content/en/docs/documentation/configuration.md index 052c0e0f19..d0c47270a3 100644 --- a/docs/content/en/docs/documentation/configuration.md +++ b/docs/content/en/docs/documentation/configuration.md @@ -113,14 +113,33 @@ for this feature. ## DependentResource-level configuration -`DependentResource` implementations can implement the `DependentResourceConfigurator` interface -to pass information to the implementation. For example, the SDK -provides specific support for the `KubernetesDependentResource`, which can be configured via the -`@KubernetesDependent` annotation. This annotation is, in turn, converted into a -`KubernetesDependentResourceConfig` instance, which is then passed to the `configureWith` method -implementation. - -TODO +It is possible to define custom annotations to configure custom `DependentResource` implementations. For example, the +SDK provides the `@KubernetesDependent` annotation which allows configuring `KubernetesDependentResource` instance. + +In order to provide such a configuration mechanism for your own `DependentResource` implementations, they must be +annotated with the `@Configured` annotation. This annotation defines 3 fields that tie everything together: + +- `by`, which specifies which annotation class will be used to configure your dependents, +- `with`, which specifies the class holding the configuration object for your dependents and +- `converter`, which specifies the `ConfigurationConverter` implementation in charge of converting the annotation + specified by the `by` field into objects of the class specified by the `with` field. + +`ConfigurationConverter` instances implement a single `configFrom` method, which will receive, as expected, the +annotation instance annotating the dependent resource instance to be configured, but it can also extract information +from the `DependentResourceSpec` instance associated with the `DependentResource` class so that metadata from it can be +used in the configuration, as well as the parent `ControllerConfiguration`, if needed. The role of +`ConfigurationConverter` implementations is to extract the annotation information, augment it with metadata from the +`DependentResourceSpec` and the configuration from the parent controller on which the dependent is defined, to finally +create the configuration object that the `DependentResource` instances will use. + +However, one last element is required to finish the configuration process: the target `DependentResource` class must +implement the `ConfiguredDependentResource` interface, parameterized with the annotation class defined by the +`@Configured` annotation `by` field. This interface is called by the framework to inject the configuration at the +appropriate time and retrieve the configuration, if it's available. + +For more information on how to use this feature, we recommend looking at how this mechanism is implemented for +`KubernetesDependentResource` in the core framework, `SchemaDependentResource` in the samples or `CustomAnnotationDep` +in the `BaseConfigurationServiceTest` test class. ## EventSource-level configuration From 261a698b209b5664523aad9d291e95c2bf0c87d9 Mon Sep 17 00:00:00 2001 From: Chris Laprun Date: Mon, 19 May 2025 16:19:32 +0200 Subject: [PATCH 2/3] fix: remove now unneeded interface Signed-off-by: Chris Laprun --- .../dependent/DependentResourceConfigurationProvider.java | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/dependent/DependentResourceConfigurationProvider.java diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/dependent/DependentResourceConfigurationProvider.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/dependent/DependentResourceConfigurationProvider.java deleted file mode 100644 index a0c9dc67ae..0000000000 --- a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/dependent/DependentResourceConfigurationProvider.java +++ /dev/null @@ -1,6 +0,0 @@ -package io.javaoperatorsdk.operator.api.config.dependent; - -public interface DependentResourceConfigurationProvider { - @SuppressWarnings("rawtypes") - Object getConfigurationFor(DependentResourceSpec spec); -} From 977d509ff38e29a95e369800338ade907479b3f6 Mon Sep 17 00:00:00 2001 From: Chris Laprun Date: Wed, 21 May 2025 10:05:33 +0200 Subject: [PATCH 3/3] docs: expand KubernetesDependentResource example Signed-off-by: Chris Laprun --- .../en/docs/documentation/configuration.md | 30 +++++++++++++++---- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/content/en/docs/documentation/configuration.md b/docs/content/en/docs/documentation/configuration.md index d0c47270a3..06eda5f2a2 100644 --- a/docs/content/en/docs/documentation/configuration.md +++ b/docs/content/en/docs/documentation/configuration.md @@ -113,11 +113,9 @@ for this feature. ## DependentResource-level configuration -It is possible to define custom annotations to configure custom `DependentResource` implementations. For example, the -SDK provides the `@KubernetesDependent` annotation which allows configuring `KubernetesDependentResource` instance. - -In order to provide such a configuration mechanism for your own `DependentResource` implementations, they must be -annotated with the `@Configured` annotation. This annotation defines 3 fields that tie everything together: +It is possible to define custom annotations to configure custom `DependentResource` implementations. In order to provide +such a configuration mechanism for your own `DependentResource` implementations, they must be annotated with the +`@Configured` annotation. This annotation defines 3 fields that tie everything together: - `by`, which specifies which annotation class will be used to configure your dependents, - `with`, which specifies the class holding the configuration object for your dependents and @@ -137,6 +135,28 @@ implement the `ConfiguredDependentResource` interface, parameterized with the an `@Configured` annotation `by` field. This interface is called by the framework to inject the configuration at the appropriate time and retrieve the configuration, if it's available. +For example, `KubernetesDependentResource`, a core implementation that the framework provides, can be configured via the +`@KubernetesDependent` annotation. This set up is configured as follows: + +```java + +@Configured( + by = KubernetesDependent.class, + with = KubernetesDependentResourceConfig.class, + converter = KubernetesDependentConverter.class) +public abstract class KubernetesDependentResource + extends AbstractEventSourceHolderDependentResource> + implements ConfiguredDependentResource> { + // code omitted +} +``` + +The `@Configured` annotation specifies that `KubernetesDependentResource` instances can be configured by using the +`@KubernetesDependent` annotation, which gets converted into a `KubernetesDependentResourceConfig` object by a +`KubernetesDependentConverter`. That configuration object is then injected by the framework in the +`KubernetesDependentResource` instance, after it's been created, because the class implements the +`ConfiguredDependentResource` interface, properly parameterized. + For more information on how to use this feature, we recommend looking at how this mechanism is implemented for `KubernetesDependentResource` in the core framework, `SchemaDependentResource` in the samples or `CustomAnnotationDep` in the `BaseConfigurationServiceTest` test class.