From 15eadc84c31414768ef64acc14ac48d9239718c9 Mon Sep 17 00:00:00 2001 From: Visha Angelova Date: Fri, 25 Jul 2025 15:08:17 +0200 Subject: [PATCH 1/5] Add documentation for the auto-upgrade agents feature --- reference/fleet/agent-policy.md | 16 ++++++++ reference/fleet/upgrade-elastic-agent.md | 51 ++++++++++++++++++++++-- 2 files changed, 64 insertions(+), 3 deletions(-) diff --git a/reference/fleet/agent-policy.md b/reference/fleet/agent-policy.md index 8e6dc0c893..a151cd08c7 100644 --- a/reference/fleet/agent-policy.md +++ b/reference/fleet/agent-policy.md @@ -2,6 +2,8 @@ navigation_title: Policies mapped_pages: - https://www.elastic.co/guide/en/fleet/current/agent-policy.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -55,6 +57,7 @@ Hosted policies display a lock icon in the {{fleet}} UI, and actions are restric | [Edit or delete a policy](#policy-main-settings) | ![yes](images/green-check.svg "") | ![no](images/red-x.svg "") | | [Add custom fields](#add-custom-fields) | ![yes](images/green-check.svg "") | ![no](images/red-x.svg "") | | [Configure agent monitoring](#change-policy-enable-agent-monitoring) | ![yes](images/green-check.svg "") | ![no](images/red-x.svg "") | +| [Configure an automatic {{agent}} upgrade](#agent-policy-automatic-agent-upgrade) {applies_to}`stack: ga 9.1.0` | ![yes](images/green-check.svg "") | ![no](images/red-x.svg "") | | [Change the output of a policy](#change-policy-output) | ![yes](images/green-check.svg "") | ![no](images/red-x.svg "") | | [Add a {{fleet-server}} to a policy](#add-fleet-server-to-policy) | ![yes](images/green-check.svg "") | ![no](images/red-x.svg "") | | [Configure secret values in a policy](#agent-policy-secret-values) | ![yes](images/green-check.svg "") | ![no](images/red-x.svg "") | @@ -260,6 +263,19 @@ You can set a rate limit for the action handler for diagnostics requests coming This setting configures retries for the file upload client handling diagnostics requests coming from {{fleet}}. The setting affects only {{fleet}}-managed {{agents}}. By default, a maximum of `10` retries are allowed with an initial duration of `1s` and a backoff duration of `1m`. The client may retry failed requests with exponential backoff. +## Configure an automatic {{agent}} upgrade [#agent-policy-automatic-agent-upgrade] + +```{applies_to} +stack: ga 9.1.0 +``` + +For a high-scale deployment of {{fleet}}, you can configure an automatic, gradual rollout of a new minor or patch version to a percentage of the {{agents}} in your policy. For more information, refer to [Auto-upgrade agents enrolled in a policy](/reference/fleet/upgrade-elastic-agent.md#auto-upgrade-agents). + +::::{note} +This feature is only available for certain subscription levels. For more information, refer to [{{stack}} subscriptions](https://www.elastic.co/subscriptions). +:::: + + ## Change the output of a policy [change-policy-output] Assuming your [{{stack}} subscription level](https://www.elastic.co/subscriptions) supports per-policy outputs, you can change the output of a policy to send data to a different output. diff --git a/reference/fleet/upgrade-elastic-agent.md b/reference/fleet/upgrade-elastic-agent.md index 9895a992c2..9ece97eb1d 100644 --- a/reference/fleet/upgrade-elastic-agent.md +++ b/reference/fleet/upgrade-elastic-agent.md @@ -2,6 +2,8 @@ navigation_title: Upgrade {{agent}}s mapped_pages: - https://www.elastic.co/guide/en/fleet/current/upgrade-elastic-agent.html +applies_to: + stack: ga products: - id: fleet - id: elastic-agent @@ -44,7 +46,7 @@ These restrictions apply whether you are upgrading {{agents}} individually or in ## Upgrading {{agent}} [upgrade-agent] -To upgrade your {{agent}}s, go to **Management > {{fleet}} > Agents** in {{kib}}. You can perform the following upgrade-related actions: +To upgrade your {{agents}}, go to **Management** → **{{fleet}}** → **Agents** in {{kib}}. You can perform the following upgrade-related actions: | User action | Result | | --- | --- | @@ -55,6 +57,8 @@ To upgrade your {{agent}}s, go to **Management > {{fleet}} > Agents** in {{kib}} | [Restart an upgrade for a single agent](#restart-upgrade-single) | Restart an upgrade process that has stalled for a single agent. | | [Restart an upgrade for multiple agents](#restart-upgrade-multiple) | Do a bulk restart of the upgrade process for a set of agents. | +With the right [subscription level](https://www.elastic.co/subscriptions), you can also configure an automatic, gradual upgrade of a percentage of the {{agents}} enrolled in an {{agent}} policy. For more information, refer to [Auto-upgrade agents enrolled in a policy](#auto-upgrade-agents). {applies_to}`stack: ga 9.1.0` + ## Upgrade a single {{agent}} [upgrade-an-agent] @@ -84,7 +88,6 @@ To upgrade your {{agent}}s, go to **Management > {{fleet}} > Agents** in {{kib}} ::: - ## Do a rolling upgrade of multiple {{agent}}s [rolling-agent-upgrade] You can do rolling upgrades to avoid exhausting network resources when updating a large number of {{agent}}s. @@ -182,7 +185,6 @@ If an upgrade fails, you can view the agent logs to find the reason: ::: - ## Restart an upgrade for a single agent [restart-upgrade-single] An {{agent}} upgrade process may sometimes stall. This can happen for various reasons, including, for example, network connectivity issues or a delayed shutdown. @@ -217,6 +219,49 @@ When the upgrade process for multiple agents has been detected to have stalled, 5. Restart the upgrades. +## Auto-upgrade agents enrolled in a policy [auto-upgrade-agents] + +```{applies_to} +stack: ga 9.1.0 +``` + +::::{note} +This feature is only available for certain subscription levels. For more information, refer to [{{stack}} subscriptions](https://www.elastic.co/subscriptions). +:::: + +To configure an automatic rollout of a new minor or patch version to a percentage of the agents enrolled in your {{agent}} policy. follow these steps: + +1. In {{kib}}, go to **Management** → **{{fleet}}** → **Agent policies**. +2. Select the agent policy for which you want to configure an automatic agent upgrade. +3. On the agent policy's details page, find **Auto-upgrade agents**, and select **Manage** next to it. +4. In the **Manage auto-upgrade agents** window, click **Add target version**. +5. From the **Target agent version** dropdown, select the minor or patch version to which you want to upgrade a percentage of your agents. +6. In the **% of agents to upgrade** field, enter the percentage of agents you want to upgrade to this target version. + + Note that rounding is applied, and the actual percentage of the upgraded agents may vary slightly. For example, if you want to upgrade 30% of the agents in a policy with 25 agents, this may result in the upgrade of 8 agents (32%). + +7. You can then add a different target version, and specify the percentage of agents you want to be upgraded to that version. The total percentage of agents to be upgraded cannot exceed 100%. +8. Click **Save**. + +Once the configuration is saved, an asynchronous task runs every 30 minutes, gradually upgrading the agents in the policy to the specified target version. In case of any failed upgrades, the upgrades are retried with exponential backoff mechanism until the upgrade is successful. + +::::{note} +Only agents enrolled in the policy are considered for the automatic upgrade. If new agents are assigned to the policy, the number of {{agents}} to be upgraded is adjusted according to the set percentages. +:::: + +### View the status of the automatic upgrade [auto-upgrade-view-status] + +You can view the status of the automatic upgrade in the following ways: + +- On the agent policy's details page, find **Auto-upgrade agents**, and select **Manage** to open the **Manage auto-upgrade agents** window. + + The status of the upgrade is displayed next to the specified target version and percentage, and includes the percentage of agents that have already been upgraded. + + To view any failed upgrades, hover over the **Upgrade failed** status, then click **Go to upgrade**. + +- On the **{{fleet}}** → **Agents** page, click **Agent activity** to open a flyout showing logs of the {{agent}} activity and the progress of the automatic agent upgrade. + + ## Upgrade RPM and DEB system packages [upgrade-system-packages] If you have installed and enrolled {{agent}} using either a DEB (for a Debian-based Linux distribution) or RPM (for a RedHat-based Linux distribution) install package, the upgrade cannot be managed by {{fleet}}. Instead, you can perform the upgrade using these steps. From b21fa0663c6ebd695a8e2fa820dd77c957ab2d6d Mon Sep 17 00:00:00 2001 From: Visha Angelova Date: Mon, 28 Jul 2025 10:22:17 +0200 Subject: [PATCH 2/5] Add section for configuring the auto-upgrade --- reference/fleet/agent-policy.md | 2 +- reference/fleet/upgrade-elastic-agent.md | 29 ++++++++++++++++++++---- 2 files changed, 25 insertions(+), 6 deletions(-) diff --git a/reference/fleet/agent-policy.md b/reference/fleet/agent-policy.md index a151cd08c7..f6cc8bc516 100644 --- a/reference/fleet/agent-policy.md +++ b/reference/fleet/agent-policy.md @@ -71,7 +71,7 @@ See also the [recommended scaling options](#agent-policy-scale) for an {{agent}} ## Create a policy [create-a-policy] - +fau To manage your {{agent}}s and the data they collect, create a new policy: In {{fleet}}, open the **Agent policies** tab and click **Create agent policy**. diff --git a/reference/fleet/upgrade-elastic-agent.md b/reference/fleet/upgrade-elastic-agent.md index 9ece97eb1d..ccaa0bc8c0 100644 --- a/reference/fleet/upgrade-elastic-agent.md +++ b/reference/fleet/upgrade-elastic-agent.md @@ -236,19 +236,38 @@ To configure an automatic rollout of a new minor or patch version to a percentag 3. On the agent policy's details page, find **Auto-upgrade agents**, and select **Manage** next to it. 4. In the **Manage auto-upgrade agents** window, click **Add target version**. 5. From the **Target agent version** dropdown, select the minor or patch version to which you want to upgrade a percentage of your agents. -6. In the **% of agents to upgrade** field, enter the percentage of agents you want to upgrade to this target version. - - Note that rounding is applied, and the actual percentage of the upgraded agents may vary slightly. For example, if you want to upgrade 30% of the agents in a policy with 25 agents, this may result in the upgrade of 8 agents (32%). +6. In the **% of agents to upgrade** field, enter the percentage of active agents you want to upgrade to this target version. + + Note that: + - Unenrolling, unenrolled, inactive, and uninstalled agents are not included in the count. For example, if you set the target upgrade percentage to 50% for a policy with 10 active agents and 10 inactive agents, the target is met when 5 active agents are upgraded. + - Rounding is applied, and the actual percentage of the upgraded agents may vary slightly. For example, if you set the target upgrade percentage to 30% for a policy with 25 active agents, the target is met when 8 active agents are upgraded (32%). 7. You can then add a different target version, and specify the percentage of agents you want to be upgraded to that version. The total percentage of agents to be upgraded cannot exceed 100%. 8. Click **Save**. -Once the configuration is saved, an asynchronous task runs every 30 minutes, gradually upgrading the agents in the policy to the specified target version. In case of any failed upgrades, the upgrades are retried with exponential backoff mechanism until the upgrade is successful. +Once the configuration is saved, an asynchronous task runs every 30 minutes, gradually upgrading the agents in the policy to the specified target version. + +In case of any failed upgrades, the upgrades are retried with exponential backoff mechanism until the upgrade is successful, or the maximum number of retries is reached. Note that the maximum number of retries is the number of [configured retry delays](#auto-upgrade-settings). ::::{note} -Only agents enrolled in the policy are considered for the automatic upgrade. If new agents are assigned to the policy, the number of {{agents}} to be upgraded is adjusted according to the set percentages. +Only active agents enrolled in the policy are considered for the automatic upgrade. + +If new agents are assigned to the policy, the number of {{agents}} to be upgraded is adjusted according to the set percentages. :::: +### Configure the auto-upgrade settings [auto-upgrade-settings] + +On self-managed and cloud deployments of {{stack}}, you can configure the default task interval and the retry delays of the automatic upgrade in the {{kib}} user settings. For example: + +```yml +xpack.fleet.autoUpgrades.taskInterval: 15m <1> +xpack.fleet.autoUpgrades.retryDelays: ['5m', '10m', '20m'] <2> +``` +1. Defaults to `30m` +2. Defaults to `['30m', '1h', '2h', '4h', '8h', '16h', '24h']` + +For more information, refer to [Fleet settings in Kibana](kibana://reference/configuration-reference/fleet-settings.md). + ### View the status of the automatic upgrade [auto-upgrade-view-status] You can view the status of the automatic upgrade in the following ways: From 1bffb3c6486e839ffe4e900394c0451b5c154359 Mon Sep 17 00:00:00 2001 From: Visha Angelova Date: Mon, 28 Jul 2025 11:43:56 +0200 Subject: [PATCH 3/5] Update the configuration settings section --- reference/fleet/upgrade-elastic-agent.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/fleet/upgrade-elastic-agent.md b/reference/fleet/upgrade-elastic-agent.md index ccaa0bc8c0..b96f0a029e 100644 --- a/reference/fleet/upgrade-elastic-agent.md +++ b/reference/fleet/upgrade-elastic-agent.md @@ -257,16 +257,16 @@ If new agents are assigned to the policy, the number of {{agents}} to be upgrade ### Configure the auto-upgrade settings [auto-upgrade-settings] -On self-managed and cloud deployments of {{stack}}, you can configure the default task interval and the retry delays of the automatic upgrade in the {{kib}} user settings. For example: +On self-managed and cloud deployments of {{stack}}, you can configure the default task interval and the retry delays of the automatic upgrade in the [{{kib}} {{fleet}} settings](kibana://reference/configuration-reference/fleet-settings.md). For example: ```yml xpack.fleet.autoUpgrades.taskInterval: 15m <1> xpack.fleet.autoUpgrades.retryDelays: ['5m', '10m', '20m'] <2> ``` -1. Defaults to `30m` -2. Defaults to `['30m', '1h', '2h', '4h', '8h', '16h', '24h']` +1. The time interval between which the auto-upgrade task should run. Defaults to `30m`. +2. Array indicating how much time should pass before a failed auto-upgrade is retried. The array's length indicates the maximum number of retries. Defaults to `['30m', '1h', '2h', '4h', '8h', '16h', '24h']` -For more information, refer to [Fleet settings in Kibana](kibana://reference/configuration-reference/fleet-settings.md). +For more information, refer to the [Kibana configuration reference](kibana://reference/configuration-reference.md). ### View the status of the automatic upgrade [auto-upgrade-view-status] From 450c521a0f73acac2935b5ce7ec6c5073b6c7526 Mon Sep 17 00:00:00 2001 From: Visha Angelova Date: Mon, 28 Jul 2025 11:45:49 +0200 Subject: [PATCH 4/5] Remove typo --- reference/fleet/agent-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/fleet/agent-policy.md b/reference/fleet/agent-policy.md index f6cc8bc516..a151cd08c7 100644 --- a/reference/fleet/agent-policy.md +++ b/reference/fleet/agent-policy.md @@ -71,7 +71,7 @@ See also the [recommended scaling options](#agent-policy-scale) for an {{agent}} ## Create a policy [create-a-policy] -fau + To manage your {{agent}}s and the data they collect, create a new policy: In {{fleet}}, open the **Agent policies** tab and click **Create agent policy**. From fdc132bf6856adae481a9c2e0bfb42c13bd613b7 Mon Sep 17 00:00:00 2001 From: Visha Angelova Date: Mon, 28 Jul 2025 11:52:46 +0200 Subject: [PATCH 5/5] Fix typo --- reference/fleet/upgrade-elastic-agent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/fleet/upgrade-elastic-agent.md b/reference/fleet/upgrade-elastic-agent.md index b96f0a029e..a2a200decf 100644 --- a/reference/fleet/upgrade-elastic-agent.md +++ b/reference/fleet/upgrade-elastic-agent.md @@ -263,8 +263,8 @@ On self-managed and cloud deployments of {{stack}}, you can configure the defaul xpack.fleet.autoUpgrades.taskInterval: 15m <1> xpack.fleet.autoUpgrades.retryDelays: ['5m', '10m', '20m'] <2> ``` -1. The time interval between which the auto-upgrade task should run. Defaults to `30m`. -2. Array indicating how much time should pass before a failed auto-upgrade is retried. The array's length indicates the maximum number of retries. Defaults to `['30m', '1h', '2h', '4h', '8h', '16h', '24h']` +1. The time interval at which the auto-upgrade task should run. Defaults to `30m`. +2. Array indicating how much time should pass before a failed auto-upgrade is retried. The array's length indicates the maximum number of retries. Defaults to `['30m', '1h', '2h', '4h', '8h', '16h', '24h']`. For more information, refer to the [Kibana configuration reference](kibana://reference/configuration-reference.md).