From cc611e190197aeb93b871c0ea7203789c9081aae Mon Sep 17 00:00:00 2001 From: Visha Angelova Date: Fri, 7 Nov 2025 14:47:21 +0100 Subject: [PATCH 1/4] Add documentation for the integration rollback feature --- reference/fleet/manage-integrations.md | 1 + reference/fleet/roll-back-integration.md | 72 ++++++++++++++++++++++++ reference/fleet/toc.yml | 3 +- reference/fleet/upgrade-integration.md | 7 +++ 4 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 reference/fleet/roll-back-integration.md diff --git a/reference/fleet/manage-integrations.md b/reference/fleet/manage-integrations.md index bbd930c4bb..f8bddd09d6 100644 --- a/reference/fleet/manage-integrations.md +++ b/reference/fleet/manage-integrations.md @@ -43,6 +43,7 @@ You can perform a variety of actions in the **Integrations** app in {{kib}}. Som | [Install and uninstall integration assets](/reference/fleet/install-uninstall-integration-assets.md) | Install, uninstall, and reinstall integration assets in {{kib}}. | | [View integration assets](/reference/fleet/view-integration-assets.md) | View the {{kib}} assets installed for a specific integration. | | [Upgrade an integration](/reference/fleet/upgrade-integration.md) | Upgrade an integration to the latest version. | +| [Roll back an integration](/reference/fleet/roll-back-integration.md) {applies_to}`stack: ga 9.3` | Roll back an integration to the previously installed version if issues occur after an upgrade. | ## Customize integrations [customize-integrations] diff --git a/reference/fleet/roll-back-integration.md b/reference/fleet/roll-back-integration.md new file mode 100644 index 0000000000..03e6f470f3 --- /dev/null +++ b/reference/fleet/roll-back-integration.md @@ -0,0 +1,72 @@ +--- +navigation_title: Roll back an integration +description: Roll back an Elastic Agent integration to the previously installed version, restoring the integration policies and configurations of the previous version. +applies_to: + stack: ga 9.3 + serverless: ga +products: + - id: fleet + - id: elastic-agent +--- + +# Roll back an {{agent}} integration + +::::{note} +This feature is available only for certain subscription levels. For more information, refer to [Elastic subscriptions]({{subscriptions}}). +:::: + +If you encounter issues after upgrading an integration, you can roll back the integration to the version installed before the upgrade. During the rollback action, the integration package and all associated integration policies and their configurations are automatically restored to the previously installed version. + +Consider rolling back an integration if: + +- The upgraded integration introduces breaking changes that affect your data collection. +- The new version causes unexpected behavior or errors in your environment. +- You need to revert to a previous version for compatibility reasons. + +:::{note} +By default, the rollback action is available for 7 days following the integration upgrade. After the rollback window expires, you can no longer roll back the integration to the previously installed version. + +You can [configure the rollback time-to-live (TTL)](#configure-rollback-ttl) in {{ech}} or self-managed deployments. +::: + +## Requirements + +To successfully roll back an integration, you must have access to all of its integration policies across **all spaces**. If you don't have access to the related spaces, the rollback action will be disabled. + +## Roll back an integration + +1. In {{kib}}, go to the **Integrations** page and open the **Installed integrations** tab. +2. Search for and select the integration you want to roll back to the previously installed version. +3. Click the **Settings** tab. +4. Click **Rollback **. + + If the button is disabled for an integration, this may be because: + - The 7-day rollback window has expired. + - You don't have access to all integration policies across all spaces. + - No previous version is available to roll back to. + - The integration was never upgraded. + +5. In the confirmation window, click **Rollback integration** to confirm the action. A confirmation appears if the rollback is successful. + +You can also roll back an integration from the **Installed integrations** tab of the **Integrations** page: + +1. Search for the integration you want to roll back, then click the actions button at the end of its row. +2. Click **Rollback integration**, then confirm the action. + +After the rollback of the integration is complete, the associated integration policies, their configurations and related assets are restored to the integration's previous version. + +:::{note} +The automatic upgrade of rolled back integrations is disabled until the integrations are manually upgraded. +::: + +## Configure the rollback TTL [configure-rollback-ttl] + +The default duration of the rollback window is 7 days. To configure the rollback TTL duration, add the `xpack.fleet.integrationRollbackTTL` setting in the user settings of your {{ech}} deployment or in the `kibana.yml` configuration file of your self-managed deployment. + +For example, to extend the rollback window to 14 days, set: + +```yml +xpack.fleet.integrationRollbackTTL: 14d +``` + +For more information, refer to [{{fleet}} settings in {{kib}}](kibana://reference/configuration-reference/fleet-settings.md). \ No newline at end of file diff --git a/reference/fleet/toc.yml b/reference/fleet/toc.yml index a98cfac671..662133a11a 100644 --- a/reference/fleet/toc.yml +++ b/reference/fleet/toc.yml @@ -147,6 +147,7 @@ toc: - file: view-integration-assets.md - file: integration-level-outputs.md - file: upgrade-integration.md + - file: roll-back-integration.md - file: managed-integrations-content.md - file: integrations-assets-best-practices.md - file: otel-integrations.md @@ -209,4 +210,4 @@ toc: - file: timestamp-processor.md - file: translate_sid-processor.md - file: truncate_fields-processor.md - - file: urldecode-processor.md + - file: urldecode-processor.md \ No newline at end of file diff --git a/reference/fleet/upgrade-integration.md b/reference/fleet/upgrade-integration.md index 50f5513c25..de9bc0ac87 100644 --- a/reference/fleet/upgrade-integration.md +++ b/reference/fleet/upgrade-integration.md @@ -2,6 +2,9 @@ navigation_title: Upgrade an integration mapped_pages: - https://www.elastic.co/guide/en/fleet/current/upgrade-integration.html +applies_to: + stack: ga + serverless: ga products: - id: fleet - id: elastic-agent @@ -48,6 +51,10 @@ In larger deployments, you should test integration upgrades on a sample {{agent} You must upgrade standalone agents separately. If you used {{kib}} to create and download your standalone agent policy, see [Upgrade standalone agent policies after upgrading an integration](/reference/fleet/create-standalone-agent-policy.md#update-standalone-policies). :::: +::::{tip} +:applies_to: stack: ga 9.3 +If you encounter issues after upgrading an integration and your [Elastic subscription level](https://www.elastic.co/subscriptions) supports **integration rollback**, you can [roll back the integration to the previously installed version](/reference/fleet/roll-back-integration.md). +:::: ## Keep integration policies up to date automatically [upgrade-integration-policies-automatically] From c3e1ed67fe43f1281228e1857ce67577afb2b2e5 Mon Sep 17 00:00:00 2001 From: Visha Angelova <91186315+vishaangelova@users.noreply.github.com> Date: Fri, 7 Nov 2025 15:53:17 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Julia Bardi <90178898+juliaElastic@users.noreply.github.com> --- reference/fleet/roll-back-integration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/reference/fleet/roll-back-integration.md b/reference/fleet/roll-back-integration.md index 03e6f470f3..6bd8719fcc 100644 --- a/reference/fleet/roll-back-integration.md +++ b/reference/fleet/roll-back-integration.md @@ -31,7 +31,7 @@ You can [configure the rollback time-to-live (TTL)](#configure-rollback-ttl) in ## Requirements -To successfully roll back an integration, you must have access to all of its integration policies across **all spaces**. If you don't have access to the related spaces, the rollback action will be disabled. +To successfully roll back an integration, you must have access to all of its integration policies across **all spaces**. If you don't have access to the related spaces, the rollback action will not succeed. ## Roll back an integration @@ -45,6 +45,7 @@ To successfully roll back an integration, you must have access to all of its int - You don't have access to all integration policies across all spaces. - No previous version is available to roll back to. - The integration was never upgraded. + - The integration is not installed from the {{package-registry}}. 5. In the confirmation window, click **Rollback integration** to confirm the action. A confirmation appears if the rollback is successful. From bd55bc7b6d15d5a802a38550ba87e52f48ee5806 Mon Sep 17 00:00:00 2001 From: Visha Angelova <91186315+vishaangelova@users.noreply.github.com> Date: Fri, 7 Nov 2025 20:37:35 +0100 Subject: [PATCH 3/4] Update reference/fleet/roll-back-integration.md Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com> --- reference/fleet/roll-back-integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/fleet/roll-back-integration.md b/reference/fleet/roll-back-integration.md index 6bd8719fcc..bb52f31cf8 100644 --- a/reference/fleet/roll-back-integration.md +++ b/reference/fleet/roll-back-integration.md @@ -40,7 +40,7 @@ To successfully roll back an integration, you must have access to all of its int 3. Click the **Settings** tab. 4. Click **Rollback **. - If the button is disabled for an integration, this may be because: + If the button is disabled for an integration, this may indicate: - The 7-day rollback window has expired. - You don't have access to all integration policies across all spaces. - No previous version is available to roll back to. From 14bacc8c20ed03ea059af55e4be244594ce4206f Mon Sep 17 00:00:00 2001 From: Visha Angelova Date: Mon, 10 Nov 2025 19:06:32 +0100 Subject: [PATCH 4/4] Update the steps + add a tip for the rollback action --- reference/fleet/roll-back-integration.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/reference/fleet/roll-back-integration.md b/reference/fleet/roll-back-integration.md index bb52f31cf8..b85bfcfb1c 100644 --- a/reference/fleet/roll-back-integration.md +++ b/reference/fleet/roll-back-integration.md @@ -35,10 +35,9 @@ To successfully roll back an integration, you must have access to all of its int ## Roll back an integration -1. In {{kib}}, go to the **Integrations** page and open the **Installed integrations** tab. -2. Search for and select the integration you want to roll back to the previously installed version. -3. Click the **Settings** tab. -4. Click **Rollback **. +1. In {{kib}}, go to **Integrations** > **Installed integrations**. +2. Select the integration you want to roll back, then open the integration's **Settings** tab. +3. Click **Rollback **. If the button is disabled for an integration, this may indicate: - The 7-day rollback window has expired. @@ -47,14 +46,16 @@ To successfully roll back an integration, you must have access to all of its int - The integration was never upgraded. - The integration is not installed from the {{package-registry}}. -5. In the confirmation window, click **Rollback integration** to confirm the action. A confirmation appears if the rollback is successful. +4. In the confirmation window, click **Rollback integration**. A confirmation appears if the rollback is successful. -You can also roll back an integration from the **Installed integrations** tab of the **Integrations** page: +After the rollback of the integration is complete, the associated integration policies, their configurations and related assets are restored to the integration's previous version. -1. Search for the integration you want to roll back, then click the actions button at the end of its row. -2. Click **Rollback integration**, then confirm the action. +::::{tip} +You can also roll back an integration from **Integrations** > **Installed integrations**: -After the rollback of the integration is complete, the associated integration policies, their configurations and related assets are restored to the integration's previous version. +1. Click the actions button at the end of the integration's row. +2. Select **Rollback integration**, then confirm the action. +:::: :::{note} The automatic upgrade of rolled back integrations is disabled until the integrations are manually upgraded.