Need help with java-operator-sdk?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

java-operator-sdk
271 Stars 84 Forks Apache License 2.0 1.5K Commits 56 Opened issues

Description

Java SDK for building Kubernetes Operators

Services available

!
?

Need anything else?

Contributors list

java-operator-sdk

Java CI with Maven Discord

Build Kubernetes Operators in Java without hassle. Inspired by operator-sdk.

Table of Contents

  1. Features
  2. Why build your own Operator?
  3. Roadmap and Release Notes
  4. Join us on Discord!
  5. Usage

Features

  • Framework for handling Kubernetes API events
  • Automatic registration of Custom Resource watches
  • Retry action on failure
  • Smart event scheduling (only handle the latest event for the same resource)

Check out this blog post about the non-trivial yet common problems needed to be solved for every operator. In case you are interested how to handle more complex scenarios take a look on event sources .

Why build your own Operator?

  • Infrastructure automation using the power and flexibility of Java. See blog post .
  • Provisioning of complex applications - avoiding Helm chart hell
  • Integration with Cloud services - e.g. Secret stores
  • Safer deployment of applications - only expose cluster to users by Custom Resources

Roadmap and Release Notes

  • Testing of the framework and all samples while running on a real cluster.
  • Generate a project skeleton
  • Generate Java classes from CRD
  • Integrate with OLM (Operator Lifecycle Manager)

Overview of the 1.9.0 changes

  • The Spring Boot starters have been moved to their own repositories and are now found at:
    • https://github.com/java-operator-sdk/operator-framework-spring-boot-starter
    • https://github.com/java-operator-sdk/operator-framework-spring-boot-starter-test
  • Updated Fabric8 client to version 5.4.0
  • It is now possible to configure the controllers to not automatically add finalizers to resources. See the
    Controller
    annotation documentation for more details.
  • Added the possibility to configure how many seconds the SDK will wait before terminating reconciliation threads when a shut down is requested

Overview of the 1.8.0 changes

  • The quarkus extension has been moved to the quarkiverse and is now found at https://github.com/quarkiverse/quarkus-operator-sdk
