Unenroll Elastic Agents

You can unenroll Elastic Agents to invalidate the API key used to connect to Elasticsearch.

  1. In Fleet, select Agents.

  2. To unenroll a single agent, open the Actions menu next to the agent you want to unenroll, and then select:

    • Security and removal → Unenroll agent
    • Unenroll agent

  3. To unenroll multiple agents, bulk select the agents, open the Actions menu, and then select:

    • Security and removal → Unenroll N agents
    • Unenroll N agents

    N is the number of selected agents.

    Unable to select multiple agents? Confirm that your subscription level supports selective agent unenrollment in Fleet. For more information, refer to Elastic subscriptions.

When you unenroll an agent, Fleet sends it an unenroll action. When the agent receives the action, it stops its inputs and no longer sends data. Fleet invalidates the agent's API keys after the agent acknowledges the action. The Elastic Agent process continues to run, but it's no longer managed by Fleet.

Enrollment works differently for Elastic Agent in a containerized environment. For details, refer to Enrollment handling for containerized agents.

If unenrollment hangs because the agent is offline or can't be reached, you can force unenroll it. Force unenroll invalidates all API keys related to the agent and changes its status to Unenrolled, so that the agent no longer appears in Fleet.

A force-unenrolled agent doesn't receive the unenroll action, so it keeps running its last policy and keeps trying to check in with Fleet. It can no longer send data to the Elasticsearch cluster where Fleet runs, and it logs an invalid API key error. However, it can continue sending data to outputs that don't use the invalidated API keys, such as Kafka, Logstash, or remote Elasticsearch outputs. To stop it, you need to uninstall Elastic Agent on the host.

Warning

Force unenroll is a last resort, and you can't undo it from Fleet. Use it only for agents that are offline or can't be reached, or for compromised agents whose API keys you need to revoke immediately.

To force unenroll an agent, do one of the following:

  • If the agent's unenrollment hangs, open the Actions menu next to the agent and select Force unenroll. This option replaces Unenroll agent while unenrollment is in progress.
  • In the unenroll dialog, select Remove agent immediately under Force unenroll agent.