Quarkus extension for the Java Operator SDK (QOSDK)

Please refer to the QOSDK Readme for information on how getting started with QOSDK.

Features

  • Automatically generates a main class, so that the only thing that’s required is to write Reconciler implementation(s)

  • Automatically makes a Kubernetes/OpenShift client available for CDI injection

  • Automatically sets up an Operator instance, also available for CDI injection

  • Automatically processes the reconcilers' configuration at build time, exposing all the available configuration of JOSDK via application properties

  • Automatically registers reconcilers with the Operator and start them

  • Automatically generates CRDs for all CustomResource implementations used by reconcilers

  • Automatically generates Kubernetes descriptors

  • Automatically generates the bundle manifests for all reconcilers (using the quarkus-operator-sdk-bundle-generator extension)

  • Integrates with the Dev mode:

    • Watches your code for changes and reload automatically your operator if needed without having to hit an endpoint

    • Only re-generates the CRDs if a change impacting its generation is detected

    • Only re-processes a reconciler’s configuration if needed

    • Automatically apply the CRD to the cluster when it has changed (only in dev mode and during tests, never in production)

  • Supports micrometer registry extensions (adding a Quarkus-supported micrometer registry extension will automatically inject said registry into the operator)

  • Automatically adds a SmallRye health check

  • Sets up reflection for native binary generation

  • [Deprecated] Customize the JSON serialization that the Fabric8 client relies on by providing an ObjectMapperCustomizer implementation, qualified with the @KubernetesClientSerializationCustomizer annotation

    • The Quarkus kubernetes client extension now provides an official mechanism to do so by implementing the io.quarkus.kubernetes.client.KubernetesClientObjectMapperCustomizer interface instead so this mechanism should be used moving forward.

  • Dev mode commands:

    • Dev commands are automatically accessible from the Dev console after typing : in the Quarkus terminal in Dev mode, under the qosdk name. Two commands currently exist: qosdk api to create a Kubernetes API (hint: type qosdk api -h for more details) and qosdk versions to show which versions are targeted by QOSDK.

  • CLI command:

    • Add the Quarkus CLI command using: quarkus plug add io.quarkiverse.operatorsdk:quarkus-operator-sdk-cli:runner:jar:7.3.0

    • You can create a Kubernetes API using the quarkus operator-sdk api command, e.g. quarkus operator-sdk api -g halkyon.io -v v1 -k foo

Installation

Using the Quarkus platform

The best way to use this extension is to generate a skeleton project from code.quarkus.io, search for qosdk (or similar) and select the Operator SDK extension. Doing so will automatically import the Java Operator SDK dependencies in a managed way, using the BOM from the Quarkus platform.

Some of these topics along with upgrading strategies are discussed in https://developers.redhat.com/articles/2023/09/19/write-operators-java-josdk-part-4-upgrading-strategies.

Managing the QOSDK extension yourself

Alternatively, you can add the following to your pom.xml file, if you want to be managing the QOSDK extension yourself.

<dependency>
    <groupId>io.quarkiverse.operatorsdk</groupId>
    <artifactId>quarkus-operator-sdk</artifactId>
    <version>7.3.0</version>
</dependency>

However, it might be more convenient to use the quarkus-operator-sdk-bom dependency to ensure that all dependency versions are properly aligned:

<dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.quarkiverse.operatorsdk</groupId>
        <artifactId>quarkus-operator-sdk-bom</artifactId>
        <version>7.3.0</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>

      <!-- other dependencies as needed by your project -->

    </dependencies>
  </dependencyManagement>

If you do use the BOM, please do make sure to use the same Quarkus version as the one defined in the BOM when configuring the Quarkus plugin as the Quarkus Dev Mode will not work properly otherwise, failing with an error:

Exception in thread "main" java.lang.RuntimeException: java.lang.RuntimeException: java.lang.IllegalStateException: Hot deployment of the application is not supported when updating the Quarkus version. The application needs to be stopped and dev mode started up again
        at io.quarkus.deployment.dev.DevModeMain.start(DevModeMain.java:138)
        at io.quarkus.deployment.dev.DevModeMain.main(DevModeMain.java:62)

OLM bundle generator extension

You can add the OLM bundle generator using the Quarkus platform via code.quarkus.io, searching for olm (for example).

You can also add the quarkus-operator-sdk-bundle-generator extension manually to your dependencies in a project that’s already set up to use QOSDK.

<dependency>
    <groupId>io.quarkiverse.operatorsdk</groupId>
    <artifactId>quarkus-operator-sdk-bundle-generator</artifactId>
    <version>7.3.0</version>
</dependency>