[DOCS] "Unhealthy" Agent status and integration policy errors (#2317) (…

…#2376)

* Update instructions per workflow changes

* Add troubleshooting stub

* Update Endpoints page, link to t'shooting

* Move screenshot

* Minor edit

* Revsions and new content

Create troubleshooting topic
Add links to troubleshooting
Update screenshot
General revisions and cleanup

* Small edits, redo screenshot

* Reorder troubleshooting sections

* moar edits

* Apply suggestions from review

Co-authored-by: Benjamin Ironside Goldstein <[email protected]>

Co-authored-by: Benjamin Ironside Goldstein <[email protected]>
(cherry picked from commit f01871f)

Co-authored-by: Joe Peeples <[email protected]>

docs/getting-started/install-endpoint.asciidoc

@@ -1,5 +1,4 @@
 [[install-endpoint]]
-[role="xpack"]
 = Configure and install the {endpoint-cloud-sec} integration
 
 Like other Elastic integrations, {endpoint-cloud-sec} can be integrated into the {agent} through {fleet-guide}/fleet-overview.html[{fleet}]. Upon configuration, the integration allows the {agent} to monitor for events on your host and send data to the {security-app}.
@@ -16,15 +15,19 @@ If you're using macOS, some versions may require you to grant Full Disk Access t
 [[add-security-integration]]
 == Add the {endpoint-cloud-sec} integration
 
-. In {kib}, select **Security** -> **Manage** -> **Endpoints**. If this is not your first time using {es-sec}, select **Management** -> **Integrations**, then search for and select **{endpoint-cloud-sec}**.
+. Go to the *Integrations* page, which you can access in several ways:
+
+* In {kib}: *Management* -> *Integrations*
+* In the {security-app}: *Get started* -> *Add security integrations*
+
 +
 [role="screenshot"]
 image::images/install-endpoint/endpoint-cloud-sec-integrations-page.png[Search result for "Endpoint and Cloud Security" on the Integrations page.]
-+
-. Select **Add {endpoint-cloud-sec}** on either the Endpoints page of the {security-app} or the {endpoint-cloud-sec} integration page (*Management* -> *Integrations*). The integration configuration page appears.
+
+. Search for and select *{endpoint-cloud-sec}*, then select *Add {endpoint-cloud-sec}*. The integration configuration page appears.
 +
 [role="screenshot"]
-image::images/install-endpoint/endpoint-cloud-security-configuration.png[Add Endpoint and Cloud Security integration page.]
+image::images/install-endpoint/endpoint-cloud-security-configuration.png[Add Endpoint and Cloud Security integration page,75%]
 +
 . Configure the {endpoint-cloud-sec} integration with an **Integration name** and optional **Description**.
 . Enter a name for the agent policy in **New agent policy name**. If other agent policies already exist, you can click the **Existing hosts** tab and select an existing policy instead. For more details on {agent} configuration settings, refer to {fleet-guide}/agent-policy.html[{agent} policies].
@@ -84,4 +87,4 @@ image::images/install-endpoint/endpoint-cloud-sec-add-agent-detail.png[Add agent
 +
 The host will now appear on the **Endpoints** page in the {security-app}. It may take another minute or two for endpoint data to appear in {elastic-sec}.
 
-For macOS, continue with <<deploy-elastic-endpoint, these instructions>> to grant {elastic-endpoint} the access it needs.
+. For macOS, continue with <<deploy-elastic-endpoint, these instructions>> to grant {elastic-endpoint} the access it needs.

docs/management/admin/admin-pg-ov.asciidoc

@@ -1,7 +1,6 @@
 [[admin-page-ov]]
-[role="xpack"]
 = Endpoints
-The Endpoints page allows admins to view and manage endpoints that are running the <<install-endpoint, {endpoint-cloud-sec} integration>>.
+The Endpoints page allows administrators to view and manage endpoints that are running the <<install-endpoint, {endpoint-cloud-sec} integration>>.
 
 [NOTE]
 =====
@@ -14,32 +13,32 @@ You must have the built-in `superuser` role to access this feature. For more inf
 [discrete]
 == Endpoints list
 
-The *Endpoints* list displays all hosts running {elastic-sec} and their relevant integration details. Endpoints appear in chronological order, with newly added endpoints at the top. 
+The *Endpoints* list displays all hosts running {elastic-sec} and their relevant integration details. Endpoints appear in chronological order, with newly added endpoints at the top.
 
 [role="screenshot"]
 image::images/endpoints-pg.png[Endpoints page]
 
 The Endpoints list provides the following data:
 
-* *Endpoint*: The system hostname. Click the link to view host details in a flyout.
+* *Endpoint*: The system hostname. Click the link to display <<endpoint-details,endpoint details>> in a flyout.
 
 * *Agent Status*: The current status of the {agent}, which is one of the following:
 
 ** `Healthy`: The agent is online and communicating with {kib}.
 
 ** `Unenrolling`: The agent is currently unenrolling and will soon be removed from Fleet. Afterward, the endpoint will also uninstall.
 
-** `Unhealthy`: The agent is online but requires attention from an admin because it's reporting a process being unhealthy. An unhealthy status could also mean an upgrade failed and was rolled back to its previous version.
+** `Unhealthy`: The agent is online but requires attention from an administrator because it's reporting a problem with a process. An unhealthy status could mean an upgrade failed and was rolled back to its previous version, or an integration might be missing prerequisites or additional configuration. Refer to <<ts-unhealthy-agent,Endpoint management troubleshooting>> for more on resolving an unhealthy agent status.
 
 ** `Updating`: The agent is online and is updating the agent policy or binary, or is enrolling or unenrolling.
 
 ** `Offline`: The agent is still enrolled but may be on a machine that is shut down or currently does not have internet access. In this state, the agent is no longer communicating with {kib} at a regular interval.
 +
 NOTE: {agent} statuses in {fleet} correspond to the agent statuses in the {security-app}.
 
-* *Policy*: The name of the associated policy when the agent was installed. Click the link to view the Integration policy page.
+* *Policy:* The name of the associated integration policy when the agent was installed. Click the link to display the <<integration-policy-details,integration policy details>> page.
 
-* *Policy status*: Lists whether the policy application was a success or failure. Click the link to view response details in a flyout.
+* *Policy status:* Indicates whether the integration policy was successfully applied. Click the link to view <<policy-status,policy status>> response details in a flyout.
 
 * *OS*: The host's operating system.
 
@@ -66,14 +65,16 @@ NOTE: {agent} statuses in {fleet} correspond to the agent statuses in the {secur
 ** *Reassign agent policy*: Change the {fleet-guide}/agent-policy.html#apply-a-policy[agent policy] assigned to the host in {fleet}.
 
 [discrete]
+[[endpoint-details]]
 === Endpoint details
 
 Click any link in the *Endpoint* column to display host details in a flyout. You can also use the *Take Action* menu button to perform the same actions as those listed in the Actions context menu, such as isolating the host, viewing host details, and viewing or reassigning the agent policy. 
 
 [role="screenshot"]
-image::images/host-flyout.png[Admin page,width=75%]
+image::images/host-flyout.png[Endpoint details flyout,width=75%]
 
 [discrete]
+[[integration-policy-details]]
 === Integration policy details
 
 To view the integration policy page, click the link in the *Policy* column. If you are viewing host details, you can also click the *Policy* link on the flyout.
@@ -93,28 +94,27 @@ NOTE: Advanced settings are not recommended for most users.
 image::images/advanced-settings.png[Integration page]
 
 [discrete]
+[[policy-status]]
 === Policy status
 
-The status of the policy application appears in the *Status* column and displays one of the following possibilities:
+The status of the integration policy appears in the *Policy status* column and displays one of the following:
 
 * `Success`: The policy was applied successfully.
 
-* `Warning or Partially Applied`: The policy is pending application, or the policy was not applied in its entirety.
+* `Warning` or `Partially Applied`: The policy is pending application, or the policy was not applied in its entirety.
++
+NOTE: In some cases, actions taken on the endpoint may fail during policy application, but these cases are not critical failures - meaning there may be a failure, but the endpoints are still protected. In this case, the policy status will display as "Partially Applied."
 
-NOTE: In some cases, some actions taken on the endpoint may fail during the policy application but are not recognized as a critical failure - meaning there may be a failure, but the endpoints are still protected. In this case, the policy status will display as "Partially Applied."
+* `Failure`: The policy did not apply correctly, and endpoints are not protected.
 
-* `Failure`: The policy did not apply correctly. As such, endpoints are not protected.
+* `Unknown`: The user interface is waiting for the API response to return, or, in rare cases, the API returned an undefined error or value.
 
-* `Unknown`: The user interface is waiting for the API response to return, or, in rare cases, the API returns an undefined error or value.
+For more details on what's causing a policy status, click the link in the *Policy status* column and review the details flyout. Expand each section and subsection to display individual responses from the agent.
 
-To view policy status details, click the link and review the data in the flyout that displays.
+TIP: If you need help troubleshooting a configuration failure, refer to <<ts-unhealthy-agent,Endpoint management troubleshooting>> and {fleet-guide}/fleet-troubleshooting.html[{fleet} troubleshooting].
 
 [role="screenshot"]
-image::images/config-status.png[Config status details,width=75%]
-
-Expand each section and subsection to view individual responses from the agent.
-
-TIP: If you need help troubleshooting a configuration failure, see the {fleet-guide}/fleet-troubleshooting.html[{fleet} troubleshooting topic].
+image::images/config-status.png[Config status details,width=65%]
 
 [discrete]
 === Filter endpoints

docs/troubleshooting/management/ts-management.asciidoc

@@ -7,6 +7,35 @@ This topic covers common troubleshooting issues when using {elastic-sec} <<sec-m
 [[ts-endpoints]]
 === Endpoints
 
+[discrete]
+[[ts-unhealthy-agent]]
+.Unhealthy {agent} status
+[%collapsible]
+====
+In some cases, an `Unhealthy` {agent} status may be caused by a failure in the {endpoint-cloud-sec} integration policy. In this situation, the integration and any failing features are flagged on the agent details page in {fleet}. Expand each section and subsection to display individual responses from the agent.
+
+TIP: Integration policy response information is also available from the *Endpoints* page in the {security-app} (*Manage* -> *Endpoints*, then click the link in the *Policy status* column).
+
+[role="screenshot"]
+image::images/unhealthy-agent-fleet.png[Agent details page in {fleet} with Unhealthy status and integration failures]
+
+Common causes of failure in the {endpoint-cloud-sec} integration policy include missing prerequisites or unexpected system configuration. Consult the following topics to resolve a specific error:
+
+- <<system-extension-endpoint,Approve the system extension for {elastic-endpoint}>> (macOS)
+- <<enable-fda-endpoint,Enable Full Disk Access for {elastic-endpoint}>> (macOS)
+- <<linux-deadlock,Resolve a potential system deadlock>> (Linux)
+
+TIP: If the {endpoint-cloud-sec} integration policy is not the cause of the `Unhealthy` agent status, refer to {fleet-guide}/fleet-troubleshooting.html[{fleet} troubleshooting] for help with the {agent}.
+====
+
+[discrete]
+[[linux-deadlock]]
+.Disabled to avoid potential system deadlock (Linux)
+[%collapsible]
+====
+This section is a placeholder for future documentation.
+====
+
 [discrete]
 [[ts-transform-failed]]
 .Required transform failed
@@ -31,11 +60,3 @@ image::images/transforms-start.png[Transforms page with Start option selected]
 . On the confirmation message that displays, click *Start* to restart the transform.
 . The transform’s status changes to `started`. Refresh the page if you don't see the change.
 ====
-
-[discrete]
-[[linux-deadlock]]
-.Disabled to avoid potential system deadlock
-[%collapsible]
-====
-This section is a placeholder for future documentation.
-====