Revised ECK upgrade instructions (#6088) (#6098)

Co-authored-by: Arianna Laudazzi <[email protected]>
(cherry picked from commit d8aa26b)

Author: pebrc

docs/operating-eck/upgrading-eck.asciidoc

@@ -9,28 +9,27 @@ endif::[]
 
 This page provides instructions on how to upgrade the ECK operator.
 
-For Elastic Stack upgrade, check <<{p}-upgrading-stack,Upgrade the Elastic Stack version>>.
+For upgrades of Elastic Stack applications like Elasticsearch or Kibana, check <<{p}-upgrading-stack,Upgrade the Elastic Stack version>>.
 
 [float]
 [id="{p}-ga-upgrade"]
-== Upgrade to ECK {eck_version}
-
-ECK reached general availability (GA) status with the link:https://www.elastic.co/blog/elastic-cloud-on-kubernetes-ECK-is-now-generally-available[release of version 1.0.0]. The latest available GA version is {eck_version}. It is compatible with the previous GA releases (1.0.x and higher) and the beta release (1.0.0-beta1), and can be upgraded in-place (<<{p}-upgrade-instructions, with a few exceptions>>) by applying the new set of deployment manifests. Previous alpha releases, up to and including version 0.9.0, are not compatible with the GA and beta releases and link:https://www.elastic.co/guide/en/cloud-on-k8s/1.0-beta/k8s-upgrading-eck.html[require extra work to upgrade].
+== Before you upgrade to ECK {eck_version}
+The upgrade process results in an update to all the existing managed resources. This potentially triggers a rolling restart of all Elasticsearch and Kibana pods. This <<{p}-beta-to-ga-rolling-restart, list>> details the affected target versions that will cause a rolling restart. If you have a large Elasticsearch cluster or multiple Elastic Stack deployments, the rolling restart could cause a performance degradation. When you plan to upgrade ECK for production workloads, take into consideration the time required to upgrade the ECK operator plus the time required to roll all managed workloads and Elasticsearch clusters. Check for more information on how to <<{p}-beta-to-ga-rolling-restart, control the rolling restarts during the upgrade>>.
 
 Before upgrading, refer to the <<release-notes-{eck_version}, release notes>> to make sure that the release does not contain any breaking changes that could affect you. The <<release-highlights-{eck_version},release highlights document>> provides more details and possible workarounds for any breaking changes or known issues in each release.
 
-Note that the release notes and highlights only list the changes since the last release. If you are skipping over any intermediate versions during the upgrade -- such as going directly from 1.0.0-beta1 to {eck_version} -- review the release notes and highlights of each of the skipped releases to fully understand all the breaking changes you might encounter during and after the upgrade.
+Note that the release notes and highlights only list the changes since the last release. If during the upgrade you skip any intermediate versions and go for example from 1.0.0 directly to {eck_version}, review the release notes and highlights of each of the skipped releases to understand all the breaking changes you might encounter during and after the upgrade.
 
 [float]
 [id="{p}-upgrade-instructions"]
 == Upgrade instructions
 
-CAUTION: The upgrade process results in an update to all the existing managed resources. This potentially triggers a rolling restart of all Elasticsearch and Kibana pods. This <<{p}-beta-to-ga-rolling-restart, list>> details the affected target versions that will cause a rolling restart. If you have a large Elasticsearch cluster or multiple Elastic Stack deployments, the rolling restart could cause a performance degradation. When you plan to upgrade ECK for production workloads, take into consideration the time required to upgrade the ECK operator plus the time required to roll all managed workloads and Elasticsearch clusters. Furthermore, <<{p}-beta-to-ga-rolling-restart, Guidance>> is available on controlling this process more gracefully.
+[float]
+=== Upgrading from ECK 1.6 or earlier
 
-Operator Lifecycle Manager (OLM) and OpenShift OperatorHub users that run with automatic upgrades enabled, are advised to set the `set-default-security-context` link:https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-operator-config.html[operator flag] explicitly before upgrading to ECK 2.0. If not set ECK can fail to link:https://github.com/elastic/cloud-on-k8s/issues/5061[auto-detect] the correct security context configuration and Elasticsearch Pods may not be allowed to run.
 
 
-Release 1.7.0 moves the link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/[CustomResourceDefinitions] (CRD) used by ECK to the v1 version. If you upgrade from a previous version of ECK, the new version of the CRDs replaces the existing CRDs. If you cannot remove the current ECK installation because you have production workloads that must not be deleted, the following approach is recommended.
+Release 1.7.0 moved the link:https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/[CustomResourceDefinitions] (CRD) used by ECK to the v1 version. If you upgrade from a previous version of ECK, the new version of the CRDs replaces the existing CRDs. If you cannot remove the current ECK installation because you have production workloads that must not be deleted, the following approach is recommended.
 
 [source,shell,subs="attributes,callouts"]
 .If you are installing using the YAML manifests: replace existing CRDs
@@ -68,21 +67,37 @@ helm upgrade elastic-operator elastic/eck-operator -n elastic-system
 
 If you are using ECK through an OLM-managed distribution channel like link:https://operatorhub.io[operatorhub.io] or the OpenShift OperatorHub then the CRD version upgrade will be handled by OLM for you and you do not need to take special action.
 
-This will update the ECK installation to the latest binary and update the CRDs and other ECK resources in the cluster. If you are upgrading from the beta version, ensure that your Elasticsearch, Kibana, and APM Server manifests are updated to use the `v1` API version instead of `v1beta1` after the upgrade.
+[float]
+=== Upgrading from ECK 1.9 or earlier
+
+Operator Lifecycle Manager (OLM) and OpenShift OperatorHub users that run with automatic upgrades enabled, are advised to set the `set-default-security-context` link:https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-operator-config.html[operator flag] explicitly before upgrading to ECK 2.0 or later. If not set, ECK can fail to link:https://github.com/elastic/cloud-on-k8s/issues/5061[auto-detect] the correct security context configuration and Elasticsearch Pods may not be allowed to run.
+
+[float]
+=== Upgrading from ECK 2.0 or later
+
+There are no special instructions to follow if you upgrade from any 2.x version to {eck_version}. Use the upgrade method applicable to your installation method of choice.
+
+.If you are using our YAML manifests
+[source,shell,subs="attributes,callouts"]
+----
+kubectl apply -f https://download.elastic.co/downloads/eck/{eck_version}/crds.yaml
+kubectl apply -f https://download.elastic.co/downloads/eck/{eck_version}/operator.yaml
+----
+.If your are using Helm
+[source,shell,subs="attributes,callouts"]
+----
+helm upgrade elastic-operator elastic/eck-operator -n elastic-system
+----
+This will update the ECK installation to the latest binary and update the CRDs and other ECK resources in the cluster.
+
 
 [float]
 [id="{p}-beta-to-ga-rolling-restart"]
 == Control rolling restarts during the upgrade
 
-Upgrading the operator results in a one-time update to existing managed resources in the cluster. This potentially triggers a rolling restart of pods by Kubernetes to apply those changes. The following table shows the target version that would cause a rolling restart.
+Upgrading the operator results in a one-time update to existing managed resources in the cluster. This potentially triggers a rolling restart of pods by Kubernetes to apply those changes. The following list contains the ECK operator versions that would cause a rolling restart after they have been installed.
 
-* 1.6
-* 1.9
-* 2.0
-* 2.1
-* 2.2
-* 2.4
-* 2.5
+ 1.6, 1.9, 2.0, 2.1, 2.2, 2.4, 2.5
 
 If you have a very large Elasticsearch cluster or multiple Elastic Stack deployments, this rolling restart might be disruptive or inconvenient. To have more control over when the pods belonging to a particular deployment should be restarted, you can <<{p}-exclude-resource,add an annotation>> to the corresponding resources to temporarily exclude them from being managed by the operator. When the time is convenient, you can remove the annotation and let the rolling restart go through.
 
@@ -91,7 +106,7 @@ CAUTION: Once a resource is excluded from being managed by ECK, you will not be
 [source,shell,subs="attributes,callouts"]
 .Exclude Elastic resources from being managed by the operator
 ----
-ANNOTATION='eck.k8s.elastic.co/managed=false' <1>
+ANNOTATION='eck.k8s.elastic.co/managed=false'
 
 # Exclude a single Elasticsearch resource named "quickstart"
 kubectl annotate --overwrite elasticsearch quickstart $ANNOTATION
@@ -103,20 +118,16 @@ kubectl annotate --overwrite elastic --all $ANNOTATION
 for NS in $(kubectl get ns -o=custom-columns='NAME:.metadata.name' --no-headers); do kubectl annotate --overwrite elastic --all $ANNOTATION -n $NS; done
 ----
 
-<1> Before ECK 1.1.0, the annotation used to exclude resources was `common.k8s.elastic.co/pause=true`.
-
 Once the operator has been upgraded and you are ready to let the resource become managed again (triggering a rolling restart of pods in the process), remove the annotation.
 
 
 [source,shell,subs="attributes,callouts"]
 .Resume Elastic resource management by the operator
 ----
-RM_ANNOTATION='eck.k8s.elastic.co/managed-' <1>
+RM_ANNOTATION='eck.k8s.elastic.co/managed-'
 
 # Resume management of a single Elasticsearch cluster named "quickstart"
 kubectl annotate elasticsearch quickstart $RM_ANNOTATION
 ----
 
-<1> Before ECK 1.1.0, the annotation used to exclude resources was `common.k8s.elastic.co/pause=true`.
-
 NOTE: The ECK source repository contains a link:{eck_github}/tree/{eck_release_branch}/hack/annotator[shell script] to assist with mass addition/deletion of annotations.