You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
SDK for building Kubernetes Operators in Java. Inspired by [operator-sdk](https://github.com/operator-framework/operator-sdk).
6
5
In this first iteration we aim to provide a framework which handles the reconciliation loop by dispatching events to
7
6
a Controller written by the user of the framework.
8
7
9
8
The Controller only contains the logic to create, update and delete the actual resources related to the CRD.
10
9
11
-
## Implementation
12
-
13
-
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
14
-
kubernetes-client.
15
-
16
10
## Roadmap
17
11
18
12
Feature we would like to implement and invite the community to help us implement in the future:
@@ -21,17 +15,20 @@ Feature we would like to implement and invite the community to help us implement
21
15
* Testing support
22
16
* Class generation from CRD to POJO
23
17
24
-
25
18
## Usage
26
-
> Under sample directory you can try out our sample.
19
+
20
+
We have several sample Operators under the samples directory:
21
+
**basic*: Minimal Operator implementation which only parses the Custom Resource and prints to stdout.
22
+
Implemented with and without Spring Boot support. The two samples share the common module.
23
+
**webserver*: More realistic example creating an nginx webserver from a Custom Resource containing html code.
27
24
28
25
Add dependency to your project:
29
26
30
27
```xml
31
28
<dependency>
32
29
<groupId>com.github.containersolutions</groupId>
33
30
<artifactId>operator-framework</artifactId>
34
-
<version>0.1.1</version>
31
+
<version>{see https://search.maven.org/search?q=a:operator-framework for latest version}</version>
35
32
</dependency>
36
33
```
37
34
@@ -50,15 +47,15 @@ public class Runner {
50
47
The Controller implements the business logic and describes all the classes needed to handle the CRD.
@@ -78,23 +75,46 @@ public class CustomServiceController implements ResourceController<CustomService
78
75
Our custom resource java representation
79
76
80
77
```java
81
-
publicclassCustomServiceextendsCustomResource {
78
+
publicclassWebServerextendsCustomResource {
79
+
80
+
privateWebServerSpec spec;
82
81
83
-
privateServiceSpec spec;
82
+
privateWebServerStatus status;
84
83
85
-
publicServiceSpecgetSpec() {
84
+
publicWebServerSpecgetSpec() {
86
85
return spec;
87
86
}
88
87
89
-
publicvoidsetSpec(ServiceSpecspec) {
88
+
publicvoidsetSpec(WebServerSpecspec) {
90
89
this.spec = spec;
91
90
}
91
+
92
+
publicWebServerStatusgetStatus() {
93
+
return status;
94
+
}
95
+
96
+
publicvoidsetStatus(WebServerStatusstatus) {
97
+
this.status = status;
98
+
}
99
+
}
100
+
101
+
publicclassWebServerSpec {
102
+
103
+
privateString html;
104
+
105
+
publicStringgetHtml() {
106
+
return html;
107
+
}
108
+
109
+
publicvoidsetHtml(Stringhtml) {
110
+
this.html = html;
111
+
}
92
112
}
93
113
```
94
114
95
115
## Spring Boot Support
96
116
97
-
We provide a spring boot starter to automatically handle bean registration, and registering variouse components as beans.
117
+
We provide a spring boot starter to automatically handle bean registration, and registering various components as beans.
98
118
To use it just include the following dependency to you project:
99
119
100
120
```
@@ -105,35 +125,49 @@ To use it just include the following dependency to you project:
105
125
</dependency>
106
126
```
107
127
108
-
Note that controllers needs to be registered as a bean. Thus just annotating them also with `@Component` annotation.
109
-
See Spring docs for for details, also our sample with component scanning.
128
+
Note that controllers needs to be registered as beans in the Spring context. For example adding the `@Component` annotation
129
+
on the classes will work.
130
+
See Spring docs for for details, also our spring-boot with component scanning.
110
131
All controllers that are registered as a bean, gets automatically registered to operator.
111
132
112
133
Kubernetes client creation using properties is also supported, for complete list see: [Link for config class]
113
134
114
-
## Dealing with Consistency
115
135
116
-
### Run Single Instance
136
+
## Implementation / Design details
137
+
138
+
This library relies on the amazing [kubernetes-client](https://github.com/fabric8io/kubernetes-client) from fabric8.
139
+
Most of the heavy lifting is actually done by kubernetes-client.
140
+
141
+
What the framework adds on top of the bare client:
142
+
* Management of events from the Kubernetes API. All events are inserted into a queue by the EventScheduler. The
143
+
framework makes sure only the latest event for a certain resource is processed. This is especially important since
144
+
on startup the operator can receive a whole series of obsolete events.
145
+
* Retrying of failed actions. When an event handler throws an exception the event is put back in the queue.
146
+
* A clean interface to the user of the framework to receive events related to the Controller's resource.
147
+
148
+
### Dealing with Consistency
149
+
150
+
#### Run Single Instance
117
151
118
152
There should be always just one instance of an operator running at a time (think process). If there there would be
119
153
two ore more, in general it could lead to concurrency issues. Note that we are also doing optimistic locking when we update a resource.
120
154
In this way the operator is not highly available. However for operators this not necessary an issue,
121
155
if the operator just gets restarted after it went down.
122
156
123
-
### Operator Restarts
157
+
####Operator Restarts
124
158
125
159
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
126
160
(We use `kubectl get ... --watch` in the background). This can be a huge amount of resources depending on your use case.
127
161
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.
128
162
129
-
### At Least Once
163
+
####At Least Once
130
164
131
165
To implement controller logic, we have to override two methods: `createOrUpdateResource` and `deleteResource`.
132
166
These methods are called if a resource is create/changed or marked for deletion. In most cases these methods will be
133
167
called just once, but in some rare cases can happen that are called more then once. In practice this means that the
134
168
implementation needs to be **idempotent**.
135
169
136
-
### Deleting a Resource
170
+
####Deleting a Resource
137
171
138
172
During deletion process we use [Kubernetes finalizers](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#finalizers
139
173
"Kubernetes docs") finalizers. This is required, since it can happen that the operator is not running while the delete
0 commit comments