From 2ec657311a3cf1aa8dc0750b258a04adf117d667 Mon Sep 17 00:00:00 2001
From: csviri <csviri@gmail.com>
Date: Fri, 21 Jan 2022 11:01:07 +0100
Subject: [PATCH 1/7] docs: wip
---
docs/documentation/patterns-best-practices.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/docs/documentation/patterns-best-practices.md b/docs/documentation/patterns-best-practices.md
index 519045f5d3..2bf3c0d045 100644
--- a/docs/documentation/patterns-best-practices.md
+++ b/docs/documentation/patterns-best-practices.md
@@ -12,8 +12,12 @@ of Java Operator SDK.
## Implementing a Reconciler
+### Reconcile All The Resource All the Time
+
### Idempotency
+### Managing Resources
+
### Sync of Async Way of Resource Handling
## Why to Have Automated Retries?
From c741d71cdbc2fefd04f10fb683971aee43143eb3 Mon Sep 17 00:00:00 2001
From: csviri <csviri@gmail.com>
Date: Wed, 26 Jan 2022 17:36:03 +0100
Subject: [PATCH 2/7] docs: best practices
---
docs/documentation/patterns-best-practices.md | 23 +++++++++++++++----
1 file changed, 19 insertions(+), 4 deletions(-)
diff --git a/docs/documentation/patterns-best-practices.md b/docs/documentation/patterns-best-practices.md
index 2bf3c0d045..4c8bb9e9fd 100644
--- a/docs/documentation/patterns-best-practices.md
+++ b/docs/documentation/patterns-best-practices.md
@@ -7,16 +7,31 @@ permalink: /docs/patterns-best-practices
# Patterns and Best Practices
-This document describes patters and best practices, to build and run operators, and how to implement them in terms
-of Java Operator SDK.
+This document describes patters and best practices, to build and run operators, and how to implement them in terms of
+Java Operator SDK.
## Implementing a Reconciler
-### Reconcile All The Resource All the Time
+### Reconcile All The Resources All the Time
+
+The reconciliation can be triggered by events from multiple sources. It could be tempting to check the events, and
+reconcile just the related resource or subset of resources that controller manages. However, this is **considered as an
+anti-pattern** in operators. If triggered, all resources should be reconciled. Note that usually this means only
+comparing the target state with the current state in the cache. The reason behind this is events not reliable in
+general, thus means events can be lost.
+
+In addition to that such approach might even complicate implementation logic in the `Reconciler`, since parallel
+execution of the reconciler is not allowed for the same custom resource, there can be multiple events received for the
+same resource or dependent resource during an ongoing execution, ordering those events could be also challenging.
+
+For this reason from v2 the events are not even accessible for the `Reconciler`.
### Idempotency
-### Managing Resources
+Since all the resources are reconciled during an execution and an execution can be triggered quite often, also
+retries of a reconciliation can happen naturally in operators, the implementation of a `Reconciler`
+needs to be idempotent. Luckily, since operators are usually managing already declarative resources, this is trivial
+to do in most cases.
### Sync of Async Way of Resource Handling
From 7d38cc12a84f46aea7d5c12c5b1f6aba8dd9fa4c Mon Sep 17 00:00:00 2001
From: csviri <csviri@gmail.com>
Date: Fri, 28 Jan 2022 14:26:18 +0100
Subject: [PATCH 3/7] docs: link to Operator SDK best practices
---
docs/documentation/patterns-best-practices.md | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/documentation/patterns-best-practices.md b/docs/documentation/patterns-best-practices.md
index 4c8bb9e9fd..2e2345f9bd 100644
--- a/docs/documentation/patterns-best-practices.md
+++ b/docs/documentation/patterns-best-practices.md
@@ -10,6 +10,8 @@ permalink: /docs/patterns-best-practices
This document describes patters and best practices, to build and run operators, and how to implement them in terms of
Java Operator SDK.
+See also best practices in [Operator SDK](https://sdk.operatorframework.io/docs/best-practices/best-practices/).
+
## Implementing a Reconciler
### Reconcile All The Resources All the Time
From c8216df8289cf0241b6a4657cebc12618ba4f54a Mon Sep 17 00:00:00 2001
From: csviri <csviri@gmail.com>
Date: Mon, 31 Jan 2022 18:24:22 +0100
Subject: [PATCH 4/7] docs: wip
---
docs/documentation/patterns-best-practices.md | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/docs/documentation/patterns-best-practices.md b/docs/documentation/patterns-best-practices.md
index 2e2345f9bd..50234e2f5a 100644
--- a/docs/documentation/patterns-best-practices.md
+++ b/docs/documentation/patterns-best-practices.md
@@ -35,7 +35,12 @@ retries of a reconciliation can happen naturally in operators, the implementatio
needs to be idempotent. Luckily, since operators are usually managing already declarative resources, this is trivial
to do in most cases.
-### Sync of Async Way of Resource Handling
+### Sync or Async Way of Resource Handling
+
+In an implementation of reconciliation there can be a point when reconciler needs to wait a non-insignificant amount
+of time while a resource gets up and running. For example, reconciler would do some additional step only if a Pod is ready
+to receive requests. This problem can in two ways synchronously or asynchronously.
+
## Why to Have Automated Retries?
From 83f529da92c6ec0b01317f6c3a6f4feaa03e6e30 Mon Sep 17 00:00:00 2001
From: csviri <csviri@gmail.com>
Date: Thu, 3 Feb 2022 17:01:07 +0100
Subject: [PATCH 5/7] docs: additional docs
---
docs/documentation/patterns-best-practices.md | 22 +++++++++++++++----
1 file changed, 18 insertions(+), 4 deletions(-)
diff --git a/docs/documentation/patterns-best-practices.md b/docs/documentation/patterns-best-practices.md
index 50234e2f5a..cdfb0fba66 100644
--- a/docs/documentation/patterns-best-practices.md
+++ b/docs/documentation/patterns-best-practices.md
@@ -7,7 +7,7 @@ permalink: /docs/patterns-best-practices
# Patterns and Best Practices
-This document describes patters and best practices, to build and run operators, and how to implement them in terms of
+This document describes patterns and best practices, to build and run operators, and how to implement them in terms of
Java Operator SDK.
See also best practices in [Operator SDK](https://sdk.operatorframework.io/docs/best-practices/best-practices/).
@@ -17,10 +17,10 @@ See also best practices in [Operator SDK](https://sdk.operatorframework.io/docs/
### Reconcile All The Resources All the Time
The reconciliation can be triggered by events from multiple sources. It could be tempting to check the events, and
-reconcile just the related resource or subset of resources that controller manages. However, this is **considered as an
+reconcile just the related resource or subset of resources that the controller manages. However, this is **considered as an
anti-pattern** in operators. If triggered, all resources should be reconciled. Note that usually this means only
comparing the target state with the current state in the cache. The reason behind this is events not reliable in
-general, thus means events can be lost.
+generally, this means events can be lost.
In addition to that such approach might even complicate implementation logic in the `Reconciler`, since parallel
execution of the reconciler is not allowed for the same custom resource, there can be multiple events received for the
@@ -39,11 +39,25 @@ to do in most cases.
In an implementation of reconciliation there can be a point when reconciler needs to wait a non-insignificant amount
of time while a resource gets up and running. For example, reconciler would do some additional step only if a Pod is ready
-to receive requests. This problem can in two ways synchronously or asynchronously.
+to receive requests. This problem can be approached in two ways synchronously or asynchronously.
+The async way is just return from the reconciler, if there are informers properly in place for the target resource,
+reconciliation will be triggered on change. During the reconciliation the pod can be read from the cache of the informer
+and a check on it's state can be conducted again. The benefit of this approach is that it will free up the thread,
+so it can be used to reconcile other resources.
+
+The sync way would be to periodically poll the cache of the informer for the pod's state, until the target state
+is reached. This would block the thread until the state is reached, which in some cases could take quite long.
## Why to Have Automated Retries?
+Automatic retries are in place by default, it can be fine-tuned, but in general it's not advised to turn
+of automatic retries. One of the reason is that, issues like network error naturally happens, and are usually
+solved by a retry. Another typical situation is for example when a dependent resource or the custom resource is updated,
+during the update usually there is optimistic version control in place. So if someone updated the resource during
+reconciliation, maybe using `kubectl` or another process, the update would fail on a conflict. A retry solves this
+problem simply by executing the reconciliation again.
+
## Managing State
## Dependent Resources
From d88409d39cda80e85b0ed3625b7685ffc7b80072 Mon Sep 17 00:00:00 2001
From: csviri <csviri@gmail.com>
Date: Thu, 3 Feb 2022 17:52:39 +0100
Subject: [PATCH 6/7] fix: links on home page
---
docs/_includes/hero.html | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/_includes/hero.html b/docs/_includes/hero.html
index 100fca649c..d0057b772c 100644
--- a/docs/_includes/hero.html
+++ b/docs/_includes/hero.html
@@ -5,13 +5,13 @@
{% endif %}
<h1 class="uk-heading-hero uk-text-bold uk-text-uppercase uk-text-muted uk-inline " style="font-family: 'Asap', sans-serif"> [ <small class="uk-margin-small-right uk-margin-small-left"> {{ site.title }} </small> ]</h1>
<div class="links uk-container uk-margin-medium-top">
- <a class="uk-button uk-button-small uk-border-pill uk-button-secondary uk-margin-small-bottom" href="{{ domain }}{{ link.url }}">
+ <a class="uk-button uk-button-small uk-border-pill uk-button-secondary uk-margin-small-bottom" href="/docs/getting-started">
Get Started
</a>
- <a class="uk-button uk-button-small uk-border-pill uk-button-default uk-margin-small-bottom " href="{{ domain }}{{ link.url }}">
+ <a class="uk-button uk-button-small uk-border-pill uk-button-default uk-margin-small-bottom " href="/docs/contributing">
<span uk-icon="github"></span> Contribute
</a>
- <a class="uk-button uk-button-small uk-border-pill uk-button-default uk-margin-small-bottom" href="{{ domain }}{{ link.url }}">
+ <a class="uk-button uk-button-small uk-border-pill uk-button-default uk-margin-small-bottom" href="https://discord.gg/DacEhAy">
<span uk-icon="discord"></span> Discord Channel
</a>
</div>
From 4b8e141fc7a74da95c2abe0b108d124633d77104 Mon Sep 17 00:00:00 2001
From: csviri <csviri@gmail.com>
Date: Thu, 3 Feb 2022 18:05:12 +0100
Subject: [PATCH 7/7] docs: improvements
---
docs/documentation/patterns-best-practices.md | 12 +++++++-----
1 file changed, 7 insertions(+), 5 deletions(-)
diff --git a/docs/documentation/patterns-best-practices.md b/docs/documentation/patterns-best-practices.md
index cdfb0fba66..14416a595a 100644
--- a/docs/documentation/patterns-best-practices.md
+++ b/docs/documentation/patterns-best-practices.md
@@ -16,17 +16,19 @@ See also best practices in [Operator SDK](https://sdk.operatorframework.io/docs/
### Reconcile All The Resources All the Time
-The reconciliation can be triggered by events from multiple sources. It could be tempting to check the events, and
+The reconciliation can be triggered by events from multiple sources. It could be tempting to check the events and
reconcile just the related resource or subset of resources that the controller manages. However, this is **considered as an
-anti-pattern** in operators. If triggered, all resources should be reconciled. Note that usually this means only
-comparing the target state with the current state in the cache. The reason behind this is events not reliable in
-generally, this means events can be lost.
+anti-pattern** in operators. If triggered, all resources should be reconciled. Usually this means only
+comparing the target state with the current state in the cache for most of the resource.
+The reason behind this is events not reliable in generally, this means events can be lost. In addition to that operator
+can crash and while down will miss events.
In addition to that such approach might even complicate implementation logic in the `Reconciler`, since parallel
execution of the reconciler is not allowed for the same custom resource, there can be multiple events received for the
same resource or dependent resource during an ongoing execution, ordering those events could be also challenging.
-For this reason from v2 the events are not even accessible for the `Reconciler`.
+Since there is a consensus regarding this in the industry, from v2 the events are not even accessible for
+the `Reconciler`.
### Idempotency