Skip to content

Commit 847e818

Browse files
committed
docs
1 parent 390ace6 commit 847e818

File tree

1 file changed

+78
-4
lines changed

1 file changed

+78
-4
lines changed

docs/documentation/workflows.md

Lines changed: 78 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,14 @@ Workflows are defined as a set of [dependent resources](https://javaoperatorsdk.
2222
and dependencies between them, along with some conditions that mainly helps define optional resources and
2323
pre- and post-conditions to describe expected states of a resource at a certain point in the workflow.
2424

25+
When or after a workflow executed no state is persisted regarding the workflow execution. On every reconciliation
26+
all the resources are reconciled again, in other words the whole workflow is evaluated again.
2527

2628
## Elements of Workflow
2729

28-
- **Dependent resource** (DR) - are the resources which are reconciled.
30+
- **Dependent resource** (DR) - are the resources which are managed in reconcile logic.
2931
- **Depends-on relation** - if a DR B depends on another DR A, means that B will be reconciled after A is successfully
30-
reconciled - and ready if readyPostCondition is used.
32+
reconciled and ready if readyPostCondition is used.
3133
- **Reconcile precondition** - is a condition that needs to be fulfilled before the DR is reconciled. This allows also
3234
to define optional resources, that for example only created if a flag in a custom resource `.spec` has some
3335
specific value.
@@ -168,8 +170,8 @@ This section describes how a workflow is executed, first the rules are defined,
168170
### Rules
169171

170172
1. DR is reconciled if it does not depend on another DR, or ALL the DRs it depends on are ready. In case it
171-
has a reconcile-precondition that must met too. (Ready means that it is successfully reconciled - without any error - and
172-
if it has a ready condition that is met).
173+
has a reconcile-precondition that must be met too. (So her ready means that it is successfully reconciled - without
174+
any error - and if it has a ready condition that is met).
173175
2. If a reconcile-precondition of a DR is not met, it is deleted. If there are dependent resources which depends on it
174176
are deleted first too - this applies recursively. That means that DRs are always deleted in revers order compared
175177
how are reconciled.
@@ -182,12 +184,84 @@ This section describes how a workflow is executed, first the rules are defined,
182184

183185
### Samples
184186

187+
Notation: The arrows depicts reconciliation ordering, or in depends-on relation in reverse direction:
188+
`1 --> 2` mean `DR 2` depends-on `DR 1`.
185189

190+
#### Reconcile Sample
191+
192+
<div class="mermaid" markdown="0">
193+
194+
stateDiagram-v2
195+
1 --> 2
196+
1 --> 3
197+
2 --> 4
198+
3 --> 4
199+
200+
</div>
201+
202+
- At the workflow the reconciliation of the nodes would happen in the following way. DR with index `1` is reconciled.
203+
After DR `2` and `3` is reconciled concurrently, if both finished reconciling, node `4` is reconciled.
204+
- In case for example `2` would have a ready condition, that would be evaluated as "not met", `4` would not be reconciled.
205+
However `1`,`2` and `3` would be reconciled.
206+
- In case `1` would have a ready condition that is not met, neither `2`,`3` or `4` would be reconciled.
207+
- If there would be an error during the reconciliation of `2`, `4` would not be reconciled, but `3` would be
208+
(also `1` of course).
209+
210+
#### Sample with Reconcile Precondition
211+
212+
<div class="mermaid" markdown="0">
213+
214+
stateDiagram-v2
215+
1 --> 2
216+
1 --> 3
217+
3 --> 4
218+
3 --> 5
219+
220+
</div>
221+
222+
- Considering this sample for case `3` has reconcile-precondition, what is not met. In that case DR `1` and `2` would be
223+
reconciled. However, DR `3`,`4`,`5` would be deleted in the following way. DR `4` and `5` would be deleted concurrently.
224+
DR `3` would be deleted if `4` and `5` is deleted successfully, thus no error happened during deletion and all
225+
delete-postconditions are met.
226+
- If delete-postcondition for `5` would not be met `3` would not be deleted; `4` would be.
227+
- Similarly, in there would be an error for `5`, `3` would not be deleted, `4` would be.
186228

187229
## Cleanup
188230

231+
Cleanup works identically as delete for resources in reconciliation in case reconcile-precondition is not met, just for
232+
the whole workflow.
233+
234+
The rule is relatively simple:
235+
236+
Delete is called on a DR if there is no DR that depends on it, or if the DR-s which depends on it are
237+
successfully already deleted. Successfully deleted means, that it is deleted and if a delete-postcondition is present
238+
it is met. "Delete is called" means, that the dependent resource is checked if it implements `Deleter` interface,
239+
if implements it but do not implement `GarbageCollected` interface, the `Deleter.delete` method called. If a DR
240+
does not implement `Deleter` interface, it is considered as deleted automatically.
241+
242+
### Sample
243+
244+
245+
<div class="mermaid" markdown="0">
246+
247+
stateDiagram-v2
248+
1 --> 2
249+
1 --> 3
250+
2 --> 4
251+
3 --> 4
252+
253+
</div>
254+
255+
- The DRs are deleted in the following order: `4` is deleted, after `2` and `3` are deleted concurrently, after both
256+
succeeded `1` is deleted.
257+
- If delete-postcondition would not be met for `2`, node `1` would not be deleted. DR `4` and `3` would be deleted.
258+
- If `2` would be errored, DR `1` would not be deleted. DR `4` and `3` would be deleted.
259+
- if `4` would be errored, no other DR would be deleted.
260+
189261
## Error Handling
190262

263+
264+
191265
## Notes
192266

193267
- Workflows can be seen as a Directed Acyclic Graph (DAG) - or more precisely a set of DAGs - where nodes are the

0 commit comments

Comments
 (0)