diff --git a/deploy-manage/upgrade/deployment-or-cluster.md b/deploy-manage/upgrade/deployment-or-cluster.md index a58c369010..61c3ba7f84 100644 --- a/deploy-manage/upgrade/deployment-or-cluster.md +++ b/deploy-manage/upgrade/deployment-or-cluster.md @@ -81,336 +81,3 @@ If you’re using self-managed infrastructure - either on-prem or public cloud - * [Upgrade the {{stack}}](/deploy-manage/upgrade/deployment-or-cluster/self-managed.md) * [Upgrade on {{ece}} (ECE)](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md) * [Upgrade on {{eck}} (ECK)](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md) - -## Prepare to upgrade [prepare-to-upgrade] - -Before you upgrade, review and complete the necessary preparation steps, which vary by version. - -:::{important} -Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. -::: - -## Prepare to upgrade from 8.x [prepare-upgrade-from-8.x] - -To upgrade from 8.17.0 or earlier to 9.0.0, you must first upgrade to the latest 8.18 patch release. This enables you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and perform a rolling upgrade. Upgrading to the latest 8.18 patch release is required even if you choose a full {{es}} cluster restart. If you're using 7.x and earlier, you may need to complete multiple upgrades or perform a full-cluster restart to reach the latest 8.18 patch release before upgrading to 9.0.0. - -Alternatively, you can create a 9.0 deployment and reindex from remote. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). - -:::{note} -For flexible upgrade scheduling, 8.18.0 {{beats}} and {{ls}} are compatible with 9.0.0 {{es}}. -By default, 8.x {{es}} clients are compatible with 9.0.0 and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.0.0 {{es}} server. -::: - -Review the best practices to upgrade your deployments. - -1. Run the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md), which identifies deprecated settings, helps resolve issues, and reindexes data streams and indices created in 8.0.0 and earlier. - - :::{note} - Depending on your setup, reindexing can change your indices, and you may need to update alerts, transforms, or other code targeting the old index. - ::: - -2. Before you change configurations or reindex, ensure you have a current [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md). - - :::{tip} - Tip: In 8.3.0 and later, snapshots are generally available as simple archives. Use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to search snapshots from 5.0.0 and later, without needing an old {{es}} cluster. This ensures that your {{es}} data remains accessible after upgrades, without requiring a reindex process. - ::: - - To successfully upgrade, resolve all critical issues. If you make additional changes, create a snapshot to back up your data. - -3. To identify if your applications use unsupported features or behave differently in 9.0.0, review the deprecation logs in the Upgrade Assistant. - -4. Major version upgrades can include breaking changes that require additional steps to ensure your applications function as expected. Review the breaking changes for each product you use to learn more about potential impacts on your application. Ensure you test with the new version before upgrading existing deployments. - -5. To ensure your clients continue to operate as expected after the upgrade, make the recommended changes. - - :::{note} - As a temporary solution, use the 8.x syntax to submit requests to 9.0.0 with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). - ::: - -6. If you use {{es}} plugins, ensure each plugin is compatible with the {{es}} version you're upgrading. - -7. Before upgrading your production deployment, we recommend creating a 9.0.0 test deployment and testing the upgrade in an isolated environment. Ensure the test and production environments use the same settings. - - :::{important} - After you upgrade, you cannot downgrade {{es}} nodes. If you can't complete the upgrade process, you must [restore from the snapshot](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md). - ::: - -8. If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. The monitoring cluster and the clusters being monitored should be running the same version of the {{stack}}. Monitoring clusters are unable to 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. - - :::{note} - If you use {{ccs}}, 9.0.0 and later can search only remote clusters running the previous minor version, the same version, or a newer minor version in the same major version. For more information, refer to [Cross-cluster search](../../solutions/search/cross-cluster-search.md). - - If you use {{ccr}}, a cluster that contains follower indices must run the same or newer (compatible) version as the remote cluster. For more information and to view the version compatibility matrix, refer to [Cross cluster replication](/deploy-manage/tools/cross-cluster-replication.md). To view your remote clusters in {{kib}}, go to **Stack Management > Remote Clusters**. - :::: - -9. To reduce overhead on the cluster during the upgrade, close {{ml}} jobs. Although {{ml}} jobs can run during a rolling upgrade, doing so increases the cluster workload. - -10. If you have `.ml-anomalies-*`anomaly detection result indices created in {{es}} 7.x, reindex, mark as read-only, or delete them before you upgrade to 9.0.0. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). - -11. If you have transform destination indices created in {{es}} 7.x, reset, reindex, or delete them before you upgrade to 9.0.0. For more information, refer to [Migrate transform destination indices](#transform-migration). - - -## Reindex to upgrade [reindex-to-upgrade] - -Optionally create a 9.0.0 deployment and reindex from remote: - -1. Provision an additional deployment running 9.0.0. -2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new index requests to both clusters. -3. Verify the new cluster performs as expected, fix any problems, and then permanently swap in the new cluster. -4. Delete the old deployment. On {ecloud}, you are billed only for the time the new deployment runs in parallel with your old deployment. Usage is billed on an hourly basis. - - -## Migrate anomaly detection results [anomaly-migration] - -Reindex, mark as read-only, or delete the `.ml-anomalies-*` {{anomaly-detect}} result indices created in {{es}} 7.x. - -**Reindex**: While {{anomaly-detect}} results are being reindexed, jobs continue to run and process new data. You are unable to delete an {{anomaly-job}} that stores results in the index until the reindexing is complete. - -**Mark indices as read-only**: This is useful for large indexes that contain the results of one or two {{anomaly-jobs}}. If you delete these jobs later, you cannot create a new job with the same name. - -**Delete**: Delete jobs that are no longer needed in the {{ml-app}} app in {{kib}}. The result index is deleted when all jobs that store results in it have been deleted. - -:::{dropdown} Which indices require attention? -To identify indices that require action, use the [Deprecation info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-migration-deprecations-1): - -``` -GET /.ml-anomalies-*/_migration/deprecations -``` - -The response contains the list of critical deprecation warnings in the `index_settings` section: - -```json - "index_settings": { - ".ml-anomalies-shared": [ - { - "level": "critical", - "message": "Index created before 8.0", - "url": "https://ela.st/es-deprecation-8-reindex", - "details": "This index was created with version 7.8.23 and is not compatible with 9.0. Reindex or remove the index before upgrading.", - "resolve_during_rolling_upgrade": false - } - ] - } -``` -::: - -:::{dropdown} Reindexing anomaly result indices -For an index with less than 10GB that contains results from multiple jobs that are still required, we recommend reindexing into a new format using UI. You can use the [Get index information API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-indices-1) to obtain the size of an index: - -``` -GET _cat/indices/.ml-anomalies-custom-example?v&h=index,store.size -``` - -The reindexing can be initiated in the {{kib}} Upgrade Assistant. - -If an index size is greater than 10 GB, it is recommended to use the Reindex API. Reindexing consists of the following steps: - -1. Set the original index to read-only. - -``` -PUT .ml-anomalies-custom-example/_block/read_only -``` - -2. Create a new index from the legacy index. - -``` -POST _create_from/.ml-anomalies-custom-example/.reindexed-v9-ml-anomalies-custom-example -``` - -3. Reindex documents. To accelerate the reindexing process, it is recommended that the number of replicas be set to `0` before the reindexing and then set back to the original number once it is completed. - - 1. Get the number of replicas. - - ``` - GET /.reindexed-v9-ml-anomalies-custom-example/_settings - ``` - - Note the number of replicas in the response. For example: - - ```json - { - ".reindexed-v9-ml-anomalies-custom-example": { - "settings": { - "index": { - "number_of_replicas": "1", - "number_of_shards": "1" - } - } - } - } - ``` - - 2. Set the number of replicas to `0.` - - ```json - PUT /.reindexed-v9-ml-anomalies-custom-example/_settings - { - "index": { - "number_of_replicas": 0 - } - } - ``` - - 3. Start the reindexing process in asynchronous mode. - - ```json - POST _reindex?wait_for_completion=false - { - "source": { - "index": ".ml-anomalies-custom-example" - }, - "dest": { - "index": ".reindexed-v9-ml-anomalies-custom-example" - } - } - ``` - - The response will contain a `task_id`. You can check when the task is completed using the following command: - - ``` - GET _tasks/ - ``` - - 4. Set the number of replicas to the original number when the reindexing is finished. - - ```json - PUT /.reindexed-v9-ml-anomalies-custom-example/_settings - { - "index": { - "number_of_replicas": "" - } - } - ``` - -4. Get the aliases the original index is pointing to. - -``` -GET .ml-anomalies-custom-example/_alias -``` - -The response may contain multiple aliases if the results of multiple jobs are stored in the same index. - -```json -{ - ".ml-anomalies-custom-example": { - "aliases": { - ".ml-anomalies-example1": { - "filter": { - "term": { - "job_id": { - "value": "example1" - } - } - }, - "is_hidden": true - }, - ".ml-anomalies-example2": { - "filter": { - "term": { - "job_id": { - "value": "example2" - } - } - }, - "is_hidden": true - } - } - } -} -``` - -5. Now you can reassign the aliases to the new index and delete the original index in one step. Note that when adding the new index to the aliases, you must use the same `filter` and `is_hidden` parameters as for the original index. - -```json -POST _aliases -{ - "actions": [ - { - "add": { - "index": ".reindexed-v9-ml-anomalies-custom-example", - "alias": ".ml-anomalies-example1", - "filter": { - "term": { - "job_id": { - "value": "example1" - } - } - }, - "is_hidden": true - } - }, - { - "add": { - "index": ".reindexed-v9-ml-anomalies-custom-example", - "alias": ".ml-anomalies-example2", - "filter": { - "term": { - "job_id": { - "value": "example2" - } - } - }, - "is_hidden": true - } - }, - { - "remove": { - "index": ".ml-anomalies-custom-example", - "aliases": ".ml-anomalies-*" - } - }, - { - "remove_index": { - "index": ".ml-anomalies-custom-example" - } - }, - { - "add": { - "index": ".reindexed-v9-ml-anomalies-custom-example", - "alias": ".ml-anomalies-custom-example", - "is_hidden": true - } - } - ] -} -``` -::: - - -:::{dropdown} Marking anomaly result indices as read-only -Legacy indices created in {{es}} 7.x can be made read-only and supported in {{es}} 9.x. Making an index with a large amount of historical results read-only allows for a quick migration to the next major release, since you don’t have to wait for the data to be reindexed into the new format. However, it has the limitation that even after deleting an {{anomaly-job}}, the historical results associated with this job are not completely deleted. Therefore, the system will prevent you from creating a new job with the same name. - -To set the index as read-only, add the write block to the index: - -``` -PUT .ml-anomalies-custom-example/_block/write -``` - -Indices created in {{es}} 7.x that have a write block will not raise a critical deprecation warning. -::: - -:::{dropdown} Deleting anomaly result indices -If an index contains results of the jobs that are no longer required. To list all jobs that stored results in an index, use the terms aggregation: - -```json -GET .ml-anomalies-custom-example/_search -{ - "size": 0, - "aggs": { - "job_ids": { - "terms": { - "field": "job_id", - "size": 100 - } - } - } -} -``` - -The jobs can be deleted in the UI. After the last job is deleted, the index will be deleted as well. -::: - -## Migrate transform destination indices [transform-migration] -======= - - diff --git a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md index 72ce8208fa..204561a0f1 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md +++ b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md @@ -8,7 +8,7 @@ applies_to: An {{es}} cluster can be upgraded one node at a time so upgrading does not interrupt service. Running multiple versions of {{es}} in the same cluster beyond the duration of an upgrade is not supported, as shards cannot be replicated from upgraded nodes to nodes running the older version. -Before you start, [take the upgrade preparation steps](../../../deploy-manage/upgrade/prepare-to-upgrade.md). When performing a [rolling upgrade](#rolling-upgrades): +Before you start, [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md). When performing a [rolling upgrade](#rolling-upgrades): 1. Upgrade the data nodes first, tier-by-tier, starting with the frozen tier, then the cold tier, then the warm tier, then the hot tier, and finally any other data nodes which are not in a tier. Complete the upgrade for all nodes in each data tier before moving to the next. This ensures {{ilm-init}} can continue to move data through the tiers during the upgrade. You can get the list of nodes in a specific tier with a `GET /_nodes` request, for example: `GET /_nodes/data_frozen:true/_none`. 2. Upgrade all remaining nodes that are neither master-eligible nor data nodes. This includes dedicated ML nodes, dedicated ingest nodes, and dedicated coordinating nodes. diff --git a/deploy-manage/upgrade/deployment-or-cluster/kibana.md b/deploy-manage/upgrade/deployment-or-cluster/kibana.md index a5c6342959..5093132f9b 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/kibana.md +++ b/deploy-manage/upgrade/deployment-or-cluster/kibana.md @@ -26,7 +26,7 @@ For large deployments with more than 10 {{kib}} instances, and more than 10,000 ## Preparing for upgrading [preventing-migration-failures] -Before you start, ensure you [take the upgrade preparation steps](../prepare-to-upgrade.md). Then, take these extra steps to ensure you are ready to upgrade. +Before you start, ensure you [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md). Then, take these extra steps to ensure you are ready to upgrade. ### Ensure your {{es}} cluster is healthy [_ensure_your_es_cluster_is_healthy] diff --git a/deploy-manage/upgrade/deployment-or-cluster/self-managed.md b/deploy-manage/upgrade/deployment-or-cluster/self-managed.md index f581743dcf..692482529b 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/self-managed.md +++ b/deploy-manage/upgrade/deployment-or-cluster/self-managed.md @@ -1,6 +1,6 @@ # Upgrade Elastic on a self-managed cluster -If you've installed the {{stack}} on your own self-managed infrastructure, once you're [prepared to upgrade](/deploy-manage/upgrade/deployment-or-cluster.md#prepare-to-upgrade), you'll need to upgrade each of your Elastic components individually. +If you've installed the {{stack}} on your own self-managed infrastructure, once you're [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), you'll need to upgrade each of your Elastic components individually. It's important that you upgrade your components in this order: * [{{es}}](/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index bbfb065b08..c2d57acbb3 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -1 +1,84 @@ -# Plan your upgrade \ No newline at end of file +# Plan your upgrade + +There are a number of things 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 to a few weeks or more to complete. +* Consider opening a [support case](https://support.elastic.co/) with Elastic to alert our Elastic Support team of your system change. If you need additional assistance, [Elastic Consulting Services](https://www.elastic.co/consulting) 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 [check-system-requirements] + +Ensure the version you’re upgrading to for {{es}}, {{kib}}, and any ingest components supports your current operating system. Refer to the [Product and Operating System support matrix](https://www.elastic.co/support/matrix#matrix_os). + +### OpenJDK compatibility and FIPS compliance + +By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) within each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). {{es}} 9.0 requires Java 21 and supports Java 24. + +If you’re running {{es}} in FIPS 140-2 mode, {{es}} 9.0 has been tested with [Bouncy Castle's](https://www.bouncycastle.org/java.html) FIPS implementation and is the recommended Java security provider when running {{es}}. + +## 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 also may need to upgrade all the other components. You should record whether each component is used, and if it is, also record the current version. While not comprehensive, here’s a list of components you should check: + +* {{es}} +* {{es}} Hadoop +* {{es}} plugins +* {{es}} clients +* {{kib}} +* {{ls}} +* {{ls}} plugins +* {{beats}} +* {{beats}} modules +* {{apm-agent}} +* APM server +* {{agent}} +* {{fleet}} +* Security +* Browsers +* External services (Kafka, etc.) + +:::{tip} +When you do your inventory, you can [enable audit logging](/deploy-manage/security/logging-configuration/enabling-audit-logs.md) to evaluate resources accessing your deployment. +::: + +## Test your development environment + +We highly recommend testing and upgrading in your development environment before your production environment. Therefore, it is crucial to ensure that both your development and production environments have the same settings. Consider checking the following components beforehand: + +* Enrichment information +* Plugins +* Mapping +* Index lifecycle management (ILM) +* Snapshot lifecycle management (SLM) +* Index templates +* {{ml-cap}} jobs +* Inbound sample data +* Live data +* Performance +* Outbound integrations +* Dashboards +* Alerts +* Authentication + +## Choose your upgrade path [choose-upgrade-path] + +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. + +### Elastic-managed infrastructure + +Elastic-managed infrastructure includes {{ecloud}} – the umbrella term for {{ech}} (ECH) and {{serverless-full}}. {{serverless-full}} (“Serverless”) is a fully managed cloud offering with three products: {{es-serverless}}, {{obs-serverless}}, and {{sec-serverless}}. All serverless products are built on top of the Search AI Lake. Customers on serverless receive the latest features automatically when updates are published and do not need to choose an upgrade path. + +{{ech}} 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. + +### Self-managed infrastructure + +Self-managed infrastructure – either on-prem or on public cloud, includes: +* {{stack}} +* {{ece}} (ECE) +* {{eck}} (ECK) + +For ECE and ECK, ensure the operator is running a version compatible with the {{stack}} version you’re upgrading to. If not, you need to upgrade that before you can upgrade your cluster. + +If you’re running the {{stack}} on your own self-managed infrastructure, you must upgrade each component individually. + +% Refer to the diagram below for a visualization of the different deployment methods. \ No newline at end of file diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 27bf9733f5..bb90bce22c 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -1,86 +1,330 @@ -# Prepare to upgrade [upgrade-prep] +# Prepare to upgrade -There are a number of things you need to plan for before performing the actual upgrade, so create a test plan. Consider the following recommendations: +Before you upgrade, review and complete the necessary preparation steps, which vary by version. -* 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 to a few weeks or more to complete. -* Consider opening a [support case](https://support.elastic.co/) with Elastic to alert our Elastic Support team of your system change. If you need additional assistance, [Elastic Consulting Services](https://www.elastic.co/consulting) provides the technical expertise and step-by-step approach for upgrading your Elastic deployment. -* Schedule a system maintenance window within your organization. +:::{important} +Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. +::: + +## Prepare to upgrade from 8.x [prepare-upgrade-from-8.x] + +To upgrade from 8.17.0 or earlier to 9.0.0, you must first upgrade to the latest 8.18 patch release. This enables you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and perform a rolling upgrade. Upgrading to the latest 8.18 patch release is required even if you choose a full {{es}} cluster restart. If you're using 7.x and earlier, you may need to complete multiple upgrades or perform a full-cluster restart to reach the latest 8.18 patch release before upgrading to 9.0.0. + +Alternatively, you can create a 9.0 deployment and reindex from remote. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). + +:::{note} +For flexible upgrade scheduling, 8.18.0 {{beats}} and {{ls}} are compatible with 9.0.0 {{es}}. +By default, 8.x {{es}} clients are compatible with 9.0.0 and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.0.0 {{es}} server. +::: + +Review the best practices to upgrade your deployments. + +1. Run the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md), which identifies deprecated settings, helps resolve issues, and reindexes data streams and indices created in 8.0.0 and earlier. + + :::{note} + Depending on your setup, reindexing can change your indices, and you may need to update alerts, transforms, or other code targeting the old index. + ::: + +2. Before you change configurations or reindex, ensure you have a current [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md). + + :::{tip} + Tip: In 8.3.0 and later, snapshots are generally available as simple archives. Use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to search snapshots from 5.0.0 and later, without needing an old {{es}} cluster. This ensures that your {{es}} data remains accessible after upgrades, without requiring a reindex process. + ::: + + To successfully upgrade, resolve all critical issues. If you make additional changes, create a snapshot to back up your data. + +3. To identify if your applications use unsupported features or behave differently in 9.0.0, review the deprecation logs in the Upgrade Assistant. + +4. Major version upgrades can include breaking changes that require additional steps to ensure your applications function as expected. Review the breaking changes for each product you use to learn more about potential impacts on your application. Ensure you test with the new version before upgrading existing deployments. + +5. To ensure your clients continue to operate as expected after the upgrade, make the recommended changes. + + :::{note} + As a temporary solution, use the 8.x syntax to submit requests to 9.0.0 with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). + ::: + +6. If you use {{es}} plugins, ensure each plugin is compatible with the {{es}} version you're upgrading. + +7. Before upgrading your production deployment, we recommend creating a 9.0.0 test deployment and testing the upgrade in an isolated environment. Ensure the test and production environments use the same settings. + + :::{important} + After you upgrade, you cannot downgrade {{es}} nodes. If you can't complete the upgrade process, you must [restore from the snapshot](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md). + ::: + +8. If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. The monitoring cluster and the clusters being monitored should be running the same version of the {{stack}}. Monitoring clusters are unable to 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. + + :::{note} + If you use {{ccs}}, 9.0.0 and later can search only remote clusters running the previous minor version, the same version, or a newer minor version in the same major version. For more information, refer to [Cross-cluster search](../../solutions/search/cross-cluster-search.md). + + If you use {{ccr}}, a cluster that contains follower indices must run the same or newer (compatible) version as the remote cluster. For more information and to view the version compatibility matrix, refer to [Cross cluster replication](/deploy-manage/tools/cross-cluster-replication.md). To view your remote clusters in {{kib}}, go to **Stack Management > Remote Clusters**. + :::: + +9. To reduce overhead on the cluster during the upgrade, close {{ml}} jobs. Although {{ml}} jobs can run during a rolling upgrade, doing so increases the cluster workload. + +10. If you have `.ml-anomalies-*`anomaly detection result indices created in {{es}} 7.x, reindex, mark as read-only, or delete them before you upgrade to 9.0.0. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). + +11. If you have transform destination indices created in {{es}} 7.x, reset, reindex, or delete them before you upgrade to 9.0.0. For more information, refer to [Migrate transform destination indices](#transform-migration). + + +## Reindex to upgrade [reindex-to-upgrade] -## Check system requirements [check-system-requirements] +Optionally create a 9.0.0 deployment and reindex from remote: -Ensure the version you’re upgrading to for {{es}}, {{kib}}, and any ingest components supports your current operating system. Refer to the [Product and Operating System support matrix](https://www.elastic.co/support/matrix#matrix_os). +1. Provision an additional deployment running 9.0.0. +2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new index requests to both clusters. +3. Verify the new cluster performs as expected, fix any problems, and then permanently swap in the new cluster. +4. Delete the old deployment. On {ecloud}, you are billed only for the time the new deployment runs in parallel with your old deployment. Usage is billed on an hourly basis. -### OpenJDK compatibility and FIPS compliance -By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) within each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). {{es}} 9.0 requires Java 21 and supports Java 24. +## Migrate anomaly detection results [anomaly-migration] -If you’re running {{es}} in FIPS 140-2 mode, {{es}} 9.0 has been tested with [Bouncy Castle's](https://www.bouncycastle.org/java.html) FIPS implementation and is the recommended Java security provider when running {{es}}. +Reindex, mark as read-only, or delete the `.ml-anomalies-*` {{anomaly-detect}} result indices created in {{es}} 7.x. -## Conduct a component inventory +**Reindex**: While {{anomaly-detect}} results are being reindexed, jobs continue to run and process new data. You are unable to delete an {{anomaly-job}} that stores results in the index until the reindexing is complete. -It is very important to map all the components that are being used on the {{stack}}. When you upgrade your deployment, you also may need to upgrade all the other components. You should record whether each component is used, and if it is, also record the current version. While not comprehensive, here’s a list of components you should check: +**Mark indices as read-only**: This is useful for large indexes that contain the results of one or two {{anomaly-jobs}}. If you delete these jobs later, you cannot create a new job with the same name. -* {{es}} -* {{es}} Hadoop -* {{es}} plugins -* {{es}} clients -* {{kib}} -* {{ls}} -* {{ls}} plugins -* {{beats}} -* {{beats}} modules -* {{apm-agent}} -* APM server -* {{agent}} -* {{fleet}} -* Security -* Browsers -* External services (Kafka, etc.) +**Delete**: Delete jobs that are no longer needed in the {{ml-app}} app in {{kib}}. The result index is deleted when all jobs that store results in it have been deleted. -:::{tip} -When you do your inventory, you can [enable audit logging](/deploy-manage/security/logging-configuration/enabling-audit-logs.md) to evaluate resources accessing your deployment. +:::{dropdown} Which indices require attention? +To identify indices that require action, use the [Deprecation info API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-migration-deprecations-1): + +``` +GET /.ml-anomalies-*/_migration/deprecations +``` + +The response contains the list of critical deprecation warnings in the `index_settings` section: + +```json + "index_settings": { + ".ml-anomalies-shared": [ + { + "level": "critical", + "message": "Index created before 8.0", + "url": "https://ela.st/es-deprecation-8-reindex", + "details": "This index was created with version 7.8.23 and is not compatible with 9.0. Reindex or remove the index before upgrading.", + "resolve_during_rolling_upgrade": false + } + ] + } +``` ::: -## Test your development environment +:::{dropdown} Reindexing anomaly result indices +For an index with less than 10GB that contains results from multiple jobs that are still required, we recommend reindexing into a new format using UI. You can use the [Get index information API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-indices-1) to obtain the size of an index: + +``` +GET _cat/indices/.ml-anomalies-custom-example?v&h=index,store.size +``` + +The reindexing can be initiated in the {{kib}} Upgrade Assistant. + +If an index size is greater than 10 GB, it is recommended to use the Reindex API. Reindexing consists of the following steps: + +1. Set the original index to read-only. + +``` +PUT .ml-anomalies-custom-example/_block/read_only +``` + +2. Create a new index from the legacy index. + +``` +POST _create_from/.ml-anomalies-custom-example/.reindexed-v9-ml-anomalies-custom-example +``` + +3. Reindex documents. To accelerate the reindexing process, it is recommended that the number of replicas be set to `0` before the reindexing and then set back to the original number once it is completed. + + 1. Get the number of replicas. + + ``` + GET /.reindexed-v9-ml-anomalies-custom-example/_settings + ``` + + Note the number of replicas in the response. For example: -We highly recommend testing and upgrading in your development environment before your production environment. Therefore, it is crucial to ensure that both your development and production environments have the same settings. Consider checking the following components beforehand: + ```json + { + ".reindexed-v9-ml-anomalies-custom-example": { + "settings": { + "index": { + "number_of_replicas": "1", + "number_of_shards": "1" + } + } + } + } + ``` -* Enrichment information -* Plugins -* Mapping -* Index lifecycle management (ILM) -* Snapshot lifecycle management (SLM) -* Index templates -* {{ml-cap}} jobs -* Inbound sample data -* Live data -* Performance -* Outbound integrations -* Dashboards -* Alerts -* Authentication + 2. Set the number of replicas to `0.` -## Choose your upgrade path [choose-upgrade-path] + ```json + PUT /.reindexed-v9-ml-anomalies-custom-example/_settings + { + "index": { + "number_of_replicas": 0 + } + } + ``` -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. + 3. Start the reindexing process in asynchronous mode. -### Elastic-managed infrastructure + ```json + POST _reindex?wait_for_completion=false + { + "source": { + "index": ".ml-anomalies-custom-example" + }, + "dest": { + "index": ".reindexed-v9-ml-anomalies-custom-example" + } + } + ``` -Elastic-managed infrastructure includes {{ecloud}} – the umbrella term for {{ech}} (ECH) and {{serverless-full}}. {{serverless-full}} (“Serverless”) is a fully managed cloud offering with three products: {{es-serverless}}, {{obs-serverless}}, and {{sec-serverless}}. All serverless products are built on top of the Search AI Lake. Customers on serverless receive the latest features automatically when updates are published and do not need to choose an upgrade path. + The response will contain a `task_id`. You can check when the task is completed using the following command: -{{ech}} 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. + ``` + GET _tasks/ + ``` -### Self-managed infrastructure + 4. Set the number of replicas to the original number when the reindexing is finished. -Self-managed infrastructure – either on-prem or on public cloud, includes: -* {{stack}} -* {{ece}} (ECE) -* {{eck}} (ECK) + ```json + PUT /.reindexed-v9-ml-anomalies-custom-example/_settings + { + "index": { + "number_of_replicas": "" + } + } + ``` -For ECE and ECK, ensure the operator is running a version compatible with the {{stack}} version you’re upgrading to. If not, you need to upgrade that before you can upgrade your cluster. +4. Get the aliases the original index is pointing to. -If you’re running the {{stack}} on your own self-managed infrastructure, you must upgrade each component individually. +``` +GET .ml-anomalies-custom-example/_alias +``` -% Refer to the diagram below for a visualization of the different deployment methods. +The response may contain multiple aliases if the results of multiple jobs are stored in the same index. +```json +{ + ".ml-anomalies-custom-example": { + "aliases": { + ".ml-anomalies-example1": { + "filter": { + "term": { + "job_id": { + "value": "example1" + } + } + }, + "is_hidden": true + }, + ".ml-anomalies-example2": { + "filter": { + "term": { + "job_id": { + "value": "example2" + } + } + }, + "is_hidden": true + } + } + } +} +``` + +5. Now you can reassign the aliases to the new index and delete the original index in one step. Note that when adding the new index to the aliases, you must use the same `filter` and `is_hidden` parameters as for the original index. + +```json +POST _aliases +{ + "actions": [ + { + "add": { + "index": ".reindexed-v9-ml-anomalies-custom-example", + "alias": ".ml-anomalies-example1", + "filter": { + "term": { + "job_id": { + "value": "example1" + } + } + }, + "is_hidden": true + } + }, + { + "add": { + "index": ".reindexed-v9-ml-anomalies-custom-example", + "alias": ".ml-anomalies-example2", + "filter": { + "term": { + "job_id": { + "value": "example2" + } + } + }, + "is_hidden": true + } + }, + { + "remove": { + "index": ".ml-anomalies-custom-example", + "aliases": ".ml-anomalies-*" + } + }, + { + "remove_index": { + "index": ".ml-anomalies-custom-example" + } + }, + { + "add": { + "index": ".reindexed-v9-ml-anomalies-custom-example", + "alias": ".ml-anomalies-custom-example", + "is_hidden": true + } + } + ] +} +``` +::: + + +:::{dropdown} Marking anomaly result indices as read-only +Legacy indices created in {{es}} 7.x can be made read-only and supported in {{es}} 9.x. Making an index with a large amount of historical results read-only allows for a quick migration to the next major release, since you don’t have to wait for the data to be reindexed into the new format. However, it has the limitation that even after deleting an {{anomaly-job}}, the historical results associated with this job are not completely deleted. Therefore, the system will prevent you from creating a new job with the same name. + +To set the index as read-only, add the write block to the index: + +``` +PUT .ml-anomalies-custom-example/_block/write +``` + +Indices created in {{es}} 7.x that have a write block will not raise a critical deprecation warning. +::: + +:::{dropdown} Deleting anomaly result indices +If an index contains results of the jobs that are no longer required. To list all jobs that stored results in an index, use the terms aggregation: + +```json +GET .ml-anomalies-custom-example/_search +{ + "size": 0, + "aggs": { + "job_ids": { + "terms": { + "field": "job_id", + "size": 100 + } + } + } +} +``` + +The jobs can be deleted in the UI. After the last job is deleted, the index will be deleted as well. +::: +## Migrate transform destination indices [transform-migration] +======= \ No newline at end of file