org.microbean.kubernetes.controller.cdi

Class KubernetesControllerExtension

java.lang.Object

org.microbean.cdi.AbstractBlockingExtension

org.microbean.kubernetes.controller.cdi.KubernetesControllerExtension

All Implemented Interfaces:

Extension

public class KubernetesControllerExtension
extends AbstractBlockingExtension

An AbstractBlockingExtension that distributes Kubernetes events to interested listeners asynchronously.

Usage

To use this extension, simply place it on your classpath (along with your selection from a menu of certain required runtime dependencies described below). If you have a mechanism for describing the kinds of Kubernetes resources you'd like to watch for events, and if you have observer methods created to do something with those events, both of which are described below, then this extension will take care of connecting to the Kubernetes API server and listing and watching for new events for you.

Dependency Choices

This extension relies on the presence of certain CDI beans. In some cases, those beans are not produced by this extension. For maximum flexibility, this project does not mandate how certain beans are produced. Below is a list of the beans that are required, and suggested—but not required—ways of producing them.

Maven

If you are using Maven, you may indicate that you want this extension to be included on your project's runtime classpath with the following dependency stanza:

<dependency>
  <groupId>org.microbean</groupId>
  <artifactId>microbean-kubernetes-controller-cdi</artifactId>
  <version>0.2.1</version>
  <scope>runtime</scope>
</dependency>

KubernetesClient Bean

This extension indirectly requires that a KubernetesClient be available in the CDI container (qualified with @Default). You can use the microBean Kubernetes Client CDI project for this, or you can arrange to fulfil this requirement yourself.

If you are going to use the microBean Kubernetes Client CDI project to provide a Default-qualified KubernetesClient, you can indicate that you want it to be included on your project's runtime classpath with the following dependency stanza:

<dependency>
  <groupId>org.microbean</groupId>
  <artifactId>microbean-kubernetes-client-cdi</artifactId>
  <version>0.3.1</version>
  <scope>runtime</scope>
</dependency>

Configuration Beans

You'll need an implementation of the microBean Configuration API. Usually, the microBean Configuration project is what you want. You can indicate that you want it to be included on your project's runtime classpath with the following dependency stanza:

<dependency>
  <groupId>org.microbean</groupId>
  <artifactId>microbean-configuration</artifactId>
  <version>0.4.2</version>
  <scope>runtime</scope>
</dependency>

You'll need a means of getting that configuration implementation into CDI. Usually, you would use the microBean Configuration CDI project. You can indicate that you want it to be included on your project's runtime classpath with the following dependency stanza:

<dependency>
  <groupId>org.microbean</groupId>
  <artifactId>microbean-configuration-cdi</artifactId>
  <version>0.4.2</version>
  <scope>runtime</scope>
</dependency>

Event Selectors

To describe the kinds of Kubernetes resources you're interested in, you'll need one or more event selectors in your CDI application. An event selector, for the purposes of this class, is a CDI bean (either a managed bean or a producer method, most commonly) with certain types in its set of bean types. Specifically, the event selector type, X, must conform to this specification:

<X extends Listable<? extends KubernetesResourceList> & VersionWatchable<? extends Closeable, Watcher<? extends HasMetadata>>>

Many return types of methods belonging to KubernetesClient conveniently conform to this specification.

The event selector will also need to be annotated with an annotation that you write describing the sort of event selection it is. This annotation does not need any elements, but must itself be annotated with the @KubernetesEventSelector annotation. It must be applicable to parameters and your event selector beans, so if as is most common you are writing a producer method it must be applicable to methods as well.

Here is an example producer method that will cause this extension to look for all ConfigMap events:

@Produces
@ApplicationScoped
@AllConfigMapEvents // see declaration below
private static final Operation<ConfigMap, ConfigMapList, DoneableConfigMap, Resource<ConfigMap, DoneableConfigMap>> selectAllConfigMaps(final KubernetesClient client) {
  return client.configMaps();
}}

Note in particular that Operation implements both Listable and VersionWatchable with the proper type parameters.

The @AllConfigMapEvents annotation is simply:

@Documented
@KubernetesEventSelector
@Qualifier
@Retention(value = RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.PARAMETER })
public @interface AllConfigMapEvents {

}

Observer Methods

Observer methods are where your CDI application actually takes delivery of a Kubernetes resource as a CDI event.

You will need a notional pair consisting of an event selector and an observer method that conforms to certain requirements that help "link" it to its associated event selector. To realize this pair, you write a normal CDI observer method that adheres to the following additional requirements:

1. Its observed event type is a concrete class that extends HasMetadata and is the same type with which the associated event selector is primarily concerned. For example, if your event selector is primarily concerned with ConfigMaps, then your observer method's observed event type should also be ConfigMap.
2. Its observed event type is qualified with the same annotation that (a) qualifies the event selector and (b) is, in turn, qualified with @KubernetesEventSelector. For example, if @AllConfigMapEvents appears on your event selector producer method, then it should appear on your observer method's ConfigMap parameter that is annotated with @Observes.
3. Its observed event type is qualified with one of @Added, @Modified or @Deleted.
4. If you need access to the prior state of the Kubernetes resource your observer method is observing, you may add it as a standard (injected) parameter in the method's parameter list, but it must be (a) qualified with the @Prior annotation and (b) of a type identical to that of the observed event type. For example, if your observed event type is ConfigMap, then your prior state parameter must also be of type ConfigMap and must be annotated with @Prior.

Building upon the prior example, here is an example of an observer method that is "paired" with the event selector above:

private final void onConfigMapModification(@Observes @AllConfigMapEvents @Modified final ConfigMap configMap, @Prior final Optional<ConfigMap> prior) {
  assert configMap != null;
  // do something interesting with this modified ConfigMap
}

Author:

Laird Nelson

See Also:

AbstractBlockingExtension, Controller, KubernetesEventSelector, Added, Modified, Deleted, Prior

Field Summary

Fields inherited from class org.microbean.cdi.AbstractBlockingExtension

logger

Constructor Summary

Constructors

Modifier	Constructor and Description
	KubernetesControllerExtension() Creates a new KubernetesControllerExtension.
protected	KubernetesControllerExtension(CountDownLatch latch) Creates a new KubernetesControllerExtension.

Method Summary

Methods inherited from class org.microbean.cdi.AbstractBlockingExtension

createLogger, unblock, unblockAll

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KubernetesControllerExtension

public KubernetesControllerExtension()

Creates a new KubernetesControllerExtension.

See Also:

KubernetesControllerExtension(CountDownLatch)

KubernetesControllerExtension

protected KubernetesControllerExtension(CountDownLatch latch)

Creates a new KubernetesControllerExtension.

Most users should prefer the zero-argument constructor instead.

Parameters:

latch - a CountDownLatch passed to the AbstractBlockingExtension.AbstractBlockingExtension(CountDownLatch) constructor; must not be null

See Also:

KubernetesControllerExtension(), AbstractBlockingExtension.AbstractBlockingExtension(CountDownLatch)