[8.19] Add documentation for the Fleet auto-upgrade feature (#1832)

* [8.19] Add documentation for the Fleet auto-upgrade feature

* Update docs/en/ingest-management/agent-policies.asciidoc

Co-authored-by: Colleen McGinnis <[email protected]>

---------

Co-authored-by: Colleen McGinnis <[email protected]>

Author: vishaangelova

docs/en/ingest-management/agent-policies.asciidoc

@@ -100,6 +100,10 @@ The following table illustrates the {fleet} user actions available to different
 |{y}
 |{n}
 
+|<<agent-policy-automatic-agent-upgrade,Configure an automatic {agent} upgrade>>
+|{y}
+|{n}
+
 |<<change-policy-output,Change the output of a policy>>
 |{y}
 |{n}
@@ -367,6 +371,14 @@ 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.
 
+[discrete]
+[[agent-policy-automatic-agent-upgrade]]
+== Configure an automatic {agent} upgrade
+
+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,Auto-upgrade agents enrolled in a policy>>.
+
+NOTE: This feature is only available for certain subscription levels. For more information, refer to {subscriptions}[{stack} subscriptions].
+
 [discrete]
 [[change-policy-output]]
 == Change the output of a policy

docs/en/ingest-management/fleet/upgrade-elastic-agent.asciidoc

@@ -51,7 +51,7 @@ These restrictions apply whether you are upgrading {agents} individually or in b
 [[upgrade-agent]]
 == Upgrading {agent}
 
-To upgrade your {agent}s, go to *Management > {fleet} > Agents* in {kib}. You
+To upgrade your {agents}, go to *Management* → *{fleet}* → *Agents* in {kib}. You
 can perform the following upgrade-related actions:
 
 [options,header]
@@ -78,6 +78,8 @@ can perform the following upgrade-related actions:
 
 |===
 
+With the right {subscriptions}[subscription level], 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,Auto-upgrade agents enrolled in a policy>>.
+
 [discrete]
 [[upgrade-an-agent]]
 == Upgrade a single {agent}
@@ -263,6 +265,69 @@ triggered, select **Immediately**. Avoid using this setting for batches of more
 than 10 agents.
 . Restart the upgrades.
 
+[discrete]
+[[auto-upgrade-agents]]
+== Auto-upgrade agents enrolled in a policy
+
+NOTE: This feature is only available for certain subscription levels. For more information, refer to {subscriptions}[{stack} 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:
+
+. In {kib}, go to **Management** → **{fleet}** → **Agent policies**.
+. Select the agent policy for which you want to configure an automatic agent upgrade.
+. On the agent policy's details page, find **Auto-upgrade agents**, and select **Manage** next to it.
+. In the **Manage auto-upgrade agents** window, click **Add target version**.
+. From the **Target agent version** dropdown, select the minor or patch version to which you want to upgrade a percentage of your agents.
+. 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%).
+
+. 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%.
+. 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, or the maximum number of retries is reached. Note that the maximum number of retries is the number of <<auto-upgrade-settings,configured retry delays>>.
+
+[NOTE]
+====
+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.
+====
+
+[discrete]
+[[auto-upgrade-settings]]
+=== Configure the 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 {kibana-ref}/fleet-settings-kb.html[{kib} {fleet} settings]. For example:
+
+[source,yml]
+------------
+xpack.fleet.autoUpgrades.taskInterval: 15m <1>
+xpack.fleet.autoUpgrades.retryDelays: ['5m', '10m', '20m'] <2>
+------------
+<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 {kibana-ref}/settings.html[Configure {kib}].
+
+[discrete]
+[[auto-upgrade-view-status]]
+=== View the status of the automatic upgrade
+
+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.
+
 [discrete]
 [[upgrade-system-packages]]
 == Upgrade RPM and DEB system packages