Merge pull request #1371 from yue9944882/spring-auto-configure-dep

Feat(Spring-Integration): Support auto-configure to shorten configuration steps

Author: k8s-ci-robot

docs/java-controller-tutorial-rewrite-rs-controller.md

@@ -46,11 +46,33 @@ plugins are present in the [pom.xml](https://github.com/yue9944882/replicaset-co
 </plugin>
 ```
 
+#### Introducing Spring Integration Dependency
+
+Adding the following dependency to your `pom.xml`.
+
+```xml
+<dependency>
+	<groupId>io.kubernetes</groupId>
+	<artifactId>client-java-spring-integration</artifactId>
+	<version>${ >= 11.0.0 recommended}</version>
+</dependency>
+```
+
+The dependency will auto-configure the necessary configuration beans for injecting informers
+and reconcilers to your application. And note that you can disable the configuration beans by
+setting the following properties in your spring context:
+
+
+```text
+kubernetes.informer.enabled=false   # disables informer injection
+kubernetes.reconciler.enabled=false # disables reconciler injection
+```
+
 #### Adding a Main Class 
 
 So that the project can be packaged as a executable jar. See the example class [here](https://github.com/yue9944882/replicaset-controller/blob/master/src/main/java/com/github/yue9944882/kubernetes/Application.java).
 
-#### Loading Post-Processor Spring Beans
+##### Loading Post-Processor Spring Beans (Required only if you're using < 11.0.0 releases)
 
 Adding the following annotation to whatever Java class under spring context, so that processors can be activated.
 
@@ -60,10 +82,6 @@ Adding the following annotation to whatever Java class under spring context, so
 
 Corresponding example is available [here](https://github.com/yue9944882/replicaset-controller/blob/master/src/main/java/com/github/yue9944882/kubernetes/config/ControllerConfiguration.java#L20).
 
-__NOTE__: In the future releases (already landed on master, will release after 11.0.0), you will be able to activate the processors by configuration- 
-beans. To previewing the feature, you can take a glance at the test codes for [KubernetesReconcilerConfigurer](https://github.com/kubernetes-client/java/blob/351ffa13d49cb76445788d78bf83e03a5edf139a/spring/src/test/java/io/kubernetes/client/spring/extended/controller/KubernetesReconcilerCreatorTest.java#L75-L79) and 
-[KubernetesInformerConfigurer](https://github.com/kubernetes-client/java/blob/351ffa13d49cb76445788d78bf83e03a5edf139a/spring/src/test/java/io/kubernetes/client/spring/extended/controller/KubernetesInformerCreatorTest.java#L73-L76).
-
 #### Declaring Your Informer Factory
 
 You're supposed to create a new class (can be a inner-class) extending `io.kubernetes.client.informer.SharedInformerFactory`,
@@ -99,10 +117,11 @@ The registered informer-factory won't be running unless you explcitly calls `sta
 the method is the trigger to run the controller, so hold it carefully until you're ready :). In the example project, the 
 informer-factory was started inside `ControllerManager#run`.
 
-The [KubernetesInformerFactoryProcessor](https://github.com/kubernetes-client/java/blob/master/spring/src/main/java/io/kubernetes/client/spring/extended/controller/KubernetesInformerFactoryProcessor.java) 
-will be parsing the `@KubernetesInformers` annotation on informer-factory class and then register `SharedInformer` and 
-`Lister` beans for the kubernetes resource classes. You can easily acquire them by declaring them as parameters in the
-bean method. See this example source to see the per-resource informer/lister bean registration [here](https://github.com/yue9944882/replicaset-controller/blob/c8dda02fe444d7154117b9bf0583557502694e1b/src/main/java/com/github/yue9944882/kubernetes/config/ControllerConfiguration.java#L35-L43).
+As a deeper insight, it's the [KubernetesInformerFactoryProcessor](https://github.com/kubernetes-client/java/blob/master/spring/src/main/java/io/kubernetes/client/spring/extended/controller/KubernetesInformerFactoryProcessor.java) 
+parsing the `@KubernetesInformers` annotation on informer-factory class and then register `SharedInformer` and 
+`Lister` beans for the kubernetes resource classes. You can easily acquire them by `@Autowired` (for >= 11.0.0 release) 
+or declaring them as parameters in the bean method. See this example source to see the per-resource informer/lister 
+bean registration [here](https://github.com/yue9944882/replicaset-controller/blob/c8dda02fe444d7154117b9bf0583557502694e1b/src/main/java/com/github/yue9944882/kubernetes/config/ControllerConfiguration.java#L35-L43).
 
 
 #### Declaring Your Reconciler
@@ -126,10 +145,78 @@ the watch connections are managed by informer-factory and they're multiplex'd. S
 to the watch connection. For more detail, take a look at the example code [here](https://github.com/yue9944882/replicaset-controller/blob/c8dda02fe444d7154117b9bf0583557502694e1b/src/main/java/com/github/yue9944882/kubernetes/ReplicaSetReconciler.java#L27-L40).
 
 
+#### Injecting Informer/Lister using @Autowired (Optional for >= 11.0.0 releases)
+
+You can easily acquire `SharedInformer` and `Lister` instances via `@Autowired` annotations instead of passing them from
+the bean constructor, see the following example:
+
+```java
+public class ReplicaSetReconciler implements Reconciler {
+    @Autowired private SharedInformer<V1Pod> podInformer;
+    @Autowired private Lister<V1Pod> podLister;
+    @Autowired private SharedInformer<V1Node> nodeInformer;
+    @Autowired private Lister<V1Node> nodeLister;
+    ...
+}
+```
+
+Note that the type parameter for the informer and lister i.e. the kubernetes api resource type must be declared in your 
+`@KubernetesInformers` annotation.
+
+#### Setting Event-Filter or ReadyFunc for your reconciler
+
+Both the event-filter method and ready-func method is supposed to be "public" access.
+
+```java
+public class ReplicaSetReconciler implements Reconciler {
+    ...
+    @AddWatchEventFilter(apiTypeClass = V1Pod.class)
+    public boolean onAddFilter(V1Pod pod) {
+      return true; // returns true to handle the event
+    }
+    
+    @UpdateWatchEventFilter(apiTypeClass = V1Pod.class)
+    public boolean onUpdateFilter(V1Pod oldPod, V1Pod newPod) {
+      return true; // returns true to handle the event
+    }
+    
+    @DeleteWatchEventFilter(apiTypeClass = V1Pod.class)
+    public boolean onDeleteFilter(V1Pod pod) {
+      return true; // returns true to handle the event
+    }
+    
+    @KubernetesReconcilerReadyFunc
+    public boolean podInformerCacheReady() {
+      return podInformer.hasSynced(); // return true if reconciler is ready to run.
+    }
+    ..
+}
+```
+
+#### Creating Your Controller Bean (Required for >= 11.0.0 releases)
+
+The controller bean is the entry bean to run your reconciler class definition. You're supposed to create a controller 
+bean instance using `KubernetesControllerFactory`:
+
+
+```java
+@Configuration
+public class MyConfiguration {
+    ...
+    @Bean
+    public KubernetesControllerFactory replicasetController(
+        SharedInformerFactory sharedInformerFactory,
+        Reconciler reconciler) {
+      return new KubernetesControllerFactory(sharedInformerFactory, reconciler);
+    }
+    ...
+}
+```
+
 #### Running the Reconcilers
 
 Now both the informer-factory and the reconciler are set, the last step is to stitch them together by adding a starter
-(or runner) bean implemeting `InitializingBean` as is shown in the following approaches:
+(or a `CommandLineRunner`) or a bean implemeting `InitializingBean` as is shown in the following approaches:
 
 
 - (Option 1) Run it immediately.

examples/src/main/java/io/kubernetes/client/examples/SpringControllerExample.java

@@ -67,8 +67,9 @@ public CommandLineRunner commandLineRunner(
     // *REQUIRED*
     // Configurer components that registers informers to the informer-factory in the context.
     @Bean
-    public KubernetesInformerConfigurer kubernetesInformerConfigurer(ApiClient apiClient) {
-      return new KubernetesInformerConfigurer(apiClient);
+    public KubernetesInformerConfigurer kubernetesInformerConfigurer(
+        ApiClient apiClient, SharedInformerFactory sharedInformerFactory) {
+      return new KubernetesInformerConfigurer(apiClient, sharedInformerFactory);
     }
 
     // *REQUIRED*
@@ -126,7 +127,6 @@ public static class MySharedInformerFactory extends SharedInformerFactory {}
   // io.kubernetes.client.extended.controller.Controller}
   // with the name specified and registering it to the spring bean-factory.
   @KubernetesReconciler(
-      value = "node-printing-controller",
       watches =
           @KubernetesReconcilerWatches({
             @KubernetesReconcilerWatch(

spring/src/main/java/io/kubernetes/client/spring/extended/controller/KubernetesInformerConfigurer.java

@@ -12,6 +12,7 @@
 */
 package io.kubernetes.client.spring.extended.controller;
 
+import io.kubernetes.client.informer.SharedInformerFactory;
 import io.kubernetes.client.openapi.ApiClient;
 import org.springframework.beans.factory.FactoryBean;
 
@@ -23,14 +24,17 @@ public class KubernetesInformerConfigurer
     implements FactoryBean<KubernetesInformerFactoryProcessor> {
 
   private final ApiClient apiClient;
+  private final SharedInformerFactory sharedInformerFactory;
 
-  public KubernetesInformerConfigurer(ApiClient apiClient) {
+  public KubernetesInformerConfigurer(
+      ApiClient apiClient, SharedInformerFactory sharedInformerFactory) {
     this.apiClient = apiClient;
+    this.sharedInformerFactory = sharedInformerFactory;
   }
 
   @Override
   public KubernetesInformerFactoryProcessor getObject() throws Exception {
-    return new KubernetesInformerFactoryProcessor(apiClient);
+    return new KubernetesInformerFactoryProcessor(apiClient, sharedInformerFactory);
   }
 
   @Override

spring/src/main/java/io/kubernetes/client/spring/extended/controller/KubernetesInformerFactoryProcessor.java

@@ -19,16 +19,11 @@
 import io.kubernetes.client.openapi.ApiClient;
 import io.kubernetes.client.spring.extended.controller.annotation.KubernetesInformer;
 import io.kubernetes.client.spring.extended.controller.annotation.KubernetesInformers;
-import io.kubernetes.client.util.ClientBuilder;
 import io.kubernetes.client.util.generic.GenericKubernetesApi;
-import java.io.IOException;
 import java.time.Duration;
-import java.util.Map;
-import java.util.Optional;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.BeansException;
-import org.springframework.beans.factory.NoSuchBeanDefinitionException;
 import org.springframework.beans.factory.config.ConfigurableListableBeanFactory;
 import org.springframework.beans.factory.support.AbstractBeanDefinition;
 import org.springframework.beans.factory.support.BeanDefinitionRegistry;
@@ -57,53 +52,22 @@ public class KubernetesInformerFactoryProcessor
 
   private BeanDefinitionRegistry beanDefinitionRegistry;
 
-  private ApiClient apiClient = null;
+  private final ApiClient apiClient;
+  private final SharedInformerFactory sharedInformerFactory;
 
-  public KubernetesInformerFactoryProcessor(ApiClient apiClient) {
+  public KubernetesInformerFactoryProcessor(
+      ApiClient apiClient, SharedInformerFactory sharedInformerFactory) {
     this.apiClient = apiClient;
+    this.sharedInformerFactory = sharedInformerFactory;
   }
 
   @Override
   public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory)
       throws BeansException {
-    Optional<String> sharedInformerFactoryBeanName;
-    try {
-      Map<String, SharedInformerFactory> sharedInformerFactories =
-          beanFactory.getBeansOfType(SharedInformerFactory.class);
-      if (sharedInformerFactories.size() > 1) {
-        log.warn("More than sharedInformerFactory registered..");
-        return;
-      }
-      sharedInformerFactoryBeanName = sharedInformerFactories.keySet().stream().findFirst();
-    } catch (NoSuchBeanDefinitionException e) {
-      // should never happen..
-      log.error("No sharedInformerFactory bean registered..");
-      return;
-    }
-
-    if (!sharedInformerFactoryBeanName.isPresent()) {
-      log.info("No sharedInformerFactory selected, skipping informers constructing..");
-      return;
-    }
-
-    if (this.apiClient == null) {
-      try {
-        this.apiClient = beanFactory.getBean(ApiClient.class);
-      } catch (NoSuchBeanDefinitionException e) {
-        log.info("No ApiClient bean found, falling-back to default initialization..");
-        try {
-          this.apiClient = ClientBuilder.standard().build();
-        } catch (IOException ex) {
-          log.error("failed initializing ApiClient", ex);
-          return;
-        }
-      }
-    }
 
     this.apiClient.setHttpClient(
         this.apiClient.getHttpClient().newBuilder().readTimeout(Duration.ZERO).build());
 
-    SharedInformerFactory sharedInformerFactory = beanFactory.getBean(SharedInformerFactory.class);
     KubernetesInformers kubernetesInformers =
         sharedInformerFactory.getClass().getAnnotation(KubernetesInformers.class);
     if (kubernetesInformers == null || kubernetesInformers.value().length == 0) {

spring/src/main/java/io/kubernetes/client/spring/extended/controller/KubernetesReconcilerConfigurer.java

@@ -58,9 +58,6 @@ public int getOrder() {
   @Override
   public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory)
       throws BeansException {
-    if (this.sharedInformerFactory == null) {
-      this.sharedInformerFactory = beanFactory.getBean(SharedInformerFactory.class);
-    }
     String[] names = beanFactory.getBeanNamesForType(Reconciler.class);
     for (String name : names) {
       Reconciler reconciler = (Reconciler) beanFactory.getBean(name);

spring/src/main/java/io/kubernetes/client/spring/extended/controller/KubernetesReconcilerProcessor.java

@@ -34,9 +34,12 @@
   /**
    * The name of the Kubernetes Reconciler.
    *
+   * <p>NOTE: No longer in use for version >= 11.0.0
+   *
    * @return the string
    */
-  String value();
+  @Deprecated
+  String value() default "";
 
   /**
    * Watches kubernetes resources.

spring/src/main/java/io/kubernetes/client/spring/extended/controller/annotation/KubernetesReconciler.java

@@ -0,0 +1,28 @@
+/*
+Copyright 2020 The Kubernetes Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package io.kubernetes.client.spring.extended.controller.config;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@ConditionalOnProperty(value = "kubernetes.actuator.prometheus.enabled")
+public @interface ConditionalOnActuatorPrometheusEndpointEnabled {}

spring/src/main/java/io/kubernetes/client/spring/extended/controller/config/ConditionalOnActuatorPrometheusEndpointEnabled.java

@@ -0,0 +1,28 @@
+/*
+Copyright 2020 The Kubernetes Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package io.kubernetes.client.spring.extended.controller.config;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@ConditionalOnProperty(value = "kubernetes.informer.enabled", matchIfMissing = true)
+public @interface ConditionalOnKubernetesInformerEnabled {}