Alright, let's get this out of the way upfront: the official Elastic documentation for deploying their agent at scale feels like it was written for a lab where you have three pristine, identical VMs. Reality is a sprawling, messy zoo of OS versions, stale images, and conflicting systemd services.
We just wrapped up a 10k+ endpoint rollout using Ansible as the driver. Here are the bits that actually matter, which you won't find in the marketing slicks.
First, forget a single monolithic playbook. You need to split the logic: one role for *installing* the agent (handling package managers, repo setup, the actual .deb/.rpm/.pkg), and a separate role for *configuring* it (managing `elastic-agent.yml` and the agent policy ID). Why? Because you'll be updating policy and configuration ten times for every one time you need to re-touch the installation. Keeps the variables clean.
The biggest headache wasn't Ansible—it was Elastic's own upgrade paths. If you're moving from Beats or a legacy Elastic Agent, the file paths and service names change. Our playbook now starts with a brutal "pre-flight" task that identifies and nukes any old Beats processes, removes orphaned configs from `/etc/*beats`, and stops conflicting services. You'd be surprised how many "agent not reporting" tickets were solved by a hidden `filebeat` process running as a user service.
Also, don't let the Fleet UI generate your agent policy YAML and just drop it in. It's bloated. Pull it, then trim. We strip out all the non-essential `inputs` and lean on the policy ID to pull the actual runtime config from Fleet. Your Ansible role should just manage the minimal local `elastic-agent.yml` with the Fleet URL, enrollment token, and policy ID. Let Fleet do what it's supposed to do for central management.
One last thing: inventory. Dynamic inventory from your CMDB is great, until you hit a subnet with a misconfigured agent that starts spamming failed enrollment attempts. We built in a mandatory "tag" step—a file on the endpoint that marks it as approved for Elastic Agent—before the playbook will even attempt to install. Saved us from a few self-inflicted DDoS incidents on the Fleet server.
The promise of "single, unified agent" is nice, but the devil is in the state management. Ansible's good at desired state, but you have to script the hell out of the current state discovery first.
—IR
Trust but verify – especially the audit log.