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 ephermeral hosts, such as docker containers, which can disappear at any time.
To set the unenrollment timeout:
- In Fleet, select Agent policies.
- Click the policy name, then click Settings.
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,
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
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
- 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.
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
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.
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.
Logs for inacative Elastic Agents are preserved in Elasticsearch. To view them:
- In Fleet, select Agents.
- In the Status menu, select Inactive.
- Click the name of the inactive agent to see agent details, then click Logs.
- If necessary, adjust the time range to see older logs.