From d8fffabad5d6241beb2a9c89765f2bd1868d1cb0 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic Date: Thu, 21 Nov 2024 13:01:47 +0000 Subject: [PATCH] Backport updated upgrade guides to 8.8 --- docs/upgrade/upgrade-7.17-8.x.asciidoc | 158 +++++++++++++++++++++++ docs/upgrade/upgrade-security.asciidoc | 172 ++++++++++--------------- 2 files changed, 229 insertions(+), 101 deletions(-) create mode 100644 docs/upgrade/upgrade-7.17-8.x.asciidoc diff --git a/docs/upgrade/upgrade-7.17-8.x.asciidoc b/docs/upgrade/upgrade-7.17-8.x.asciidoc new file mode 100644 index 0000000000..ef8bc58a0e --- /dev/null +++ b/docs/upgrade/upgrade-7.17-8.x.asciidoc @@ -0,0 +1,158 @@ +[[upgrade-7.17-8x]] +== Upgrade from 7.17 to an 8.x version + +[float] +=== Why it's important to upgrade + +Upgrading provides you access to {elastic-sec}'s latest features, enhancements, 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. For more benefits, check out our blog, https://www.elastic.co/blog/top-5-reasons-to-upgrade-elastic-security[Top 5 reasons to upgrade Elastic Security]. Also, it's important to ensure that your deployment is fully maintained and supported. For more information, refer to https://www.elastic.co/support/eol[Elastic's Product End of Life Dates]. + +[float] +=== Plan for your upgrade + +Before upgrading to {elastic-sec} 8.x, 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 week to complete. + +* Open a https://support.elastic.co[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. + +* Choose a version to upgrade to. We recommend the latest minor and patch version. Be sure to upgrade your development or non-production deployment to the same version as your production deployment. + +* Ensure that you have {kibana-ref}/xpack-monitoring.html[stack monitoring] enabled in {kib}. Take note of your current index and search rate. + +* Review your selected version's features, Elastic connectors, integrations, and detection rules to determine if you can replace any customized content with out-of-the-box functionality. This can help reduce your workload and the complexity of your upgrade. + +* If your organization sends alerts (formerly known as signals) to an external SOAR (security orchestration, automation, and response) platform, you may need to change your workflows to accommodate the new <> used in 8.x. + +* Review release notes, deprecations, and breaking changes for {security-guide}/release-notes.html[{elastic-sec}], {ref}/es-release-notes.html[{es}], {kibana-ref}/release-notes.html[{kib}], and, if applicable, {fleet-guide}/release-notes.html[{fleet} and {agent}], {beats-ref}/release-notes.html[{beats}], and {logstash-ref}/releasenotes.html[{ls}]. Identify any issues that might affect your deployment. Work with your Elastic team on any questions you may have. Start with breaking changes for your solution and platform components, such as {es} and {kib}. + +* Schedule a system maintenance window within your organization. + +[float] +=== Pre-upgrade steps + +To prepare for the upgrade process, follow these steps before you start: + +. Do a software version inventory across your entire Elastic deployment, including {es}, {kib}, {agent}, {beats}, and {ls}. + +. If you're running any versions earlier than 7.17, you must first upgrade them all to the latest 7.17.x patch release before upgrading to 8.x. This enables you to use the Upgrade Assistant to upgrade to 8.x. ++ +NOTE: If you're managing your deployments using {ece-ref}/ece-upgrade.html[{ece}] (ECE) or {eck-ref}/k8s-upgrading-eck.html[{eck}] (ECK), you may need to upgrade the system clusters first. + +. Note that alerts in 8.x are written using the `kibana_system` user instead of the `current user`, so any user-modified ingest pipelines configured against the alert index (this is uncommon) will use the `kibana_system` user privileges, which may break your ingest pipeline. If you encounter this issue, please do not update your ingest pipeline. Instead, contact your Elastic Support rep for assistance. + +. Run the {kibana-ref}/upgrade-assistant.html[Upgrade Assistant]. Take note of any critical error messages, then work with your Elastic Support rep to resolve them. ++ +.Requirements +[sidebar] +-- +To run the Upgrade Assistant, you must have the `superuser` role on the cluster. +-- + +. If you're not using {ref}/snapshots-take-snapshot.html#automate-snapshots-slm[{slm} (SLM)], you must set up and configure a policy, then run the policy to create at least one {ref}/snapshot-restore.html[snapshot] -- a backup of indices taken from a running cluster. If you need to roll back during the upgrade process, use a recent snapshot to avoid data loss. Snapshots are {ref}/snapshot-restore.html#how-snapshots-work[incremental] -- depending on the cluster size and the input/output rate, the initial snapshot may take several hours to complete. If you're using SLM, {ref}/snapshots-take-snapshot.html#check-slm-history[check the SLM history] to ensure that snapshots are completing successfully. + +[float] +=== Perform an 8.x upgrade on a deployment + +IMPORTANT: We strongly recommend performing the following steps on a non-production deployment first to address any potential issues before upgrading your production deployments. If you're using a cross-cluster search environment, upgrade your remote deployments first. + +. If you haven't already done so, back up your cluster data to a {ref}/snapshots-take-snapshot.html[snapshot]. + +. We recommend you <> in case there are issues with the detection engine after the upgrade. + +. Upgrade {es}. +** If you're using {ecloud}, we recommend upgrades with no downtime. Refer to {cloud}/ec-upgrade-deployment.html[these instructions]. +** If you're using {ece} (ECE), refer to {ece-ref}/ece-upgrade-deployment.html[these instructions]. +** If you're using {eck} (ECK), refer to {eck-ref}/k8s-upgrading-stack.html[these instructions]. +** If you're upgrading a self-orchestrated deployment, refer to {stack-ref}/upgrading-elasticsearch.html[these instructions] and upgrade the data nodes tier by tier in this order: +... Frozen tier +... Cold tier +... Warm tier +... Hot tier +... Any other nodes not in a tier +... All remaining nodes that are neither master-eligible nor data nodes +... Master-eligible nodes + +. Upgrade {kib}. Refer to {stack-ref}/upgrading-kibana.html[these instructions]. ++ +NOTE: If you're using Elastic Cloud Hosted or {ece}, this is already included in the {es} upgrade. + +. Validate that {es} and {kib} are operating as expected by completing the following checks: +.. For {es}: +... Check the status of your clusters and ensure that they're green by running a `GET _cat/health` API request. For more information, refer to the {ref}/cat-health.html[cat health API documentation]. +... Ensure that the index and search rate are close to what they were before upgrading. To view these, find **Stack Monitoring** in the navigation menu or by using the {kibana-ref}/introduction.html#kibana-navigation-search[global search field], then select **{es}** → **Overview**. ++ +TIP: You can also check the index document count using the {ref}/cat-indices.html[cat index API]. +... Verify that {slm} SLM is taking snapshots by {ref}/snapshots-take-snapshot.html#check-slm-history[checking the SLM history]. +... If you use {ml}, ensure that it is up and running. +.. For {kib}: +... Ensure that you and your users can successfully log in to {kib} and access desired pages. +... Check {kibana-ref}/discover.html[Discover] and verify that the index patterns you typically use are available. +... Verify that your commonly used {kibana-ref}/dashboard.html[dashboards] are available and working properly. +... If you use any Watcher-based {kib} scheduled {kibana-ref}/reporting-getting-started.html[reporting], ensure that it's working properly. + +. Upgrade your ingest components (such as {ls}, {fleet} and {agent}, {beats}, etc.). For details, refer to the {stack-ref}/upgrading-elastic-stack.html[Elastic Stack upgrade docs]. + +. Validate that ingest is operating correctly. +.. Open *Discover*, go through data views for each of your expected ingest data streams, and ensure that data is being ingested in the expected format and volume. + +. Validate that {elastic-sec} is operating correctly. +.. On the **Rules** page, re-enable your desired SIEM detection rules (**Rule Management** tab), and ensure that enabled rules are running without errors or warnings (**Rule Monitoring** tab). +.. Ensure that any SOAR workflows that consume alerts are working. +.. Verify that any custom dashboards your team has created are working properly, especially if they operate on alert documents. + +. If you performed these steps on a non-production deployment, repeat these same steps on your production environment. If you're using a cross-cluster search environment and performed these steps on your remote clusters, repeat these same steps on your other deployments. +. Confirm with your appropriate stakeholders that the upgrade process has been successful. + +[float] +=== Post-upgrade steps + +The following sections describe procedures to complete after upgrading {elastic-sec} to 8.x. + +[float] +[[reenable-rules-upgrade]] +==== Re-enable disabled rules + +Any active rules when you upgrade from 7.17 to 8.0.1 or newer are automatically disabled, and a tag named `auto_disabled_8.0` is added to those rules for tracking purposes. Once the upgrade is complete, you can filter rules by the new tag, then use bulk actions to re-enable them: + +. Find **Detection rules (SIEM)** in the navigation menu or by using the {kibana-ref}/introduction.html#kibana-navigation-search[global search field]. +. From the *Tags* dropdown, search for `auto_disabled_8.0`. +. Click *Select all _x_ rules*, or individually select the rules you want to re-enable. +. Click *Bulk actions -> Enable* to re-enable the rules. + +Alternatively, you can use the <> API to re-enable rules. + +[float] +[[fda-upgrade]] +==== Full Disk Access (FDA) approval for {elastic-endpoint} + +When you manually install {elastic-endpoint}, you must approve a system extension, kernel extension, and enable Full Disk Access (FDA). There is a new FDA requirement in 8.x. Refer to <> to review the required permissions. + +[float] +[[data-views-upgrade]] +==== Requirements to display Data views in the {security-app} + +To make the *Data view* option appear in an environment with legacy alerts, a user with elevated role privileges must visit the {security-app}, open a page that displays alert data (at least one alert must be present), and then refresh the page. The user's role privileges must allow them to enable the detections feature in a {kib} space. For more information, refer to <>. + +[float] +[[alert-schema-upgrade]] +==== New alert schema + +The system index for detection alerts has been renamed from `.siem-signals-` to `.alerts-security.alerts-` and is now a hidden index. Therefore, the schema used for alert documents in {elastic-sec} has changed. Users that access documents in the `.siem-signals` indices using the {elastic-sec} API must modify their API queries and scripts to operate properly on the new 8.x alert documents. Refer to <> and review the new <>. + +[float] +[[preview-upgrade]] +==== New privileges required to view alerts and preview rules + +* To view alerts, users need `manage`, `write`, `read`, and `view_index_metadata` privileges for two new indices, `.alerts-security.alerts` and `.internal.alerts-security.alerts`. Existing users who are upgrading to 8.x can retain their privileges to the `.siem-signals` index. + +* To <>, users need `read` access to the new `.preview.alerts-security.alerts` index. Refer to <> for more information. + +[float] +[[im-rules-upgrade]] +==== Updates to indicator match rules + +Changes to the indicator match rule type's <> might require you to update existing rules or create new ones after upgrading to 8.x. Be mindful of the following: + +* If an indicator match rule's default threat indicator path was not defined before the upgrade, it will default to `threatintel.indicator` after the upgrade. This allows the rule to continue using indicator data ingested by {filebeat} version 7.x. If a custom value was defined before the upgrade, the value will not change. +* If an existing indicator match rule was configured to use threat indicator indices generated from {filebeat} version 7.x, updating the default threat indicator path to `threat.indicator` after you upgrade to {stack} version 8.x and {agent} or {filebeat} version 8.x configures the rule to use threat indicator indices generated by those later versions. +* You must create separate rules to query threat intelligence indices created by {filebeat} version 7.x and version 8.x because each version requires a different default threat indicator path value. Review the recommendations for <>. \ No newline at end of file diff --git a/docs/upgrade/upgrade-security.asciidoc b/docs/upgrade/upgrade-security.asciidoc index a4cd51b189..89985c19ce 100644 --- a/docs/upgrade/upgrade-security.asciidoc +++ b/docs/upgrade/upgrade-security.asciidoc @@ -1,11 +1,10 @@ -[chapter] [[upgrade-intro]] = Upgrade {elastic-sec} to {version} -Before you upgrade {elastic-sec}, take the necessary <>, which will vary depending on what version you are upgrading to: +Before you upgrade {elastic-sec}, take the necessary preparation steps, which will vary depending on what version you are upgrading to: -* <> +* <> * <> * <> @@ -22,7 +21,7 @@ state. By default, snapshots include the `kibana` feature state. ==== [float] -=== Upgrading multiple {kib} instances +== Upgrading multiple {kib} instances When upgrading several {kib} instances connected to the same {es} cluster, ensure that all outdated instances are shut down before starting the upgrade. @@ -38,137 +37,106 @@ but upgrading from a pre-release to the Generally Available version is unsupport You should use pre-release versions only for testing in a temporary environment. [float] -=== Support for Elastic prebuilt detection rule automatic updates -<> are supported for the current {elastic-sec} version and the latest three previous minor releases. For example, if you’re upgrading to {elastic-sec} 8.10, you’ll be able to use the Rules UI to update your prebuilt rules until {elastic-sec} 8.14 is released. After that point, you can still manually download and install updated prebuilt rules, but you must upgrade to the latest {elastic-sec} version to receive automatic updates. - -[float] -[[preventing-migration-failures]] -=== Preparing for migration - -Take these extra steps to ensure you are ready for migration. - -[float] -==== Ensure your {es} cluster is healthy -Problems with your {es} cluster can prevent {kib} upgrades from succeeding. - -During the upgrade process, {kib} creates new indices into which updated documents are written. If a cluster is approaching the low watermark, there's a high risk of {kib} not being able to create these. Reading, transforming, and writing updated documents can be memory intensive, using more available heap than during routine operation. You must ensure that enough heap is available to prevent requests from timing out or throwing errors from circuit breaker exceptions. You should also ensure that all shards are replicated and assigned. - -A healthy cluster has: - - * Enough free disk space, at least twice the amount of storage taken up by the `.kibana` and `.kibana_task_manager` indices - * Sufficient heap size - * A "green" cluster status - -[float] -==== Ensure that all {kib} instances are the same +=== Ensure that all {kib} instances are the same When you perform an upgrade migration of different {kib} versions, the migration can fail. Ensure that all {kib} instances are running the same version, configuration, and plugins. [float] -==== Back up your data - -Be sure to have a {ref}/snapshot-restore.html[snapshot] of all your data before migrating, so that if something goes wrong during migration, you can restore from the snapshot and try again. - -Review the {kibana-ref}/resolve-migrations-failures.html[common causes of {kib} upgrade failures] and how to prevent them. - +== Support for Elastic prebuilt detection rule automatic updates +<> are supported for the current {elastic-sec} version and the latest three previous minor releases. For example, if you’re upgrading to {elastic-sec} 8.10, you’ll be able to use the Rules UI to update your prebuilt rules until {elastic-sec} 8.14 is released. After that point, you can still manually download and install updated prebuilt rules, but you must upgrade to the latest {elastic-sec} version to receive automatic updates. [float] -[[upgrade-8.x]] -== Upgrade from an earlier 8.x version +[[upgrade-8x-8x]] +== Upgrade from an 8.x to an 8.x version -. Review the breaking changes for each product you use and make the necessary changes so your code is compatible with {version}. - -** {apm-guide-ref}/apm-breaking.html[APM {version} breaking changes] -** {beats-ref}/breaking-changes.html[Beats {version} breaking changes] -** {ref}/breaking-changes.html[{es} {version} breaking changes] -** {security-guide}/release-notes.html[{elastic-sec} {version} breaking changes] -** {kibana-ref}/release-notes.html[{kib} {version} breaking changes] -** {logstash-ref}/breaking-changes.html[{ls} {version} breaking changes] -+ -. If you use any {es} plugins, ensure each plugin has a version compatible with {es} version {version}. +Follow this guide to upgrade from an earlier 8.x version to a later 8.x version. -. Test the upgrade in an isolated environment before upgrading your production -cluster. +[float] +=== Plan for your upgrade -. Ensure 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. +Before upgrading from an earlier 8.x version, consider the following recommendations: -. If you use a separate {ref}/monitoring-production.html[monitoring cluster], you should upgrade the monitoring cluster before the production cluster. Generally, the monitoring cluster and the clusters being monitored should be running the same {stack} version. A monitoring cluster cannot monitor production clusters running newer stack versions. If necessary, the monitoring cluster can monitor production clusters running the latest release of the previous major 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 week to complete. -[float] -[[upgrade-notes-8.8]] -=== Considerations when upgrading to 8.8 +* Open a https://support.elastic.co[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. -After you upgrade to 8.8 or later, frequency settings for <> created in 8.7 or earlier are automatically moved from the rule level to the action level. The action schedules remain the same and will continue to run on their previously specified frequency (`On each rule execution`, `Hourly`, `Daily`, or `Weekly`). +* Choose a version to upgrade to. We recommend the latest minor and patch version. Be sure to upgrade your development or non-production deployment to the same version as your production deployment. -[float] -[[upgrade-7.17-8x]] -== Upgrade from 7.17 to an 8.x version +* Ensure that you have {kibana-ref}/xpack-monitoring.html[stack monitoring] enabled in {kib}. Take note of your current index and search rate. -This section provides the necessary steps you need to take before upgrading to 8.x. It also contains new requirements and other pertinent information that affect various features in the {security-app}. +* Review your selected version's features, Elastic connectors, integrations, and detection rules to determine if you can replace any customized content with out-of-the-box functionality. This can help reduce your workload and the complexity of your upgrade. -First, review the breaking changes for each product you use and make the necessary changes so your code is compatible with {version}. +* Review release notes, deprecations, and breaking changes for {security-guide}/release-notes.html[{elastic-sec}], {ref}/es-release-notes.html[{es}], {kibana-ref}/release-notes.html[{kib}], and, if applicable, {fleet-guide}/release-notes.html[{fleet} and {agent}], {beats-ref}/release-notes.html[{beats}], and {logstash-ref}/releasenotes.html[{ls}]. Identify any issues that might affect your deployment. Work with your Elastic team on any questions you may have. Start with breaking changes for your solution and platform components, such as {es} and {kib}. -** {apm-guide-ref}/apm-breaking.html[APM {version} breaking changes] -** {beats-ref}/breaking-changes.html[Beats {version} breaking changes] -** {ref}/breaking-changes.html[{es} {version} breaking changes] -** {security-guide}/release-notes.html[{elastic-sec} {version} breaking changes] -** {kibana-ref}/release-notes.html[{kib} {version} breaking changes] -** {logstash-ref}/breaking-changes.html[{ls} {version} breaking changes] +* Schedule a system maintenance window within your organization. [float] -[[reenable-rules-upgrade]] -=== Re-enable disabled rules +=== Pre-upgrade steps -Any active rules when you upgrade from 7.17 to 8.0.1 or newer are automatically disabled, and a tag named `auto_disabled_8.0` is added to those rules for tracking purposes. Once the upgrade is complete, you can filter rules by the newly added tag, then use bulk actions to re-enable them: +To prepare for the upgrade process, follow these steps before you start: -. Go to the Rules page (*Detect -> Rules*). -. From the *Tags* dropdown, search for `auto_disabled_8.0`. -. Click *Select all _x_ rules*, or individually select the rules you want to re-enable. -. Click *Bulk actions -> Enable* to re-enable the rules. +. Do a software version inventory across your entire Elastic deployment, including {es}, {kib}, {agent}, {beats}, and {ls}. -Alternatively, you can use the <> API to re-enable rules. +. If you're not using {ref}/snapshots-take-snapshot.html#automate-snapshots-slm[{slm} (SLM)], you must set up and configure a policy, then run the policy to create at least one {ref}/snapshot-restore.html[snapshot]—a backup of indices taken from a running cluster. If you need to roll back during the upgrade process, use a recent snapshot to avoid data loss. Snapshots are {ref}/snapshot-restore.html#how-snapshots-work[incremental]—depending on the cluster size and the input/output rate, the initial snapshot may take several hours to complete. If you're using SLM, {ref}/snapshots-take-snapshot.html#check-slm-history[check the SLM history] to ensure that snapshots are completing successfully. [float] -[[fda-upgrade]] -=== Full Disk Access (FDA) approval for {elastic-endpoint} +=== Perform an 8.x to 8.x upgrade on a deployment -When you manually install {elastic-endpoint}, you must approve a system extension, kernel extension, and enable Full Disk Access (FDA). There is a new FDA requirement in 8.x. Refer to <> to review the required permissions. +IMPORTANT: We strongly recommend performing the following steps on a non-production deployment first to address any potential issues before upgrading your production deployments. If you're using a cross-cluster search environment, upgrade your remote deployments first. -[float] -[[data-views-upgrade]] -=== Requirements to display Data views in the {es-sec-app} +. If you haven't already done so, back up your cluster data to a {ref}/snapshots-take-snapshot.html[snapshot]. -To make the *Data view* option appear in an environment with legacy alerts, a user with elevated role privileges must visit the {es-sec-app}, open a page that displays alert data (such as the Overview page), then refresh the page. The user's role privileges must allow them to enable the detections feature in a Kibana space. Refer to <> for more information. +. We recommend you <> in case there are issues with the detection engine after the upgrade. -NOTE: If new alerts are generated in an upgraded environment without legacy alerts, refreshing any page with alert data in {elastic-sec} will make the *Data view* option appear in the {es-sec-ui}. +. Upgrade {es}. +** If you're using {ecloud}, we recommend upgrades with no downtime. Refer to {cloud}/ec-upgrade-deployment.html[these instructions]. +** If you're using {ece} (ECE), refer to {ece-ref}/ece-upgrade-deployment.html[these instructions]. +** If you're using {eck} (ECK), refer to {eck-ref}/k8s-upgrading-stack.html[these instructions]. +** If you're upgrading a self-orchestrated deployment, refer to {stack-ref}/upgrading-elasticsearch.html[these instructions] and upgrade the data nodes tier by tier in this order: +... Frozen tier +... Cold tier +... Warm tier +... Hot tier +... Any other nodes not in a tier +... All remaining nodes that are neither master-eligible nor data nodes +... Master-eligible nodes -[float] -[[alert-schema-upgrade]] -=== New alert schema +. Upgrade {kib}. Refer to {stack-ref}/upgrading-kibana.html[these instructions]. ++ +NOTE: If you're using Elastic Cloud Hosted or {ece}, this is already included in the {es} upgrade. -The system index for detection alerts has been renamed from `.siem-signals-` to `.alerts-security.alerts-` and is now a hidden index. Therefore, the schema used for alert documents in {elastic-sec} has changed. Users that access documents in the `.siem-signals` indices using the {elastic-sec} API must modify their API queries and scripts to operate properly on the new 8.x alert documents. Refer to <> and review the new <>. +. Validate that {es} and {kib} are operating as expected by completing the following checks: +.. For {es}: +... Check the status of your clusters and ensure that they're green by running a `GET _cat/health` API request. For more information, refer to the {ref}/cat-health.html[cat health API documentation]. +... Ensure that the index and search rate are close to what they were before upgrading. Go to **Stack Monitoring** -> **{es}** -> **Overview**. ++ +TIP: You can also check the index document count using the {ref}/cat-indices.html[cat index API]. +... Verify that {slm} (SLM) is taking snapshots by {ref}/snapshots-take-snapshot.html#check-slm-history[checking the SLM history]. +... If you use {ml}, ensure that it is up and running. +.. For {kib}: +... Ensure that you and your users can successfully log in to {kib} and access desired pages. +... Check {kibana-ref}/discover.html[Discover] and verify that the index patterns you typically use are available. +... Verify that your commonly used {kibana-ref}/dashboard.html[dashboards] are available and working properly. +... If you use any Watcher-based {kib} scheduled {kibana-ref}/reporting-getting-started.html[reporting], ensure that it's working properly. -[float] -[[preview-upgrade]] -=== New privileges required to view alerts and preview rules +. Upgrade your ingest components (such as {ls}, {fleet} and {agent}, {beats}, etc.). For details, refer to the {stack-ref}/upgrading-elastic-stack.html[Elastic Stack upgrade docs]. -* To view alerts, users need `manage`, `write`, `read`, and `view_index_metadata` privileges to two new indices, `.alerts-security.alerts` and `.internal.alerts-security.alerts`. Existing users who are upgrading to 8.x can retain their privileges to the `.siem-signals` index. +. Validate that ingest is operating correctly. +.. Open *Discover*, go through data views for each of your expected ingest data streams, and ensure that data is being ingested in the expected format and volume. -* To <>, users need `read` access to the new `.preview.alerts-security.alerts` index. Refer to <> for more information. +. Validate that {elastic-sec} is operating correctly. +.. On the **Rules** page, re-enable your desired SIEM detection rules (**Rule Management** tab), and ensure that enabled rules are running without errors or warnings (**Rule Monitoring** tab). +.. Ensure that any SOAR workflows that consume alerts are working. +.. Verify that any custom dashboards your team has created are working properly, especially if they operate on alert documents. -[float] -[[im-rules-upgrade]] -=== Updates to indictor match rules +. If you performed these steps on a non-production deployment, repeat these same steps on your production environment. If you're using a cross-cluster search environment and performed these steps on your remote clusters, repeat these same steps on your other deployments. +. Confirm with your appropriate stakeholders that the upgrade process has been successful. -Changes to the indicator match rule's <> might require you to update existing rules or create new ones after upgrading to 8.x. Be mindful of the following: +[float] +[[upgrade-notes-8.8]] +=== Considerations when upgrading to 8.8 or later -* If an indicator match rule's default threat indicator path was not defined before the upgrade, it will default to `threatintel.indicator` after the upgrade. This allows the rule to continue using indicator data ingested by {filebeat} version 7.x. If a custom value was defined before the upgrade, the value will not change. -* If an existing indicator match rule was configured to use threat indicator indices generated from {filebeat} version 7.x, updating the default threat indicator path to `threat.indicator` after you upgrade to {stack} version 8.x and {agent} or {filebeat} version 8.x configures the rule to use threat indicator indices generated by those later versions. -* You must create separate rules to query threat intelligence indices created by {filebeat} version 7.x and version 8.x because each version requires a different default threat indicator path value. Review the recommendations for <>. +After you upgrade to 8.8 or later, frequency settings for <> created in 8.7 or earlier are automatically moved from the rule level to the action level. The action schedules remain the same and will continue to run on their previously specified frequency (`On each rule execution`, `Hourly`, `Daily`, or `Weekly`). [float] [[upgrade-7.16-8.x]] @@ -178,4 +146,6 @@ To upgrade from 7.16.0 or earlier to {version}, you must first upgrade your {sta Initially, {agent}s will be version 7.17. This is fine because {elastic-sec} 8.x supports the last minor release in 7.x (7.17) and any subsequent {elastic-endpoint} versions in 8.x. After the {stack} upgrade, you can decide whether to upgrade {agent}s to 8.x, which is recommended to ensure you get the latest features. -NOTE: You do not need to shut down your {agent}s or endpoints to upgrade the {stack}. \ No newline at end of file +NOTE: You do not need to shut down your {agent}s or endpoints to upgrade the {stack}. + +include::upgrade-7.17-8.x.asciidoc[] \ No newline at end of file