IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Unenroll Elastic Agents Upgrade Fleet-managed Elastic Agents »
Elastic Docs ›Fleet and Elastic Agent Guide [8.3] ›Centrally manage Elastic Agents in Fleet ›Elastic Agents

Set unenrollment timeout for ephemeral hosts

edit

Set unenrollment timeout for ephemeral hosts

edit

This setting is only valid for Fleet-managed agents.

Set the unenrollment timeout in the agent policy to specify the amount of time Fleet waits for an Elastic Agent to check in before forcing unenrollment.

This setting is useful for Elastic Agents running on ephemeral hosts, such as docker containers, which can disappear at any time.

To set the unenrollment timeout:

  1. In Fleet, select Agent policies.
  2. Click the policy name, then click Settings.

  3. In the Unenrollment timeout field, enter a value in seconds.

    Set the unenrollment timeout to a value that’s high enough to prevent Fleet from accidentally unenrolling agents during a temporary outage. For example, 1440.

Why set an unenrollment timeout?

edit

Containers might be killed, deleted, or moved, preventing agents from unenrolling gracefully. If there’s no unenrollment timeout specified, the agent will continue to appear as Offline in Fleet, and its API keys will remain active until explicitly revoked. To remove these "orphan" agents from the main Agent list and make them inactive, you need to force unenroll them in Fleet. However, in some environments, like Elasticsearch Service on Elastic Cloud, you may not be allowed to unenroll agents, which means the agents will appear as Offline indefinitely.

To avoid this problem, set the unenrollment timeout in the agent policy for Elastic Agents running on ephemeral hosts. If an Elastic Agent fails to check in with Fleet during the timeout period, Fleet will:

  • force unenroll the agent
  • set the agent status to Inactive
  • invalidate the API keys used by the agent

The agent’s ID and logs will be preserved in Elasticsearch, but container logs will be lost.

The Elastic Cloud agent policy, which is used by Fleet Server in Elastic Cloud, already has an unenrollment timeout specified. You cannot change this setting.

What if I don’t set an unenrollment timeout?

edit

If there is no unenrollment timeout specified and an Elastic Agent fails to check in, the agent remains enrolled in Fleet and its status is set to Offline. When the agent checks in with Fleet again, the status changes to Healthy, and the agent receives updates, as needed.

In most cases, you should avoid setting an unenrollment timeout for Elastic Agents running on laptops or servers that may be shut down, paused, or restarted for short periods of time before coming back online.

What if an Elastic Agent is accidentally unenrolled?

edit

You must reenroll the Elastic Agent in Fleet to resume normal functioning. The Elastic Agent will enroll using a new agent ID and API keys, which means the Agent will be appear as a new entry in the Agents list. When you click to see the Agent details, including logs, you’ll see details for the new agent.

If you reenroll an Elastic Agent inside the same container, it uses the local log files, disk queue, and registry from the previous run and resumes sending data to Elasticsearch. This minimizes data loss and duplication.

How do I see logs for inactive Elastic Agents?

edit

Logs for inactive Elastic Agents are preserved in Elasticsearch. To view them:

  1. In Fleet, select Agents.
  2. In the Status menu, select Inactive.
  3. Click the name of the inactive agent to see agent details, then click Logs.
  4. If necessary, adjust the time range to see older logs.
« Unenroll Elastic Agents Upgrade Fleet-managed Elastic Agents »