[DOCS] Upgrade 9.0 beta1 (#2961)

* Update upgrading-stack.asciidoc Pushing to save edits. * Update upgrading-stack.asciidoc * Saving to not lose edits. * Saving changes. * Lots of edits; saving. * Fix build errors * Change page nesting * Edits * Update structure --------- Co-authored-by: natasha-moore-elastic <[email protected]>
elastic · Feb 17, 2025 · d1df4b4 · d1df4b4
1 parent 4939c3f
commit d1df4b4
Show file tree

Hide file tree

Showing 11 changed files with 425 additions and 108 deletions.
diff --git a/docs/en/install-upgrade/index.asciidoc b/docs/en/install-upgrade/index.asciidoc
@@ -16,8 +16,16 @@ include::air-gapped-install.asciidoc[]
 
 include::upgrading-stack.asciidoc[]
 
+include::upgrade-orchestrator.asciidoc[]
+
+include::upgrade-deployment-cluster.asciidoc[]
+
 include::upgrading-stack-cloud.asciidoc[]
 
+include::upgrade-on-ece.asciidoc[]
+
+include::upgrade-on-eck.asciidoc[]
+
 include::upgrading-stack-on-prem.asciidoc[]
 
 include::upgrading-elasticsearch.asciidoc[]

diff --git a/docs/en/install-upgrade/upgrade-deployment-cluster.asciidoc b/docs/en/install-upgrade/upgrade-deployment-cluster.asciidoc
@@ -0,0 +1,23 @@
+[[upgrade-deployment-cluster]]
+== Upgrade your deployment or cluster
+
+Before you upgrade your deployment or cluster to {version}, ensure you're <<prepare-upgrade-9.0,prepared to upgrade>>. 
+
+The procedures you follow to upgrade depend on whether you've installed Elastic components using Elastic-managed infrastructure or self-managed infrastructure. 
+
+If you're running Elastic-managed infrastructure, your options are: 
+
+* <<upgrade-elastic-stack-for-elastic-cloud,Upgrading on Elastic Cloud Hosted (ECH)>>
+* Upgrading on {serverless-full} (updates are automatic and require no user management)
+
+If you're running your own self-managed infrastructure—either on-prem or on public cloud—your options are: 
+
+* <<upgrading-elastic-stack-on-prem,Upgrading the {stack}>> (upgrade each component individually)
+* <<upgrade-on-ece,Upgrading on {ece}>> (ECE)
+* <<upgrade-on-eck,Upgrading on {eck}>> (ECK)
+
+NOTE: Before you begin upgrading on ECE or ECK, ensure your orchestrator is compatible with {version}.  
+
+
+
+
diff --git a/docs/en/install-upgrade/upgrade-ingest-components.asciidoc b/docs/en/install-upgrade/upgrade-ingest-components.asciidoc
diff --git a/docs/en/install-upgrade/upgrade-on-ece.asciidoc b/docs/en/install-upgrade/upgrade-on-ece.asciidoc
@@ -0,0 +1,46 @@
+[[upgrade-on-ece]]
+=== Upgrade on {ece} (ECE)
+
+Similar to {ecloud} Hosted, a single click in the {ecloud} console can upgrade a deployment running on ECE to a newer version. During the upgrade process, {es}, {kib}, and all of your deployment components are upgraded simultaneously.
+
+Once you're <<prepare-upgrade-9.0,prepared to upgrade>>, do the following: 
+
+. Ensure your current ECE and Docker versions are https://www.elastic.co/support/matrix/#matrix_os[compatible] with {version} (the minimum required version for 9.x is ECE 3.0). If you don’t have a compatible version installed, <<upgrade-orchestrator,upgrade your orchestrator>>. 
+. Download the most recent {ece-ref}/ece-manage-elastic-stack.html#ece_most_recent_elastic_stack_packs[stack pack] for the version you're upgrading to, then {ece-ref}/ece-manage-elastic-stack.html#ece-manage-elastic-stack-add[add the stack pack] to your installation via the Cloud UI. 
+. Back up your data to a snapshot. First, {ece-ref}/ece-manage-repositories.html[configure a snapshot repository] to enable snapshots. 
+
+[discrete]
+[[perform-upgrade-ece]]
+==== Perform the upgrade
+
+. Log in to the {ece-ref}/ece-login.html[Cloud UI]. 
+. On the Deployments page, select your deployment. 
++
+Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters.
+
+To upgrade a deployment:
+
+. In the *Deployment version* section, click *Upgrade*.
+. Select version {version}.
+. Click *Upgrade*, then *Confirm upgrade*. The new configuration takes a few minutes to create.
++
+NOTE: If any incompatibilities are detected when you attempt to upgrade to {version}, the UI provides a link to the Upgrade Assistant, which checks for deprecated settings in your cluster and indices and helps you resolve them. After resolving the issues, return to the deployments page and restart the upgrade. 
+
+Security realm settings::
+During the upgrade process, you are prompted to update the security realm settings if your user settings include a `xpack.security.authc.realms` value. 
++
+If the security realms are configured in `user_settings`, you'll be prompted to modify the settings:
++
+.. On the *Update security realm settings* window, edit the settings.
++
+.. Click *Update settings*.
++
+If the security realm settings are located in `user_settings_override`, contact Support to help you upgrade.
+
+After you're done upgrading, upgrade your ingest components in the following order: 
+
+. {ls}: {logstash-ref}/upgrading-logstash.html[upgrade instructions]
+. {beats}: {beats-ref}/upgrading.html[upgrade instructions]
+. {agent}: {fleet-guide}/upgrade-elastic-agent.html[upgrade instructions]
+. {apm-agent}s: {observability-guide}/apm-upgrade.html[upgrade instructions]
+
diff --git a/docs/en/install-upgrade/upgrade-on-eck.asciidoc b/docs/en/install-upgrade/upgrade-on-eck.asciidoc
@@ -0,0 +1,143 @@
+[[upgrade-on-eck]]
+=== Upgrade on {eck} (ECK)
+
+The ECK orchestrator can safely perform upgrades to newer versions of the various {stack} resources. 
+
+To upgrade on ECK, first do the following: 
+
+. Ensure you're <<prepare-upgrade-9.0, prepared to upgrade>>. 
+. Ensure the ECK version is {eck-ref}/k8s-supported.html[compatible] with the {stack} version you’re targeting. If necessary, <<upgrade-orchestrator, upgrade your orchestrator>>. 
+
+[discrete]
+[[perform-upgrade-eck]]
+==== Perform the upgrade
+
+When you are ready, modify the `version` field in the resource spec to the desired stack version and the orchestrator will start the upgrade process automatically. Do this for each resource, including {es} and {kib}. In the following example, we’re modifying the version to `9.0.0`. 
+
+[source,yaml,subs="attributes,+macros"]
+----
+apiVersion: elasticsearch.k8s.elastic.co/v1
+kind: Elasticsearch
+metadata:
+  name: elasticsearch-sample
+  namespace: production
+spec:
+  version: 9.0.0
+  monitoring:
+    metrics:
+      elasticsearchRefs:
+        - name: monitoring-cluster
+          namespace: observability
+    logs:
+      elasticsearchRefs:
+        - name: monitoring-cluster
+          namespace: observability
+  http:
+    service:
+      spec:
+        type: LoadBalancer
+  nodeSets:
+  - name: master
+    count: 3
+    config:
+      node.roles: ["master"]
+      xpack.ml.enabled: true
+      node.store.allow_mmap: false
+    volumeClaimTemplates:
+    - metadata:
+        name: elasticsearch-data
+      spec:
+        accessModes:
+        - ReadWriteOnce
+        resources:
+          requests:
+            storage: 20Gi
+        storageClassName: standard
+    podTemplate:
+      metadata:
+        labels:
+          key: sample
+      spec:
+        initContainers:
+        - name: sysctl
+          securityContext:
+            privileged: true
+          command: ['sh', '-c', 'sysctl -w vm.max_map_count=262144']
+        containers:
+        - name: elasticsearch
+          resources:
+            requests:
+              memory: 2Gi
+              cpu: 0.5
+            limits:
+              memory: 2Gi
+              cpu: 1
+  - name: data
+    count: 3
+    config:
+      node.roles: ["data", "ingest", "ml", "transform"]
+      node.store.allow_mmap: false
+    volumeClaimTemplates:
+    - metadata:
+        name: elasticsearch-data
+      spec:
+        accessModes:
+        - ReadWriteOnce
+        resources:
+          requests:
+            storage: 20Gi
+        storageClassName: standard
+    podTemplate:
+      metadata:
+        labels:
+          key: sample
+      spec:
+        initContainers:
+        - name: sysctl
+          securityContext:
+            privileged: true
+          command: ['sh', '-c', 'sysctl -w vm.max_map_count=262144']
+        containers:
+        - name: elasticsearch
+          resources:
+            requests:
+              memory: 2Gi
+              cpu: 0.5
+            limits:
+              memory: 2Gi
+              cpu: 1
+---
+apiVersion: kibana.k8s.elastic.co/v1
+kind: Kibana
+metadata:
+  name: kibana-sample
+  namespace: production
+spec:
+  version: 9.0.0
+  monitoring:
+    metrics:
+      elasticsearchRefs:
+        - name: monitoring-cluster
+          namespace: observability
+    logs:
+      elasticsearchRefs:
+        - name: monitoring-cluster
+          namespace: observability
+  http:
+    service:
+      spec:
+        type: LoadBalancer
+  count: 1
+  elasticsearchRef:
+    name: elasticsearch-sample
+
+----
+
+ECK will ensure that {stack} resources are upgraded in the correct order. For more information on how the orchestrator performs upgrades and how to tune its behavior, check out {eck-ref}/k8s-orchestration.html[Nodes orchestration]. 
+
+Next, upgrade your ingest components in the following order: 
+
+. {ls}: {logstash-ref}/upgrading-logstash.html[upgrade instructions]
+. {beats}: {beats-ref}/upgrading.html[upgrade instructions]
+. {agent}: {fleet-guide}/upgrade-elastic-agent.html[upgrade instructions]
+. {apm-agent}s: {observability-guide}/apm-upgrade.html[upgrade instructions]
diff --git a/docs/en/install-upgrade/upgrade-orchestrator.asciidoc b/docs/en/install-upgrade/upgrade-orchestrator.asciidoc
@@ -0,0 +1,20 @@
+[[upgrade-orchestrator]]
+== Upgrade your orchestrator
+
+NOTE: This topic applies only to customers running the {stack} on {ece} (ECE) or {eck} (ECK). 
+
+Elastic provides customers with two major self-managed orchestrators to manage the {stack}. Before you can upgrade the products in the stack, you need to ensure your orchestrator is running a compatible version. If it's incompatible, you'll need to upgrade the orchestrator first before you can upgrade the stack.  
+
+[discrete]
+=== Upgrade ECE
+
+{ece} (ECE) provides an easy way to provision, manage, and scale a fleet of {es} deployments from a central place. It can be installed on a public cloud platform, such as AWS, GCP or Microsoft Azure, on your own private cloud, or on bare metal.
+
+If you’re planning to upgrade to {version}, the minimum required version is ECE 3.0.0. If you're running an earlier version, refer to {ece-ref}/ece-upgrade.html[Upgrade your installation] for instructions on how to upgrade.   
+
+[discrete]
+=== Upgrade ECK
+
+{eck} (ECK) is built on the Kubernetes operator pattern and extends the basic Kubernetes orchestration capabilities to support the setup and management of Elastic products and solutions on Kubernetes.
+
+If you're planning to upgrade to {version}, refer to the list of {eck-ref}/k8s-supported.html[supported versions] to ensure your current ECK version is compatible. If it isn't, refer to {eck-ref}/k8s-upgrading-eck.html[Upgrade ECK] for instructions on how to upgrade. 
diff --git a/docs/en/install-upgrade/upgrading-elasticsearch.asciidoc b/docs/en/install-upgrade/upgrading-elasticsearch.asciidoc
@@ -1,5 +1,5 @@
 [[upgrading-elasticsearch]]
-== Upgrade {es}
+=== Upgrade {es}
 
 An {es} cluster can be upgraded one node at
 a time so upgrading does not interrupt service. Running multiple versions of
@@ -332,7 +332,7 @@ upgraded master.
 
 [discrete]
 [[archived-settings]]
-=== Archived settings
+==== Archived settings
 
 If you upgrade an {es} cluster that uses deprecated cluster or index settings
 that are not used in the target version, they are archived. We

diff --git a/docs/en/install-upgrade/upgrading-kibana.asciidoc b/docs/en/install-upgrade/upgrading-kibana.asciidoc
@@ -1,5 +1,5 @@
 [[upgrading-kibana]]
-== Upgrade {kib}
+=== Upgrade {kib}
 
 [WARNING]
 ====

diff --git a/docs/en/install-upgrade/upgrading-stack-cloud.asciidoc b/docs/en/install-upgrade/upgrading-stack-cloud.asciidoc
@@ -1,30 +1,27 @@
 [[upgrade-elastic-stack-for-elastic-cloud]]
-=== Upgrade on Elastic Cloud
+=== Upgrade on {ecloud} Hosted
 
-Once you are <<upgrading-elastic-stack, prepared to upgrade>>,
-a single click in the Elastic Cloud console can upgrade a deployment to a newer
-version, add more processing capacity, change plugins, and enable or disable
-high availability, all at the same time. During the upgrade process,
-{es}, {kib}, and all of your deployment components are upgraded simultaneously.
+Once you are <<prepare-upgrade-9.0,prepared to upgrade>>,
+a single click in the {ecloud} console can upgrade a deployment to a newer version, add more processing capacity, change plugins, and enable or disable high availability, all at the same time. During the upgrade process, {es}, {kib}, and all of your deployment components are upgraded simultaneously.
 
-Minor version upgrades, upgrades from {prev-major-last} to {version}, 
+Minor version upgrades, upgrades from 8.18 to {version}, 
 and cluster configuration changes can be performed with no downtime. 
-Elastic Cloud only supports upgrades to released versions. 
+{ecloud} only supports upgrades to released versions. 
 Preview releases and master snapshots are not supported.
 
-{ess} and {ece} do not support the ability to upgrade to or from release candidate builds, such as 8.0.0-rc1.
+{ecloud} Hosted and {ece} do not support the ability to upgrade to or from release candidate builds, such as 9.0.0-rc1.
 
-If you use a separate {cloud}/ec-enable-logging-and-monitoring.html[monitoring deployment], you should upgrade the monitoring deployment before the production deployment. In general, the monitoring deployment and the deployments being monitored should be running the same version of the Elastic Stack. A monitoring deployment cannot monitor production deployments running newer versions of the stack. If necessary, the monitoring deployment can monitor production deployments running the latest release of the previous major version.
+If you use a separate {cloud}/ec-enable-logging-and-monitoring.html[monitoring deployment], you should upgrade the monitoring deployment before the production deployment. In general, the monitoring deployment and the deployments being monitored should be running the same version of the {stack}. A monitoring deployment cannot monitor production deployments running newer versions of the stack. If necessary, the monitoring deployment can monitor production deployments running the latest release of the previous major version.
 
-IMPORTANT: Although it's simple to upgrade an Elastic Cloud deployment, 
+IMPORTANT: Although it's simple to upgrade an {ecloud} deployment, 
 the new version might include breaking changes that affect your application. 
 Make sure you review the deprecation logs, make any necessary changes, 
 and test against the new version before upgrading your production deployment.
 
 //To learn more about the upgrade process on Elastic Cloud, see {cloud}/ec-upgrade-deployment.html[Upgrade versions].
 
 Upgrade Assistant::
-Prior to upgrading, Elastic Cloud checks the deprecation API to retrieve information about the cluster, node, and index-level settings that need to be removed or changed. If there are any issues that would prevent a successful upgrade, the upgrade is blocked. Use the {kibana-ref-all}/{prev-major-last}/upgrade-assistant.html[Upgrade Assistant] in {prev-major-last} to identify and resolve issues and reindex any indices created before 7.0. 
+Prior to upgrading, {ecloud} checks the deprecation API to retrieve information about the cluster, node, and index-level settings that need to be removed or changed. If there are any issues that would prevent a successful upgrade, the upgrade is blocked. Use the {kibana-ref}/upgrade-assistant.html[Upgrade Assistant] in 8.18 to identify and resolve issues and reindex any indices created before 8.0. 
 
 Snapshots::
 To keep your data safe during the upgrade process, a snapshot is taken automatically 
@@ -56,45 +53,37 @@ If the security realms are configured in `user_settings`, you'll be prompted to
 . On the *Update security realm settings* window, edit the settings.
 +
 . Click *Update settings*.
-If the security realm settings are located in `user_settings_override`, contact support to help you upgrade.
+If the security realm settings are located in `user_settings_override`, contact Support to help you upgrade.
 
 [discrete]
 [[perform-cloud-upgrade]]
-=== Perform the upgrade
+==== Perform the upgrade
 
-Log in to your Elastic Cloud environment:
+Log in to your {ecloud} environment:
+
+. Log in to the {ecloud} Hosted https://cloud.elastic.co/login[console]. 
+. Select your deployment on the home page in the {ecloud} Hosted card or go to the Deployments page.
++
+Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list.
 
 //include::tab-widgets/code.asciidoc[]
 //include::tab-widgets/cloud-login-widget.asciidoc[]
-include::{docs-root}/shared/cloud/tab-widgets/code.asciidoc[]
-include::{docs-root}/shared/cloud/tab-widgets/cloud-login-widget.asciidoc[]
+//include::{docs-root}/shared/cloud/tab-widgets/code.asciidoc[]
+//include::{docs-root}/shared/cloud/tab-widgets/cloud-login-widget.asciidoc[]
 
 To upgrade a deployment:
 
 . In the *Deployment version* section, click *Upgrade*.
 . Select version {version}.
-. Click *Upgrade* and then *Confirm upgrade*. The new configuration takes a few minutes to create.
+. Click *Upgrade*, then *Confirm upgrade*. The new configuration takes a few minutes to create.
 +
 NOTE: If any incompatibilities are detected when you attempt to upgrade to {version}, the UI provides a link to the Upgrade Assistant, which checks for deprecated settings in your cluster and indices and helps you resolve them. After resolving the issues, return to the deployments page and restart the upgrade. 
 
-[discrete]
-[[upgrading-clients-ingest]]
-=== Upgrading {es} clients and ingest components
-
-Once you have upgraded from {prev-major-last}, you need to update your {es} clients and ingest components
-in the following order:
-
-. Java API Client: {java-api-client}/installation.html#maven[dependency configuration]
-. Logstash: {logstash-ref}/upgrading-logstash.html[upgrade instructions]
-. Beats: {beats-ref}/upgrading.html[upgrade instructions]
-. {agent}: {fleet-guide}/upgrade-elastic-agent.html[upgrade instructions]
-
 [discrete]
 [[upgrading-reindex]]
-=== Reindex to upgrade
+==== Reindex to upgrade
 
-If you are running a pre-{prev-major-version} version, you might need to perform multiple upgrades 
-or a full-cluster restart to get to {prev-major-last} to prepare to upgrade to {version}. 
+If you are running a pre-{prev-major-version} version, you might need to perform multiple upgrades or a full-cluster restart to get to 8.18 to then prepare to upgrade to {version}. 
 
 Alternatively, you can create a new {version} deployment and reindex from remote:
 
@@ -107,6 +96,19 @@ and temporarily send new index requests to both clusters.
 permanently swap in the new cluster.
 
 . Delete the old deployment. 
-On Elastic Cloud, you are billed only for the time that the new deployment 
+On {ecloud}, you are billed only for the time that the new deployment 
 runs in parallel with your old deployment.
 Usage is billed on an hourly basis.
+
+
+[discrete]
+[[upgrading-clients-ingest]]
+==== Upgrading {es} clients and ingest components
+
+Once you have upgraded from 8.18, you need to update your ingest components in the following order:
+
+//. Java API Client: {java-api-client}/installation.html#maven[dependency configuration]
+. {ls}: {logstash-ref}/upgrading-logstash.html[upgrade instructions]
+. {beats}: {beats-ref}/upgrading.html[upgrade instructions]
+. {agent}: {fleet-guide}/upgrade-elastic-agent.html[upgrade instructions]
+. {apm-agent}s: {observability-guide}/apm-upgrade.html[upgrade instructions]