Add beta -> upgrade docs (#2407)

docs/release-notes/highlights-1.0.0-beta1.asciidoc

@@ -44,7 +44,7 @@ Default limits are now set for the various resource types if none are explicitly
 === Breaking Changes
 
 The 1.0.0-beta version of the operator does not delete resources created by older versions of the operator, but it also does not manage them. 
-Attempting to delete resources created with a 0.9.0 version will hang if ECK 1.0.0-beta1 is running. Please see the <<{p}-1.0.0-beta1-backwards-compatibility, upgrading documentation>> for more information.
+Attempting to delete resources created with a 0.9.0 version will hang if ECK 1.0.0-beta1 is running. Please see the <<{p}-upgrading-eck, upgrading documentation>> for more information.
 
 [float]
 [id="{p}-known-issues-1.0.0-beta1"]

docs/upgrading-eck.asciidoc

@@ -7,131 +7,27 @@ endif::[]
 == Upgrading ECK
 
 [float]
-[id="{p}-upgrade-to-v1beta1"]
-=== Upgrading to ECK 1.0.0-beta1 from previous versions
+[id="{p}-ga-upgrade"]
+=== Upgrading to ECK 1.0.0 from previous versions
 
-ECK 1.0.0-beta1 includes changes that are incompatible with previous versions of the operator. Notable changes include:
+ECK 1.0.0 is largely compatible with the beta version of the operator (see <<{p}-ga-openshift,the exceptions for earlier Kubernetes and OpenShift versions>>). There is not a direct upgrade path from the alpha version.
 
-- Custom resource version has changed from `v1alpha1` to `v1beta1`.
-- Some CRD fields have been removed and some others have been renamed to clarify their purpose.
-- Elasticsearch cluster orchestration is now managed through link:https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/[StatefulSet] resources.
+To upgrade from 1.0.0-beta1, follow the <<{p}-quickstart>>. Note that all Elasticsearch Pods go through a rolling restart when the operator is upgraded.
 
-NOTE: See the <<release-notes-1.0.0-beta1>> for more information about all the features included in this release.
+After the upgrade, use the `v1` API version for all Elastic manifests.
 
-It is recommended to install ECK 1.0.0-beta1 in a fresh Kubernetes cluster and migrate data over from existing clusters if possible. If you wish to install ECK into an existing Kubernetes cluster that has a previous version of the operator installed, it is important to consider the following:
-
-- The old operator will be replaced by the new operator during the installation process.
-- Existing Elasticsearch, Kibana and APM Server resources created by an old version of the operator will continue to work but they will not be managed by the new operator. This means that the orchestration benefits provided by the operator such as rolling upgrades will no longer be available to those resources.
-- If the old operator is replaced without removing old resources first, you will have to manually disable finalizers to delete them later.
-- Existing Kubernetes manifests should be converted to the new format in order to work with the new operator.
-- link:https://github.com/elastic/cloud-on-k8s/issues/2039[Some incompatible settings] in Elasticsearch resources created for an older ECK version lead to parsing errors in ECK 1.0.0-beta1, preventing any reconciliation from happening.
-
-If some downtime is acceptable, upgrading in place can be performed as follows:
-
-CAUTION: These instructions are general guidelines only. You should have a thoroughly tested upgrade plan for your environment before attempting to modify any production deployments.
-
-. <<{p}-convert-manifests,Convert existing manifests to the new format>>.
-. link:https://www.elastic.co/guide/en/cloud-on-k8s/0.9/k8s-snapshot.html[Create snapshots of your existing Elasticsearch clusters].
-. link:https://www.elastic.co/guide/en/cloud-on-k8s/0.9/k8s-uninstall.html[Uninstall ECK].
-. link:https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-quickstart.html[Install new version of ECK].
-. Re-create the resources by applying the manifests converted in the first step.
-. Restore data from the snapshots.
+See the <<release-highlights-1.0.0>> for more information on new features.
 
 [float]
-[id="{p}-convert-manifests"]
-==== Convert Manifests
-
-.Elasticsearch
-* Replace `v1alpha1` in the `apiVersion` field with `v1beta1`
-* Rename `nodes` to `nodeSets`
-* Ensure that every `nodeSets` entry has a `name` and rename `nodeCount` to `count`
-* Remove `setVmMaxMapCount`. See: <<{p}-virtual-memory>>.
-* Remove `groups` from `updateStrategy`. See: <<{p}-update-strategy>>.
-* Remove `featureFlags`
-* If you specified `secureSettings`, convert `secretName` into an array item by prefixing it with `-`
-
-[source,patch,subs="attributes"]
-----
--apiVersion: elasticsearch.k8s.elastic.co/v1alpha1
-+apiVersion: elasticsearch.k8s.elastic.co/v1beta1
- kind: Elasticsearch
- metadata:
-   name: elasticsearch-sample
- spec:
-   version: {version}
--  setVmMaxMapCount: true
--  featureFlags: {}
-   updateStrategy:
-     changeBudget:
-       maxUnavailable: 1
--    groups: []
-   secureSettings:
--    secretName: "gcs-credentials"
-+  - secretName: "gcs-credentials"
--  nodes:
--  - nodeCount: 3
-+  nodeSets:
-+  - count: 3
-+    name: master-nodes
-----
+[id="{p}-ga-openshift"]
+=== Upgrades in earlier Kubernetes and OpenShift versions
 
+Upgrading from ECK 1.0.0-beta1 to 1.0.0 has some special considerations for users running either:
+- Kubernetes versions < 1.13
+- OpenShift 3.11
 
-.Kibana
-* Replace `v1alpha` in the `apiVersion` field with `v1beta1`
-* Rename `nodeCount` to `count`
-* If you specified `secureSettings`, convert `secretName` into an array item by prefixing it with `-`
-
-[source,patch,subs="attributes"]
-----
--apiVersion: kibana.k8s.elastic.co/v1alpha1
-+apiVersion: kibana.k8s.elastic.co/v1beta1
- kind: Kibana
- metadata:
-   name: kibana-sample
- spec:
-   version: {version}
--  nodeCount: 1
-+  count: 1
-   elasticsearchRef:
-     name: "elasticsearch-sample"
-   secureSettings:
--    secretName: "gcs-credentials"
-+  - secretName: "gcs-credentials"
-----
-
-
-.APM Server
-* Replace `v1alpha` in the `apiVersion` field with `v1beta1`
-* Rename `nodeCount` to `count`
-* If you specified `secureSettings`, convert `secretName` into an array item by prefixing it with `-`
-
-[source,patch,subs="attributes"]
-----
--apiVersion: apm.k8s.elastic.co/v1alpha1
-+apiVersion: apm.k8s.elastic.co/v1beta1
- kind: ApmServer
- metadata:
-   name: apm-server-sample
- spec:
-   version: {version}
--  nodeCount: 1
-+  count: 1
-   elasticsearchRef:
-     name: "elasticsearch-sample"
-   secureSettings:
--    secretName: "gcs-credentials"
-+  - secretName: "gcs-credentials"
-----
-
-[float]
-[id="{p}-1.0.0-beta1-backwards-compatibility"]
-==== Backwards compatibility
+In this case, ECK must be uninstalled and reinstalled (due to link:https://github.com/kubernetes/kubernetes/issues/73752[an upstream bug] that was not backported). To uninstall ECK, see <<{p}-uninstalling-eck>>. Then you can follow the <<{p}-quickstart>> to install anew. You may wish to save your existing `v1beta1` manifests and update them to the `v1` API version, and to <<{p}-snapshots,take snapshots>> and restore them as well.
 
-The 1.0.0-beta version of the operator does not delete resources created by older versions of the operator, but it also does not manage them. Attempting to delete resources created with a 0.9.0 version will hang if ECK 1.0.0-beta1 is running. To unblock the deletion, remove any registered finalizer from the resource (substituting the correct name for `quickstart`):
+In this case, ECK must be uninstalled and reinstalled (due to link:https://github.com/kubernetes/kubernetes/issues/73752[an upstream bug] that was not backported). To uninstall ECK, see <<{p}-uninstalling-eck>>. Then you can follow the <<{p}-quickstart>> to install anew. You can save your existing `v1beta1` manifests, update them to the `v1` API version, <<{p}-snapshots,take snapshots>> and restore them as well.
 
-[source,sh]
-----
-kubectl patch elasticsearch quickstart --patch '{"metadata": {"finalizers": []}}' --type=merge
-kubectl patch kibana quickstart --patch '{"metadata": {"finalizers": []}}' --type=merge
-kubectl patch apmserver quickstart --patch '{"metadata": {"finalizers": []}}' --type=merge
-----
+After the upgrade, use the `v1` API version for all Elastic manifests.