improve readme and docs & add logo!

Author: adam-sandor

README.md

@@ -1,40 +1,47 @@
-# java-operator-sdk
-![Java CI with Maven](https://github.com/ContainerSolutions/java-operator-sdk/workflows/Java%20CI%20with%20Maven/badge.svg)
+# ![java-operator-sdk](logo.png) 
+![Java CI with Maven](https://github.com/ContainerSolutions/java-operator-sdk/workflows/Java%20CI%20with%20Maven/badge.svg | width = 300)
 
-SDK for building Kubernetes Operators in Java. Inspired by [operator-sdk](https://github.com/operator-framework/operator-sdk).
-User (you) only writes the logic in a Controller that creates/updates or deletes resources related to a custom resource.
-All the issues around are handled by the framework for you.
-Check out this [blog post](https://blog.container-solutions.com/a-deep-dive-into-the-java-operator-sdk) 
-about the non-trivial yet common problems needs to be solved for every operator. 
-
-## Join us on Discord!
+Build Kubernetes Operators in Java without hassle. Inspired by [operator-sdk](https://github.com/operator-framework/operator-sdk).
 
-[Discord Invite Link](https://discord.gg/DacEhAy)
+#### Features
+* Framework for handling Kubernetes API events
+* Registering Custom Resource watches
+* Retry action on failure
+* Smart event scheduling (only handle latest event for the same resource)
 
-## Roadmap
+Check out this [blog post](https://blog.container-solutions.com/a-deep-dive-into-the-java-operator-sdk) 
+about the non-trivial yet common problems needs to be solved for every operator. 
 
-Feature we would like to implement and invite the community to help us implement in the future:
+#### 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
 
-* ~~Spring Boot support~~
-* Class generation from CRD to POJO
-* GraalVM / Quarkus support
+#### Roadmap
+* Testing of the framework and all samples while running on a real cluster.
+* Generate a project skeleton
+* Generate Java classes from CRD definion (and/or the other way around)
+* Integrate with Quarkus (including native image build)
+* Integrate with OLM (Operator Lifecycle Manager)
 
-## Additional Features
+#### Join us on Discord!
 
-* Configurable Retry Handling
-* Smart Event Processing Scheduling
+[Discord Invite Link](https://discord.gg/DacEhAy)
 
-## User Guide
+#### User Guide
 
 You can (will) find detailed documentation [here](docs/DOCS.md). 
 Note that these docs are currently in progress. 
 
-## Usage
+#### Usage
 
 We have several sample Operators under the samples directory:
 * *basic*: 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.
 * *webserver*: More realistic example creating an nginx webserver from a Custom Resource containing html code.
+* *mysql-schema*: Operator managing schemas in a MySQL database
+* *spring-boot-plain/auto-config*: Samples showing integration with Spring Boot.
 
 Add [dependency](https://search.maven.org/search?q=a:operator-framework) to your project:
 
@@ -120,7 +127,7 @@ public class WebServerSpec {
 }
 ```
 
-### Spring Boot
+#### Spring Boot
 
 You can also let Spring Boot wire your application together and automatically register the controllers.
 
@@ -143,55 +150,3 @@ public class Application {
     }
 }
 ```
-
-add Spring's `@Service` annotation to your controller classes so they will be automatically registered as resource controllers.
-
-The Operator's Spring Boot integration leverages [Spring's configuration mechanisms](https://docs.spring.io/spring-boot/docs/1.0.1.RELEASE/reference/html/boot-features-external-config.html) to configure
-- [The Kubernetes client](spring-boot-starter/src/main/java/com/github/containersolutions/operator/spingboot/starter/OperatorProperties.java)
-- [Retries](spring-boot-starter/src/main/java/com/github/containersolutions/operator/spingboot/starter/RetryProperties.java)
-
-## Implementation / Design details
-
-This library relies on the amazing [kubernetes-client](https://github.com/fabric8io/kubernetes-client) from fabric8. 
-Most of the heavy lifting is actually done by kubernetes-client.
-
-What the framework adds on top of the bare client:
-* Management of events from the Kubernetes API. All events are inserted into a queue by the EventScheduler. The 
-framework makes sure only the latest event for a certain resource is processed. This is especially important since
-on startup the operator can receive a whole series of obsolete events.
-* Retrying of failed actions. When an event handler throws an exception the event is put back in the queue.
-* A clean interface to the user of the framework to receive events related to the Controller's resource.
-
-### Dealing with Consistency 
-
-#### Run Single Instance
-
-There should be always just one instance of an operator running at a time (think process). If there there would be 
-two ore more, in general it could lead to concurrency issues. Note that we are also doing optimistic locking when we update a resource.
-In this way the operator is not highly available. However for operators this not necessary an issue, 
-if the operator just gets restarted after it went down. 
-
-#### At Least Once
-
-To implement controller logic, we have to override two methods: `createOrUpdateResource` and `deleteResource`. 
-These methods are called if a resource is create/changed or marked for deletion. In most cases these methods will be
-called just once, but in some rare cases can happen that are called more then once. In practice this means that the 
-implementation needs to be **idempotent**.    
-
-#### Smart Scheduling
-
-In our scheduling algorithm we make sure, that no events are processed concurrently for a resource. In addition we provide
-a customizable retry mechanism to deal with temporal errors.
-
-#### Operator Restarts
-
-When an operator is started we got events for every resource (of a type we listen to) already on the cluster. Even if the resource is not changed 
-(We use `kubectl get ... --watch` in the background). This can be a huge amount of resources depending on your use case.
-So it could be a good case just have a status field on the resource which is checked, if there anything needs to be done.
-
-#### Deleting a Resource
-
-During deletion process we use [Kubernetes finalizers](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#finalizers 
-"Kubernetes docs") finalizers. This is required, since it can happen that the operator is not running while the delete 
-of resource is executed (think `oc delete`). In this case we would not catch the delete event. So we automatically add a
-finalizer first time we update the resource if its not there. 

docs/DOCS.md

@@ -35,8 +35,6 @@ the cluster's API server.
 Controllers are where you implement the business logic of the Operator. An Operator can host multiple Controllers, 
 each handling a different type of Custom Resource. In our samples each Operator has a single Controller. 
 
-### Generation Awareness
-
 ## Automatic Retries
 
 ## Running The Operator
@@ -53,3 +51,37 @@ TODO: explain running operator locally against a cluster
 ### Generation Awareness
 
 ## Spring Boot Support
+
+## Dealing with Consistency 
+
+### Run Single Instance
+
+There should be always just one instance of an operator running at a time (think process). If there there would be 
+two ore more, in general it could lead to concurrency issues. Note that we are also doing optimistic locking when we update a resource.
+In this way the operator is not highly available. However for operators this not necessary an issue, 
+if the operator just gets restarted after it went down. 
+
+### At Least Once
+
+To implement controller logic, we have to override two methods: `createOrUpdateResource` and `deleteResource`. 
+These methods are called if a resource is create/changed or marked for deletion. In most cases these methods will be
+called just once, but in some rare cases can happen that are called more then once. In practice this means that the 
+implementation needs to be **idempotent**.    
+
+### Smart Scheduling
+
+In our scheduling algorithm we make sure, that no events are processed concurrently for a resource. In addition we provide
+a customizable retry mechanism to deal with temporal errors.
+
+### Operator Restarts
+
+When an operator is started we got events for every resource (of a type we listen to) already on the cluster. Even if the resource is not changed 
+(We use `kubectl get ... --watch` in the background). This can be a huge amount of resources depending on your use case.
+So it could be a good case just have a status field on the resource which is checked, if there anything needs to be done.
+
+### Deleting a Resource
+
+During deletion process we use [Kubernetes finalizers](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#finalizers 
+"Kubernetes docs") finalizers. This is required, since it can happen that the operator is not running while the delete 
+of resource is executed (think `oc delete`). In this case we would not catch the delete event. So we automatically add a
+finalizer first time we update the resource if its not there.