From 5417faaf4c60d309d265e1496e2b6c292729df1d Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Fri, 24 Jul 2020 11:22:03 +0100 Subject: [PATCH 1/3] docs: remove leader sdk implementation that is no longer supported - fix broken links --- .../golang/advanced-topics.md | 48 ++++++------------- 1 file changed, 15 insertions(+), 33 deletions(-) diff --git a/website/content/en/docs/building-operators/golang/advanced-topics.md b/website/content/en/docs/building-operators/golang/advanced-topics.md index b076687bf4..7681525268 100644 --- a/website/content/en/docs/building-operators/golang/advanced-topics.md +++ b/website/content/en/docs/building-operators/golang/advanced-topics.md @@ -28,7 +28,14 @@ type MyAppStatus struct { } ``` + ### Adding 3rd Party Resources To Your Operator @@ -231,38 +238,7 @@ func contains(list []string, s string) bool { During the lifecycle of an operator it's possible that there may be more than 1 instance running at any given time e.g when rolling out an upgrade for the operator. In such a scenario it is necessary to avoid contention between multiple operator instances via leader election so that only one leader instance handles the reconciliation while the other instances are inactive but ready to take over when the leader steps down. -There are two different leader election implementations to choose from, each with its own tradeoff. - -- [Leader-with-lease][leader_with_lease]: The leader pod periodically renews the leader lease and gives up leadership when it can't renew the lease. This implementation allows for a faster transition to a new leader when the existing leader is isolated, but there is a possibility of split brain in [certain situations][lease_split_brain]. -- [Leader-for-life][leader_for_life]: The leader pod only gives up leadership (via garbage collection) when it is deleted. This implementation precludes the possibility of 2 instances mistakenly running as leaders (split brain). However, this method can be subject to a delay in electing a new leader. For instance when the leader pod is on an unresponsive or partitioned node, the [`pod-eviction-timeout`][pod_eviction_timeout] dictates how long it takes for the leader pod to be deleted from the node and step down (default 5m). - -By default the SDK enables the leader-with-lease implementation. However you should consult the docs above for both approaches to consider the tradeoffs that make sense for your use case. - -The following examples illustrate how to use the two options: - -#### Leader for life - -A call to `leader.Become()` will block the operator as it retries until it can become the leader by creating the configmap named `memcached-operator-lock`. - -```Go -import ( - ... - "github.com/operator-framework/operator-sdk/pkg/leader" -) - -func main() { - ... - err = leader.Become(context.TODO(), "memcached-operator-lock") - if err != nil { - log.Error(err, "Failed to retry for leader lock") - os.Exit(1) - } - ... -} -``` -If the operator is not running inside a cluster `leader.Become()` will simply return without error to skip the leader election since it can't detect the operator's namespace. - -#### Leader with lease +By default the SDK enables the [Leader-with-lease][leader_with_lease] implementation. The leader pod periodically renews the leader lease and gives up leadership when it can't renew the lease. This implementation allows for a faster transition to a new leader when the existing leader is isolated, but there is a possibility of split brain in [certain situations][lease_split_brain]. The leader-with-lease approach can be enabled via the [Manager Options][manager_options] for leader election. @@ -287,14 +263,20 @@ func main() { When the operator is not running in a cluster, the Manager will return an error on starting since it can't detect the operator's namespace in order to create the configmap for leader election. You can override this namespace by setting the Manager's `LeaderElectionNamespace` option. [typical-status-properties]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties + + [scheme_package]:https://github.com/kubernetes/client-go/blob/master/kubernetes/scheme/register.go [deployments_register]: https://github.com/kubernetes/api/blob/master/apps/v1/register.go#L41 [runtime_package]: https://godoc.org/k8s.io/apimachinery/pkg/runtime [scheme_builder]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/scheme#Builder [metrics_doc]: https://book.kubebuilder.io/reference/metrics.html [lease_split_brain]: https://github.com/kubernetes/client-go/blob/30b06a83d67458700a5378239df6b96948cb9160/tools/leaderelection/leaderelection.go#L21-L24 -[leader_for_life]: https://godoc.org/github.com/operator-framework/operator-sdk/pkg/leader [leader_with_lease]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/leaderelection [pod_eviction_timeout]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/#options [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options From 532de026da3290b803ccff83468f3542bae9b4cc Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Fri, 24 Jul 2020 14:07:15 +0100 Subject: [PATCH 2/3] doc: fix link for leader election --- .../golang/advanced-topics.md | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/website/content/en/docs/building-operators/golang/advanced-topics.md b/website/content/en/docs/building-operators/golang/advanced-topics.md index 7681525268..a876161879 100644 --- a/website/content/en/docs/building-operators/golang/advanced-topics.md +++ b/website/content/en/docs/building-operators/golang/advanced-topics.md @@ -238,7 +238,38 @@ func contains(list []string, s string) bool { During the lifecycle of an operator it's possible that there may be more than 1 instance running at any given time e.g when rolling out an upgrade for the operator. In such a scenario it is necessary to avoid contention between multiple operator instances via leader election so that only one leader instance handles the reconciliation while the other instances are inactive but ready to take over when the leader steps down. -By default the SDK enables the [Leader-with-lease][leader_with_lease] implementation. The leader pod periodically renews the leader lease and gives up leadership when it can't renew the lease. This implementation allows for a faster transition to a new leader when the existing leader is isolated, but there is a possibility of split brain in [certain situations][lease_split_brain]. +There are two different leader election implementations to choose from, each with its own tradeoff. + +- [Leader-with-lease][leader_with_lease]: The leader pod periodically renews the leader lease and gives up leadership when it can't renew the lease. This implementation allows for a faster transition to a new leader when the existing leader is isolated, but there is a possibility of split brain in [certain situations][lease_split_brain]. +- [Leader-for-life][leader_for_life]: The leader pod only gives up leadership (via garbage collection) when it is deleted. This implementation precludes the possibility of 2 instances mistakenly running as leaders (split brain). However, this method can be subject to a delay in electing a new leader. For instance when the leader pod is on an unresponsive or partitioned node, the [`pod-eviction-timeout`][pod_eviction_timeout] dictates how long it takes for the leader pod to be deleted from the node and step down (default 5m). + +By default the SDK enables the leader-with-lease implementation. However you should consult the docs above for both approaches to consider the tradeoffs that make sense for your use case. + +The following examples illustrate how to use the two options: + +#### Leader for life + +A call to `leader.Become()` will block the operator as it retries until it can become the leader by creating the configmap named `memcached-operator-lock`. + +```Go +import ( + ... + "github.com/operator-framework/operator-sdk/pkg/leader" +) + +func main() { + ... + err = leader.Become(context.TODO(), "memcached-operator-lock") + if err != nil { + log.Error(err, "Failed to retry for leader lock") + os.Exit(1) + } + ... +} +``` +If the operator is not running inside a cluster `leader.Become()` will simply return without error to skip the leader election since it can't detect the operator's namespace. + +#### Leader with lease The leader-with-lease approach can be enabled via the [Manager Options][manager_options] for leader election. @@ -277,6 +308,7 @@ https://github.com/kubernetes/kubernetes/pull/92717/files [scheme_builder]: https://godoc.org/sigs.k8s.io/controller-runtime/pkg/scheme#Builder [metrics_doc]: https://book.kubebuilder.io/reference/metrics.html [lease_split_brain]: https://github.com/kubernetes/client-go/blob/30b06a83d67458700a5378239df6b96948cb9160/tools/leaderelection/leaderelection.go#L21-L24 +[leader_for_life]: https://godoc.org/github.com/operator-framework/operator-lib/leader [leader_with_lease]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/leaderelection [pod_eviction_timeout]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/#options [manager_options]: https://godoc.org/github.com/kubernetes-sigs/controller-runtime/pkg/manager#Options From cc28f73afc7638cd0595430fe004ddbf1282ae5b Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Fri, 24 Jul 2020 14:58:58 +0100 Subject: [PATCH 3/3] doc: fix link for leader election --- .../building-operators/golang/advanced-topics.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/website/content/en/docs/building-operators/golang/advanced-topics.md b/website/content/en/docs/building-operators/golang/advanced-topics.md index a876161879..4fe2fde316 100644 --- a/website/content/en/docs/building-operators/golang/advanced-topics.md +++ b/website/content/en/docs/building-operators/golang/advanced-topics.md @@ -28,14 +28,7 @@ type MyAppStatus struct { } ``` - ### Adding 3rd Party Resources To Your Operator @@ -294,14 +287,7 @@ func main() { When the operator is not running in a cluster, the Manager will return an error on starting since it can't detect the operator's namespace in order to create the configmap for leader election. You can override this namespace by setting the Manager's `LeaderElectionNamespace` option. [typical-status-properties]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties - - +[godoc-conditions]: https://godoc.org/github.com/operator-framework/operator-lib/status#Conditions [scheme_package]:https://github.com/kubernetes/client-go/blob/master/kubernetes/scheme/register.go [deployments_register]: https://github.com/kubernetes/api/blob/master/apps/v1/register.go#L41 [runtime_package]: https://godoc.org/k8s.io/apimachinery/pkg/runtime