From 5bf08deb90ebb85d95128b731ab01efdc11825a0 Mon Sep 17 00:00:00 2001 From: csviri Date: Fri, 14 Jan 2022 16:24:52 +0100 Subject: [PATCH] docs: /readme.md and docs update --- README.md | 312 ++------------------------ docs/documentation/faq.md | 7 + docs/documentation/features.md | 25 +++ docs/documentation/getting-started.md | 3 +- 4 files changed, 55 insertions(+), 292 deletions(-) diff --git a/README.md b/README.md index 4ea7d5ade3..f6f31e357f 100644 --- a/README.md +++ b/README.md @@ -3,312 +3,42 @@ ![Java CI with Maven](https://github.com/java-operator-sdk/java-operator-sdk/workflows/Java%20CI%20with%20Maven/badge.svg) [![Discord](https://img.shields.io/discord/723455000604573736.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.com/channels/723455000604573736) -Build Kubernetes Operators in Java without hassle. Inspired -by [operator-sdk](https://github.com/operator-framework/operator-sdk). +#Build Kubernetes Operators in Java Without Hassle -Our webpage with documentation is getting better every day: https://javaoperatorsdk.io/ +## Documentation -**!! NOTE the main branch now contains source code for v2, which is under development, for actual -version see [v1 branch](https://github.com/java-operator-sdk/java-operator-sdk/tree/v1) !!** +Documentation can be found on the **[JOSDK WebSite](https://javaoperatorsdk.io/)**. -Table of Contents -========== +It's getting better every day! :) -1. [Features](#Features) -1. [Why build your own Operator?](#Why-build-your-own-Operator) -1. [Roadmap and Release Notes](#Roadmap-and-Release-Notes) -1. [Join us on Discord!](#Join-us-on-Discord) -1. [Usage](#Usage) +## Contact us -## Features +Join us on [Discord](https://discord.gg/DacEhAy) or feel free to ask any question on +[Kubernetes Slack Operator Channel](https://kubernetes.slack.com/archives/CAW0GV7A5) + +## How to Contribute + +See the [contribution](https://javaoperatorsdk.io/docs/contributing) guide on the website. + +## What is Java Operator SDK + +Java Operator SDK is a higher level framework and related tooling to support writing Kubernetes Operators in Java. +It makes it use to utilize best practices and patters of an Operator development. Features include: * 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) * Handling Observed Generations automatically -* for all see [features](https://javaoperatorsdk.io/docs/features) section on the webpage - -Check out -this [blog post](https://csviri.medium.com/deep-dive-building-a-kubernetes-operator-sdk-for-java-developers-5008218822cb) -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](https://csviri.medium.com/java-operator-sdk-introduction-to-event-sources-a1aab5af4b7b) -. - -## Why build your own Operator? - -* Infrastructure automation using the power and flexibility of Java. - See [blog post](https://blog.container-solutions.com/cloud-native-java-infrastructure-automation-with-kubernetes-operators) - . -* 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 - -#### 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](https://discord.gg/DacEhAy) - -## Usage - -We have several simple Operators under the [smoke-test-samples](smoke-test-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 complete samples in the standalone [sample-operators](sample-operators): - -* *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](https://search.maven.org/search?q=a:operator-framework) to your project with Maven: - -```xml - - - 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: - -```groovy -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. - -```java -public class Runner { - - public static void main(String[] args) { - Operator operator = new Operator(DefaultConfigurationService.instance()); - operator.register(new WebPageReconciler()); - operator.start(); - } -} -``` - -The Controller implements the business logic and describes all the classes needed to handle the CRD. - -```java - -@ControllerConfiguration -public class WebPageReconciler implements Reconciler { - - // Return the changed resource, so it gets updated. See javadoc for details. - @Override - public UpdateControl reconcile(WebPage resource, - Context context) { - // ... your logic ... - return UpdateControl.updateStatus(resource); - } -} -``` - -A sample custom resource POJO representation - -```java - -@Group("sample.javaoperatorsdk") -@Version("v1") -public class WebPage extends CustomResource implements - Namespaced { - -} - -public class WebPageSpec { - - 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: - -```xml - - - 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](https://quarkus.io) extension is also provided to ease the development of Quarkus-based operators. - -Add [this dependency](https://search.maven.org/search?q=a:quarkus-operator-sdk) -to your project: - -```xml - - - 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: - -```java - -@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](https://search.maven.org/search?q=a:operator-framework-spring-boot-starter) to your project: - -```xml - - - 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); - } -} -``` - -#### Spring Boot test support +* Support For Intelligent Error Handling -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. +For all features and their usage see the [related section on the website](https://javaoperatorsdk.io/docs/features). -```xml +## Related Projects - - io.javaoperatorsdk - operator-framework-spring-boot-starter-test - {see https://search.maven.org/search?q=a:operator-framework-spring-boot-starter for - latest version} - - -``` +Operator SDK plugin: https://github.com/operator-framework/java-operator-plugins -Mock the operator: +Quarkus Extension: https://github.com/quarkiverse/quarkus-operator-sdk -```java -@SpringBootTest -@EnableMockOperator -public class SpringBootStarterSampleApplicationTest { - @Test - void contextLoads() { - } -} -``` diff --git a/docs/documentation/faq.md b/docs/documentation/faq.md index f4127b39fe..fd7f2ff46b 100644 --- a/docs/documentation/faq.md +++ b/docs/documentation/faq.md @@ -5,3 +5,10 @@ layout: docs permalink: /docs/faq --- +## Q: How can I access events? +In the v1.* version events were exposed to `Reconciler` (in v1 called `ResourceController`). This +included events (Create, Update) of the custom resource, but also events produced by Event Sources. After +long discussions also with developers of golang version (controller-runtime), we decided to remove access to +these events. We already advocated to not use events in the reconciliation logic, since events can be lost. +Instead reconcile all the resources on every execution of reconciliation. On first this might sound a little +opinionated, but there was a sound agreement between the developers that this is the way to go. \ No newline at end of file diff --git a/docs/documentation/features.md b/docs/documentation/features.md index dd8be46ecf..a143316370 100644 --- a/docs/documentation/features.md +++ b/docs/documentation/features.md @@ -281,6 +281,31 @@ following attributes are available in most parts of reconciliation logic and dur For more information about MDC see this [link](https://www.baeldung.com/mdc-in-log4j-2-logback). +## Automatic generation of CRDs + +Note that this is feature of [Fabric8 Kubernetes Client](https://github.com/fabric8io/kubernetes-client) not the JOSDK. But it's worth to mention here. + +To automatically generate CRD manifests from your annotated Custom Resource classes, you only need to add the following +dependencies to your project: + +```xml + + + 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. diff --git a/docs/documentation/getting-started.md b/docs/documentation/getting-started.md index 649d454a45..72a06df93c 100644 --- a/docs/documentation/getting-started.md +++ b/docs/documentation/getting-started.md @@ -20,7 +20,8 @@ You can read about the common problems what is this operator framework is solvin ## Getting Started The easiest way to get started with SDK is start [minikube](https://kubernetes.io/docs/tasks/tools/install-minikube/) and -execute one of our [examples](https://github.com/java-operator-sdk/samples/tree/main/mysql-schema) +execute one of our [examples](https://github.com/java-operator-sdk/samples/tree/main/mysql-schema). +There is a dedicated page to describe how to [use samples](/docs/using-samples). Here are the main steps to develop the code and deploy the operator to a Kubernetes cluster. A more detailed and specific version can be found under `samples/mysql-schema/README.md`.