diff --git a/docs/en/install-upgrade/index.asciidoc b/docs/en/install-upgrade/index.asciidoc index 9ba33ba3d..2e4c3bdc3 100644 --- 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 new file mode 100644 index 000000000..1298104b2 --- /dev/null +++ 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 <>. + +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: + +* <> +* 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: + +* <> (upgrade each component individually) +* <> (ECE) +* <> (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 new file mode 100644 index 000000000..e69de29bb diff --git a/docs/en/install-upgrade/upgrade-on-ece.asciidoc b/docs/en/install-upgrade/upgrade-on-ece.asciidoc new file mode 100644 index 000000000..14b719846 --- /dev/null +++ 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 <>, 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, <>. +. 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 new file mode 100644 index 000000000..310d3e196 --- /dev/null +++ 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 <>. +. Ensure the ECK version is {eck-ref}/k8s-supported.html[compatible] with the {stack} version you’re targeting. If necessary, <>. + +[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] \ No newline at end of file diff --git a/docs/en/install-upgrade/upgrade-orchestrator.asciidoc b/docs/en/install-upgrade/upgrade-orchestrator.asciidoc new file mode 100644 index 000000000..1685ae995 --- /dev/null +++ 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 index 4fa2b7e24..f6bd73740 100644 --- 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 index c8e9c36fb..a0b012408 100644 --- 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 index de0785de9..448a34e92 100644 --- a/docs/en/install-upgrade/upgrading-stack-cloud.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack-cloud.asciidoc @@ -1,22 +1,19 @@ [[upgrade-elastic-stack-for-elastic-cloud]] -=== Upgrade on Elastic Cloud +=== Upgrade on {ecloud} Hosted -Once you are <>, -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 <>, +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. @@ -24,7 +21,7 @@ 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] \ No newline at end of file diff --git a/docs/en/install-upgrade/upgrading-stack-on-prem.asciidoc b/docs/en/install-upgrade/upgrading-stack-on-prem.asciidoc index 158952e4b..e2bc23631 100644 --- a/docs/en/install-upgrade/upgrading-stack-on-prem.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack-on-prem.asciidoc @@ -1,5 +1,5 @@ [[upgrading-elastic-stack-on-prem]] -=== Upgrade Elastic on-prem +== Upgrade Elastic on self-managed infrastructure Once you are <>, you will need to upgrade each of your Elastic components individually. @@ -8,12 +8,14 @@ you will need to upgrade each of your Elastic components individually. jobs can continue to run during a rolling upgrade, it increases the overhead on the cluster during the upgrade process. -. Upgrade the components of your Elastic Stack in the following order: +. Upgrade the components of your {stack} in the following order: ++ -.. {es} Hadoop: {hadoop-ref}/install.html[install instructions] +//.. {es} Hadoop: {hadoop-ref}/install.html[install instructions] .. {es}: <> -.. Kibana: <> -.. 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] \ No newline at end of file +.. {kib}: <> +//.. 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] \ No newline at end of file diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 4219c92ac..7c6803b02 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -1,69 +1,93 @@ [[upgrading-elastic-stack]] -== Upgrade to Elastic {version} += Upgrade to Elastic {version} -Before you upgrade to {version}, it's important to take some preparation steps. -ifeval::["{version}"!="8.0.0"] -These steps vary based on your current version: +Upgrading to the latest version provides you access to Elastic latest features, enhancements, performance improvements, and bug fixes, many of which enable you to save your organization money, respond faster to potential threats, and improve the tools you use to investigate and analyze your data. As new versions are released, older versions reach their end of life at a regular cadence, so it’s important to ensure that your deployment is fully maintained and supported. For more information, refer to Elastic’s https://www.elastic.co/support/eol[Product End of Life Dates]. -* <> -* <> -endif::[] +[discrete] +[[plan-upgrade]] +== Plan your upgrade -IMPORTANT: Upgrading from a release candidate build, such as 8.0.0-rc1 or -8.0.0-rc2, is not supported. Pre-releases should only be used for testing in a -temporary environment. +Before you upgrade, there are a number of things that you need to plan for before performing the actual upgrade, so create a test plan. Consider the following recommendations: + +* Plan for an appropriate amount of time to complete the upgrade. Depending on your configuration and the size of your cluster, the process can take up a few weeks or or more to complete. + +* Consider opening a https://support.elastic.co/case[support case] with Elastic to alert our Elastic Support team of your system change. If you need additional assistance, https://www.elastic.co/consulting[Elastic Consulting Services] provides the technical expertise and step-by-step approach for upgrading your Elastic deployment. + +* Schedule a system maintenance window within your organization. + +**Check system requirements** + +Ensure the version you’re upgrading to for Elasticsearch, Kibana, and any ingest components supports your current operating system. Refer to the Product and Operating System https://www.elastic.co/support/matrix#matrix_os[support matrix]. + +**JVM and FIPS compliance** + +By default, {es} includes a bundled Java Virtual Machine (JVM) supported by Elastic. While we strongly recommend using the bundled JVM in all installations of Elasticsearch, if you choose to use your own JVM, ensure it’s compatible by reviewing the Product and JVM https://www.elastic.co/support/matrix#matrix_jvm[support matrix]. {es} 9.0+ requires Java 21 or later. + +If you’re running {es} in FIPS 140-2 mode, {es} 9.0+ has been tested with https://www.bouncycastle.org/java.html[Bouncy Castle]'s FIPS implementation and is the recommended Java security provider when running Elasticsearch. + +*Conduct a component inventory* + +It is very important to map all the components that are being used on the {stack}. When you upgrade your deployment, you may also need to upgrade all the other components. You should record if each component is used, and if it is, you should record its current version. While this is not a comprehensive list, here are some components you should check: + +* {es} +* {es} Hadoop +* {es} Plugins +* {es} clients +* {kib} +* {ls} +* {ls} plugins +* {beats} +* {beats} modules +* {apm-agent}s +* APM server +* {agent} +* {fleet} +* Enterprise Search server +* Security +* Browsers +* External services (Kafka, etc.) + +TIP: When you do your inventory, you can {ref}/enable-audit-logging.html[enable audit logging] to evaluate resources that are accessing your deployment. -ifeval::["{version}"!="8.0.0"] [discrete] -[[prepare-to-upgrade-8x]] -=== Prepare to upgrade from an earlier 8.x version +[[choose-upgrade-path]] +== Choose your upgrade path -. Review the breaking changes for each product you use and make the necessary -changes so your code is compatible with {version}: -+ --- -include::breaking.asciidoc[tag=breaking-changes-links] +The procedures you follow to upgrade depend on your infrastructure and deployment method. You’ve installed Elastic components using either Elastic-managed infrastructure or self-managed infrastructure. -include::breaking.asciidoc[tag=breaking-changes-admon] --- +Elastic-managed infrastructure includes {ecloud} – the umbrella term for {ecloud} Hosted (ECH) and {serverless-full}. {serverless-full} (“Serverless”) is the fully managed cloud offering and has three products: {es-serverless}, {obs-serverless}, and {sec-serverless}. All serverless products are built on top of the Search AI Lake. Customers receive the latest features automatically when updates are published. -include::upgrading-stack.asciidoc[tag=generic-upgrade-steps] -endif::[] +{ecloud} Hosted is Elastic’s cloud offering for managing {stack} deployments, built on top of {es}. A single click in the {ecloud} console can upgrade a deployment to a newer version. -//// -// List of upgrade steps used in both 8.x and 7.x -// tag::generic-upgrade-steps[] -. If you use any {es} plugins, make sure there is a version of each plugin that is -compatible with {es} version {version}. +Self-managed infrastructure — either on-prem or on public cloud, includes: -. Test the upgrade in an isolated environment before upgrading your production -cluster. +* {stack} +* {ece} (ECE) +* {eck} (ECK) -. Make sure you have a current snapshot before you start the upgrade. -+ -IMPORTANT: You cannot downgrade {es} nodes after upgrading. -If you cannot complete the upgrade process, -you will need to restore from the snapshot. +For ECE and ECK, you need to ensure the orchestrator is running a compatible version with the {stack} version you’re upgrading to. If not, you need to <> your orchestrator before you can upgrade your cluster. -. If you use a separate {ref}/monitoring-production.html[monitoring cluster], you should upgrade the monitoring cluster before the production cluster. In general, the monitoring cluster and the clusters being monitored should be running the same version of the stack. A monitoring cluster cannot monitor production clusters running newer versions of the stack. If necessary, the monitoring cluster can monitor production clusters running the latest release of the previous major version. -// end::generic-upgrade-steps[] -//// +If you’re running the {stack} on your own self-managed infrastructure, you’ll need to upgrade each component individually. [discrete] -[[prepare-to-upgrade]] -=== Prepare to upgrade from 7.x +[[prepare-upgrade-9.0]] +== Prepare to upgrade -To upgrade to {version} from 7.16 or earlier, **you must first upgrade to {prev-major-last}**. -This enables you to use the **Upgrade Assistant** to identify and resolve issues, -reindex indices created before 7.0, and then perform a rolling upgrade. +Before you upgrade to {version}, it's important to take some preparation steps. Unless noted, these following recommendations are best practices regardless of deployment method. + +IMPORTANT: Upgrading from a release candidate build, such as 9.0.0-rc1 or 9.0.0-rc2, is not supported. Pre-releases should only be used for testing in a temporary environment. + +To upgrade to {version} from 8.17 or earlier, **you must first upgrade to the latest patch version of 8.18**. This enables you to use the **Upgrade Assistant** to identify and resolve issues, +reindex indices created before 8.0, and then perform a rolling upgrade. + +*Upgrading to 8.18 before upgrading to {version} is required +even if you opt to do a full-cluster restart of your {es} cluster.* -**Upgrading to {prev-major-last} before upgrading to {version} is required -even if you opt to do a full-cluster restart of your {es} cluster.** Alternatively, you can create a new {version} deployment and reindex from remote. -For more information, see <>. +For more information, refer to <>. -{beats} and {ls} {prev-major-last} are compatible with {es} {version} +{beats} and {ls} 8.17 are compatible with {es} {version} to give you flexibility in scheduling the upgrade. .Remote cluster compatibility @@ -78,26 +102,20 @@ For more information, see {ref}/xpack-ccr.html[Cross cluster replication] for ve You can view your remote clusters from **Stack Management > Remote Clusters**. ==== -. Use the {kibana-ref-all}/{prev-major-last}/upgrade-assistant.html[Upgrade Assistant] -to prepare for your upgrade from {prev-major-last} to {version}. -The **Upgrade Assistant** identifies deprecated settings and guides -you through resolving issues and reindexing indices created before 7.0. -Make sure you have a current snapshot before making configuration changes -or reindexing. -+ -**You must resolve all critical issues before proceeding with the upgrade.** +. Once you've upgraded to 8.18, use the {kibana-ref}/upgrade-assistant.html[*Upgrade Assistant*] to prepare for your upgrade from 8.18 to {version}. The Upgrade Assistant identifies deprecated settings and guides you through resolving issues and reindexing indices created before 8.0. {es} fully supports indices created in the current or previous major version. Older indices are partly supported as read-only archives with limited capabilities. +//For example, {es} {version} fully supports indices, data streams, and searchable snapshots created in {es}8.x, but those created in {es} 7.x would be read-only and indices Elasticsearch 6.x or older would not be compatible with Elasticsearch 9.x.// -. Review the deprecation logs from the **Upgrade Assistant** to -determine if your applications are using features that are not supported -or behave differently in 8.x. -See the <> for more information -about changes in {version} that could affect your application. +. Ensure you have a current {ref}/snapshots-take-snapshot.html[snapshot] before making configuration changes or reindexing. +*You must resolve all critical issues before proceeding with the upgrade.* If you make any additional changes, take a new snapshot to back up your data. + -IMPORTANT: Make sure you check the breaking changes for each minor 8.x release -up to {version}. +NOTE: If you’re upgrading on {ecloud} Hosted, to keep your data safe during the upgrade process, a snapshot is taken automatically before any changes are made to your cluster. If you’re upgrading on {ece}, you need to {ece-ref}/ece-manage-repositories.html[configure a snapshot repository] to enable snapshots. + +. Ensure you carefully review the deprecation logs from the Upgrade Assistant to determine if your applications are using features that are not supported or behave differently in {version}. -. Make the recommended changes to ensure that your applications -continue to operate as expected after the upgrade. +. Major version upgrades can include breaking changes that require you to take additional steps to ensure that your applications behave as expected after the upgrade. Review all {version} <> for each product you use to view more information about changes that could affect your application. Ensure you test against the new version before upgrading existing deployments. ++ +IMPORTANT: Ensure you check the breaking changes for each minor 8.x release up to {version}. +. Make the recommended changes to ensure that your clients continue to operate as expected after the upgrade. + NOTE: As a temporary solution, you can submit requests to {major-version} using the {prev-major-version} syntax with the REST API compatibility mode. @@ -106,5 +124,60 @@ it does not guarantee the same behavior. REST API compatibility should be a bridge to smooth out the upgrade process, not a long term strategy. For more information, see {ref}/rest-api-compatibility.html[REST API compatibility]. +. If you use any {es} plugins, ensure there is a version of each plugin that is compatible with {version}. +. We recommend creating a 9.0 test deployment and testing the upgrade in an isolated environment before upgrading your production deployment. Ensure that both your test and production environments have the same settings. ++ +IMPORTANT: You cannot downgrade {es} nodes after upgrading. If you cannot complete the upgrade process, you will need to {ref}/snapshots-restore-snapshot.html[restore from the snapshot]. ++ +. If you use a separate {ref}/monitoring-production.html[monitoring cluster], you should upgrade the monitoring cluster before the production cluster. In general, the monitoring cluster and the clusters being monitored should be running the same version of the stack. A monitoring cluster cannot monitor production clusters running newer versions of the stack. If necessary, the monitoring cluster can monitor production clusters running the latest release of the previous major version. + + + + + +//// +Before you upgrade to {version}, it's important to take some preparation steps. +ifeval::["{version}"!="8.0.0"] +These steps vary based on your current version: + +* <> +* <> +endif::[] + +IMPORTANT: Upgrading from a release candidate build, such as 8.0.0-rc1 or +8.0.0-rc2, is not supported. Pre-releases should only be used for testing in a +temporary environment. + +ifeval::["{version}"!="8.0.0"] +[discrete] +[[prepare-to-upgrade-8x]] +=== Prepare to upgrade from an earlier 8.x version + +. Review the breaking changes for each product you use and make the necessary +changes so your code is compatible with {version}: ++ +-- +include::breaking.asciidoc[tag=breaking-changes-links] + +include::breaking.asciidoc[tag=breaking-changes-admon] +-- include::upgrading-stack.asciidoc[tag=generic-upgrade-steps] +endif::[] + +//// +// List of upgrade steps used in both 8.x and 7.x +// tag::generic-upgrade-steps[] +//. If you use any {es} plugins, make sure there is a version of each plugin that is compatible with {es} version {version}. + +//. Test the upgrade in an isolated environment before upgrading your production cluster. + +//. Make sure you have a current snapshot before you start the upgrade. +//+ +//IMPORTANT: You cannot downgrade {es} nodes after upgrading. +//If you cannot complete the upgrade process, you will need to restore from the snapshot. + +//. If you use a separate {ref}/monitoring-production.html[monitoring cluster], you should upgrade the monitoring cluster before the production cluster. In general, the monitoring cluster and the clusters being monitored should be running the same version of the stack. A monitoring cluster cannot monitor production clusters running newer versions of the stack. If necessary, the monitoring cluster can monitor production clusters running the latest release of the previous major version. +// +// end::generic-upgrade-steps[] +