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..b85bfcfb1c --- /dev/null +++ b/reference/fleet/roll-back-integration.md @@ -0,0 +1,74 @@ +--- +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 not succeed. + +## Roll back an integration + +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. + - 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}}. + +4. In the confirmation window, click **Rollback integration**. A confirmation appears if the rollback is successful. + +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. + +::::{tip} +You can also roll back an integration from **Integrations** > **Installed integrations**: + +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. +::: + +## 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]