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
Copy file name to clipboardExpand all lines: docs/content/en/docs/_index.md
+30Lines changed: 30 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,4 +5,34 @@ menu: {main: {weight: 1}}
5
5
weight: 1
6
6
---
7
7
8
+
# Java Operator SDK Documentation
9
+
10
+
Welcome to the Java Operator SDK (JOSDK) documentation! This comprehensive guide will help you build powerful Kubernetes operators using Java.
11
+
12
+
## What is JOSDK?
13
+
14
+
The Java Operator SDK is a high-level framework designed to make implementing Kubernetes operators in Java as straightforward as possible. It provides:
15
+
16
+
-**Natural Java APIs** that feel familiar to Java developers
17
+
-**Built-in best practices** so you can focus on your business logic
18
+
-**Automatic handling** of common operator patterns and problems
19
+
-**Comprehensive tooling** for testing and development
20
+
21
+
## Quick Navigation
22
+
23
+
-**[Getting Started](getting-started/)** - New to operators or JOSDK? Start here!
24
+
-**[Documentation](documentation/)** - Detailed guides on all JOSDK features
25
+
-**[Migration](migration/)** - Upgrading from older versions
26
+
-**[FAQ](faq/)** - Common questions and answers
27
+
28
+
## Key Features
29
+
30
+
- Support for both custom and well-known Kubernetes resources
Copy file name to clipboardExpand all lines: docs/content/en/docs/contributing/_index.md
+40-56Lines changed: 40 additions & 56 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,82 +3,66 @@ title: Contributing To Java Operator SDK
3
3
weight: 110
4
4
---
5
5
6
-
First of all, we'd like to thank you for considering contributing to the project! We really
7
-
hope to create a vibrant community around this project but this won't happen without help from
8
-
people like you!
6
+
Thank you for considering contributing to the Java Operator SDK project! We're building a vibrant community and need help from people like you to make it happen.
9
7
10
8
## Code of Conduct
11
9
12
-
We are serious about making this a welcoming, happy project. We will not tolerate discrimination,
13
-
aggressive or insulting behaviour.
10
+
We're committed to making this a welcoming, inclusive project. We do not tolerate discrimination, aggressive, or insulting behavior.
14
11
15
-
To this end, the project and everyone participating in it is bound by the [Code of
16
-
Conduct]({{baseurl}}/coc). By participating, you are expected to uphold this code. Please report
17
-
unacceptable behaviour to any of the project admins.
12
+
This project and all participants are bound by our [Code of Conduct]({{baseurl}}/coc). By participating, you're expected to uphold this code. Please report unacceptable behavior to any project admin.
18
13
19
-
## Bugs
14
+
## Reporting Bugs
20
15
21
-
If you find a bug,
22
-
please [open an issue](https://github.com/java-operator-sdk/java-operator-sdk/issues)! Do try
23
-
to include all the details needed to recreate your problem. This is likely to include:
16
+
Found a bug? Please [open an issue](https://github.com/java-operator-sdk/java-operator-sdk/issues)! Include all details needed to recreate the problem:
24
17
25
-
-The version of the Operator SDK being used
26
-
-The exact platform and version of the platform that you're running on
27
-
-The steps taken to cause the bug
28
-
- Reproducer code is also very welcome to help us diagnose the issue and fix it quickly
18
+
- Operator SDK version being used
19
+
-Exact platform and version you're running on
20
+
-Steps to reproduce the bug
21
+
- Reproducer code (very helpful for quick diagnosis and fixes)
29
22
30
-
## Building Features and Documentation
23
+
## Contributing Features and Documentation
31
24
32
-
If you're looking for something to work on, take look at the issue tracker, in particular any items
33
-
labelled [good first issue](https://github.com/java-operator-sdk/java-operator-sdk/labels/good%20first%20issue)
34
-
.
35
-
Please leave a comment on the issue to mention that you have started work, in order to avoid
36
-
multiple people working on the same issue.
25
+
Looking for something to work on? Check the issue tracker, especially items labeled [good first issue](https://github.com/java-operator-sdk/java-operator-sdk/labels/good%20first%20issue). Please comment on the issue when you start work to avoid duplicated effort.
37
26
38
-
If you have an idea for a feature - whether or not you have time to work on it - please also open an
39
-
issue describing your feature and label it "enhancement". We can then discuss it as a community and
40
-
see what can be done. Please be aware that some features may not align with the project goals and
41
-
might therefore be closed. In particular, please don't start work on a new feature without
42
-
discussing it first to avoid wasting effort. We do commit to listening to all proposals and will do
43
-
our best to work something out!
27
+
### Feature Ideas
44
28
45
-
Once you've got the go ahead to work on a feature, you can start work. Feel free to communicate with
46
-
team via updates on the issue tracker or the [Discord channel](https://discord.gg/DacEhAy) and ask
47
-
for feedback, pointers etc. Once you're happy with your code, go ahead and open a Pull Request.
29
+
Have a feature idea? Open an issue labeled "enhancement" even if you can't work on it immediately. We'll discuss it as a community and see what's possible.
48
30
49
-
## Pull Request Process
31
+
**Important**: Some features may not align with project goals. Please discuss new features before starting work to avoid wasted effort. We commit to listening to all proposals and working something out when possible.
32
+
33
+
### Development Process
50
34
51
-
First, please format your commit messages so that they follow
52
-
the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
35
+
Once you have approval to work on a feature:
36
+
1. Communicate progress via issue updates or our [Discord channel](https://discord.gg/DacEhAy)
37
+
2. Ask for feedback and pointers as needed
38
+
3. Open a Pull Request when ready
39
+
40
+
## Pull Request Process
53
41
54
-
On opening a PR, a GitHub action will execute the test suite against the new code. All code is
55
-
required to pass the tests, and new code must be accompanied by new tests.
42
+
### Commit Messages
43
+
Format commit messages following [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
56
44
57
-
All PRs have to be reviewed and signed off by another developer before being merged. This review
58
-
will likely ask for some changes to the code - please don't be alarmed or upset
59
-
at this; it is expected that all PRs will need tweaks and a normal part of the process.
45
+
### Testing and Review
46
+
- GitHub Actions will run the test suite on your PR
47
+
- All code must pass tests
48
+
- New code must include new tests
49
+
- All PRs require review and sign-off from another developer
50
+
- Expect requests for changes - this is normal and part of the process
51
+
- PRs must comply with Java Google code style
60
52
61
-
The PRs are checked to be compliant with the Java Google code style.
53
+
### Licensing
54
+
All Operator SDK code is released under the [Apache 2.0 licence](LICENSE).
62
55
63
-
Be aware that all Operator SDK code is released under the [Apache 2.0 licence](LICENSE).
56
+
## Development Environment Setup
64
57
65
-
##Development environment setup
58
+
### Code Style
66
59
67
-
### Code style
60
+
SDK modules and samples follow Java Google code style. Code gets formatted automatically on every `compile`, but to avoid PR rejections due to style issues, set up your IDE:
68
61
69
-
The SDK modules and samples are formatted to follow the Java Google code style.
70
-
On every `compile` the code gets formatted automatically, however, to make things simpler (i.e.
71
-
avoid getting a PR rejected simply because of code style issues), you can import one of the
72
-
following code style schemes based on the IDE you use:
62
+
**IntelliJ IDEA**: Install the [google-java-format](https://plugins.jetbrains.com/plugin/8527-google-java-format) plugin
advice](https://gist.github.com/PurpleBooth/b24679402957c63ec426) and the [Contributor
84
-
Covenant](https://www.contributor-covenant.org/).
68
+
These guidelines were inspired by [Atom](https://github.com/atom/atom/blob/master/CONTRIBUTING.md), [PurpleBooth's advice](https://gist.github.com/PurpleBooth/b24679402957c63ec426), and the [Contributor Covenant](https://www.contributor-covenant.org/).
This section contains detailed documentation for all Java Operator SDK features and concepts. Whether you're building your first operator or need advanced configuration options, you'll find comprehensive guides here.
9
+
10
+
## Core Concepts
11
+
12
+
-**[Implementing a Reconciler](reconciler/)** - The heart of any operator
13
+
-**[Architecture](architecture/)** - How JOSDK works under the hood
Copy file name to clipboardExpand all lines: docs/content/en/docs/documentation/architecture.md
+20-48Lines changed: 20 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,62 +3,34 @@ title: Architecture and Internals
3
3
weight: 85
4
4
---
5
5
6
-
This document gives an overview of the internal structure and components of Java Operator SDK core,
7
-
in order to make it easier for developers to understand and contribute to it. This document is
8
-
not intended to be a comprehensive reference, rather an introduction to the core concepts and we
9
-
hope that the other parts should be fairly easy to understand. We will evolve this document
10
-
based on the community's feedback.
6
+
This document provides an overview of the Java Operator SDK's internal structure and components to help developers understand and contribute to the project. While not a comprehensive reference, it introduces core concepts that should make other components easier to understand.
11
7
12
8
## The Big Picture and Core Components
13
9
14
10
15
11
16
-
An [Operator](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java)
The `Controller` class, however, is an internal class managed by the framework itself and
21
-
usually shouldn't interacted with directly by end users. It
22
-
manages all the processing units involved with reconciling a single type of Kubernetes resource.
12
+
An [Operator](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java) is a set of independent [controllers](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/Controller.java).
23
13
24
-
Other components include:
14
+
The `Controller` class is an internal class managed by the framework and typically shouldn't be interacted with directly. It manages all processing units involved with reconciling a single type of Kubernetes resource.
is responsible for dispatching requests to the appropriate `Reconciler` method and handling
44
-
the reconciliation results, making the instructed Kubernetes API calls.
16
+
### Core Components
17
+
18
+
-**[Reconciler](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Reconciler.java)** - The primary entry point for developers to implement reconciliation logic
19
+
-**[EventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/EventSource.java)** - Represents a source of events that might trigger reconciliation
20
+
-**[EventSourceManager](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventSourceManager.java)** - Aggregates all event sources for a controller and manages their lifecycle
21
+
-**[ControllerResourceEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/controller/ControllerResourceEventSource.java)** - Central event source that watches primary resources for changes, propagates events, and caches state
22
+
-**[EventProcessor](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventProcessor.java)** - Processes incoming events sequentially per resource while allowing concurrent overall processing. Handles rescheduling and retrying
23
+
-**[ReconcilerDispatcher](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/ReconciliationDispatcher.java)** - Dispatches requests to appropriate `Reconciler` methods and handles reconciliation results, making necessary Kubernetes API calls
45
24
46
25
## Typical Workflow
47
26
48
-
A typical workflows looks like following:
27
+
A typical workflow follows these steps:
49
28
50
-
1. An `EventSource` produces an event, that is propagated to the `EventProcessor`.
51
-
2. The resource associated with the event is read from the internal cache.
52
-
3. If the resource is not already being processed, a reconciliation request is
53
-
submitted to the executor service to be executed in a different thread, encapsulated in a
54
-
`ControllerExecution` instance.
55
-
4. This, in turns, calls the `ReconcilerDispatcher` which dispatches the call to the appropriate
56
-
`Reconciler` method, passing along all the required information.
57
-
5. Once the `Reconciler` is done, what happens depends on the result returned by the
58
-
`Reconciler`. If needed, the `ReconcilerDispatcher` will make the appropriate calls to the
59
-
Kubernetes API server.
60
-
6. Once the `Reconciler` is done, the `EventProcessor` is called back to finalize the
61
-
execution and update the controller's state.
62
-
7. The `EventProcessor` checks if the request needs to be rescheduled or retried and if there are no
63
-
subsequent events received for the same resource.
64
-
8. When none of this happens, the processing of the event is finished.
29
+
1.**Event Generation**: An `EventSource` produces an event and propagates it to the `EventProcessor`
30
+
2.**Resource Reading**: The resource associated with the event is read from the internal cache
31
+
3.**Reconciliation Submission**: If the resource isn't already being processed, a reconciliation request is submitted to the executor service in a different thread (encapsulated in a `ControllerExecution` instance)
32
+
4.**Dispatching**: The `ReconcilerDispatcher` is called, which dispatches the call to the appropriate `Reconciler` method with all required information
33
+
5.**Reconciler Execution**: Once the `Reconciler` completes, the `ReconcilerDispatcher` makes appropriate Kubernetes API server calls based on the returned result
34
+
6.**Finalization**: The `EventProcessor` is called back to finalize execution and update the controller's state
35
+
7.**Rescheduling Check**: The `EventProcessor` checks if the request needs rescheduling or retrying, and whether subsequent events were received for the same resource
36
+
8.**Completion**: When no further action is needed, event processing is finished
0 commit comments