8000 docs: samples facelift (#784) · Sgitario/java-operator-sdk@12f6125 · GitHub
[go: up one dir, main page]
Skip to content

Commit 12f6125

Browse files
csviricsviri
authored
docs: samples facelift (operator-framework#784)
1 parent a499e5c commit 12f6125

File tree

3 files changed

+26
-67
lines changed

3 files changed

+26
-67
lines changed

‎docs/documentation/getting-started.md

Lines changed: 0 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -38,60 +38,5 @@ to the cluster. This is why it was important to set up kubectl up front.
3838
1. Verify if the operator is up and running. Don't run it locally anymore to avoid conflicts in processing events from
3939
the cluster's API server.
4040

41-
## Controllers
42-
Controllers are where you implement the business logic of the Operator. An Operator can host multiple Controllers,
43-
each handling a different type of Custom Resource. In our samples each Operator has a single Controller.
4441

45-
[comment]: <> (## Automatic Retries)
4642

47-
[comment]: <> (## Running The Operator)
48-
49-
[comment]: <> (## Development Tips & Tricks)
50-
51-
[comment]: <> (TODO: explain running operator locally against a cluster)
52-
53-
[comment]: <> (## Event Processing Details)
54-
55-
[comment]: <> (### Handling Finalizers)
56-
57-
[comment]: <> (### Managing Consistency)
58-
59-
[comment]: <> (### Event Scheduling)
60-
61-
[comment]: <> (### Event Dispatching )
62-
63-
[comment]: <> (### Generation Awareness)
64-
65-
## Dealing with Consistency
66-
67-
### Run Single Instance
68-
69-
There should be always just one instance of an operator running at a time (think process). If there would be
70-
two ore more, in general it could lead to concurrency issues. Note that we are also doing optimistic locking when we update a resource.
71-
In this way the operator is not highly available. However for operators this is not necessarily an issue,
72-
if the operator just gets restarted after it went down.
73-
74-
### At Least Once
75-
76-
To implement controller logic, we have to override two methods: `createOrUpdateResource` and `deleteResource`.
77-
These methods are called if a resource is created/changed or marked for deletion. In most cases these methods will be
78-
called just once, but in some rare cases, it can happen that they are called more then once. In practice this means that the
79-
implementation needs to be **idempotent**.
80-
81-
### Smart Scheduling
82-
83-
In our scheduling algorithm we make sure, that no events are processed concurrently for a resource. In addition we provide
84-
a customizable retry mechanism to deal with temporal errors.
85-
86-
### Operator Restarts
87-
88-
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
89-
(We use `kubectl get ... --watch` in the background). This can be a huge amount of resources depending on your use case.
90-
So it could be a good case to just have a status field on the resource which is checked, if there is anything needed to be done.
91-
92-
### Deleting a Resource
93-
94-
During deletion process we use [Kubernetes finalizers](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#finalizers
95-
"Kubernetes docs"). This is required, since it can happen that the operator is not running while the delete
96-
of resource is executed (think `oc delete`). In this case we would not catch the delete event. So we automatically add a
97-
finalizer first time we update the resource if it's not there.

‎docs/documentation/patterns-best-practices.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ permalink: /docs/patterns-best-practices
1010
This document describes patters and best practices, to build and run operators, and how to implement them in terms
1111
of Java Operator SDK.
1212

13-
## Implementing a Controller
13+
## Implementing a Reconciler
1414

1515
### Idempotency
1616

‎docs/documentation/use-samples.md

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,26 @@ layout: docs
55
permalink: /docs/using-samples
66
---
77

8-
# How to use sample Operators
8+
# Sample Operators we Provide
99

10-
We have several sample Operators under
11-
the [samples](https://github.com/java-operator-sdk/java-operator-sdk/tree/master/smoke-test-samples) directory:
10+
We have few simple Operators under
11+
the [smoke-test-samples](https://github.com/java-operator-sdk/java-operator-sdk/tree/master/smoke-test-samples) directory.
12+
These are used mainly to showcase some minimal operators, but also to do some sanity checks during development:
1213

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

17-
There are also more samples in the standalone [samples repo](https://github.com/java-operator-sdk/samples):
18+
In addition to that, there are examples under [sample-operators](https://github.com/java-operator-sdk/java-operator-sdk/tree/master/sample-operators)
19+
directory which are intended to show usage of different components in different scenarios, but mainly are more real world
20+
examples:
1821

19-
* *webserver*: Simple example creating an NGINX webserver from a Custom Resource containing HTML code.
20-
* *mysql-schema*: Operator managing schemas in a MySQL database.
21-
* *tomcat*: Operator with two controllers, managing Tomcat instances and Webapps for these.
22+
* *webpage*: Simple example creating an NGINX webserver from a Custom Resource containing HTML code.
23+
* *mysql-schema*: Operator managing schemas in a MySQL database. Shows how to manage non Kubernetes resources.
24+
* *tomcat*: Operator with two controllers, managing Tomcat instances and Webapps running in Tomcat. The intention
25+
with this example to show how to manage multiple related custom resources and/or more controllers.
26+
27+
# Implementing a Sample Operator
2228

2329
Add [dependency](https://search.maven.org/search?q=a:operator-framework) to your project with Maven:
2430

@@ -59,7 +65,7 @@ The Controller implements the business logic and describes all the classes neede
5965
```java
6066

6167
@ControllerConfiguration
62-
public class WebServerController implements Reconciler<WebServer> {
68+
public class WebPageReconciler implements Reconciler<WebPage> {
6369

6470
// Return the changed resource, so it gets updated. See javadoc for details.
6571
@Override
@@ -77,9 +83,8 @@ A sample custom resource POJO representation
7783

7884
@Group("sample.javaoperatorsdk")
7985
@Version("v1")
80-
public class WebServer extends CustomResource<WebServerSpec, WebServerStatus> implements
86+
public class WebPage extends CustomResource<WebPageSpec, WebPageStatus> implements
8187
Namespaced {
82-
8388
}
8489

8590
public class WebServerSpec {
@@ -107,7 +112,7 @@ might want to skip this step. This is done by setting the `CHECK_CRD_ENV_KEY` en
107112
### Automatic generation of CRDs
108113

109114
To automatically generate CRD manifests from your annotated Custom Resource classes, you only need to add the following
110-
dependencies to your project:
115+
dependencies to your project (in the background an annotation processor is used), with Maven:
111116

112117
```xml
113118

@@ -118,6 +123,15 @@ dependencies to your project:
118123
</dependency>
119124
```
120125

126+
or with Gradle:
127+
128+
```groovy
129+
dependencies {
130+
annotationProcessor 'io.fabric8:crd-generator-apt:<version>'
131+
...
132+
}
133+
```
134+
121135
The CRD will be generated in `target/classes/META-INF/fabric8` (or in `target/test-classes/META-INF/fabric8`, if you use
122136
the `test` scope) with the CRD name suffixed by the generated spec version. For example, a CR using
123137
the `java-operator-sdk.io` group with a `mycrs` plural form will result in 2 files:

0 commit comments

Comments
 (0)
0