Quarkus extension for the Java Operator SDK (QOSDK)

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

Features

  • Developer experience:

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

    • Automatically registers reconcilers with the operator and start them

    • Automatically configures native compilation support

  • Configuration support:

    • Configuration is processed at build time, attempting to address as many issues as possible during compilation

    • Ability to override some configuration options at runtime via application properties or other supported Quarkus mechanism

    • Implement ConfigurableReconciler and/or ConfigurationServiceCustomizer to further tweak reconcilers or operator-level configuration at runtime. Implementations are automatically picked up.

    • Custom configuration annotations support for select features (dependent resources, rate limiter, …)

  • CDI support:

    • Automatically injectable Kubernetes/OpenShift client

    • Operator bean is created, available for CDI injection

    • All Reconciler implementations are available as CDI beans

    • All DependentResource implementations are available as CDI beans

    • Workflow conditions can be implemented as CDI beans

  • Custom Resource Definition (CRD) support:

    • Automatically generates CRDs for all CustomResource implementations used by reconcilers

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

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

  • Kubernetes descriptors augmentation:

    • Automatically generated kubernetes descriptors (using the Quarkus kubernetes extension)

    • Generate RBACs leveraging configuration metadata (for example, automatically provide access to dependent resources with the appropriate restrictions, when using declarative dependent resources workflows)

  • OLM bundle generation for reconcilers using the quarkus-operator-sdk-bundle-generator extension

  • Helm chart generation for reconcilers using the quarkus-operator-sdk-helm extension, leveraging the Quarkus Helm extension

  • Quarkus Dev mode support:

    • Live-coding experience for operators

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

    • Optimizes re-computation of configuration to changed classes

  • Operational support:

    • 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 (OperatorHealthCheck)

  • 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.7.3

    • 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.7.3</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.7.3</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>

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

    </dependencies>
  </dependencyManagement>

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

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.7.3</version>
</dependency>

Helm chart generator extension

You can easily generate Helm charts for your operator by adding the quarkus-helm extension to your project:

<dependency>
    <groupId>io.quarkiverse.helm</groupId>
    <artifactId>quarkus-helm</artifactId>
    <version>${io.quarkiverse.helm.version}</version>
</dependency>

QOSDK will automatically augment what the Quarkus Helm extension generates to add specific information required to deploy your operators correctly.