Overview of the 1.7.0 changes
  • Doneable
    classes have been removed along with all the involved complexity
  • Controller
    annotation has been simplified: the
    crdName
    field has been removed as that value is computed from the associated custom resource implementation
  • Custom Resource implementation classes now need to be annotated with
    Group
    and
    Version
    annotations so that they can be identified properly. Optionally, they can also be annotated with
    Kind
    (if the name of the implementation class doesn't match the desired kind) and
    Plural
    if the plural version cannot be automatically computed (or the default computed version doesn't match your expectations).
  • The
    CustomResource
    class that needs to be extended is now parameterized with spec and status types, so you can have an empty default implementation that does what you'd expect. If you don't need a status, using
    Void
    for the associated type should work.
  • Custom Resources that are namespace-scoped need to implement the
    Namespaced
    interface so that the client can generate the proper URLs. This means, in particular, that
    CustomResource
    implementations that do not implement
    Namespaced
    are considered cluster-scoped. As a consequence, the
    isClusterScoped
    method/field has been removed from the appropriate classes (
    Controller
    annotation, in particular) as this is now inferred from the
    CustomResource
    type associated with your
    Controller
    .

Many of these changes might not be immediately apparent but will result in

404
errors when connecting to the cluster. Please check that the Custom Resource implementations are properly annotated and that the value corresponds to your CRD manifest. If the namespace appear to be missing in your request URL, don't forget that namespace-scoped Custom Resources need to implement the
Namescaped
interface.

Join us on Discord!

Discord Invite Link

Usage

We have several sample Operators under the samples directory:

  • pure-java: Minimal Operator implementation which only parses the Custom Resource and prints to stdout. Implemented with and without Spring Boot support. The two samples share the common module.
  • spring-boot-plain: Sample showing integration with Spring Boot.

There are also more samples in the standalone samples repo:

  • webserver: Simple example creating an NGINX webserver from a Custom Resource containing HTML code.
  • mysql-schema: Operator managing schemas in a MySQL database.
  • tomcat: Operator with two controllers, managing Tomcat instances and Webapps for these.

Add dependency to your project with Maven:

  io.javaoperatorsdk
  operator-framework
  {see https://search.maven.org/search?q=a:operator-framework for latest version}

Or alternatively with Gradle, which also requires declaring the SDK as an annotation processor to generate the mappings between controllers and custom resource classes:

dependencies {
    implementation "io.javaoperatorsdk:operator-framework:${javaOperatorVersion}"
    annotationProcessor "io.javaoperatorsdk:operator-framework:${javaOperatorVersion}"
}

Once you've added the dependency, define a main method initializing the Operator and registering a controller.

public class Runner {

public static void main(String[] args) { Operator operator = new Operator(DefaultConfigurationService.instance()); operator.register(new WebServerController()); } }

The Controller implements the business logic and describes all the classes needed to handle the CRD.

@Controller
public class WebServerController implements ResourceController {

// Return the changed resource, so it gets updated. See javadoc for details. @Override public UpdateControl createOrUpdateResource(CustomService resource, Context context) { // ... your logic ... return UpdateControl.updateStatusSubResource(resource); } }

A sample custom resource POJO representation

@Group("sample.javaoperatorsdk")
@Version("v1")
public class WebServer extends CustomResource implements
    Namespaced {

}

public class WebServerSpec {

private String html;

public String getHtml() { return html; }

public void setHtml(String html) { this.html = html; } }

Deactivating CustomResource implementations validation

The operator will, by default, query the deployed CRDs to check that the

CustomResource
implementations match what is known to the cluster. This requires an additional query to the cluster and, sometimes, elevated privileges for the operator to be able to read the CRDs from the cluster. This validation is mostly meant to help users new to operator development get started and avoid common mistakes. Advanced users or production deployments might want to skip this step. This is done by setting the
CHECK_CRD_ENV_KEY
environment variable to
false
.

Automatic generation of CRDs

To automatically generate CRD manifests from your annotated Custom Resource classes, you only need to add the following dependencies to your project:

  io.fabric8
  crd-generator-apt
  provided

The CRD will be generated in

target/classes/META-INF/fabric8
(or in
target/test-classes/META-INF/fabric8
, if you use the
test
scope) with the CRD name suffixed by the generated spec version. For example, a CR using the
java-operator-sdk.io
group with a
mycrs
plural form will result in 2 files:
  • mycrs.java-operator-sdk.io-v1.yml
  • mycrs.java-operator-sdk.io-v1beta1.yml

NOTE:

Quarkus users using the

quarkus-operator-sdk
extension do not need to add any extra dependency to get their CRD generated as this is handled by the extension itself.

Quarkus

A Quarkus extension is also provided to ease the development of Quarkus-based operators.

Add this dependency to your project:

  io.quarkiverse.operatorsdk
  quarkus-operator-sdk
  {see https://search.maven.org/search?q=a:quarkus-operator-sdk for latest version}
  

Create an Application, Quarkus will automatically create and inject a

KubernetesClient
( or
OpenShiftClient
),
Operator
,
ConfigurationService
and
ResourceController
instances that your application can use. Below, you can see the minimal code you need to write to get your operator and controllers up and running:
@QuarkusMain
public class QuarkusOperator implements QuarkusApplication {

@Inject Operator operator;

public static void main(String... args) { Quarkus.run(QuarkusOperator.class, args); }

@Override public int run(String... args) throws Exception { operator.start(); Quarkus.waitForExit(); return 0; } }

Spring Boot

You can also let Spring Boot wire your application together and automatically register the controllers.

Add this dependency to your project:

  io.javaoperatorsdk
  operator-framework-spring-boot-starter
  {see https://search.maven.org/search?q=a:operator-framework-spring-boot-starter for
    latest version}
  

Create an Application

@SpringBootApplication
public class Application {

public static void main(String[] args) { SpringApplication.run(Application.class, args); } }

Spring Boot test support

Adding the following dependency would let you mock the operator for the tests where loading the spring container is necessary, but it doesn't need real access to a Kubernetes cluster.

  io.javaoperatorsdk
  operator-framework-spring-boot-starter-test
  {see https://search.maven.org/search?q=a:operator-framework-spring-boot-starter for
    latest version}
  

Mock the operator:

@SpringBootTest
@EnableMockOperator
public class SpringBootStarterSampleApplicationTest {

@Test void contextLoads() { } }

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.