Java SDK for building Kubernetes Operators
Build Kubernetes Operators in Java without hassle. Inspired by operator-sdk.
| S.No. | Contents | | ----- | -------- | | 1. | Features | | 2. | Why build your own Operator? | | 3. | Roadmap | | 4. | Join us on Discord! | | 5. | User Guide | | 6. | Usage | | 7. | Spring Boot |
Check out this blog post about the non-trivial yet common problems needed to be solved for every operator.
You can (will) find detailed documentation here. Note that these docs are currently in progress.
:warning: 1.7.0 Upgrade The 1.7.0 upgrade comes with big changes due to the update to the 5.0.0 version of the fabric8 Kubernetes client. While this should improve the user experience quite nicely, there are a couple of things to be aware of when upgrading from a previous version as detailed below.
Doneableclasses have been removed along with all the involved complexity
Controllerannotation has been simplified: the
crdNamefield has been removed as that value is computed from the associated custom resource implementation
Groupand
Versionannotations 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
Pluralif the plural version cannot be automatically computed (or the default computed version doesn't match your expectations).
CustomResourceclass 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
Voidfor the associated type should work.
Namespacedinterface so that the client can generate the proper URLs. This means, in particular, that
CustomResourceimplementations that do not implement
Namespacedare considered cluster-scoped. As a consequence, the
isClusterScopedmethod/field has been removed from the appropriate classes (
Controllerannotation, in particular) as this is now inferred from the
CustomResourcetype associated with your
Controller.
Many of these changes might not be immediately apparent but will result in
404errors 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
Namescapedinterface.
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/auto-config: Samples showing integration with Spring Boot. * quarkus: Minimal application showing automatic configuration / injection of Operator / Controllers.
And there are 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(new DefaultKubernetesClient(), 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 {@Override public DeleteControl deleteResource(CustomService resource, Context<webserver> context) { // ... your logic ... return DeleteControl.DEFAULT_DELETE; } // Return the changed resource, so it gets updated. See javadoc for details. @Override public UpdateControl<customservice> createOrUpdateResource(CustomService resource, Context<webserver> 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; }
}
A Quarkus extension is also provided to ease the development of Quarkus-based operators.
Add this dependency to your project:
io.javaoperatorsdk operator-framework-quarkus-extension {see https://search.maven.org/search?q=a:operator-framework-quarkus-extension for latest version}
Create an Application, Quarkus will automatically create and inject a
KubernetesClient,
Operatorand
ConfigurationServiceinstances that your application can use, as shown below:
@QuarkusMain public class QuarkusOperator implements QuarkusApplication {@Inject KubernetesClient client;
@Inject Operator operator;
@Inject ConfigurationService configuration;
public static void main(String... args) { Quarkus.run(QuarkusOperator.class, args); }
@Override public int run(String... args) throws Exception { final var config = configuration.getConfigurationFor(new CustomServiceController(client)); System.out.println("CR class: " + config.getCustomResourceClass());
Quarkus.waitForExit(); return 0;
} }
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
java @SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
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: ```java @SpringBootTest @EnableMockOperator public class SpringBootStarterSampleApplicationTest {
@Test void contextLoads() {} } ```